wanzi/ftb-project-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
。
2026-07-08 11:55:21 +08:00
parent aaaff6aa1f
commit 27cc1badc7
3 changed files with 90 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/roadmap.md
View File

@@ -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**