# Gitea（Docker）落地：分支保护 + Actions/Runner + OpenAPI 全量门禁（操作手册）

本文档用于在**新环境/新机器**上从零落地本仓库的“规范驱动 + 接口先行”门禁体系，确保换环境后无需重新摸索。

---

## 0. 目标与产物

落地后应满足：
- [ ] `main` 禁止直接 push，仅允许 PR 合并
- [ ] PR 合并到 `main` 时自动运行 Actions（全量门禁）
- [ ] 环境无法访问 GitHub 时也能正常运行校验

仓库内相关文件（必须存在于 `main`）：
- `agents.md`：AI 编码总纲
- `spec/contracting.md`：契约标准
- `scripts/*.sh`：核心校验脚本（Level/Traceability/Diff）
- `.gitea/workflows/pr-check.yaml`：全量门禁工作流

---

## 1. Gitea Actions 基础建设

按照 `docs/setup-gitea-actions-gate.md` 中的步骤完成：
1.  **Gitea 配置**：在 `app.ini` 中启用 `[ACTIONS] ENABLED = true`。
2.  **Runner 部署**：启动 `gitea/act_runner:latest` 容器并成功注册到 Gitea。
3.  **内网连接**：使用宿主机内网 IP 作为 `GITEA_INSTANCE_URL`。

---

## 2. 启用全量自动化门禁

### 2.1 门禁项列表

当前的 `.gitea/workflows/pr-check.yaml` (Job ID: `sdd-full-gate`) 包含以下检查：

| 门禁项 | 脚本位置 | 检查逻辑 | 失败处理 |
| :--- | :--- | :--- | :--- |
| **1. 契约成熟度** | `check-openapi-level.sh` | 校验 `info.x-contract-level`。合并 main 必须 ≥ L2。 | AI 需更新 OpenAPI 文件等级。 |
| **2. 需求追踪** | `check-traceability.sh` | 校验代码中的 `[AC-ID]` 是否在 `requirements.md` 中定义过。 | AI 需补充需求文档或修正代码注释。 |
| **3. Breaking Change** | `check-openapi-diff.sh` | 对比 `main` 分支，拦截被删除的 Endpoint 或 Method。 | AI 需还原破坏性变更或与人类确认。 |
| **4. 最小自测** | 内置命令 | 执行 `mvn test`（Java）。若 Runner 环境无 mvn 则跳过并提示。 | AI 需修复单测或编译错误。 |

### 2.2 在 Gitea 中开启硬约束

1.  **触发第一次运行**：新建一个 PR 到 `main`（修改 `src/` 或 `spec/` 下的文件）。
2.  **配置分支保护**：
    *   进入 `仓库设置 -> 分支 -> 保护分支(main)`。
    *   勾选 **“启用状态检查”**。
    *   在输入框中填入：`sdd-full-gate`。
    *   保存。

---

## 3. 常见排障与优化

### 3.1 离线环境报错
如果报错 `GITEA_SERVER_URL is required`，请确认已合并最新的 `.gitea/workflows/pr-check.yaml`。当前版本已支持自动探测 `GITHUB_` 与 `GITEA_` 系列变量。

### 3.2 Maven (mvn) 找不到
如果日志提示 `Warning: mvn not found`，说明你的 Runner 镜像（ubuntu-latest）没有预装 Maven。
*   **短期**：脚本会自动跳过，不阻断合并。
*   **长期建议**：定制 Docker 镜像或在宿主机安装 Maven 并卷入容器。

### 3.3 Python yaml 模块缺失
脚本会自动尝试 `pip install pyyaml`。如果依然失败，YAML 语法解析步骤将自动跳过，不影响核心契约校验。

---

## 4. 关联文档入口

- `agents.md`：AI 实时遵循的提交与编码节奏。
- `docs/contracting-guide.md`：契约治理与 Gitea 避坑指南。
- `docs/session-handoff-protocol.md`：复杂任务接续协议。