feat(v2.4): 完成领域主写迁移

docs/roadmap.md

@@ -1,21 +1,31 @@
 # 开发路线图
 
-## 当前阶段：V2.3 — 关系表写入与预计算闭环
+## 当前阶段：V2.4 — 领域 CRUD 主写迁移完成
 
-V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppData Store 写入形状，但 AppData 保存成功后会同步关系表、刷新/标脏小宝风险摘要，并记录慢 API 与慢 Prisma 查询。领域 CRUD 仍是后续阶段，当前重点是让版本详情、需求池、与我相关和小宝预警在大数据量下持续命中关系表快读。
+V2.4 将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。
 
 ### 当前状态快照（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 时需要统一为当前前端业务状态机。
+- 版本详情已有需求、调研、产品方案、UI、开发任务、测试用例、Bug、概览等核心 Tab；渲染重的路径优先接入关系表快读，并保留 AppData fallback。
+- 后端已落地 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime、WorkActivity 领域 CRUD/write API。
+- Prisma schema 已包含 Product、Project、Version、Requirement、VersionPlan、DevTask、TestCase、Bug、WorkActivity、TaskWorklog、Overtime、Xiaobao、AiLog、AppData 等关系模型；高增长表的分区 migration 已落地。
+- 主写入源已经切到领域 API：前端 store 优先调用 `apps/web/lib/domain-api.ts`，AppData 只保留兼容读取、失败回退和少量配置。
+- 需求池已切到服务端分页、搜索、筛选、排序，不再要求加载全量 AppData 文档。
+- `packages/shared` 状态契约已统一为当前业务状态机。
+- V2.4.5 保守边界：成员身份写 `users`；部门、角色、密码规则、加班原因暂留 AppData 配置，等待后续 RBAC/配置表阶段。
 
 ### 已完成（按时间倒序）
 
+**2026-07-08**
+- V2.4.0 completed shared domain status contract alignment for Requirement, VersionPlan, DevTask, TestCase, Bug, and Version.
+- V2.4.1 switched Product / Project / Version root mutations to domain APIs and left `products-overview` as compatibility fallback.
+- V2.4.2 switched Requirement writes to relation-table CRUD and added server-side pagination, search, filters, sorting, and cursor support for the requirement pool.
+- V2.4.3 switched VersionPlan and DevTask writes to version-scoped domain APIs, with work activity evidence and Xiaobao dirty marking.
+- V2.4.4 switched TestCase and Bug writes to version-scoped domain APIs, preserving round-copy and bug workflow behavior.
+- V2.4.5 switched Member, TaskCategory, TaskWorklog, OvertimeRecord, and WorkActivity writes to domain APIs. AppData remains only for compatibility fallback and low-frequency config such as departments, roles, password rules, and overtime reasons.
+- Added focused source-contract tests proving migrated frontend stores use domain APIs as primary writes rather than AppData document saves.
+
 **2026-07-06**
 - Added production CI/CD flow: GitHub Actions builds `web` and `server` Docker images, pushes immutable commit-SHA tags to GHCR, deploys by SSH, pulls images on the server, runs `pnpm --filter server db:deploy`, restarts Compose, and verifies `/api/v1/health/version`.
 - Added runtime version metadata: backend `GET /api/v1/health/version`, Docker build args/env, and a frontend refresh banner when browser assets are older than the server runtime.
@@ -50,6 +60,11 @@ V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppDa
 - 新增 `pnpm deploy:verify` 校验生产部署文件完整性
 - 新增 `docs/deployment.md`，覆盖本地开发、云服务器部署、升级、备份和排查流程
 
+**2026-06-26**
+- Workspace daily report upgraded from manual worklog summary to mixed activity aggregation.
+- Added `work-activities` AppData key and a typed activity factory for VersionPlan, DevTask, TestCase, and Bug actions.
+- `/workspace` daily report now groups delivery/progress/creation/risk/progress-note records and flags in-progress work that needs today's progress update.
+
 **2026-06-24**
 - 新增 NestJS `DataModule` + Prisma `AppData`，提供 `GET/PUT /api/v1/data/:key`
 - 产品/项目/版本树、需求池、调研/产品方案/UI、开发任务、测试用例、Bug 改为服务端持久化
