1.9 KiB
1.9 KiB
后端 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 文件：
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 -u origin <任务分支>
然后向 main 创建 PR。不要提交其他任务的 changelog、.tmp-* 文件或任何凭据。