docs(路线图): 合并V2.5阶段基线

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.4） | 高增长领域直接写关系表；AppData 仅用于历史兼容、迁移兜底和少量配置项 |
+| 持久化 | PostgreSQL 关系表领域主写 + AppData 兼容兜底（V2.4/V2.5） | 高增长领域直接写关系表；AppData 进入禁写、核对、归档退场阶段 |
-| 后端 | NestJS + Prisma + PostgreSQL（V2.4） | Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/TaskWorklog/Overtime/WorkActivity 均有领域 CRUD |
+| 后端 | NestJS + Prisma + PostgreSQL（V2.5） | Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/TaskWorklog/Overtime/WorkActivity 均有领域 CRUD，V2.5 收口 RBAC/审计/一致性 |
 | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
 
 ## 模块结构
@@ -114,7 +114,7 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 
 ## 数据持久化
 
-**当前 V2.4 分层：** 领域 CRUD 主写 + AppData 兼容/迁移兜底
+**当前 V2.5 分层：** 领域 CRUD 主写 + AppData 禁写/核对/归档退场
 
 领域主写层已经覆盖主要业务实体：
 - 根数据：Product、Project、Version 直接写领域 API，`products-overview` 只作为兼容读取/兜底。
@@ -135,6 +135,22 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 - V2.3：AppData 保存成功后触发关系表同步，让快读路径保持新鲜；同步失败只记日志，不阻塞用户保存。
 - V2.4：领域 CRUD 成为主写入路径，AppData 写桥保留给历史数据和回滚兜底。不要恢复业务 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）
 
 当前仓库已补齐云服务器生产部署基线：
@@ -270,13 +286,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:
 

docs/decisions.md

@@ -578,3 +578,33 @@
 - 分区键进入每次领域写入，能维持 V2.2 分区表设计的查询边界。
 - AppData fallback 让迁移可回滚、可兼容旧数据，但不再制造长期双事实源。
 - RBAC/配置表会影响权限模型和管理流程，单独成阶段更安全；V2.4.5 只收口当前高频业务写入，避免为了“全收口”临时设计不稳的权限 schema。
+
+## 45. V2 后端关系化采用八阶段交付链路
+
+**问题**：V2.1/V2.2/V2.3 已经分别解决了服务端持久化、关系表快读和 AppData 写入后同步关系表。后续如果只写“AppData 退场、权限审计、性能增强、企业能力、生产稳定”这些大方向，容易出现三个偏差：V2.4 写领域 CRUD 时没有提前埋权限和审计，V2.5 把 AppData 当成可直接删除的旧表，V2.6 才发现分页、索引和查询边界没有在 API 设计期处理。
+
+**决策**：
+- V2.1：AppData 服务端持久化，先把业务数据从浏览器 localStorage 迁到服务端。
+- V2.2：关系表 + 分区 + 快读 API，优先支撑版本详情、需求池、工作台和小宝预警等读热点。
+- V2.3：AppData 写入后同步关系表，兼容期内保证快读数据跟随更新。
+- V2.4：领域 CRUD 主写迁移。每个领域 API 从第一版就必须带资源作用域、当前用户、`actorId`、基础审计事件入口、分页、索引和分区键查询边界。
+- V2.5：AppData 分阶段退场 + RBAC/审计/一致性收口。退场顺序固定为“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”。
+- V2.6：大数据性能增强 + 小宝预警后台化。在关系表主源稳定后做压测、慢查询治理、缓存/摘要、后台任务、幂等、锁和失败重试。
+- V2.7：企业级协作能力 + 管理治理，补通知、协同、组织治理、管理视图和企业级配置。
+- V2.8：生产硬化稳定版 + 运维闭环。生产部署基线已存在，V2.8 聚焦备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚和运维手册。
+
+**理由**：这条链路保持了从低风险兼容到强一致主源的顺序。权限/审计必须随领域 CRUD 进入代码路径，否则后补会重写接口边界；AppData 退场必须有闸门和回滚价值，不能直接删除；性能基础要从 V2.4 的 API 设计开始，V2.6 只做规模化增强和后台化能力。这样每个阶段都有清晰验收物，也能避免长期双主源、无审计写入和大数据查询返工。
+
+## 46. 业务主数据源切换到 PostgreSQL 领域关系表
+
+**问题**：AppData JSONB 文档表解决了浏览器 localStorage 丢数据问题，但如果继续把 `app_data.value` 当长期主数据源，会带来三个风险：整份 JSON 写入难以做字段级事务和权限校验，大数据量下筛选/分页/统计仍要依赖派生同步，线上排查时容易出现 AppData 与关系表不一致。
+
+**决策**：
+- PostgreSQL 领域关系表是后续业务主数据源，AppData 只保留为迁移、回填、兼容读取和审计排查入口。
+- 新增业务模块不得新增 AppData key 作为主存储；必须先设计关系表、Prisma model、领域 CRUD API 和必要的索引/分区键。
+- 现有 AppData key 按领域逐步迁移：先补关系表写 API，再让前端 store 写领域 API，最后移除对应 `saveServerData/loadServerData` 主路径。
+- V2.2 快读失败时的 AppData fallback 只能作为迁移期兜底，不能通过硬编码 `usingV22=false` 长期绕开关系表。
+- 删除或停用 JSON 文档前必须完成数据备份、迁移计数核对、抽样校验和回滚预案。
+- 一次性同步脚本可以存在，但必须作为运维迁移工具管理，不能依赖提交 `.env` 或手工修改源码开关。
+
+**理由**：系统未来要承载大量需求、任务、测试用例、Bug、活动和风险数据。关系表才能提供可验证的约束、事务、索引、分页、权限和审计能力。AppData 是低风险迁移桥，不是最终架构；继续扩大 JSON 主存储会把数据一致性和性能问题推迟到更难修的阶段。

