后端 API Changelog 推送说明

接口发生新增、修改或删除时，在 hl-api-changelog 仓库提交一份 changelog。

1. 放在哪里

管理后台：changelogs-v2/YYYY-MM/
小程序：changelogs-v2-mp/YYYY-MM/

文件名：

DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md

例如：

changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md

日期使用提交时的上海日期；不要把“前端待处理”“已完成”等状态写进文件名。

2. 写什么

可以复制仓库根目录的 CHANGELOG_TEMPLATE.md，至少写清：

关联的 Issue 和后端 PR；
接口路径和 HTTP 方法；
新增、修改或删除的请求/响应字段；
字段必填性、枚举、状态、空值、金额和兼容规则；
前端需要做什么；
后端测试、部署和网关验证结果。

元数据中：

backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""

需要前端修改：frontend_status: "pending"
不需要前端修改：frontend_status: "not_required"
后端不要代替前端填写 implemented、released 或 verified

3. 校验

在 hl-api-changelog 仓库执行：

npm test
npm run check:filenames -- --base origin/main --head HEAD
npm run check:frontmatter -- --base origin/main --head HEAD

确保正文没有 TODO、待补充 或模板占位符。

4. 提交和推送

只暂存本次 changelog 文件，直接 commit main（不建分支/PR）：

git status --short
git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
git diff --cached --check
git commit -m "docs: hand off API contract (#5205)"
git push origin main

不要提交其他任务的 changelog、.tmp-* 文件或任何凭据。

5. author 字段（必填）

所有 changelog frontmatter 必须包含 author 字段，格式为推送者登录名 + (GIT) 后缀：

author: "wx(GIT)"   # wx 推送写 wx(GIT)；yst 推送写 yst(GIT)；以此类推

谁 push 到 main 就写谁，多会话并行时用于追溯该条 changelog 的推送人。新写文件必须带；修改旧文件时顺手补上。

2.3 KiB 原始文件 Blame 文件历史 Unescape Escape