wanzi/ftb-project-management

Fork 0

Files

Script Generator 978bc7aff1 docs(workflow): add workflow and effort engine design

2026-06-25 13:10:00 +08:00

6.8 KiB

Raw Blame History

Workflow and Effort Engine Design

背景

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

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

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

目标

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

非目标

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

开发任务规则

状态机：

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 计算。

测试用例规则

状态机：

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 规则

状态机保持：

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

实施顺序建议

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

6.8 KiB Raw Blame History Unescape Escape