用 Commit 把需求、缺陷与交付证据串起来

提交信息既服务开发者，也服务自动化追踪。只有“修复问题”“更新代码”这类标题，无法回答改动对应哪个需求、为什么进入该版本、回滚时应关注什么。一个实用方案是把语义化标题与工作项脚注结合。

标题描述改动，脚注描述关系

标题使用“类型(范围): 中文摘要”，例如“fix(order): 修复重复提交时的幂等判断”。需求使用 Refs 关联，缺陷使用 Fixes 关联。工作项号放在独立脚注，不塞进标题，使日志浏览和机器解析都更稳定。示例编号应使用团队工作项，不在公开仓库写入客户信息。

类型缺失、标题为空、格式无法解析属于错误，应阻断提交；需求提交未写 Refs 或修复提交未写 Fixes 可以先警告，因为并非所有文档或维护提交都有工作项。硬规则太多会诱导团队绕过检查，软规则则用于提高覆盖率。

如果分支命名已经携带工作项号，提交钩子可以自动追加脚注。前提是解析规则严格、无法确定时静默不写、用户手工填写时绝不覆盖。自动化的目标是减少重复输入，而不是替用户猜关联。

工作项进入开发后生成分支计划；每个提交通过脚注关联工作项；CI 把提交、测试报告和产物版本写入交付记录；PR 合入后回读真实合入提交；发布系统再记录部署版本。最终可以从一个 Bug 追到修复提交、测试证据、合入记录和发布版本。

定期检查可解析提交比例、有效工作项关联率、错误关联数和绕过钩子次数。追溯链的价值不在格式整齐，而在事故发生时能快速回答“哪些版本包含这项改动，以及证据在哪里”。

可复用交付物： 提交格式、工作项脚注和交付追溯链。这些内容是从工程实践抽象出的通用方法，不包含内部仓库、真实工作项、业务数据、凭据、地址或实现源码。

最低验收： 从工作项可追到提交、测试、PR 合入提交和发布版本，且不存在错误关联。验收记录必须分开事实、推断、缺口和授权范围；只读检查不能自动扩展为提交、推送、评论或发布。

fix(order): 修复退款重复提交

数据库唯一约束作为最终幂等边界，API 对相同键返回原结果。

Refs: REQ-118
Fixes: BUG-241
Tested-by: ci/refund-contract/8471
Risk: database-index

Git trailer 使用稳定键名并允许重复值。Fixes 是否自动关闭工作项由平台策略决定；如果仅表示关联而非关闭，使用 Refs，避免合入到错误分支后提前关闭缺陷。

提交钩子只做快速语法检查，服务端 CI 再验证工作项是否存在、类型与关系是否合理。客户端钩子可被绕过，不能成为唯一门禁。自动追加 trailer 的脚本先解析现有 trailer：人工值存在就保留，分支中出现多个候选 ID 就拒绝推断。

1	git interpret-trailers --parse < commit-message.txt

合并策略会改变 SHA：squash 或 rebase 后，应以平台返回的真实合入提交建立关系，不能继续把本地提交当作发布主键。回滚也要产生新的提交与发布记录，并指向被回退的 release；不要重写已经共享的历史来“修正”关联。

每月随机抽取已发布需求，反向走一遍“生产实例 → 制品 → 合入提交 → 工作项 → 测试证据”。记录断链位置和错误关联，而不只统计格式合规率。任何自动修复历史关系的任务先输出 dry-run 差异，避免批量关闭工作项或写错发布记录。

规范复核日期：2026-08-22。

用测试分支验证标题校验、自动脚注、人工脚注优先和无法推断四条路径，再接入真实仓库。