docs(roadmap): 明确V2关系化阶段链路

docs/architecture.md

@@ -33,8 +33,8 @@ Requirement          Version               TestCase
 | 前端 | Next.js 14 (App Router) | TypeScript + 客户端组件为主 |
 | UI | Tailwind CSS + Shadcn/ui | 紧凑信息密度、现代风格 |
 | 状态 | Zustand | 每个领域一个 store |
-| 持久化 | PostgreSQL AppData + 关系表快读/同步（V2.3） | AppData 仍是兼容窗口内主写入；V2.2/V2.3 关系表用于热路径快读和写后同步 |
-| 后端 | NestJS + Prisma + PostgreSQL（V2.3） | Product/Requirement 有领域 CRUD；其他领域仍在从 AppData 向领域 API 迁移 |
+| 持久化 | PostgreSQL AppData + 关系表迁移层（V2.4） | V2.2/V2.3 关系表用于热路径快读和写后同步；V2.4 起领域关系表逐步成为主写入，AppData 仅作兼容/迁移入口 |
+| 后端 | NestJS + Prisma + PostgreSQL（V2.4） | Product/Requirement 已有领域 CRUD；其他领域正在从 AppData 向领域 API 迁移 |
 | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
 
 ## 模块结构
@@ -114,7 +114,7 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 
 ## 数据持久化
 
-**当前 V2.3 分层：** AppData 兼容写入 + 关系表快读/同步
+**当前 V2.4 分层：** AppData 兼容写入 + 关系表快读/同步 + 领域 CRUD 主写迁移
 
 兼容写入层仍使用通用服务端文档表 `app_data`：
 - 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`
@@ -128,7 +128,23 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 - V2.2：高增长业务表使用分区表，并提供版本详情、需求池、工作台和小宝预警的快读 API。
 - V2.3：AppData 保存成功后触发关系表同步，让快读路径保持新鲜；同步失败只记日志，不阻塞用户保存。
 
-尚未完成的是 V2.4 领域 CRUD 迁移：Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等主写入仍未完整切到领域 API。迁移前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
+V2.4 正在推进领域 CRUD 主写迁移：Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等主写入需要逐步切到领域 API。迁移前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
+
+**目标主源（新方向）：** 业务主数据必须落到 PostgreSQL 领域关系表。
+- `app_data` 不再作为长期事实源，只保留迁移、回填、兼容读取和故障排查价值。
+- 新增业务模块不得新增 AppData key 作为主存储；必须先设计关系表、Prisma model 和领域 CRUD API。
+- 现有 AppData key 需要逐步完成一次性迁移、双读校验、关系表写入切换和 JSON fallback 移除。
+- 前端 store 可以继续保留 Zustand 状态形状，但持久化入口要从 `saveServerData(key)` 迁到领域 API。
+- `app_data` 删除前必须有备份/导出和数据量核对，不能直接丢弃历史 JSON。
+
+**V2 迁移阶段边界：**
+- V2.1 先把业务数据从浏览器移到服务端 AppData，解决部署和清站点数据丢失问题。
+- V2.2 建关系表、分区、快读 API 和小宝摘要读取，写入仍走 AppData。
+- V2.3 在 AppData 保存成功后非阻塞同步关系表，让快读路径持续有新数据。
+- V2.4 逐领域把主写入口迁到关系表 CRUD；领域 API 必须从一开始带资源作用域、当前用户、`actorId`、基础审计事件入口、分页和索引边界。
+- V2.5 才做 AppData 分阶段退场和 RBAC/审计/一致性收口：先禁写，再双读核对，再移除 fallback，最后只读归档/导出，不能直接删历史 JSON。
+- V2.6 在关系表主源稳定后做大数据性能增强和小宝预警后台化；性能基础不后置，增强项包括压测、慢查询治理、缓存/摘要、后台任务、幂等和失败重试。
+- V2.7 面向企业级协作与管理治理，V2.8 面向生产硬化与运维闭环；生产部署基线已经存在，V2.8 重点是备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚和运维手册。
 
 ## 生产部署层（2026-07-01）
 
@@ -265,13 +281,13 @@ The first V2.2 read layer is query-first and AppData-compatible. `V22QueryModule
 - Workspace reads only the current user's unfinished plans, dev tasks, test cases, and bugs.
 - Xiaobao warning reads `xiaobao_risk_summaries` first, then maps the precomputed summary into the existing warning UI shape.
 
-During the V2.2 compatibility window, writes still go through the existing AppData stores. The frontend consumes V2.2 relation-table results for render-heavy pages and falls back to AppData only when the V2.2 read is unavailable or empty.
+During the V2.2 compatibility window, writes still go through the existing AppData stores. The frontend consumes V2.2 relation-table results for render-heavy pages and falls back to AppData only when the V2.2 read is unavailable or empty. This is a migration bridge, not the target steady state.
 
 ## V2.3 AppData-to-Relational Write Sync Layer (2026-07-03)
 
-V2.3 closes the first compatibility gap after V2.2: AppData remains the frontend write source, but successful `PUT /api/v1/data/:key` calls now trigger a backend relation-table sync.
+V2.3 closes the first compatibility gap after V2.2: AppData remains the frontend write source only during the compatibility window, but successful `PUT /api/v1/data/:key` calls now trigger a backend relation-table sync.
 
-`DataService` writes AppData with the existing optimistic-lock rules first. After the AppData write succeeds, it calls `AppDataV23SyncService.syncAfterAppDataPut(key)`. Sync failures are logged and do not fail the user save, because AppData is still the source of truth during this compatibility window and V2.2 read paths keep their AppData fallback.
+`DataService` writes AppData with the existing optimistic-lock rules first. After the AppData write succeeds, it calls `AppDataV23SyncService.syncAfterAppDataPut(key)`. Sync failures are logged and do not fail the user save during this compatibility window. The next phase must replace AppData writes with domain CRUD writes so relation tables become the source of truth.
 
 `AppDataV23SyncService` reuses the V2.2 pure mapper, then writes only the table family affected by the changed AppData key: