# 后端 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
```