API Changelog Bot和Claude Opus 5
047a4be4fd
2026-09-21 wx 第二次点名：「不要在changelog里写让前端等待部署 这不是你第一回犯错了 工作流是你部署完测试环境推送changelog」。 §2.1 的 backend_status 门禁挡得住预告式推送，挡不住这一类：20_7443 的 frontmatter 已经是 deployed、CI 全绿，但正文 status_note 结尾写着「该缺陷已在修……修好后另发 交接件」。mmg 因此一直没动工，隔天才来问「这个是有啥问题吗 还是没做到呢」——门禁 只看 frontmatter，看不见自由文本里的这句话，所以「deployed + 校验绿」并不代表这份 交接件可执行。消费方也没有能力消解这种不确定性：他查不了我们的部署状态、看不到 dev-v3、不知道「另发」是哪天，读到「等」就只能等，而且是静默地等。 - scripts/validate-changelog-frontmatter.mjs：新增 validateNoWaitLanguage，对所有 v2 文档逐行扫描（与 change_type 无关，前端条目同样适用）。三类措辞：部署状态对冲、 未来交付承诺、直接叫停对接；「等待」做共现判定而非裸词匹配，避免把「前端需轮询 等待支付回调」这类业务语义一起拦掉。前向引用（「以后续订正为准」「见后续订正」） 一并封住——它和「修好后另发」是同一件事换个说法，实测被绕过一次。 - tests：4 个用例，含 1 个阴性对照（灰度开关状态、已知缺口工单号、业务流程里的等待 必须放行），防止作者为了过门禁把该写的契约边界一起删掉。 - BACKEND_CHANGELOG_DELIVERY_GUIDE.md §2.1：写明规则、背景与那条分界线——这条影响 他「怎么写代码」，还是只影响他「什么时候开始写」？后者一律删。 阳性对照：对已推送的 HEAD 版 20_7443 跑新规则，命中 2 处（第 308、451 行「修好后另发」）， 即它能抓住真实发生过的那次。既有 changelog-path-aliases 测试对 11_7510 的 2 条 E_ALIAS_STATE 红是本次改动之前就存在的，与本提交无关，pre-push 钩子也不跑该用例。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
10 KiB
后端 API Changelog 推送说明
接口发生新增、修改或删除时，在 hl-api-changelog 仓库提交一份 changelog。
1. 放在哪里
- 管理后台：
changelogs-v2/YYYY-MM/ - 小程序：
changelogs-v2-mp/YYYY-MM/
文件名：
DD_issue_业务标题-{新增接口|修改接口|删除接口|修复|前端缺陷|前端优化|前端修复}-{管理后台|小程序端}.md
纯前端条目（无后端工单）issue 段写字面量 frontend，如 10_frontend_标题-前端缺陷-管理后台.md。
例如：
changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
日期使用提交时的上海日期；不要把“前端待处理”“已完成”等状态写进文件名。
2. 写什么
必须复制并按仓库根目录的 CHANGELOG_TEMPLATE.md 组织接口文档。接口类 Changelog 不能只写
路径和变更摘要，至少写清：
- 关联的 Issue 和后端 PR；
- 接口路径和 HTTP 方法；
- 新增、修改或删除的请求/响应字段；
- 字段必填性、枚举、状态、空值、金额和兼容规则；
- 前端需要做什么；
- 后端测试、部署和网关验证结果。
多接口条目必须让每个接口小节独立包含入参、出参、请求示例、响应示例、错误响应和业务边界；
“变更接口清单”的 METHOD /path 必须与逐接口详情一一对应。该结构由
check:frontmatter 机器校验，缺失时分别报 E_API_TEMPLATE、E_API_ENDPOINTS 或
E_API_DETAIL。存量接口文档一旦修改，也必须升级到当前模板标准。
元数据中：
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
- 需要前端修改：
frontend_status: "pending"（此时前端侧可回写frontend_owner认领 +verified_at实测日期） - 不需要前端修改：
frontend_status: "not_required" - 后端不要代替前端填写
implemented、released或verified
not_required 条目任何人（含前端）不得回写 frontend_owner / frontend_ref / target_release / verified_at——这 4 个字段是「前端需要动作」的认领/验收标记，not_required 语义是「前端零改动、无需认领」，填了就会被发布门禁（E_FRONTEND 残留校验）拦下。前端要表达「已知悉」用评论/口头即可，不动 frontmatter。若前端评估后认为其实需要适配，应把 frontend_status 改成 pending 再回写 owner，而不是在 not_required 上叠字段。（2026-08-19 #6077 实例：mmg 回写 not_required 条目的 frontend_owner=mmg+verified_at，合并后被门禁拦，清空后放行。）
2.1 发布门禁（硬规则，2026-08-10 wx 定）
给前端推送的 changelog，内容必须是测试环境已经存在、可实测到的。
- 接口类条目（新增接口/修改接口/删除接口）：推送前必须走完「PR 合并 → 部署测试服 → 测试服真实 API 验证」，frontmatter 必须
backend_status: "deployed"，并在正文「验证证据」章节贴实测结果。 backend_status为merged/pending/implemented等未部署状态的条目禁止 push（校验规则 E_BACKEND_PENDING 会拦）。「先给前端契约、部署随后」的预告式推送一律禁止——前端拿到 changelog 会立刻联调，接口不在等于空耗与误判。- 🔴 正文里不得出现任何「让前端等我们」的措辞（2026-09-21 wx 第二次点名，校验规则
E_WAIT_LANGUAGE会拦）：等部署/待部署/未部署/稍后另发/修好后另发/另发交接件/暂不可用/暂缓对接/该缺陷已在修/自行确认部署，以及「等待」与「部署/后端/我们/上线/修复/另发/发版/滚动」同行共现。- 为什么 §2.1 的
backend_status门禁不够：它是 frontmatter 字段，而这类句子活在自由文本里，门禁一个字也看不见——deployed+ 校验器全绿不等于这份交接件可执行。2026-09-20 的20_7443就是这样：frontmatter 已deployed、CI 绿，正文status_note结尾一句「该缺陷已在修……修好后另发交接件」，mmg 因此一直没动工，直到 09-21 才来问「这个是有啥问题吗 还是没做到呢」。 - 为什么不能交给前端自己判断：消费方查不了我们的部署状态、看不到
dev-v3、不知道「另发」是哪天。我方如实写下的「未核」，到他那里只剩一个可选动作——等，而且是静默地等：文件推了、门禁绿了、日报也记了，唯一的异常信号是有人在安静空转，比压根没发更难发现（没发至少还会有人来催）。对 wx 该说「没核」，对下游只能说「能接」，或者干脆先别发。 - 正文只允许两类内容：①已经就绪的契约；②前端调用时会撞上的限定（灰度开关状态、前置字段要求、会抛的错误码、已知缺口的工单号）。分界线是问一句：**这条影响他「怎么写代码」，还是只影响他「什么时候开始写」？**后者一律删掉。
- 某部分确实还没就绪时：要么整份不发，要么把没就绪的那块整段删掉，只交他现在就能接的部分；绝不写成「稍后另发」。
- ⚠️ 本规则只拦我方在制品，不拦契约边界——「生产环境灰度开关尚未开启（属独立运维动作）」「TRANSFER-only 订单在 9 个下游消费方无产出，已记 #8056」这类必须照写，否则就撞上「交接件要把自己的覆盖范围写在脸上」那条相反的要求；
E_WAIT_LANGUAGE配了阴性对照用例保证不误拦这类句子。
- 为什么 §2.1 的
- 纯前端条目（前端缺陷/前端优化/前端修复）：
backend_status: "not_required"，change_type 用对应前端类型；frontend_status: "not_required"时不得残留 frontend_owner / frontend_ref / target_release / verified_at。 - 背景：2026-08-06~08-07 三条未部署即推送的条目（#5599/#5567/#5633）导致前端在测试环境验不到字段（2026-08-10 投诉属实）；当时仓库 CI 因校验规则假阳性长期常红被忽略，规则已于 2026-08-10 修正（前端条目类型合法化、
{orderId}路径参数不再误判为占位符），此后 CI 红 = 真违规，必须当场修复回填。
推送校验（强制）：
- 推荐一次性启用本地钩子，之后 push 自动拦截：
git config core.hooksPath .githooks - 未启用钩子则每次 push 前手动跑 §3 的两条校验命令，红了不许推。
- 仓库 CI（changelog-filename-gate）对每次 push 复检；push 后请回看 Gitea Actions 状态，红 X 必须当场处理。
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 时不要改联系人。