docs(版本模块): 规则引擎与任务类型设计

docs/roadmap.md

@@ -1,11 +1,17 @@
 # 开发路线图
 
-## 当前阶段：V1 — 前端 Mock + 业务流程打磨
+## 当前阶段：V2.1 — 服务端持久化第一阶段
 
-所有数据用 localStorage 持久化，重点验证业务模型和交互。
+业务流程仍保持 V1 的前端 store 形状，但业务数据主存储已切到 NestJS + PostgreSQL `app_data` 文档表。浏览器只保留登录态，不再保存产品、项目、版本、需求、版本详情、成员、任务类型等业务数据。
 
 ### 已完成（按时间倒序）
 
+**2026-06-24**
+- 新增 NestJS `DataModule` + Prisma `AppData`，提供 `GET/PUT /api/v1/data/:key`
+- 产品/项目/版本树、需求池、调研/产品方案/UI、开发任务、测试用例、Bug 改为服务端持久化
+- 成员/角色/部门、任务类型、任务工时日志、加班记录改为服务端持久化
+- 登录改为读取服务端成员数据；浏览器只保留登录会话
+
 **2026-06-16**
 - 项目模块顶部卡片（总版本数/已开发/需求数/Bug 总数）
 - 项目模块版本记录与版本详情数据联动（耗时 + 状态胶囊）
@@ -47,38 +53,70 @@
 
 ## V2 — 后端接入
 
-NestJS + Prisma + PostgreSQL Schema 已设计，等业务流程稳定后开始迁移。
+NestJS + Prisma + PostgreSQL 已开始接入。第一阶段先用 `app_data` JSONB 文档表承接现有 store 数据形状，避免浏览器清站点数据导致业务数据丢失；第二阶段再逐步拆成关系表。
 
 ### 关键任务
 
-1. **运行 Prisma migration**：把现有的 lib/*.ts 类型转为 Prisma schema
-2. **API 层**：每个 store 对应一组 CRUD endpoint
-3. **localStorage → API 切换**：保留 localStorage 作为离线缓存
-4. **认证**：NextAuth.js + JWT
-5. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
+1. **服务端文档层**：`app_data` + `/api/v1/data/:key`（第一阶段已实现）
+2. **localStorage → API 切换**：业务主数据不再写浏览器（第一阶段已实现）
+3. **运行 Prisma 同步/迁移**：本地和服务器数据库都需要创建 `app_data`
+4. **关系化拆表**：把稳定模块从 JSONB 拆成 Product/Project/Version/Task 等领域表
+5. **认证**：NextAuth.js + JWT
+6. **权限**：RBAC（Owner/Admin/Member/Viewer），按项目/版本级别
+7. **版本规则引擎收敛**：VersionPlan 完成条件、关联需求候选、TaskCategory 语义码、TestCase.categoryId 统一收束到规则层
 
 ### 数据迁移策略
 
-提供管理员脚本把当前用户的 localStorage 数据导出为 SQL，导入到 PostgreSQL。
+当前不做本地导入导出。清站点数据后浏览器旧数据无法恢复，后续新增数据直接写入 PostgreSQL。若以后需要迁移旧浏览器数据，再单独做管理员导入工具。
 
-## V3 — AI 集成
+## V3 — AI Agent 集成
 
-### 已规划场景
+详细 Agent 规范见 `agent-spec.md`。本节只列规划，不重复 Agent 实现细节。
 
-1. **需求智能分解**：输入需求描述，AI 拆解为子任务（技术分析+UI 调整+联调+测试）
-2. **风险预警**：自动识别延期/阻塞集中/工时偏差大的任务，提前预警
-3. **排期建议**：基于成员负载和历史耗时，建议下一阶段任务分配
-4. **需求转任务**：需求采纳后一键生成 DevTask 草稿
-5. **健康度智能解读**：把数据指标转化为自然语言报告
+### V3.1 — Prototype Decompose Agent（首个 Agent）
 
-### 落地方式
+**目标**：从产品方案的原型 + 关联需求，拆解出开发任务草案 + 测试用例草案。
 
-`apps/server/src/modules/ai/`：
-- `AiGateway` — 统一 prompt 管理、token 计量、降级
-- `AiTaskService.decompose(description)`
-- `AiRiskService.analyze(projectId)`
-- `AiScheduleService.suggest(projectId)`
-- `AiLog` 表存调用记录，便于审计
+**已完成的数据底座**（2026-06）：
+- DevTask / TestCase 加 references[] + aiDraft + aiDraftAt
+- 创建表单加「原型批注」字段
+- 列表中 AI 草案视觉区分（紫色边 + 徽章）
+- 编辑后自动清除 aiDraft 标记
+- agent-spec.md / glossary.md 文档落地
+- 约定：原型链接 = 产品方案 (VersionPlan type=product) 已完成计划的 resultUrl，不在 Version 上独立存储
+
+**待实现**：
+1. 后端 `AiGateway` + `PrototypeDecomposeService`（NestJS module）
+2. 前端「AI 拆解任务和用例」按钮（产品方案 Tab）
+3. 对账报告组件（弹窗呈现三段：完美对应 / 单边 / 含糊）
+4. 用户确认后批量创建 DevTask + TestCase 草案
+5. AiLog 表（调用记录、token 计量、用时）
+
+**MVP 范围限制**：
+- 不自动分配 assignee（留给用户在草案上手填）
+- 不做"上一版基准 diff"（按 decisions.md #17 决议）
+- 单 Agent 单 Round，不做多 Agent 编排
+
+### V3.2 — Risk Watch Agent + Schedule Suggest Agent
+
+**Risk Watch Agent**：自动识别延期/阻塞集中/工时偏差大的任务，提前预警
+
+**Schedule Suggest Agent**：基于成员负载和历史耗时，建议下一阶段任务分配
+
+**多 Agent 协作设计**：到 V3.2 才真正涉及，当前 agent-spec.md 仅占位
+
+### V3.3 — 其他场景候选
+
+1. 需求智能分类（自动归档到产品 / 项目）
+2. 健康度智能解读（数据指标 → 自然语言报告）
+3. 需求转任务（需求采纳后一键生成 DevTask 草稿）
+
+### 落地约束
+
+- **不直接动数据**：所有 Agent 写入必须带 `aiDraft: true`，用户编辑后才转正
+- **必须有引用**：所有 AI 产物带 references，用户能追溯到源头
+- **必须有对账报告**：拆解类 Agent 输出前端展示三段报告，让用户决策
+- **可降级**：原型不可达 / 输入数据不全 / 模型超时，明确告知用户失败原因，不写入任何数据
 
 ## 不在路线图（明确不做）
 
@@ -95,6 +133,6 @@ NestJS + Prisma + PostgreSQL Schema 已设计，等业务流程稳定后开始
 |------|------|
 | V1 业务流程打磨 | 进行中 |
 | V1 朋友试用反馈 | 持续中 |
-| V2 后端接入 | 等 V1 稳定 |
+| V2 后端接入 | 进行中（V2.1 AppData 已实现） |
 | V3 AI 集成 | 等 V2 数据沉淀 |
 | 公开发布 | TBD |