46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
---
|
||
title: "Workflow Tree Spec"
|
||
type: concept
|
||
tags: [workflow, specification, documentation, quality-assurance]
|
||
last_updated: 2026-04-25
|
||
---
|
||
|
||
## Definition
|
||
工作流树规范格式——为每个工作流生成的结构化规范文档，工程师可直接依据实现，QA 可直接导出测试用例，运维可理解系统行为，产品负责人可验证需求是否满足。
|
||
|
||
## Required Sections（必须章节）
|
||
|
||
1. **Overview**：2-3 句话描述工作流目标、触发者和产出
|
||
2. **Actors**：参与此工作流的所有角色（人/系统/Agent）
|
||
3. **Prerequisites**：工作流启动前必须满足的条件
|
||
4. **Trigger**：触发来源（用户操作/API调用/定时任务/事件）
|
||
5. **Workflow Tree**：每步的 Actor/Action/Timeout/Input/Output on SUCCESS/Output on FAILURE + Observable States
|
||
6. **ABORT_CLEANUP**：失败清理流程（含触发条件、清理动作顺序、客户视图、运维视图）
|
||
7. **State Transitions**：状态机转换图
|
||
8. **Handoff Contracts**：每个系统边界的交接合同
|
||
9. **Cleanup Inventory**：工作流创建的所有资源及其销毁方法
|
||
10. **Reality Checker Findings**：规范与代码对照验证结果
|
||
11. **Test Cases**：每个分支对应一个测试用例
|
||
12. **Assumptions**：所有未经代码验证的假设
|
||
13. **Open Questions**：待确认事项
|
||
|
||
## Branch Coverage（分支覆盖要求）
|
||
每个工作流规范必须覆盖 **7 类分支**：
|
||
1. 快乐路径（所有步骤成功，所有输入有效）
|
||
2. 输入验证失败（具体错误信息 + 客户看到什么）
|
||
3. 超时失败（每个步骤的超时值 + 超时后行为）
|
||
4. 瞬态失败（网络抖动/限流，可重试并退避）
|
||
5. 永久失败（无效输入/配额超限，立即失败并清理）
|
||
6. 部分失败（步骤7/12失败，已创建资源必须销毁）
|
||
7. 并发冲突（同一资源同时被创建/修改）
|
||
|
||
## Status Lifecycle
|
||
```
|
||
Draft → Review → Approved
|
||
↑
|
||
Reality Checker 验证（必须，不可跳过）
|
||
```
|
||
|
||
## Source
|
||
- [[specialized-workflow-architect]]（Workflow Architect Agent）
|