docs: 发布门禁硬规则——给前端推送的必须是测试环境已存在可实测的+pre-push 钩子

- 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>

.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

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 接口事故）。