wanzi/ftb-project-management

Fork 0

Files

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

2026-06-25 09:52:05 +08:00

8.2 KiB

Raw Blame History

版本模块规则引擎与任务类型设计

背景

版本详情里的调研、产品方案、UI 设计、开发任务、测试用例已经形成一条执行链路，但有几处规则还散在 UI 组件里：

开发任务的任务类型太粗，测试用例还没有任务类型。
AI 拆解只输出 role，不能稳定落到当前系统的任务类型字典。
计划任务可以通过右上角勾选直接完成，绕过子任务和成果提交。
关联需求的候选来源不够明确，容易误用全量需求池。
调研、产品方案、UI 设计的关联需求选择缺少全选能力。

这次设计的目标是把这些规则收敛到字典、选择器和工作流引擎里，而不是继续在页面组件里散写条件。

目标

任务类型能支撑更细的开发与测试范围。
DevTask 和 TestCase 共用同一套任务类型字典。
AI 拆解必须输出任务类型，并能稳定映射到系统字典。
VersionPlan 的完成条件由统一规则函数判断。
所有关联需求入口只从当前版本所属项目下的已采纳需求中选择，不从全量需求池选择。
调研、产品方案、UI 设计的关联需求选择支持全选。
项目文档明确约束：跨模块联动、状态流转、完成条件、AI 契约必须优先考虑引擎、状态机或统一规则函数。

非目标

不做本地数据导入导出。
不在这一步把 app_data 全量拆成关系表。
不让 AI 自动分配负责人。
不让 AI 直接写入正式 DevTask/TestCase；仍然只写入草案。

方案概览

新增或调整三个规则层：

task-category.ts：任务类型字典扩展为开发、测试、实施、其他，并增加稳定语义码。
requirement-selector.ts：统一筛选当前项目下可用于关联的需求。
version-plan-workflow.ts：统一计算计划进度、是否能提交成果、是否能完成、缺少什么条件。

页面组件只负责展示和触发动作，不直接决定业务规则。

任务类型字典

TaskCategory 继续作为开发任务和测试用例的共享字典，但增加一个稳定字段：

interface TaskCategory {
  id: string;          // 存储主键，仍用于 DevTask.categoryId / TestCase.categoryId
  code: string;        // 稳定语义码，给 AI 和映射逻辑使用
  name: string;        // 展示名称，可被管理员调整
  group: 'development' | 'testing' | 'implementation' | 'other';
  color?: string;
  sortOrder: number;
  isSystem: boolean;
}

推荐预置分类示例：

开发：前端页面、前端交互、后端接口、后端业务逻辑、数据库/数据结构、权限/流程、第三方集成、接口联调
测试：功能测试、接口测试、异常场景、兼容性测试、回归测试、数据校验
实施：数据处理、实施支持、配置部署
其他：文档、协调、待确认

id 用于系统存储，code 用于 AI 输出和迁移兼容。管理员可以改名称，但不建议随意修改系统预置 code。

测试用例任务类型

TestCase 增加 categoryId：

interface TestCase {
  categoryId: string;
}

影响范围：

TestCaseCreateModal 增加任务类型必填项。
TestCaseRow 和 TestCaseDetailDrawer 展示类型标签。
useTestCaseStore.fetchTestCases 对旧数据做兼容补齐，默认映射到测试分组的第一个系统类型。
AI 草案写入 TestCase 时也要映射 categoryCode -> categoryId。

关联需求选择规则

所有关联需求入口统一使用同一套候选规则：

requirements.filter((r) =>
  r.projectId === version.projectId &&
  r.status === 'adopted'
)

含义：

候选来自当前版本所属项目下的需求，不从产品级全量需求池直接取。
只有已采纳需求可被新选择。
如果历史计划已经关联了某条需求，但该需求后来不再满足候选条件，编辑时保留旧关联并标记为“历史关联”，避免悄悄丢数据。
版本需求 Tab、调研计划、产品方案、UI 设计、开发任务和测试用例中的需求选择都复用该规则函数。

调研、产品方案、UI 设计的关联需求控件增加：

全选当前候选。
清空选择。
已选数量 / 候选数量提示。
候选为空时说明需要先在项目下采纳需求。

