docs(项目状态): 校准 V2.3 与 V2.4 迁移边界

docs/roadmap.md

@@ -4,6 +4,16 @@
 
 V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppData Store 写入形状，但 AppData 保存成功后会同步关系表、刷新/标脏小宝风险摘要，并记录慢 API 与慢 Prisma 查询。领域 CRUD 仍是后续阶段，当前重点是让版本详情、需求池、与我相关和小宝预警在大数据量下持续命中关系表快读。
 
+### 当前状态快照（2026-07-08）
+
+- 项目已经不是早期骨架。前端业务功能已覆盖产品、项目、版本详情、需求池、工作台、成员/角色/任务类型、加班、小宝预警和 AI 配置等主要管理端路由。
+- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入 V2.2 关系表快读，并保留 AppData fallback。
+- 后端已落地 Product、Requirement 领域 CRUD，DataModule AppData 乐观锁，V2.2 快读 API，V2.3 AppData 写后同步关系表，AI Provider 抽象和健康版本接口。
+- Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
+- 主写入源仍处在兼容窗口：多数前端 store 继续通过 `apps/web/lib/server-data.ts` 的 `loadServerData` / `saveServerData` 写 AppData；`useProductStore` 仍以 `products-overview` 文档作为产品/项目/版本树主写入。
+- Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等领域写 API 尚未完整替代 AppData Store。若后续称为 V2.4，应理解为“领域 CRUD 迁移阶段”，不是 V2.3 已完成内容。
+- `packages/shared` 中仍保留早期枚举口径；切换领域 API 时需要统一为当前前端业务状态机。
+
 ### 已完成（按时间倒序）
 
 **2026-07-06**
@@ -87,14 +97,14 @@ V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppDa
 
 ## V2 — 后端接入
 
-NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段再逐步拆成关系表。
+NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。下一步才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD。
 
 ### 关键任务
 
 1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现）
 2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
-3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data`
-4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表
+3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
+4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型和同步桥已落地，领域写 API 仍待迁移）
 5. **认证**：NextAuth.js + JWT
 6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
 7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
@@ -103,6 +113,18 @@ NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSO
 
 当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。
 
+## V2.4 — 领域 CRUD 迁移（下一阶段）
+
+目标是让关系表从“快读 + AppData 同步副本”逐步升级为主写入路径。迁移顺序应优先选择写入频率高、实体边界清晰、已经在 V2.2 mapper 中稳定的领域：
+
+1. Project / Version：替代 `products-overview` 中的项目和版本主写入，保留产品树兼容读取。
+2. VersionPlan / DevTask / TestCase / Bug：按 `versionId` 分区键提供领域写 API，写入后继续复用现有小宝 dirty 策略和工作活动记录。
+3. Member / TaskCategory：替代 `members`、`task-categories` AppData 文档，统一权限、人员和任务类型字典来源。
+4. TaskWorklog / Overtime / WorkActivity：保留追加型写入语义，避免从当前 AppData 快照反向删除历史证据。
+5. 前端 store 分批切换：每切一个领域，都要保留兼容读取和回滚路径，直到 AppData 对应 key 不再是事实源。
+
+V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 `draft/reviewing/approved` 或 `todo/in_review/done/closed` 状态重新带回系统。
+
 ## V3 — AI Agent 集成
 
 详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
@@ -171,7 +193,7 @@ NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSO
 |------|------|
 | V1 业务流程打磨 | 进行中 |
 | V1 朋友试用反馈 | 持续中 |
-| V2 后端接入 | 进行中（V2.1 AppData 已实现） |
+| V2 后端接入 | 进行中（V2.3 AppData 写桥 + 关系表快读/同步已实现，V2.4 领域 CRUD 迁移待推进） |
 | V3 AI 集成 | 等 V2 数据沉淀 |
 | 公开发布 | TBD |
 **2026-06-26**