182 行
5.2 KiB
Markdown
182 行
5.2 KiB
Markdown
# 后端 API Changelog 推送与交接指南
|
||
|
||
> 本文可直接发送给后端同事。适用于 `wx/HL` 的管理后台与小程序接口变更。
|
||
|
||
## 一、什么时候必须推送 changelog
|
||
|
||
以下变化需要 changelog：
|
||
|
||
- 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
|
||
```
|
||
|
||
小程序：
|
||
|
||
```text
|
||
changelogs-v2-mp/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-小程序端.md
|
||
```
|
||
|
||
年月日必须使用提交时 `Asia/Shanghai` 的真实日期。状态不得写入文件名，不要增加“前端待处理”“已完成”等额外片段。
|
||
|
||
## 五、填写 v2 元数据
|
||
|
||
```yaml
|
||
---
|
||
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 仓库执行：
|
||
|
||
```powershell
|
||
npm test
|
||
npm run check:filenames -- --base origin/main --head HEAD
|
||
npm run check:frontmatter -- --base origin/main --head HEAD
|
||
```
|
||
|
||
单文件还可以执行：
|
||
|
||
```powershell
|
||
hl changelog lint D:/path/changelog.md
|
||
```
|
||
|
||
发布前 lint 允许前端仍是 `pending`，但要求：
|
||
|
||
- `backend_status: deployed`；
|
||
- `gateway_status` 不再是 `pending`；
|
||
- 正文不存在 `TODO`、`待补充` 或模板占位符。
|
||
|
||
## 八、提交和推送
|
||
|
||
只暂存本任务文件，禁止使用会卷入其他线程文件的宽泛命令：
|
||
|
||
```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 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
|
||
```
|