# PROGRESS · Migrate Staging Database 不必手填 SHA（2026-09-15）

工作树：`.worktrees/staging-dispatch-autofill-sha-20260915`  
分支：`codex/staging-dispatch-autofill-sha-20260915`  
任务书基线：`origin/staging` @ `de47c06d`（任务书本身；代码基线 `ebd6175b`）  
本机 Windows。

未开 BUG 号（任务书规定）。未改 `CHANGELOG.md`。未改 `deploy-production.yml` / `migrate-production-database.yml` / `backend-quality-gate.yml`。`concurrency.group: staging-mutation` 未动。第一步之后的步骤一行未改。

## 任务状态

| 任务 | 状态 | 说明 |
| --- | --- | --- |
| 1 `migrate-staging-database.yml` SHA 可选 | 完成 | `required: false`；空或 `latest` 解析最新成功门禁 SHA，再走原格式/门禁/head 校验 |
| 2 `deploy-staging.yml` | **不做** | 见下 |
| 3 文档 | 完成 | `deploy/README.md`、本文件、状态板 |

## 任务 2 结论

**不做。** `Deploy staging` 在门禁通过后会被自动 dispatch，并带上 `deploy_sha` 与 `gate_run_id`。手动表单只在重跑或回滚时用，而回滚必须手填 SHA 并勾选 `allow_rollback`。自动解析永远给出最新修订，帮不上回滚。改它还要动更复杂的 rollback 分支与合同测试，收益低。`allow_rollback` 保持 required。

## 实现要点

只改了 `workflow_dispatch.inputs` 和第一步开头的解析。后面步骤仍读 `steps.revision.outputs.sha` / `gate_run_id` / `head_check`，语义不变。

- 非空且不是 `latest`：完全走原逻辑（格式 → 精确 SHA 门禁查找 → head 比对）。
- 空或 `latest`：查 `actions/runs?branch=staging&event=push&status=success&limit=100`，同一套 jq 过滤，取 `id` 最大的 `head_sha`，打印 `resolved deploy_sha=<sha> (latest gated staging commit)`，然后继续原校验（再查一遍精确 SHA 门禁）。
- 解析失败：硬失败。没有成功门禁运行时：「staging 上还没有任何通过门禁的提交，先等门禁跑完再迁移」。API 失败：「查不到 staging 的门禁运行记录，Gitea API 请求失败」。**不会**退回 staging head。

`latest` 三个字母是任务书让步 1：若 Gitea 这个版本把留空做成缺省失败而不是空串，可以填 `latest` 代替 40 位。留空是主路径。

## 既有断言改动

| 文件 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| `staging-backend-workflows.test.ts` 新增一条 | 无 | 锁 `required: false`、自动解析、人话失败、手填路径仍做 40 位与精确 SHA 门禁；生产两个 workflow 仍 `required: true` | 本单合同。未弱化既有断言 |

## 验证

| 命令 | 结果 |
| --- | --- |
| `python -c "import yaml; yaml.safe_load(...)"` | **yaml-ok** |
| `npx tsx --test tests/staging-backend-workflows.test.ts` | **43 / 37 pass / 6 fail**。本单新增「manual staging migration can leave deploy_sha empty…」**通过**。失败 6 条为既有 Windows 缺口（`python3` 退出码 9009、bash/rsync 脚本），与本单无关。 |
| 手填路径源码 | 原 `^[0-9a-f]{40}$`、精确 SHA 门禁查找、`head_check=deferred` 仍在解析之后 |
| 生产两个按钮 | 仍 `required: true` |

真人：推 staging 后在 Gitea 打开 `Migrate Staging Database`，确认按钮还在、表单能开、SHA 可留空。见任务书 §9。