98 行
2.8 KiB
Markdown
98 行
2.8 KiB
Markdown
# 后端 API Changelog 推送说明
|
||
|
||
接口发生新增、修改或删除时，在 `hl-api-changelog` 仓库提交一份 changelog。
|
||
|
||
## 1. 放在哪里
|
||
|
||
- 管理后台：`changelogs-v2/YYYY-MM/`
|
||
- 小程序：`changelogs-v2-mp/YYYY-MM/`
|
||
|
||
文件名：
|
||
|
||
```text
|
||
DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
|
||
```
|
||
|
||
日期使用提交时的上海日期；不要把“前端待处理”“已完成”等状态写进文件名。
|
||
|
||
## 2. 写什么
|
||
|
||
可以复制仓库根目录的 `CHANGELOG_TEMPLATE.md`，至少写清：
|
||
|
||
- 关联的 Issue 和后端 PR；
|
||
- 接口路径和 HTTP 方法；
|
||
- 新增、修改或删除的请求/响应字段；
|
||
- 字段必填性、枚举、状态、空值、金额和兼容规则；
|
||
- 前端需要做什么；
|
||
- 后端测试、部署和网关验证结果。
|
||
|
||
元数据中：
|
||
|
||
```yaml
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "pending"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
```
|
||
|
||
- 需要前端修改：`frontend_status: "pending"`
|
||
- 不需要前端修改：`frontend_status: "not_required"`
|
||
- 后端不要代替前端填写 `implemented`、`released` 或 `verified`
|
||
|
||
## 3. 校验
|
||
|
||
在 `hl-api-changelog` 仓库执行：
|
||
|
||
```powershell
|
||
npm test
|
||
npm run check:filenames -- --base origin/main --head HEAD
|
||
npm run check:frontmatter -- --base origin/main --head HEAD
|
||
```
|
||
|
||
确保正文没有 `TODO`、`待补充` 或模板占位符。
|
||
|
||
## 4. 提交和推送
|
||
|
||
只暂存本次 changelog 文件，**直接 commit main**（不建分支/PR）：
|
||
|
||
```powershell
|
||
git status --short
|
||
git add -- changelogs-v2/2026-07/24_5205_车务首页汇总状态补全-修改接口-管理后台.md
|
||
git diff --cached --check
|
||
git commit -m "docs: hand off API contract (#5205)"
|
||
git push origin main
|
||
```
|
||
|
||
不要提交其他任务的 changelog、`.tmp-*` 文件或任何凭据。
|
||
|
||
## 5. author 字段（必填）
|
||
|
||
所有 changelog frontmatter 必须包含 `author` 字段，格式为推送者登录名 + `(GIT)` 后缀：
|
||
|
||
```yaml
|
||
author: "wx(GIT)" # wx 推送写 wx(GIT)；yst 推送写 yst(GIT)；以此类推
|
||
```
|
||
|
||
谁 push 到 main 就写谁，多会话并行时用于追溯该条 changelog 的推送人。新写文件必须带；修改旧文件时顺手补上。
|
||
|
||
**正文开头同步加作者行**（2026-08-04 wx 定）：除 frontmatter `author` 字段外，正文最前面（frontmatter 结束后、一级标题前）必须加一行作者标识，方便阅读者直接看到：
|
||
|
||
```markdown
|
||
---
|
||
|
||
**作者：wx**
|
||
|
||
# 订单: xxx
|
||
```
|
||
|
||
与 frontmatter `author` 字段同源：wx 推送写 `**作者：wx**`，yst 推送写 `**作者：yst**`。模板已含此行（见 CHANGELOG_TEMPLATE.md）。
|