K12Study/docs/architecture/logical-view.md

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. 逻辑架构图

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 契约与事件解耦，不直接跨模块读写表。