Sync: add workflow registry and review notes
This commit is contained in:
39
wiki/concepts/Handoff-Contract.md
Normal file
39
wiki/concepts/Handoff-Contract.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: "Handoff Contract"
|
||||
type: concept
|
||||
tags: [workflow, system-integration, contract, reliability]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
交接合同——两个系统、服务或 Agent 之间每次交接时必须明确定义的接口规范，确保交接的每个环节都有明确的成功/失败/超时约定，防止隐式假设导致级联故障。
|
||||
|
||||
## Contract Elements（合同要素）
|
||||
|
||||
```
|
||||
HANDOFF: [From] -> [To]
|
||||
PAYLOAD: { field: type, field: type, ... }
|
||||
SUCCESS: { field: type, ... }
|
||||
FAILURE: { error: string, code: string, retryable: bool }
|
||||
TIMEOUT: Xs — treated as FAILURE
|
||||
ON FAILURE: [recovery action]
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `PAYLOAD` | 交接时传递的数据结构，必须包含类型注解 |
|
||||
| `SUCCESS` | 成功时的返回数据结构 |
|
||||
| `FAILURE` | 失败时的标准错误格式（含错误码和可重试标识）|
|
||||
| `TIMEOUT` | 超时阈值，超时视为失败 |
|
||||
| `ON FAILURE` | 失败后的恢复动作（重试、清理、escalation）|
|
||||
|
||||
## Why It Matters
|
||||
没有显式交接合同的工作流边界是最常见的故障来源：
|
||||
- 服务 A 假设服务 B 总是返回某个字段，但 B 偶尔不返回 → 静默故障
|
||||
- 超时值未约定，一方认为 5s 合理，另一方认为 30s 才够 → 不匹配
|
||||
- 失败后未约定恢复动作，部分场景重试有效，部分场景重试造成数据重复
|
||||
|
||||
## Source
|
||||
- [[specialized-workflow-architect]]（Workflow Architect Agent）
|
||||
30
wiki/concepts/Observable-States.md
Normal file
30
wiki/concepts/Observable-States.md
Normal file
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: "Observable States"
|
||||
type: concept
|
||||
tags: [workflow, observability, system-modeling]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
可观察状态——每个工作流状态（快乐路径中的每一步 + 每个失败模式）必须同时从四个视角描述系统当前状态，确保客户、运维、数据库和日志各方都能准确感知系统发生了什么。
|
||||
|
||||
## Four Dimensions（四维度）
|
||||
|
||||
| 维度 | 描述 | 示例 |
|
||||
|------|------|------|
|
||||
| **Customer View** | 当前客户在 UI 上看到什么 | 加载中 / "处理中..." / 空白 / 错误提示 |
|
||||
| **Operator View** | 运维/管理员在管理面板看到什么 | 实体处于"处理中"状态 / 任务步骤显示 "step_3_running" |
|
||||
| **Database View** | 数据库中数据当前状态 | `job.status = "running"`, `job.current_step = "step_1"` |
|
||||
| **Log View** | 系统日志当前记录了什么 | `[order-service] step 1 started entity_id=abc123` |
|
||||
|
||||
## Why Four Dimensions?
|
||||
单一视角不足以支撑调试和运维：
|
||||
- **只有 Customer View**：运维无法知道后台发生了什么
|
||||
- **只有 Database View**：客户不知道自己看到了什么
|
||||
- **只有 Log View**：没有结构化数据支撑告警和审计
|
||||
- **只有 Operator View**：缺乏原始数据记录
|
||||
|
||||
四个维度必须同步更新、互相印证，构成完整的可观测性闭环。
|
||||
|
||||
## Source
|
||||
- [[specialized-workflow-architect]]（Workflow Architect Agent）
|
||||
44
wiki/concepts/Workflow-Registry.md
Normal file
44
wiki/concepts/Workflow-Registry.md
Normal file
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: "Workflow Registry"
|
||||
type: concept
|
||||
tags: [workflow, documentation, system-modeling]
|
||||
last_updated: 2026-04-25
|
||||
---
|
||||
|
||||
## Definition
|
||||
工作流注册表——系统所有工作流的权威参考指南，以四个交叉索引视角组织，确保任何角色（工程师、运维、产品负责人、AI Agent）都能从任意角度快速查找所需工作流。
|
||||
|
||||
## Four Views（四视角）
|
||||
|
||||
### View 1: By Workflow（按工作流，主列表）
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| Workflow | 工作流名称 |
|
||||
| Spec file | 规范文件名 |
|
||||
| Status | Approved / Review / Draft / **Missing** / Deprecated |
|
||||
| Trigger | 触发条件 |
|
||||
| Primary actor | 主要执行者 |
|
||||
| Last reviewed | 最近审查日期 |
|
||||
|
||||
> **Missing** = 代码中存在但无规范，红色警报，立即暴露。
|
||||
|
||||
### View 2: By Component（按组件）
|
||||
每个代码组件映射到其参与的所有工作流。工程师查看任意文件时，可立即知道哪些工作流涉及该文件。
|
||||
|
||||
### View 3: By User Journey（按用户旅程）
|
||||
每条用户旅程映射到其背后的底层工作流，含客户旅程/运营旅程/系统间旅程。
|
||||
|
||||
### View 4: By State（按状态）
|
||||
每个实体状态映射到能转入或转出的工作流。
|
||||
|
||||
## Maintenance Rules
|
||||
- 每发现或规范一个新工作流必须更新注册表（强制）
|
||||
- Missing 状态的工作流视为红色警报，需在下一轮审查中处理
|
||||
- 四个视角必须交叉引用一致
|
||||
- Draft 升为 Approved 时必须同步更新注册表
|
||||
- 永不删除行——使用 Deprecated 而非删除以保留历史
|
||||
|
||||
## Related
|
||||
- [[Workflow-Tree-Spec]]（规范格式）
|
||||
- [[Discovery-Audit]]（发现隐式工作流的方法）
|
||||
- [[Observable-States]]（每个工作流状态的可见性）
|
||||
45
wiki/concepts/Workflow-Tree-Spec.md
Normal file
45
wiki/concepts/Workflow-Tree-Spec.md
Normal file
@@ -0,0 +1,45 @@
|
||||
---
|
||||
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）
|
||||
Reference in New Issue
Block a user