diff --git a/.githooks/pre-push b/.githooks/pre-push new file mode 100644 index 0000000..b719d0b --- /dev/null +++ b/.githooks/pre-push @@ -0,0 +1,25 @@ +#!/bin/sh +# changelog 发布门禁(推送前强制校验) +# 启用(每台机一次): git config core.hooksPath .githooks +# 拦截目标: 接口类 changelog 未部署测试服(backend_status != deployed)就推送给前端, +# 以及文件名/frontmatter 结构违规。规则实现见 scripts/validate-changelog-*.mjs。 +zero=0000000000000000000000000000000000000000 +status=0 +while read local_ref local_sha remote_ref remote_sha; do + # 删除远端分支的推送没有本地内容可校验 + [ "$local_sha" = "$zero" ] && continue + if [ "$remote_sha" = "$zero" ]; then + base=$(git rev-parse --verify origin/main 2>/dev/null) || continue + else + base=$remote_sha + fi + [ "$base" = "$local_sha" ] && continue + node scripts/validate-changelog-filenames.mjs --base "$base" --head "$local_sha" || status=1 + node scripts/validate-changelog-frontmatter.mjs --base "$base" --head "$local_sha" || status=1 +done +if [ "$status" -ne 0 ]; then + echo "" >&2 + echo "推送被 changelog 发布门禁拦截:接口类条目必须测试服已部署+实测(backend_status=deployed)后才能推送给前端。" >&2 + echo "修正文件后重试;规则详见 BACKEND_CHANGELOG_DELIVERY_GUIDE.md §2.1。" >&2 +fi +exit $status diff --git a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md index ced468b..1fdf713 100644 --- a/BACKEND_CHANGELOG_DELIVERY_GUIDE.md +++ b/BACKEND_CHANGELOG_DELIVERY_GUIDE.md @@ -10,9 +10,11 @@ 文件名: ```text -DD_issue_业务标题-{新增接口|修改接口|删除接口}-{管理后台|小程序端}.md +DD_issue_业务标题-{新增接口|修改接口|删除接口|修复|前端缺陷|前端优化|前端修复}-{管理后台|小程序端}.md ``` +纯前端条目(无后端工单)issue 段写字面量 `frontend`,如 `10_frontend_标题-前端缺陷-管理后台.md`。 + 例如: ```text @@ -48,6 +50,21 @@ verified_at: "" - 不需要前端修改:`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 接口事故)。