121 lines
3.2 KiB
Markdown
121 lines
3.2 KiB
Markdown
# 流程校验规则（FlowValidator）
|
||
|
||
## 一、设计目标
|
||
|
||
流程校验的目标是：
|
||
|
||
- 防止“跳过环节”造成关键步骤遗漏
|
||
- 允许受控回退（返工有记录）
|
||
- 支持通过配置 `flow.phases` 调整环节名称与顺序
|
||
|
||
## 二、环节来源与基础约束
|
||
|
||
### 2.1 phases 来源
|
||
|
||
`phases` 必须来自配置 `flow.phases`（见 `aide-program/docs/formats/config.md`）。
|
||
|
||
### 2.2 基础约束
|
||
|
||
- phases 列表不能为空
|
||
- phases 中的环节名必须唯一
|
||
- 当前状态 `current_phase` 必须属于 phases
|
||
|
||
当以上条件不满足时，返回错误并提示用户修正配置或重新 start。
|
||
|
||
## 三、动作级校验
|
||
|
||
### 3.1 start 校验
|
||
|
||
允许：
|
||
|
||
- `start <phase>`：`phase` ∈ phases
|
||
|
||
建议额外约束（可选，但需在实现前确认）：
|
||
|
||
- 若 phase 不是 phases[0]，输出 `⚠` 提醒“从中间环节开始”
|
||
|
||
### 3.2 next-step / back-step / issue / error
|
||
|
||
前置条件：
|
||
|
||
- 状态文件存在（已 start）
|
||
- `current_phase` 合法
|
||
|
||
行为：
|
||
|
||
- 不改变 phase（phase 保持 current_phase）
|
||
- 仅记录一次历史
|
||
|
||
### 3.3 next-part 校验
|
||
|
||
前置条件：
|
||
|
||
- 状态文件存在（已 start）
|
||
- `to_phase` ∈ phases
|
||
|
||
允许：
|
||
|
||
- `to_phase` 必须等于 phases 中 `current_phase` 的**相邻下一项**
|
||
|
||
禁止：
|
||
|
||
- 跳跃（例如 `flow-design → verify`）
|
||
- 原地（例如 `impl → impl`）
|
||
|
||
### 3.4 back-part 校验
|
||
|
||
前置条件：
|
||
|
||
- 状态文件存在（已 start）
|
||
- `to_phase` ∈ phases
|
||
|
||
允许：
|
||
|
||
- `to_phase` 必须位于 `current_phase` 之前（可回退到任意之前环节）
|
||
|
||
禁止：
|
||
|
||
- 前进（例如 `flow-design → impl` 使用 back-part）
|
||
- 原地（例如 `verify → verify`）
|
||
|
||
## 四、默认 phases 的状态机（示例）
|
||
|
||
当 `flow.phases = ["task-optimize","flow-design","impl","verify","docs","finish"]` 时，推荐状态机如下：
|
||
|
||
```plantuml
|
||
@startuml
|
||
skinparam defaultFontName "PingFang SC"
|
||
|
||
[*] --> task_optimize : start(task-optimize)\n或 start(flow-design)
|
||
|
||
task_optimize --> flow_design : next-part(flow-design)
|
||
flow_design --> impl : next-part(impl)
|
||
impl --> verify : next-part(verify)
|
||
verify --> docs : next-part(docs)
|
||
docs --> finish : next-part(finish)
|
||
|
||
flow_design --> task_optimize : back-part(task-optimize)
|
||
impl --> flow_design : back-part(flow-design)
|
||
verify --> impl : back-part(impl)
|
||
docs --> verify : back-part(verify)
|
||
finish --> docs : back-part(docs)
|
||
|
||
task_optimize --> task_optimize : next-step/back-step/issue/error
|
||
flow_design --> flow_design : next-step/back-step/issue/error
|
||
impl --> impl : next-step/back-step/issue/error
|
||
verify --> verify : next-step/back-step/issue/error
|
||
docs --> docs : next-step/back-step/issue/error
|
||
finish --> finish : next-step/back-step/issue/error
|
||
|
||
@enduml
|
||
```
|
||
|
||
> 注：示例图允许从 `flow-design` start，以兼容“跳过 prep 直接 exec”的场景；是否默认允许由实现选择，但必须在行为与提示上保持一致。
|
||
|
||
## 五、与 Hooks 的关系
|
||
|
||
部分校验属于“流程校验”，部分属于“环节特定校验”（Hooks）：
|
||
|
||
- 流程校验：只关心 phases 顺序与动作合法性（本文件）
|
||
- 环节特定校验：如离开 `flow-design` 时 PlantUML 校验、离开 `docs` 时 CHANGELOG 校验（见 `hooks.md`）
|