Jyotisha/docs/tasks/PROGRESS-staging-dispatch-autofill-sha-20260915.md

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。