docs(workflow): add workflow and effort engine design
This commit is contained in:
Script Generator
@@ -0,0 +1,207 @@
|
||||
# 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. 跑类型检查、单元测试和手工页面验证。
|
||||
Reference in New Issue
Block a user