# K12Study 逻辑视图
## 1. 分层结构
- 终端层
  - `frontend`（React 管理端）
  - `app`（微信小程序）
- 接入与安全层
  - `gateway`（统一入口、鉴权、路由、跨域、trace）
  - `auth`（登录、刷新、当前用户）
- 平台能力层
  - `upms`（租户、组织、用户、角色、菜单、路由元数据）
  - `ai-client`（Java 侧 AI 适配）
  - `python-ai`（AI 处理服务）
- 业务域层（规划中）
  - `course`、`question`、`achievement`、`recommendation`
- 数据与基础设施层
  - PostgreSQL（多 schema）
  - Redis（缓存、会话、热点）
  - NebulaGraph / Neo4j（知识图谱）
  - Milvus（向量检索）
  - Nacos（注册配置）

## 2. 逻辑架构图
```mermaid
graph TD
    WEB[Frontend React] --> GW[Gateway]
    MINI[Mini Program] --> GW

    GW --> AUTH[Auth Service]
    GW --> UPMS[UPMS Service]
    GW --> COURSE[Course Service]
    GW --> QUESTION[Question Service]
    GW --> ACHIEVE[Achievement Service]
    GW --> REC[Recommendation Service]

    AUTH --> PG[(PostgreSQL)]
    UPMS --> PG
    COURSE --> PG
    QUESTION --> PG
    ACHIEVE --> PG
    REC --> PG

    AUTH --> REDIS[(Redis)]
    UPMS --> REDIS
    COURSE --> REDIS
    QUESTION --> REDIS
    ACHIEVE --> REDIS
    REC --> REDIS

    QUESTION --> AICLIENT[AI Client]
    AICLIENT --> PYAI[Python AI]
    PYAI --> KG[(NebulaGraph / Neo4j)]
    PYAI --> VDB[(Milvus)]
    PYAI --> PG
```

## 3. 主链路视角
### 3.1 基础架构链路
- 登录：`frontend/app -> /api/auth/tokens -> auth -> token`
- 权限与路由：`frontend/app -> /api/upms/routes -> upms`
- 组织数据：`/api/upms/areas|tenants|departments`

### 3.2 教学业务链路
- 教师发作业：题库/试卷/作业配置 -> 投放班级。
- 学生提交：答题内容 + 文件（可选）。
- 批改流程：自动批改 + 人工复核 -> 成绩汇总 -> 错题沉淀。
- 复习与推荐：复习计划 -> 推荐内容 -> 用户反馈 -> 闭环效果。
- 成就激励：事件触发 -> 规则命中 -> 成就发放/进度更新。

### 3.3 AI 知识链路
- 文件入库：`upms.tb_sys_file -> ai.tb_ai_knowledge_file`
- 同步任务：`ai.tb_ai_knowledge_sync_task` 异步推送图谱/向量库
- 检索与推理：业务服务通过 `ai-client` 调 `python-ai`

## 4. 设计约束
- API 对外统一前缀 `/api/*`，内部服务前缀保持领域语义。
- 多租户与组织隔离字段在核心表统一保留（`tenant_id/tenant_path/dept_id/dept_path/adcode`）。
- 业务域之间优先通过 API 契约与事件解耦，不直接跨模块读写表。