后端 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

2.5 写作方法论（对齐 yst 团队 changelog-conventions SKILL，2026-08-04 起执行）

受众优先：触达 /admin/* /mp/* /v3/admin/* /v3/mp/* 等对外前缀的改动一律写前端 changelog，哪怕"前端代码零改动"（前端 AI 可能有 workaround 需清理信号）。/v3/internal/* Feign 接口必须拆出去单独走后端 changelog，不许和 admin/mp 接口塞同一份（反例：# traveler 11 接口事故）。

自包含：禁止"详见 Knife4j / Swagger / 同目录 xx.md"。所有请求参数表、响应字段表、枚举值（值+中文+说明）、错误码、完整 JSON 示例必须内联——消费方 AI 没有内部文档权限。

消费方语言：写"下拉框去掉草稿选项"，不写"status 字段 ApiModelProperty 注解更新"；值变了用 原来 → 现在 表格，不写散文。

示例要求：每个接口至少 1 组「典型成功」示例（请求+响应完整 JSON）；修改类接口建议补「边界」「异常」共 3 组。GET 示例也要写全 URL + Authorization 头 + 注明"无请求体"。

不写后端实现：禁止出现 DB 表/字段名、雪花 ID 序列化细节、Nacos 配置拼接、端口/重启/回滚耗时等后端实现与运维内容（后端运维信息写后端 changelog）。"任何一行拿掉后接口契约仍成立，就该删"。

emoji 分类（标题用）：⚠️ 破坏性变更 / ✨ 新增 / 🔧 行为变更 / 📝 仅文档。

commit message 用中文：新增退款政策字段（产品详情接口），不用英文。

多接口 changelog（≥3 接口）：按接口分小节，每个接口自含「使用场景/入参/出参/错误码/业务边界/示例」，不把多接口入参混到一张大表。

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 的推送人。新写文件必须带；修改旧文件时顺手补上。

联系人章节（模仿 yst 格式，2026-08-04 wx 定）：除 frontmatter author 字段外，正文末尾"关联 / 联系人"章节必须标注后端负责人，格式与 yst 的 changelog 一致：

## 关联 / 联系人

### 联系人

- **后端负责人**: @wx

与 frontmatter author 字段同源：wx 负责写 @wx，yst 负责写 @yst。不要在正文开头加"作者"行（已废弃）。模板已含此章节（见 CHANGELOG_TEMPLATE.md）。修改他人 changelog 时不要改联系人。

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