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

docs/workflow.md

@@ -39,7 +39,8 @@
 - [ ] 是否需要在 `workspace-engine.ts` 加聚合？
 - [ ] 删除版本时是否需要清理这类数据？
 - [ ] 工作台 / 版本详情 / 项目详情三处的统计是否同步？
-- [ ] localStorage 旧数据是否需要兼容处理？
+- [ ] 是否需要新增 `app_data` key（后端 `data-keys.ts` + 前端 `server-data.ts`）？
+- [ ] 是否需要从旧浏览器数据做一次性迁移？（当前不做本地导入导出）
 
 ## Drawer（侧边详情）规范
 
@@ -85,15 +86,19 @@
 
 朋友拉新代码出现"显示问题"时，按顺序排查：
 
-1. 旧 localStorage 数据格式不兼容 → 让朋友清缓存
-2. 类型定义和实际数据不一致（缺字段）
-3. 列宽溢出导致裁切
-4. 派生计算错误（filter 条件错）
-5. 跨模块联动断了（store 的 store.getState() 调用时机）
+1. 后端是否启动：`GET http://localhost:3001/api/v1/config/ai` 应返回 200
+2. 数据库是否启动并完成 Prisma 同步：`app_data` 表必须存在
+3. 对应 `app_data.key` 是否有值，例如 `products-overview` / `requirements` / `dev-tasks`
+4. 前端 store 是否已经调用对应 `fetch*` 方法
+5. 类型定义和实际 JSON 数据不一致（缺字段）
+6. 列宽溢出导致裁切
+7. 派生计算错误（filter 条件错）
+8. 跨模块联动断了（store 的 store.getState() 调用时机）
 
 ## 测试 / 验证流程
 
 - 改动后必须 `npx tsc --noEmit` 通过
+- 涉及服务端数据持久化：`pnpm --filter server exec prisma validate --schema prisma/schema.prisma`
 - 涉及 UI 改动：`curl http://localhost:3000/<path>` 检查 200
 - 不会自动跑 dev server，假定它已经运行
 
@@ -116,3 +121,66 @@ Workspace 页面（树筛选 + tab 筛选 + 已完成开关）
 ```
 
 新增模块时，只需在 `aggregateWorkItems` 中添加聚合逻辑，工作台自动展示。
+
+## AI 拆解工作流（V3.1）
+
+详细 Agent 规范见 `agent-spec.md`。这里是用户视角的工作流：
+
+```
+1. 创建版本（不需要单独填原型链接）
+   ↓
+2. 在版本详情 → 产品方案 Tab 创建一条 product 计划
+   ↓
+3. 完成产品方案计划，提交「成果」（成果链接即原型链接，附成果标题）
+   ↓
+4. 从当前项目已采纳需求中关联需求到本版本
+   ↓
+5. 点击「AI 拆解任务和用例」按钮（位于产品方案 Tab）
+   ↓
+6. Agent 从 product 类型的 completed 计划取 resultUrl 作为原型，
+   抓取原型 + 关联需求 + 版本成员，输出对账报告 + 任务/用例草案
+   ↓
+7. 用户审核对账报告
+   ├─ 报告全 ✅：直接确认写入
+   ├─ 报告有 ⚠️/❓：选择性放弃部分草案 / 补充信息后重跑
+   └─ 报告全 ❓：放弃 AI 拆解，人工创建
+   ↓
+8. 确认后，DevTask / TestCase 草案写入对应 Tab，标记 aiDraft: true
+   ↓
+9. 团队成员在 DevTask Tab 看到紫色边的 AI 草案任务
+   ↓
+10. 任意成员编辑任务（改标题/描述/负责人/优先级/时间/分类），保存后 aiDraft 自动清除
+    （changeStatus / setBlocked 等用户主动操作也会清除）
+```
+
+**触发条件**（AI 拆解按钮可点）：
+- 至少有 1 条 type=product 的产品方案计划处于 completed 且 resultUrl 非空
+- 至少 1 条需求关联到本版本
+
+**人工创建任务/用例的引用要求**：
+- 创建 DevTask 时已选「关联需求」自动作为 reference 写入
+- 创建表单加「原型批注」字段（手填，逗号或空格分隔，如 `QY0007, QY0023`）
+- 至少一类引用非空才能保存（V3.1 暂未做强校验，靠 UI 引导）
+
+## 高级开发约束：规则先归位
+
+涉及以下任意类型的改动时，先判断规则应该放在哪一层，不允许直接在页面组件里散写临时判断：
+
+- 跨模块联动：例如 Requirement、VersionPlan、DevTask、TestCase、Bug 互相派生状态。
+- 状态流转：例如 `pending -> in_progress -> completed`、`todo -> testing -> submitted`。
+- 完成条件：例如子任务是否完成、是否提交成果、是否允许点击完成。
+- 候选数据来源：例如关联需求只能来自当前项目已采纳需求，不能从全量需求池随手取。
+- AI 写入契约：例如 AI 输出任务类型、引用来源、草案标记。
+
+默认落点：
+
+- 可派生数据进 `*-engine.ts` 或纯函数 helper。
+- 有状态流转的实体要有状态机或 workflow helper。
+- 多个组件共用的候选筛选规则进 selector/helper。
+- AI 输入输出字段先更新 `agent-spec.md` 和 shared type，再改 prompt/schema。
+
+版本模块新增规则：
+
+- `version-plan-workflow.ts` 是调研/产品方案/UI 设计完成条件的唯一入口。
+- `requirement-selector.ts` 是版本内关联需求候选的唯一入口。
+- `TaskCategory.code` 是 AI 和系统任务类型的稳定映射锚点，`id` 只作为存储主键。