# 规范驱动 + 接口先行（SDD + API-First）实战流程 Runbook（从 0 到可合并）

本文档用于复盘并固化一次完整的“从初始化规范体系 → 落地 Gitea 门禁 → 实际业务跑通（以 ai-robot 多渠道改造为例）”的全流程。

目标：换环境/换人/换模型后，可以按此 SOP 复现同样的协作链路，并在后续迭代中持续优化。

---

## 0. 核心原则（务必先读）

1. **SSOT（单一可信源）优先**：以 `spec/<module>/requirements.md` + OpenAPI 契约为准，任何实现必须可追溯到 AC。
2. **Consumer-first 并行**：依赖契约由调用方先写 `openapi.deps.yaml`，提供方后补实现并以 provider-driven 校验对齐。
3. **分支治理**：`main` 禁止直接 push，仅允许 PR 合并；feature 分支允许并行与草案（L0/L1）。
4. **门禁物理化**：规则必须进入 Actions/脚本，否则只停留在“口头约束”。
5. **长任务可接续**：满足阈值即启用 `docs/session-handoff-protocol.md`，并维护 `docs/progress/...`。

---

## 1. 仓库文档分层（最终形态）

- 方法论（详细、指导生成规范）：`docs/spec-product-zh.md`
- AI 入口硬规则（极简、命令式）：`agents.md`
- AI 契约硬规则（L0-L3、门禁、自检）：`spec/contracting.md`
- 人类落地指南（hooks/CI/操作细节）：`docs/contracting-guide.md`
- 会话接续协议（复杂任务强制）：`docs/session-handoff-protocol.md`
- Gitea Actions 门禁落地手册：`docs/setup-gitea-actions-gate.md`

---

## 2. Gitea（Docker）落地门禁：一次性 checklist

> 若是新环境，从这里开始。

### 2.1 分支保护（必须）

在 Gitea 仓库：`设置 -> 分支 -> 保护分支(main)`
- [ ] 禁止直接推送 main
- [ ] 禁止强制推送（force push）
- [ ] 禁止删除 main

> 经验：不要用 `pre-receive` 一刀切拒绝 `refs/heads/main`，否则 PR 合并也会被拒绝。

### 2.2 启用 Actions + Runner（必须）

- 在 Gitea `app.ini` 中启用：

```ini
[ACTIONS]
ENABLED = true
```

- 启动 runner（内网环境用宿主机内网 IP，不要用 127.0.0.1 / host.docker.internal）：

```bash
docker run -d --name gitea-act-runner --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /data/act_runner:/data \
  -e GITEA_INSTANCE_URL="http://<HOST_IP>:<GITEA_PORT>" \
  -e GITEA_RUNNER_REGISTRATION_TOKEN="<REG_TOKEN>" \
  -e GITEA_RUNNER_NAME="runner-1" \
  gitea/act_runner:latest
```

### 2.3 离线环境必做（避免访问 GitHub）

- workflow **不要**使用 `actions/checkout@v3`。
- 使用离线 checkout（仓库内 workflow 已实现）：
  - 优先 `GITHUB_*` 变量，fallback `GITEA_*` 变量
  - `git clone "$SERVER_URL/$REPO_NAME.git" .` + `git checkout "$COMMIT_SHA"`

### 2.4 Required Checks（必须）

- 首次运行 workflow 后，在保护分支启用状态检查。
- 推荐 job 名称：
  - 轻量门禁：`contract-level-check`
  - 全量门禁：`sdd-full-gate`

> 注意：Gitea 通常需要 **至少跑过一次 Actions** 才能在 UI 中选择/识别状态检查项。

---

## 3. 规范生成（文档阶段）SOP（强模型执行）

> 目标：把需求与契约先做对，再进入编码。

### 3.1 分支策略（文档与代码共存）

- 若“旧代码在 master，新规范在 main”，且历史不相关：
  - 推荐创建 feature 分支后合并：

```bash
git checkout master
git checkout -b feat/<feature>
git merge main --allow-unrelated-histories
```

- 若出现 untracked 覆盖：先提交 checkpoint（保护性提交）再 merge。

### 3.2 生成顺序（每次只生成 1 个文件）

严格按顺序：
1) `spec/<module>/requirements.md`
2) `spec/<module>/openapi.deps.yaml`
3) `spec/<module>/openapi.provider.yaml`
4) `spec/<module>/design.md`
5) `spec/<module>/tasks.md`

每生成 1 个文件：
- 人类审阅通过后，做 **spec-only commit**（只提交该文件）。

---

## 4. 编码执行（实现阶段）SOP（弱模型可执行）

> 目标：按 `tasks.md` 原子任务执行，降低长上下文导致的偏移。