docs/roadmap.md

@@ -1,8 +1,34 @@
 # 开发路线图
 
-## 当前阶段：V2.4 — 领域 CRUD 主写迁移完成
+## 当前阶段：V2.5 — AppData 分阶段退场 + RBAC/审计/一致性收口
 
-V2.4 将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。
+V2.4 已将高增长和核心业务领域从“AppData 主写 + 关系表同步副本”推进到“领域 CRUD 主写关系表 + AppData 兼容/迁移兜底”。V2.2 快读 API 和 V2.3 AppData 写后同步继续保留，但它们现在是兼容基础设施，不再是已迁移领域的数据新鲜度主链路。
+
+V2.5 的目标是正式收口后端权限、审计、AppData 禁写和一致性核对。AppData 不能直接删除，必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”的顺序推进。
+
+### 当前重点
+
+1. **RBAC 收口**：领域 mutation API 接入服务端权限校验、资源作用域和当前用户上下文。
+2. **审计事件**：所有领域 mutation 写 append-only audit event，支持后台查询和敏感字段脱敏。
+3. **AppData 禁写**：业务 AppData key 进入 `write_frozen` 或 `read_only_archive`，读仍可用，写返回明确替代领域 API。
+4. **导出归档**：提供 AppData archive export/verify 脚本，包含 checksum、key list 和应用版本元数据。
+5. **一致性校验**：提供 counts、partition key、orphan refs、audit coverage 的本地脚本和后台页面。
+6. **管理端可视化**：补 `/admin/audit` 与 `/admin/consistency`，并由 `audit:view` / `consistency:view` 控制。
+
+## V2 分阶段交付链路
+
+| 阶段 | 主题 | 边界 |
+|------|------|------|
+| V2.1 | AppData 服务端持久化 | 业务数据从浏览器 localStorage 迁到服务端 `app_data`，先解决清站点数据丢失问题。 |
+| V2.2 | 关系表 + 分区 + 快读 API | 建高增长领域表、分区键、快读查询和小宝摘要读取，写入仍走 AppData。 |
+| V2.3 | AppData 写入后同步关系表 | AppData 仍是兼容期写入事实源，保存成功后非阻塞同步关系表和风险摘要脏标记。 |
+| V2.4 | 领域 CRUD 主写迁移 | 逐领域补写 API，前端保存迁到领域 API；同时埋权限、作用域、审计和分页/索引基础。 |
+| V2.5 | AppData 分阶段退场 + RBAC/审计/一致性收口 | 禁写 AppData、移除 fallback、归档/导出旧 JSON，正式收紧权限、审计和一致性校验。 |
+| V2.6 | 大数据性能增强 + 小宝预警后台化 | 在关系表主源稳定后做压测、慢查询治理、缓存/摘要、后台任务、幂等重试和小宝定时预警。 |
+| V2.7 | 企业级协作能力 + 管理治理 | 补齐通知、协同、组织治理、管理视图、数据治理和企业级配置能力。 |
+| V2.8 | 生产硬化稳定版 + 运维闭环 | 在现有 CI/CD 基线上补备份恢复演练、发布 smoke test、监控告警、日志检索、迁移回滚和运维手册。 |
+
+阶段顺序不能倒置：权限/审计骨架从 V2.4 开始随领域 API 落地，V2.5 做全面收口；分页、索引、分区键查询从 V2.4 就必须进入 API 设计，V2.6 只做增强和压测治理；AppData 退场必须按“禁写 → 双读核对 → 移除 fallback → 只读归档/导出 → 后续删表”推进，不能一次性删除历史 JSON。
 
 ### 当前状态快照（2026-07-08）
 
@@ -108,6 +134,7 @@ V2.4 将高增长和核心业务领域从“AppData 主写 + 关系表同步副
 
 ### 进行中
 
+- V2.4 领域 CRUD 主写迁移：从 AppData JSONB 主写入切换到关系表 API，并随 API 落基础权限、审计和查询性能边界。
 - 项目详情页 VersionCard 状态胶囊数据联动（部分已完成）
 
 ## V2 — 后端接入
@@ -120,9 +147,12 @@ NestJS + Prisma + PostgreSQL 已推进到 V2.4。第一阶段用 `app_data` JSON
 2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
 3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data` 与 V2.2/V2.3 关系表
 4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表（关系模型、同步桥和 V2.4 领域写 API 已落地）
-5. **认证**：NextAuth.js + JWT
+5. **领域 CRUD 主写入**：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表（V2.4 已完成）
-6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
+6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口
-7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
+7. **AppData 主路径移除**：完成迁移核对后逐模块删除 JSON fallback 和 `/data/:key` 主写入依赖
+8. **认证**：NextAuth.js + JWT
+9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
+10. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
 
 ### 数据迁移策略
 
@@ -210,5 +240,6 @@ V2.4 完成后的兼容边界：AppData 不再是上述领域的事实源，只
 | V1 业务流程打磨 | 进行中 |
 | V1 朋友试用反馈 | 持续中 |
 | V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；RBAC/认证仍待后续阶段） |
+| V2 后端接入 | 进行中（V2.4 领域 CRUD 主写迁移已完成；V2.5 RBAC/审计/AppData 退场进行中） |
 | V3 AI 集成 | 等 V2 数据沉淀 |
 | 公开发布 | TBD |