# Workflow and Effort Engine Design

## 背景

AI 拆解、开发任务、测试用例和 Bug 当前已经共享了几个核心问题：

- 状态流转分散在组件和 Zustand store 中，容易出现点一条却影响一组的误操作。
- AI 拆解生成的开发任务可能被自动开始逻辑推进到“开发中”，但实际开始时间应该来自人员手动点击。
- 测试用例有 `startedAt/completedAt`，但缺少统一的预估时间、实际时间和加权进度展示。
- AI 估时偏宽，未按“团队使用 AI 辅助开发/测试”的效率口径收敛。

本设计采用轻量规则引擎方案，不引入状态机库。

## 目标

1. 开发任务、测试用例、Bug 的状态操作只允许单条操作。
2. 实际开始/完成时间只能由对应人员的单条状态流转写入。
3. 开发任务和测试用例都支持预估时间、实际时间、汇总进度和单条展示。
4. AI 拆解生成草稿默认停留在待处理状态，不自动进入执行中。
5. AI 估时使用明确的规则口径，按 AI 辅助研发场景收紧。

## 非目标

- 本阶段不引入 XState 等完整状态机库。
- 本阶段不做完整后端关系表拆分，仍兼容当前 AppData JSONB 持久化。
- 本阶段不做任务自动排期，只处理预估/实际耗时与状态流转。
- Bug 暂不加入预估工时体系，仅先保证单条状态操作和现有实际耗时口径不被批量误触发。

## 推荐方案

使用纯函数规则层：

- `dev-task-workflow.ts`
- `test-case-workflow.ts`
- `bug-workflow.ts`
- `work-effort-engine.ts`
- `ai-estimation-policy.ts`

组件只发起“单条命令”，store 只负责保存状态，规则判断、时间戳写入和估时计算都放到规则层。

## 开发任务规则

状态机：

```text
todo -> in_progress -> testing -> submitted
testing -> in_progress
submitted 终态
```

显示文案：

- `todo`: 待开发
- `in_progress`: 开发中
- `testing`: 自测
- `submitted`: 已提测

时间戳规则：

- AI 或人工新建任务默认 `status=todo`。
- 新建任务不得写入 `actualStartAt/actualEndAt`。
- 只有单条任务从 `todo` 流转到 `in_progress` 时，才写入 `actualStartAt`。
- 只有单条任务流转到 `submitted` 时，才写入 `actualEndAt`。
- DevTask 不再根据预计开始时间自动进入 `in_progress`。

估时规则：

- 新增 `estimateHours?: number` 作为标准预估字段。
- 旧数据兼容：若没有 `estimateHours`，仍可从 `expectedStartAt/expectedEndAt` 推导。
- 实际耗时继续由 `actualStartAt -> actualEndAt/currentTime` 计算。

## 测试用例规则

状态机：

```text
pending -> running -> passed
pending -> running -> failed
pending -> running -> blocked
passed/failed/blocked -> running
```

显示文案调整：

- `pending`: 待测试
- `running`: 测试中
- `passed`: 通过
- `failed`: 不通过
- `blocked`: 阻塞

时间戳规则：

- 新建测试用例默认 `status=pending`。
- 只有单条用例从 `pending` 流转到 `running` 时，才写入 `startedAt`。
- 只有单条用例流转到 `passed/failed/blocked` 时，才写入 `completedAt`。
- 回退到 `running` 时，清除 `completedAt/failReason/blockReason`，保留首次 `startedAt`。

估时规则：

- 新增 `estimateHours?: number`。
- 单条展示 `实际 / 预估`。
- 汇总展示测试用例总预估、总实际、完成进度和通过率。
- 完成进度按预估工时加权：`passed/failed/blocked = 100%`，`running = 50%`，`pending = 0%`。
- 通过率仍只在 `passed/failed` 中计算，不把 `blocked` 计入通过率分母。

## Bug 规则

状态机保持：

```text
open -> fixing -> fixed -> verifying -> closed
open -> rejected
verifying -> open
```

本阶段只做两点：

- 移除或禁用任何批量通过/批量不通过/批量关闭入口。
- 任何 Bug 状态按钮只作用于当前单条 Bug。

## 批量操作约束

所有列表、分组、需求维度、版本维度都不得提供隐式批量状态流转。

禁止：

- 点击需求“已提测”后，把需求下全部开发任务提测。
- 点击测试用例“通过”后，把当前需求/版本下全部用例通过。
- 点击“不通过”后，把一组用例全部置为失败。

允许：

- 统计和筛选按需求/版本聚合展示。
- 单条任务、单条测试用例、单条 Bug 的状态按钮。

## AI 估时策略

AI 输出仍保留 `estimateHours`，但必须遵守更严格的区间。

默认按“有 AI 辅助开发/测试”的团队效率估算：

| 类型 | 默认估时 |
| --- | --- |
| 简单前端字段/文案/展示调整 | 0.25h - 0.5h |
| 简单前端交互，如拖拽排序 UI、开关、筛选项 | 0.5h - 1h |
| 拖拽排序并需要持久化接口 | 1h - 1.5h |
| 简单 CRUD 接口 | 0.75h - 1.5h |
| 小型数据库字段/索引调整 | 0.5h |
| 中等业务规则变更 | 1.5h - 3h |
| 简单功能测试用例执行 | 0.25h - 0.5h |
| API/异常/兼容性测试用例执行 | 0.5h - 1h |

只有出现跨端同步、复杂权限、历史数据迁移、强一致性、批量任务、复杂兼容性时，才允许超过默认区间。

## 数据修正

需要兼容已有数据：

- AI 草稿若 `aiDraft=true` 且状态已经是 `in_progress`，并且没有明确人工流转记录，则重置为 `todo` 并清理 `actualStartAt/actualEndAt`。
- 已有测试用例缺少 `estimateHours` 时，默认补 `0.5h`。
- 已有开发任务缺少 `estimateHours` 时，从旧的预计时间窗口推导；推导不到则使用 `1h`。

## UI 调整

开发任务：

- AI 草稿进入列表时显示“待开发”。
- 单条任务详情中保留状态按钮。
- 需求维度不再提供“全部提测”。

测试用例：

- 列表显示待测试/测试中/通过/不通过/阻塞。
- 单条用例显示预估、实际、时间范围。
- 总览显示预估合计、实际合计、完成进度、通过率。
- 不再提供任何批量通过/不通过。

Bug：

- 只保留单条 Bug 状态按钮。

## 测试策略

单元测试：

- DevTask 状态机合法/非法流转。
- DevTask 时间戳写入点。
- TestCase 状态机合法/非法流转。
- TestCase 时间戳写入点。
- Work effort 聚合。
- AI 估时策略边界。

集成级验证：

- AI 拆解采纳后，开发任务为待开发，测试用例为待测试。
- 点击一条开发任务提测，只影响这一条。
- 点击一条测试用例通过/不通过，只影响这一条。
- 页面总览的预估/实际/进度与单条数据一致。

## 实施顺序建议

1. 新增 workflow/effort/estimation 规则层和单元测试。
2. 改 DevTask 创建、AI 采纳、状态流转和自动开始逻辑。
3. 给 TestCase 增加 `estimateHours`，统一时间和进度计算。
4. 移除开发任务、测试用例、Bug 的批量状态入口。
5. 更新 AI prompt/schema 的估时要求。
6. 跑类型检查、单元测试和手工页面验证。