VersionPlan 工作流引擎

新增 apps/web/lib/version-plan-workflow.ts，作为计划完成规则的唯一入口。

建议导出：

interface PlanCompletionState {
  checklistTotal: number;
  checklistCompleted: number;
  requirementTotal: number;
  requirementCompleted: number;
  hasResult: boolean;
  canSubmitResult: boolean;
  canComplete: boolean;
  missingReasons: string[];
}

function getPlanCompletionState(plan: VersionPlan): PlanCompletionState;
function canTogglePlanChecklist(plan: VersionPlan, now?: Date): boolean;
function canEditPlanRequirementCoverage(plan: VersionPlan, now?: Date): boolean;

完成规则：

调研、产品方案、UI 设计都使用 tasks 作为子任务清单。
子任务必须全部勾选完成。
完成时必须提交成果，成果可以是链接或文件。
产品方案和 UI 设计如果有关联需求覆盖清单，也必须全部勾选覆盖完成。
右上角“直接完成”的勾选按钮取消。
PlanTab 和 PlanDetailDrawer 都只调用工作流引擎，不再各自写完成条件。

状态写入仍保持：

pending -> in_progress -> completed
actualStartAt 在开始时写入。
completedAt 只能通过提交成果完成时写入。

AI 拆解契约

AI 输出不直接返回数据库 categoryId，而是返回稳定语义码：

interface AgentDevTaskDraft {
  title: string;
  description?: string;
  categoryCode: string;
  priority: 'P0' | 'P1' | 'P2' | 'P3';
  estimateHours: number;
  references: AgentReference[];
}

interface AgentTestCaseDraft {
  title: string;
  description: string;
  categoryCode: string;
  priority: 'P0' | 'P1' | 'P2' | 'P3';
  references: AgentReference[];
}

映射规则：

优先按 TaskCategory.code 匹配。
匹配不到时按名称做宽松匹配。
仍匹配不到时，开发任务落到开发分组默认类型，测试用例落到测试分组默认类型。
映射失败不阻断 AI 报告展示，但确认写入前必须能得到 categoryId。

prompts/decompose.ts 的 tool schema 要求 devTaskDrafts 和 testCaseDrafts 都必须带 categoryCode。

UI 行为

计划卡片右上角不再显示直接完成的勾选按钮。
完成入口改为“提交成果”，按钮在条件不足时禁用并展示缺失原因。
完成弹窗保留链接/文件两种结果类型。
调研、产品方案、UI 设计新建/编辑时都展示关联需求选择，并支持全选。
测试用例新建弹窗增加任务类型选择。
AI 草案确认弹窗展示每条任务/用例的任务类型。

兼容与迁移

当前业务数据仍存于 PostgreSQL app_data JSONB。

新增字段时在 store fetch 阶段做轻量兼容补齐。
旧 TestCase 没有 categoryId 时补齐默认测试类型。
旧 TaskCategory 没有 code 时按系统预置映射补齐；自定义类型生成稳定 code。
不恢复业务 localStorage 缓存。

验证计划

实现时至少覆盖：

version-plan-workflow 单元测试：
- 子任务未完成不能完成。
- 未提交成果不能完成。
- 子任务完成 + 成果存在才可完成。
- 产品方案/UI 设计有关联需求覆盖时，未覆盖完不能完成。
任务类型映射测试：
- categoryCode 能映射系统类型。
- 未知 categoryCode 有合理 fallback。
- TestCase 旧数据能补齐类型。
AI schema 测试：
- devTaskDrafts 和 testCaseDrafts 都要求 categoryCode。
手工 UI 验证：
- 调研/产品/UI 关联需求全选可用。
- 候选需求只来自当前项目已采纳需求。
- 顶部直接完成按钮消失。
- 测试用例创建必须选择任务类型。

后续实现顺序

写规则引擎和选择器测试。
实现任务类型字典扩展和旧数据兼容。
给 TestCase 增加 categoryId。
接入 VersionPlan 工作流引擎。
接入需求选择器和全选 UI。
升级 AI schema、共享类型和草案写入映射。
跑类型检查和核心测试。

8.2 KiB Raw Blame History Unescape Escape