b8596041d7
- guide §2.1: 接口类条目推送前必须走完 PR 合并→部署测试服→测试服真实 API 验证,backend_status=deployed 才许 push;预告式推送一律禁止(2026-08-10 wx 定,前端投诉实证 #5599/#5567/#5633) - .githooks/pre-push: push 前自动跑文件名+frontmatter 校验,违规拦截;启用 git config core.hooksPath .githooks - 文件名类型枚举文档同步(7 类+frontend 字面量) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
133 行
6.4 KiB
Markdown
133 行
6.4 KiB
Markdown
# 后端 API Changelog 推送说明
|
||
|
||
接口发生新增、修改或删除时，在 `hl-api-changelog` 仓库提交一份 changelog。
|
||
|
||
## 1. 放在哪里
|
||
|
||
- 管理后台：`changelogs-v2/YYYY-MM/`
|
||
- 小程序：`changelogs-v2-mp/YYYY-MM/`
|
||
|
||
文件名：
|
||
|
||
```text
|
||
DD_issue_业务标题-{新增接口|修改接口|删除接口|修复|前端缺陷|前端优化|前端修复}-{管理后台|小程序端}.md
|
||
```
|
||
|
||
纯前端条目（无后端工单）issue 段写字面量 `frontend`，如 `10_frontend_标题-前端缺陷-管理后台.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`
|
||
|
||
## 2.1 发布门禁（硬规则，2026-08-10 wx 定）
|
||
|
||
**给前端推送的 changelog，内容必须是测试环境已经存在、可实测到的。**
|
||
|
||
- 接口类条目（新增接口/修改接口/删除接口）：推送前必须走完「PR 合并 → 部署测试服 → 测试服真实 API 验证」，frontmatter 必须 `backend_status: "deployed"`，并在正文「验证证据」章节贴实测结果。
|
||
- `backend_status` 为 `merged` / `pending` / `implemented` 等未部署状态的条目**禁止 push**（校验规则 E_BACKEND_PENDING 会拦）。「先给前端契约、部署随后」的预告式推送一律禁止——前端拿到 changelog 会立刻联调，接口不在等于空耗与误判。
|
||
- 纯前端条目（前端缺陷/前端优化/前端修复）：`backend_status: "not_required"`，change_type 用对应前端类型；`frontend_status: "not_required"` 时不得残留 frontend_owner / frontend_ref / target_release / verified_at。
|
||
- 背景：2026-08-06~08-07 三条未部署即推送的条目（#5599/#5567/#5633）导致前端在测试环境验不到字段（2026-08-10 投诉属实）；当时仓库 CI 因校验规则假阳性长期常红被忽略，规则已于 2026-08-10 修正（前端条目类型合法化、`{orderId}` 路径参数不再误判为占位符），此后 **CI 红 = 真违规，必须当场修复回填**。
|
||
|
||
**推送校验（强制）**：
|
||
|
||
- 推荐一次性启用本地钩子，之后 push 自动拦截：`git config core.hooksPath .githooks`
|
||
- 未启用钩子则每次 push 前手动跑 §3 的两条校验命令，红了不许推。
|
||
- 仓库 CI（changelog-filename-gate）对每次 push 复检；push 后请回看 Gitea Actions 状态，红 X 必须当场处理。
|
||
|
||
## 2.5 写作方法论（对齐 yst 团队 changelog-conventions SKILL，2026-08-04 起执行）
|
||
|
||
**受众优先**：触达 `/admin/*` `/mp/*` `/v3/admin/*` `/v3/mp/*` 等对外前缀的改动**一律**写前端 changelog，哪怕"前端代码零改动"（前端 AI 可能有 workaround 需清理信号）。`/v3/internal/*` Feign 接口**必须拆出去**单独走后端 changelog，不许和 admin/mp 接口塞同一份（反例：# traveler 11 接口事故）。
|
||
|
||
**自包含**：禁止"详见 Knife4j / Swagger / 同目录 xx.md"。所有请求参数表、响应字段表、枚举值（值+中文+说明）、错误码、完整 JSON 示例必须内联——消费方 AI 没有内部文档权限。
|
||
|
||
**消费方语言**：写"下拉框去掉草稿选项"，不写"status 字段 ApiModelProperty 注解更新"；值变了用 `原来 → 现在` 表格，不写散文。
|
||
|
||
**示例要求**：每个接口至少 1 组「典型成功」示例（请求+响应完整 JSON）；修改类接口建议补「边界」「异常」共 3 组。GET 示例也要写全 URL + Authorization 头 + 注明"无请求体"。
|
||
|
||
**不写后端实现**：禁止出现 DB 表/字段名、雪花 ID 序列化细节、Nacos 配置拼接、端口/重启/回滚耗时等后端实现与运维内容（后端运维信息写后端 changelog）。"任何一行拿掉后接口契约仍成立，就该删"。
|
||
|
||
**emoji 分类（标题用）**：⚠️ 破坏性变更 / ✨ 新增 / 🔧 行为变更 / 📝 仅文档。
|
||
|
||
**commit message 用中文**：`新增退款政策字段（产品详情接口）`，不用英文。
|
||
|
||
**多接口 changelog（≥3 接口）**：按接口分小节，每个接口自含「使用场景/入参/出参/错误码/业务边界/示例」，不把多接口入参混到一张大表。
|
||
|
||
## 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 的推送人。新写文件必须带；修改旧文件时顺手补上。
|
||
|
||
**联系人章节（模仿 yst 格式，2026-08-04 wx 定）**：除 frontmatter `author` 字段外，正文末尾"关联 / 联系人"章节必须标注后端负责人，格式与 yst 的 changelog 一致：
|
||
|
||
```markdown
|
||
## 关联 / 联系人
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @wx
|
||
```
|
||
|
||
与 frontmatter `author` 字段同源：wx 负责写 `@wx`，yst 负责写 `@yst`。不要在正文开头加"作者"行（已废弃）。模板已含此章节（见 CHANGELOG_TEMPLATE.md）。修改他人 changelog 时不要改联系人。
|