docs: 精简后端 changelog 推送说明 #26
@ -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
|
```text
|
||||||
changelogs-v2/YYYY-MM/DD_issue_业务标题-{新增接口|修改接口|删除接口}-管理后台.md
|
DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md
|
||||||
```
|
```
|
||||||
|
|
||||||
小程序：
|
例如：
|
||||||
|
|
||||||
```text
|
```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
|
```yaml
|
||||||
---
|
|
||||||
schema: "hl-changelog/v2"
|
|
||||||
ticket: "5205"
|
|
||||||
title: "车务首页汇总状态补全"
|
|
||||||
consumer: "admin"
|
|
||||||
change_type: "修改接口"
|
|
||||||
backend_status: "deployed"
|
backend_status: "deployed"
|
||||||
gateway_status: "verified"
|
gateway_status: "verified"
|
||||||
frontend_status: "pending"
|
frontend_status: "pending"
|
||||||
@ -87,37 +42,15 @@ frontend_owner: ""
|
|||||||
frontend_ref: ""
|
frontend_ref: ""
|
||||||
target_release: ""
|
target_release: ""
|
||||||
verified_at: ""
|
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` 开始。
|
## 3. 校验
|
||||||
- 后端实际部署完成后才能改为 `backend_status: deployed`。
|
|
||||||
- 经网关验证后填写 `gateway_status: verified`；确实无需网关验证时使用 `not_required`。
|
|
||||||
- 需要前端配合时初始化 `frontend_status: pending`。
|
|
||||||
- 不需要前端修改时使用 `frontend_status: not_required`。
|
|
||||||
- 后端不得代替前端填写 `implemented`、`released` 或 `verified`。
|
|
||||||
|
|
||||||
## 六、正文必须写清
|
在 `hl-api-changelog` 仓库执行：
|
||||||
|
|
||||||
- 关联 Issue 和 PR；
|
|
||||||
- 变更接口清单；
|
|
||||||
- 请求与响应字段；
|
|
||||||
- 枚举、状态、空值、ID 和金额规则；
|
|
||||||
- 老数据和兼容行为；
|
|
||||||
- 前端/调用方需要采取的动作；
|
|
||||||
- 定向测试、网关验证和兼容性证据；
|
|
||||||
- 不影响范围。
|
|
||||||
|
|
||||||
页面展示、列表、汇总、看板、状态标签或颜色变化，还必须在后端工单中准备展示矩阵，明确数据来源、状态范围、空态、颜色和守恒规则。
|
|
||||||
|
|
||||||
## 七、本地校验
|
|
||||||
|
|
||||||
在 changelog 仓库执行：
|
|
||||||
|
|
||||||
```powershell
|
```powershell
|
||||||
npm test
|
npm test
|
||||||
@ -125,57 +58,18 @@ npm run check:filenames -- --base origin/main --head HEAD
|
|||||||
npm run check:frontmatter -- --base origin/main --head HEAD
|
npm run check:frontmatter -- --base origin/main --head HEAD
|
||||||
```
|
```
|
||||||
|
|
||||||
单文件还可以执行：
|
确保正文没有 `TODO`、`待补充` 或模板占位符。
|
||||||
|
|
||||||
```powershell
|
## 4. 提交和推送
|
||||||
hl changelog lint D:/path/changelog.md
|
|
||||||
```
|
|
||||||
|
|
||||||
发布前 lint 允许前端仍是 `pending`，但要求：
|
只暂存本次 changelog 文件：
|
||||||
|
|
||||||
- `backend_status: deployed`；
|
|
||||||
- `gateway_status` 不再是 `pending`；
|
|
||||||
- 正文不存在 `TODO`、`待补充` 或模板占位符。
|
|
||||||
|
|
||||||
## 八、提交和推送
|
|
||||||
|
|
||||||
只暂存本任务文件，禁止使用会卷入其他线程文件的宽泛命令：
|
|
||||||
|
|
||||||
```powershell
|
```powershell
|
||||||
git status --short
|
git status --short
|
||||||
git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
|
git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
|
||||||
git diff --cached --check
|
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 <任务分支>
|
git push -u origin <任务分支>
|
||||||
```
|
```
|
||||||
|
|
||||||
随后向 `main` 创建 PR。合并前再次检查上海日期；跨越上海零点且仍未合并时，按贡献规则重命名为当天日期。
|
然后向 `main` 创建 PR。不要提交其他任务的 changelog、`.tmp-*` 文件或任何凭据。
|
||||||
|
|
||||||
不要直接提交：
|
|
||||||
|
|
||||||
- 其他线程的 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
|
|
||||||
```
|
|
||||||
|
|||||||
正在加载...
x
在新工单中引用
屏蔽一个用户