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

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

Browse Source
This commit is contained in:
。
2026-07-08 16:07:39 +08:00
parent da71128ccd 27cc1badc7
commit 8043fcf293
3 changed files with 88 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/architecture.md
View File

@@ -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 仅用于历史兼容、迁移兜底和少量配置项 |
| 后端 | NestJS + Prisma + PostgreSQL（V2.4） | Product/Project/Version/Requirement/VersionPlan/DevTask/TestCase/Bug/Member/TaskCategory/TaskWorklog/Overtime/WorkActivity 均有领域 CRUD |
| 持久化 | PostgreSQL 关系表领域主写 + AppData 兼容兜底（V2.4/V2.5） | 高增长领域直接写关系表；AppData 进入禁写、核对、归档退场阶段 |
| 后端 | 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: