5.2 KiB
5.2 KiB
后端 API Changelog 推送与交接指南
本文可直接发送给后端同事。适用于
wx/HL的管理后台与小程序接口变更。
一、什么时候必须推送 changelog
以下变化需要 changelog：
- Controller 路径、HTTP 方法或权限边界变化；
- DTO、VO、BO、Feign 请求或响应字段变化；
- 字段必填性、枚举、状态、金额、空值或兼容行为变化；
- 新增、修改、废弃或删除管理后台/小程序接口；
- 前端或其他调用方需要调整请求、解析或页面行为。
纯后端内部重构且外部契约完全不变时，可不创建；必须在工单中说明 frontend_status: not_required 的判断依据。
二、准备条件
- 已有关联的合格 Gitea 工单。
- 已确认目标端：
- 管理后台：
changelogs-v2/ - 小程序端：
changelogs-v2-mp/
- 管理后台：
- 已确认变更类型：
新增接口、修改接口或删除接口。 D:/work2/hl-ui保持只读，不在前端仓库创建配合工单。- changelog 仓库使用独立任务分支或 worktree，不把其他线程的未跟踪文件一起提交。
三、生成草稿
预览：
hl changelog draft 5205 "车务首页汇总状态补全" `
--repo D:/work2/HL-v3-worktrees/5205 `
--base dev-v3 `
--track v3 `
--consumer admin `
--change-type 修改接口
确认目标路径和检测到的 Controller/DTO/VO/Feign 文件后写入：
hl changelog draft 5205 "车务首页汇总状态补全" `
--repo D:/work2/HL-v3-worktrees/5205 `
--base dev-v3 `
--track v3 `
--consumer admin `
--change-type 修改接口 `
--write
--write 会自动获取 changelog 单写租约。手工创建或修改 changelog 时，应先执行：
hl resource acquire changelog --ticket 5205 --ttl 1800
四、文件名
管理后台：
changelogs-v2/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-管理后台.md
小程序：
changelogs-v2-mp/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-小程序端.md
年月日必须使用提交时 Asia/Shanghai 的真实日期。状态不得写入文件名，不要增加“前端待处理”“已完成”等额外片段。
五、填写 v2 元数据
---
schema: "hl-changelog/v2"
ticket: "5205"
title: "车务首页汇总状态补全"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "pending"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: ""
updated_at: "2026-07-24"
base: "dev-v3"
---
规则：
- 自动草稿从
backend_status: pending、gateway_status: pending开始。 - 后端实际部署完成后才能改为
backend_status: deployed。 - 经网关验证后填写
gateway_status: verified；确实无需网关验证时使用not_required。 - 需要前端配合时初始化
frontend_status: pending。 - 不需要前端修改时使用
frontend_status: not_required。 - 后端不得代替前端填写
implemented、released或verified。
六、正文必须写清
- 关联 Issue 和 PR；
- 变更接口清单；
- 请求与响应字段；
- 枚举、状态、空值、ID 和金额规则；
- 老数据和兼容行为；
- 前端/调用方需要采取的动作；
- 定向测试、网关验证和兼容性证据；
- 不影响范围。
页面展示、列表、汇总、看板、状态标签或颜色变化，还必须在后端工单中准备展示矩阵，明确数据来源、状态范围、空态、颜色和守恒规则。
七、本地校验
在 changelog 仓库执行：
npm test
npm run check:filenames -- --base origin/main --head HEAD
npm run check:frontmatter -- --base origin/main --head HEAD
单文件还可以执行：
hl changelog lint D:/path/changelog.md
发布前 lint 允许前端仍是 pending，但要求：
backend_status: deployed；gateway_status不再是pending；- 正文不存在
TODO、待补充或模板占位符。
八、提交和推送
只暂存本任务文件，禁止使用会卷入其他线程文件的宽泛命令：
git status --short
git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
git diff --cached --check
git commit -m "docs: hand off fleet dashboard contract (#5205)"
git push -u origin <任务分支>
随后向 main 创建 PR。合并前再次检查上海日期；跨越上海零点且仍未合并时，按贡献规则重命名为当天日期。
不要直接提交：
- 其他线程的 changelog；
.tmp-*文件；- token、密码、证书、真实隐私数据；
hl-ui代码。
九、回写后端任务
合并后在后端工单和任务台账记录：
- changelog 文件路径；
- changelog 提交或 PR；
- 当前
frontend_status； - 后端部署和网关验证证据。
hl task update 5205 `
--changelog D:/path/changelog.md
后端工单可以按后端验收范围关闭；前端继续在同一 changelog 中推进消费状态。
手工持有租约时，完成后释放：
hl resource release changelog --ticket 5205