# 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`