# 环节钩子（Hooks）设计

## 一、目标

Hooks 用于在特定环节触发特定行为，常见用途：

- 环节离开时做强校验（阻止流程跳转）
- 自动生成/更新辅助产物（如 PlantUML PNG）
- 给出必要提醒（如进入 docs 提示更新 CHANGELOG）

## 二、触发点与顺序（必须统一）

### 2.1 触发点

Hooks 只在以下场景触发：

- `start`：视为“进入某个 phase”
- `next-part` / `back-part`：同时发生“离开旧 phase”与“进入新 phase”

`next-step/back-step/issue/error` 默认不触发 phase hooks（除非后续明确新增需求）。

### 2.2 顺序（影响提交内容）

为保证“生成物进入同一次提交”，推荐顺序：

1. **流程校验**（见 `validation.md`）
2. **离开旧 phase 的 pre-commit hooks**（可能生成/修改文件，失败则阻止跳转）
3. **Git add/commit**（见 `git.md`）
4. **写入状态文件**（包含本次 `git_commit`）
5. **进入新 phase 的 post-commit hooks**（提醒类/信息类为主）

> 若团队选择“先落盘再提交”，必须重新评估：失败边界、生成物提交时机、以及 `git_commit` 的写入方式。

## 三、Hook 接口约定（伪代码原型）

```
HookContext:
    root: Path
    phases: list[str]
    from_phase: str | None
    to_phase: str
    action: str                  # start/next-part/back-part
    summary: str

HookResult:
    ok: bool
    level: "info" | "warn" | "error"
    message: str
```

约定：

- pre-commit hook 失败（ok=false 且 level=error）必须阻止流程跳转
- warn/info 只允许在“需要用户可见”时输出，且保持简短

## 四、内置 Hooks 规格

### 4.1 离开 flow-design：PlantUML 校验与 PNG 生成（pre-commit）

**触发**：

- `next-part` 且 `from_phase == "flow-design"`

**目标**：

- 校验 PlantUML 语法
- 生成 PNG（若配置启用）

**输入约定（建议可配置）**：

| 配置项（建议） | 默认值（建议） | 说明 |
|---|---|---|
| `flow.hooks.plantuml.enabled` | true | 是否启用该 hook |
| `flow.hooks.plantuml.glob` | `docs/**/*.puml;docs/**/*.plantuml;discuss/**/*.puml;discuss/**/*.plantuml` | 待处理文件范围（分号分隔或列表） |
| `flow.hooks.plantuml.on_missing_tool` | `"warn"` | 未安装 plantuml 的处理：warn/error |
| `flow.hooks.plantuml.generate_png` | true | 是否生成 PNG |

**行为约定**：

- 若未匹配到任何 PlantUML 文件：静默通过
- 若 plantuml 工具缺失：
  - `on_missing_tool=warn`：输出一次 `⚠` 提示并通过
  - `on_missing_tool=error`：失败并阻止跳转
- 若语法校验失败：失败并阻止跳转（输出指出具体文件）

### 4.2 进入 docs：提醒更新 CHANGELOG（post-commit）

**触发**：

- `next-part` 且 `to_phase == "docs"`

**行为约定**：

- 输出一次 `→ 请更新 CHANGELOG.md`（保持一句话）
- 不影响状态推进与提交

### 4.3 离开 docs：校验 CHANGELOG 已更新（pre-commit）

**触发**：

- `next-part` 且 `from_phase == "docs"`

**校验目标**：

- 确保在 docs 阶段，至少有一次提交包含 `CHANGELOG.md` 的改动

**推荐实现判定（不引入额外状态字段）**：

1. 从状态历史中找出 `phase == "docs"` 且 `git_commit` 非空的条目集合
2. 遍历这些提交，判断是否有任意一次提交包含 `CHANGELOG.md`

**降级处理**：

- 若 Git 集成未启用/不可用：至少校验 `CHANGELOG.md` 文件存在，否则失败或警告（建议可配置）

**配置项（建议）**：

| 配置项（建议） | 默认值（建议） | 说明 |
|---|---|---|
| `flow.hooks.changelog.path` | `CHANGELOG.md` | changelog 路径 |
| `flow.hooks.changelog.required` | true | 离开 docs 时是否硬失败 |

## 五、Hook 失败的对外表现

- 校验类 hook 失败：输出 `✗` + 简短原因 + 下一步建议（例如“请先修复 PlantUML 语法”）
- 返回退出码 1
- 不推进环节，不产生提交（保持原子性）