@@ -97,14 +112,14 @@ V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppDa
 
 ## V2 — 后端接入
 
-NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。下一步才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD。
+NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步；第三阶段 V2.4 已逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD 主写。
 
 ### 关键任务
 
 1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现）
 2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
 3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
-4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型和同步桥已落地，领域写 API 仍待迁移）
+4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地）
 5. **认证**：NextAuth.js + JWT
 6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
 7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
@@ -113,17 +128,18 @@ NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSON
 
 当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。
 
-## V2.4 — 领域 CRUD 迁移（下一阶段）
+## V2.4 — 领域 CRUD 迁移（已完成）
 
-目标是让关系表从“快读 + AppData 同步副本”逐步升级为主写入路径。迁移顺序应优先选择写入频率高、实体边界清晰、已经在 V2.2 mapper 中稳定的领域：
+目标是让关系表从“快读 + AppData 同步副本”升级为主写入路径。V2.4 按以下顺序完成：
 
-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 不再是事实源。
+1. V2.4.0：统一 `packages/shared` 状态枚举与当前前端业务口径。
+2. V2.4.1：Project / Version 替代 `products-overview` 中的项目和版本主写入，产品树文档保留兼容读取。
+3. V2.4.2：Requirement 按 `productId` 分区键主写，并支持需求池服务端分页、搜索、筛选、排序。
+4. V2.4.3：VersionPlan / DevTask 按 `versionId` 分区键主写，写入后继续复用小宝 dirty 策略和工作活动记录。
+5. V2.4.4：TestCase / Bug 按 `versionId` 分区键主写，保留测试轮次和缺陷闭环。
+6. V2.4.5：Member / TaskCategory / TaskWorklog / Overtime / WorkActivity 主写关系表，证据型数据保留追加语义。
 
-V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 `draft/reviewing/approved` 或 `todo/in_review/done/closed` 状态重新带回系统。
+V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只用于 fallback、历史迁移和少量配置。部门、角色、密码规则、加班原因仍作为兼容配置保留，后续由 RBAC/配置表阶段单独收口。
 
 ## V3 — AI Agent 集成
 
@@ -140,14 +156,14 @@ V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端
 - 编辑后自动清除 aiDraft 标记
 - agent-spec.md / glossary.md 文档落地
 - 约定：原型链接 = 产品方案 (VersionPlan type=product) 已完成计划的 resultUrl，不在 Version 上独立存储
+- V2.4 已完成 DevTask/TestCase/Bug 的 `versionId` 版本主归属和领域主写，AI 写入可直接走版本级领域 API。
 
 **待实现**：
 1. 后端 `AiGateway` + `PrototypeDecomposeService`（NestJS module）
 2. 前端「AI 拆解任务和用例」按钮（产品方案 Tab）
 3. 对账报告组件（弹窗呈现：完美对应 / 需求未见原型 / 无需求ID分组 / 含糊）
 4. 用户确认后批量创建 DevTask + TestCase 草案
-5. DevTask 增加 `versionId`，`requirementId` 改为可选，兼容旧数据通过需求反查版本
-6. AiLog 表（调用记录、token 计量、用时）
+5. AiLog 表（调用记录、token 计量、用时）
 
 **MVP 范围限制**：
 - 不自动分配 assignee（留给用户在草案上手填）
@@ -193,10 +209,6 @@ V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端
 |------|------|
 | V1 业务流程打磨 | 进行中 |
 | V1 朋友试用反馈 | 持续中 |
-| V2 后端接入 | 进行中（V2.3 AppData 写桥 + 关系表快读/同步已实现，V2.4 领域 CRUD 迁移待推进） |
+| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；RBAC/认证仍待后续阶段） |
 | V3 AI 集成 | 等 V2 数据沉淀 |
 | 公开发布 | TBD |
-**2026-06-26**
-- Workspace daily report upgraded from manual worklog summary to mixed activity aggregation.
-- Added `work-activities` AppData key and a typed activity factory for VersionPlan, DevTask, TestCase, and Bug actions.
-- `/workspace` daily report now groups delivery/progress/creation/risk/progress-note records and flags in-progress work that needs today's progress update.