### 4.1 进入编码前必须读取
- `agents.md`
- `spec/contracting.md`
- `spec/<module>/requirements.md`
- `spec/<module>/openapi.provider.yaml` / `openapi.deps.yaml`
- `spec/<module>/design.md`
- `spec/<module>/tasks.md`

### 4.2 提交节奏（Git Cadence）

- `spec/<module>/` 变更：必须单独 commit
- 实现代码：按 tasks 子任务完成提交
- commit message：必须包含 `[AC-...]`

### 4.3 多窗口并行（推荐分工）

- 窗口 A：基础设施 + DTO + 配置 + DB
- 窗口 B：渠道适配层（Adapter/Factory/Controller）
- 窗口 C：路由层 + 会话管理
- 窗口 D：AI client + Resilience + fallback
- 窗口 E：集成测试/回归

合并策略：各窗口在同一 feature 分支上串行提交（避免互相覆盖），或各自分支最后 rebase 合并。

### 4.4 契约与实现双向对齐（L2 升级两步走）

当实现接近完成，准备进入可合并状态时：
1. **第一步：描述型升级**。AI 仅修改 `openapi.provider.yaml` 将等级提升至 L2，补充代码已实现的约束（描述、示例、错误结构）。执行 spec-only commit。
2. **第二步：实现约束对齐**。AI 根据 L2 契约中的 `required`、`enum`、`format` 等硬约束，同步补齐代码中的 `@Valid` 校验注解、枚举处理及单测。

---

## 5. 最终集成与收网 SOP

### 5.1 契约与实现双向对齐（L2 升级两步走）

当实现接近完成，准备进入可合并状态时：
1. **第一步：描述型升级**。AI 仅修改 `openapi.provider.yaml` 将等级提升至 L2，补充代码已实现的约束（描述、示例、错误结构）。执行 spec-only commit。
2. **第二步：实现约束对齐**。AI 根据 L2 契约中的 `required`、`enum`、`format` 等硬约束，同步补齐代码中的 `@Valid` 校验注解、枚举处理及单测。

### 5.2 合拢动作

1. **本地汇总**：将所有并行窗口的分支/提交合并至主功能分支。
2. **一致性自检**：确认 `spec/` 文档与 `src/` 实现 100% 对齐（AC 追踪、契约等级、任务勾选）。
3. **推送 PR**：推送到远端并发起向 `main` 的 PR。
4. **门禁验收**：观察 `sdd-full-gate` 状态。
   - 若 `Commit Message Check` 失败：补充 `[AC-...]` 或 `[TASK-...]` 标注。
   - 若 `AC Traceability Check` 失败：修正需求引用或代码注释。
5. **合并合拢**：Checks 全绿后执行合并，并同步本地 `main` 分支。

---

## 6. 自动化门禁（Actions 脚本）说明

### 5.1 当前已落地的脚本

- OpenAPI 等级门禁：`scripts/check-openapi-level.sh`
- AC 追踪门禁：`scripts/check-traceability.sh`
- OpenAPI Breaking change（最小版）：`scripts/check-openapi-diff.sh`

### 5.2 常见报错与处理

- `provider contract-level must be >= L2`：提升 `openapi.provider.yaml` 到 L2
- `No module named yaml`：workflow 会尝试安装 PyYAML，失败则跳过 YAML parse check
- `Cannot ping Gitea instance`：runner URL 不可用，换宿主机内网 IP
- `cloning https://github.com/actions/checkout`：workflow 仍在用 checkout action，需改离线 checkout

---

## 7. 需求迭代与生命周期管理 SOP

> 目标：确保功能演进过程中，规范文档同步滚动且历史可追溯。

### 7.1 迭代模式选择
- **微调模式**：直接在现有 `requirements.md` 追加 AC，ID 保持连续（如 `AC-AISVC-21`）。
- **特性模式**：在 `spec/<module>/` 下新增 `requirements-<feature>.md`，适用于独立大特性。
- **重构模式**：建立新模块目录（如 `spec/ai-service-v2/`），适用于架构级变更。

### 7.2 迭代执行步骤
1. **增量 Scoping**：分析新需求对现有 AC 的影响，明确是否涉及破坏性变更。
2. **版本滚动**：修改任一规范文件时，必须同步更新 Frontmatter 中的 `version`（如 `0.1.0 -> 0.2.0`）。
3. **任务追加**：新任务作为 `tasks.md` 的新 Phase（如 `Phase 6`），严禁删除已完成任务的历史。
4. **契约先行**：若涉及接口变动，必须先更新 `openapi.provider.yaml` 到 L0/L1，再写实现代码。

---

## 8. 维护与迭代建议

- 每次重大变更后更新：
  - `docs/setup-gitea-actions-gate.md`
  - 本文档（Runbook）
- 逐步增强门禁：OpenAPI 专业 diff、契约测试（schema 校验）、最小自测强制化（runner 预装 Maven/JDK）