From 27cc1badc753f09c873bfb603887ddbee129900b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=80=82?= Date: Wed, 8 Jul 2026 11:55:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(roadmap):=20=E6=98=8E=E7=A1=AEV2=E5=85=B3?= =?UTF-8?q?=E7=B3=BB=E5=8C=96=E9=98=B6=E6=AE=B5=E9=93=BE=E8=B7=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture.md | 30 ++++++++++++++++++++++------- docs/decisions.md | 30 +++++++++++++++++++++++++++++ docs/roadmap.md | 46 +++++++++++++++++++++++++++++++++++--------- 3 files changed, 90 insertions(+), 16 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index 004d94c..2b4b19d 100644 --- a/docs/architecture.md +++ b/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: diff --git a/docs/decisions.md b/docs/decisions.md index 84f349c..f375bd5 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -557,3 +557,33 @@ - 同步失败只记录日志，不阻塞 AppData 保存。慢 API 和慢 Prisma 查询先通过日志监控，后续再接 Prometheus/Grafana。 **理由**：这是从 AppData 兼容写入平滑过渡到领域 CRUD 的中间层。用户保存不能因为派生关系表暂时失败而丢失业务数据；同时，关系表保持跟随更新后，V2.2 快读路径才能真正承受大数据量。把同步服务独立出来，也能让后续领域 CRUD 逐步替换 AppData 时复用同一套映射和小宝 dirty 策略。 + +## 44. 业务主数据源切换到 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 主存储会把数据一致性和性能问题推迟到更难修的阶段。 + +## 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 只做规模化增强和后台化能力。这样每个阶段都有清晰验收物，也能避免长期双主源、无审计写入和大数据查询返工。 diff --git a/docs/roadmap.md b/docs/roadmap.md index 48bea1a..be4761c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,8 +1,32 @@ # 开发路线图 -## 当前阶段：V2.3 — 关系表写入与预计算闭环 +## 当前阶段：V2.4 — 领域 CRUD 主写迁移 -V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppData Store 写入形状，但 AppData 保存成功后会同步关系表、刷新/标脏小宝风险摘要，并记录慢 API 与慢 Prisma 查询。领域 CRUD 仍是后续阶段，当前重点是让版本详情、需求池、与我相关和小宝预警在大数据量下持续命中关系表快读。 +V2.4 的目标是把业务主数据源从 AppData JSONB 文档切换到 PostgreSQL 领域关系表。AppData 继续保留为迁移、回填、兼容读取和排查入口，但不再作为长期主写入源；新增业务能力必须优先设计关系表、领域 CRUD API、索引/分区键和权限边界。V2.4 做逐领域主写迁移，并随 CRUD 入口埋好基础权限、`actorId` 和审计事件骨架；完整 RBAC、审计覆盖和 AppData 退场收口放到 V2.5。 + +### 当前重点 + +1. **领域写 API**：按模块补齐 Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/Worklog/Overtime 的关系表写入 API。 +2. **前端持久化切换**：Zustand store 保留状态管理，但保存入口从 `saveServerData(key)` 迁到领域 API；读取优先 V2.2/V2.3 关系表接口。 +3. **AppData 迁移工具化**：把 AppData → 关系表同步做成可重复运行、可计数校验、可回滚的运维脚本，不提交真实 `.env`。 +4. **主写切换闸门**：每个领域完成双读核对后，先停止该领域 JSON 主写入，再进入 V2.5 的 fallback 移除和归档退场。 +5. **数据一致性校验**：为每个迁移领域补 counts、抽样记录、孤儿引用、分区键完整性和唯一约束校验。 +6. **权限/审计骨架**：领域 API 必须携带当前用户、产品/项目/版本作用域和审计事件入口，避免 V2.5 做 RBAC 时返工。 + +## 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） @@ -93,11 +117,12 @@ V2.3 在 V2.2 快读路径之后补上写入闭环：前端仍保留现有 AppDa ### 进行中 +- V2.4 领域 CRUD 主写迁移：从 AppData JSONB 主写入切换到关系表 API，并随 API 落基础权限、审计和查询性能边界。 - 项目详情页 VersionCard 状态胶囊数据联动（部分已完成） ## V2 — 后端接入 -NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。下一步才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD。 +NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段已建立分区关系表、V2.2 快读 API 和 V2.3 AppData 写后同步。当前 V2.4 才是逐领域启用写 API，让前端 store 从 AppData 主写入迁移到领域 CRUD；AppData 后续只保留为迁移兼容层。 ### 关键任务 @@ -105,15 +130,18 @@ NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSON 2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现） 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 统一收束到规则层 +5. **领域 CRUD 主写入**：前端保存不再写整份 JSON 文档，而是调用具体领域 API 写关系表 +6. **基础权限/审计骨架**：领域 API 从迁移期开始接入用户身份、资源作用域、操作人和审计事件入口 +7. **AppData 主路径移除**：完成迁移核对后逐模块删除 JSON fallback 和 `/data/:key` 主写入依赖 +8. **认证**：NextAuth.js + JWT +9. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别 +10. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层 ### 数据迁移策略 当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。 -## V2.4 — 领域 CRUD 迁移（下一阶段） +## V2.4 — 领域 CRUD 迁移（当前阶段） 目标是让关系表从“快读 + AppData 同步副本”逐步升级为主写入路径。迁移顺序应优先选择写入频率高、实体边界清晰、已经在 V2.2 mapper 中稳定的领域： @@ -123,7 +151,7 @@ NestJS + Prisma + PostgreSQL 已接入到 V2.3。第一阶段用 `app_data` JSON 4. TaskWorklog / Overtime / WorkActivity：保留追加型写入语义，避免从当前 AppData 快照反向删除历史证据。 5. 前端 store 分批切换：每切一个领域，都要保留兼容读取和回滚路径，直到 AppData 对应 key 不再是事实源。 -V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 `draft/reviewing/approved` 或 `todo/in_review/done/closed` 状态重新带回系统。 +V2.4 推进前必须先统一 `packages/shared` 的状态枚举与当前前端业务口径，避免领域 API 切换时把旧的 `draft/reviewing/approved` 或 `todo/in_review/done/closed` 状态重新带回系统。 ## V3 — AI Agent 集成 @@ -193,7 +221,7 @@ V2.4 开始前必须先统一 `packages/shared` 的状态枚举与当前前端 |------|------| | V1 业务流程打磨 | 进行中 | | V1 朋友试用反馈 | 持续中 | -| V2 后端接入 | 进行中（V2.3 AppData 写桥 + 关系表快读/同步已实现，V2.4 领域 CRUD 迁移待推进） | +| V2 后端接入 | 进行中（V2.1/V2.2/V2.3 已完成，V2.4 主写迁移中） | | V3 AI 集成 | 等 V2 数据沉淀 | | 公开发布 | TBD | **2026-06-26**