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
|
||||
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-*` 文件或任何凭据。
|
||||
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户