docs(项目状态): 校准 V2.3 与 V2.4 迁移边界

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.1） | 业务数据走 NestJS `/data/:key`，不再以浏览器存储为主 |
-| 后端 | NestJS + Prisma + PostgreSQL（V2） | 已接入通用数据文档层，后续再逐表关系化 |
+| 持久化 | PostgreSQL AppData + 关系表快读/同步（V2.3） | AppData 仍是兼容窗口内主写入；V2.2/V2.3 关系表用于热路径快读和写后同步 |
+| 后端 | NestJS + Prisma + PostgreSQL（V2.3） | Product/Requirement 有领域 CRUD；其他领域仍在从 AppData 向领域 API 迁移 |
 | AI | Anthropic SDK（V3 远景） | 健康度/风险预警/排期建议 |
 
 ## 模块结构
@@ -114,7 +114,9 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 
 ## 数据持久化
 
-**V2.1（当前）：** 通用服务端文档表 `app_data`
+**当前 V2.3 分层：** AppData 兼容写入 + 关系表快读/同步
+
+兼容写入层仍使用通用服务端文档表 `app_data`：
 - 后端：`apps/server/src/modules/data/` 提供 `GET/PUT /api/v1/data/:key`
 - 数据库：Prisma `AppData` 模型，表名 `app_data`，`key` 为主键，`value` 为 JSONB
 - 一致性：`GET` 返回 `updatedAt` 派生的 `version`；前端保存时带上最近读取的 `version`，后端用 `key + updatedAt` 原子更新，版本不匹配返回 `409 APP_DATA_CONFLICT`
@@ -122,7 +124,11 @@ DevTask 没有"已完成"状态，"已提测"就是终态——开发交付完
 - 覆盖范围：产品/项目/版本树、需求池、调研/产品方案/UI 计划、开发任务、测试用例、Bug、成员/角色/部门、任务类型、任务工时日志、加班记录
 - 浏览器仅保留登录会话（`ftb_auth_session` / `ftb_auth_persist`），不再作为业务数据主存储
 
-**后续 V2.2（计划）：** 将 `app_data` 中稳定的数据形状逐步拆成关系表和领域 CRUD API。拆表前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
+关系表层已经包含 V2.2/V2.3 能力：
+- V2.2：高增长业务表使用分区表，并提供版本详情、需求池、工作台和小宝预警的快读 API。
+- V2.3：AppData 保存成功后触发关系表同步，让快读路径保持新鲜；同步失败只记日志，不阻塞用户保存。
+
+尚未完成的是 V2.4 领域 CRUD 迁移：Project、Version、VersionPlan、DevTask、TestCase、Bug、Member、TaskCategory、TaskWorklog、Overtime 等主写入仍未完整切到领域 API。迁移前不要恢复业务 localStorage 缓存，避免线上部署后出现多端数据分叉。
 
 ## 生产部署层（2026-07-01）
 
@@ -275,3 +281,13 @@ V2.3 closes the first compatibility gap after V2.2: AppData remains the frontend
 - `xiaobao_risk_summaries` is refreshed from risk snapshots and marked `dirty=true` when plans, tasks, test cases, bugs, activities, worklogs, or overtime change.
 
 The server also has lightweight observability for this phase: a global API timing interceptor logs slow HTTP requests, and `PrismaService` logs slow query events. Thresholds are controlled by `API_SLOW_REQUEST_MS` and `PRISMA_SLOW_QUERY_MS`.
+
+## Current Backend Migration Boundary (2026-07-08)
+
+Current source-of-truth boundary:
+
+- Product and Requirement have domain CRUD modules.
+- Project, Version, VersionPlan, DevTask, TestCase, Bug, Member, TaskCategory, TaskWorklog, Overtime, and WorkActivity relation models exist for V2.2/V2.3 mapping and fast reads, but their frontend write paths still mostly go through AppData stores.
+- `products-overview` remains the primary document for the product/project/version tree until Project and Version write APIs replace it.
+- V2.2 read APIs and V2.3 relation sync are compatibility infrastructure, not proof that every relation model already has a public CRUD API.
+- `packages/shared` still contains early Requirement/Task status enums. Before switching frontend writes to domain APIs, align shared enums with the current workflow statuses in this document.