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