K12Study/docs/architecture.md

K12Study 项目模块化里程碑（2026-04-13 ~ 2026-07-01）

1. 目标与范围

• 在 7.1 前完成从基础架构到核心业务链路的可联调版本，并进入整体测试封板。
• 里程碑覆盖全流程：逻辑视图、ER/SQL、基础服务、基础架构 API、基础架构前后端、核心课程/学习业务、模块测试、项目整体测试。
• 当前项目基线：gateway + auth + upms + boot-dev + python-ai + frontend + app + init/pg。

2. 技术路线（当前版本）

• 图数据库：NebulaGraph（主选），Neo4j（开发备选）。
• 向量库：Milvus（主选）。
• 关系库：PostgreSQL（业务主数据与事实源）。
• 缓存：Redis（token、权限、热点缓存）。

3. 模块化里程碑分解

M0 逻辑视图梳理（04.13-04.15）

• 目标
  • 固化系统分层、边界与主链路，避免后续并行开发职责交叉。
• 关键任务
  • 统一 BFF/API 网关边界、认证边界、业务域边界、AI 适配边界。
  • 明确 Web / 小程序 / 后端服务 / 数据与中间件的调用方向。
• 验收产物
  • docs/architecture/logical-view.md

M1 ER 图与 SQL 设计（04.16-04.21）

• 目标
  • 完成核心业务域数据模型定版，确保接口与代码开发有稳定数据契约。
• 关键任务
  • 梳理多租户基础域（tenant/dept/user/role/menu）。
  • 梳理课程域、题目与批改域、成就与推荐域、AI 知识域的数据关系。
  • 定义 SQL 执行顺序、索引策略、跨 schema 依赖约束。
• 验收产物
  • docs/architecture/er-diagram.md
  • docs/architecture/schema-baseline.sql

M2 基础服务配置（04.22-04.26）

• 目标
  • 打通基础运行底座：PostgreSQL、Redis、注册中心、知识图谱、向量库。
• 关键任务
  • 统一本地开发环境变量命名与连接方式。
  • 约定 NebulaGraph（主）/Neo4j（备）与 Milvus 接入规范。
  • 明确健康检查、持久化卷、网络隔离策略。
• 验收产物
  • docs/architecture/base-services.md
  • docs/architecture/service-baseline.compose.yaml

M3 基础架构 API 定义（04.27-05.03）

• 目标
  • 完成基础能力 API（认证、权限、租户、组织、路由、基础文件）契约冻结。
• 关键任务
  • 统一响应结构、鉴权方式、错误码与 traceId 规范。
  • 固化 auth/upms 的 API 清单与扩展位。
• 验收产物
  • docs/architecture/api-design.md（基础架构 API 段）

M4 基础架构前后端代码构建（05.04-05.10）

• 目标
  • 实现并联调基础架构链路（登录、当前用户、动态路由、区域树、租户树、部门树）。
• 关键任务
  • 后端：auth/upms 与网关链路稳定化。
  • 前端：React 管理端基础框架与动态路由消费。
  • 小程序：基础请求层与最小页面壳可访问基础接口。
• 验收标准
  • /api/auth/*、/api/upms/* 在本地模式和网关模式都可联调。

M5 核心课程/学习业务 API 与数据模型冻结（05.11-05.24）

• 目标
  • 将剩余周期聚焦课程与学习核心内容，完成核心域契约冻结。
• 关键任务
  • 完成课程、学习路径、学习记录、学习效果等核心 API 与数据模型定义。
  • 固化核心流程输入输出 DTO 与事件流。
• 验收产物
  • docs/architecture/api-design.md（课程/学习核心段）

M6 核心课程/学习业务前后端构建（05.25-06.14）

• 目标
  • 完成课程与学习核心功能前后端落地并联调。
• 关键任务
  • 后端：课程与学习域核心能力实现。
  • 前端/小程序：课程学习主流程页面与 API 接入。
• 验收标准
  • 课程发布 -> 学习执行 -> 学习记录回写的核心闭环可演示。

M7 核心内容专项测试与修复（06.15-06.24）

• 目标
  • 核心课程/学习模块通过功能、接口、回归测试。
• 关键任务
  • 覆盖课程、学习、基础架构联动场景。
  • 修复阻塞级问题并完成回归。
• 验收产物
  • docs/architecture/test-plan.md（模块测试段）

M8 整体回归与发布评估（06.25-07.01）

• 目标
  • 完成全链路回归、性能基线与发布准入评估。
• 关键任务
  • 核心课程/学习主流程端到端回归与异常链路验证。
  • 输出上线前 go/no-go 结论。
• 验收产物
  • docs/architecture/test-plan.md（整体测试段）

4. 三库协同原则（首版）

• 关系库到图库：通过同步任务进行实体与关系映射。
• 关系库到向量库：通过切片与 embedding 任务进行索引。
• 图谱节点保留源表标识（如 source_table、source_pk），支持点击节点回查原始表数据。

5. 执行原则

• 所有模块按“先契约、后实现、再联调、最后回归”的顺序推进。
• API 契约冻结后，跨端协作不随意破坏兼容性；新增字段走向后兼容策略。
• 数据模型以 init/pg 既有结构为基础，新增结构优先走增量脚本。

6. 风险与缓冲策略

• 风险一：业务域并行开发导致接口反复变更。
  • 策略：M3/M5 设置 API 冻结点，冻结后变更必须评审。
• 风险二：AI 相关链路依赖图谱/向量服务稳定性不足。
  • 策略：先完成本地 mock + 异步任务队列，再切换真实存储。
• 风险三：最后阶段联调问题集中爆发。
  • 策略：M6 结束前必须打通最小闭环，M7 提前做模块回归。

7. 分册文档

• docs/architecture/README.md
• docs/architecture/logical-view.md
• docs/architecture/er-diagram.md
• docs/architecture/schema-baseline.sql
• docs/architecture/base-services.md
• docs/architecture/service-baseline.compose.yaml
• docs/architecture/api-design.md
• docs/architecture/test-plan.md