Files
adminandClaude Code 96594df72f feat(repo): 平台层/业务层分离收尾 + 六道闸门(把「尺子」变成机器)
**影响**
后端从「平台层里塞业务知识」改成「装配根 + 业务层自带 spec/菜单/路由」;闸门 5 道 → 6 道,
契约尺子 2 条 → 3 条;两把尺子**默认自起隔离后端** ⇒ 不用先起后端就能冒烟(CI 可跑)。
单测 220 passed / 0 failed;静态闸门 93 + 11 + 10 + 4 全绿;面 A 32/32、面 B 18/18 全绿。

**改动**
- 后端:新增 `platform/guard.rs`(生产档弱口令守卫六条判据 + 配置级/库内级两道检查)、
  `platform/menu.rs`(菜单 spec 的类型)、`bootstrap.rs`(装配根:唯一同时认识平台层与业务层的地方);
  业务模块的菜单与路由下沉到 `modules/<app>.rs`,平台层只 `merge(modules::router())` 一次。
- 闸门:新增 `check-boundary.sh`(分层红线 CP1–CP6)、`check-contract.sh`(契约端点表 + 官方端点台账
  ↔ 代码真实路由,CC2–CC10)、`check-citations.sh`(文档引文 `路径:行号` 逐条核对);
  `check-module.sh` 改为从契约期望值派生(63 → 93 条);三把尺子各带反自证用例。
- 契约:`docs/contract.md` 附录 A 扩成机器可读区段(`[ENDPOINT]` / `[FACE]` / `[OFFICIAL]` / `[RULER]` …)
  ⇒ 六把尺子的期望值只有一处;`[OFFICIAL]` 官方端点台账 53 行四态 ⇒ 覆盖 **8/47**(算出来的)。
- 尺子:`scripts/smoke_backend.sh` 让两把契约尺子默认自起隔离后端(显式给了 `B` ⇒ 不自起、不可达即退出码 2)。
- 文档:CLAUDE.md / SKILL.md / README.md / HANDOFF.md / HOWTO_MODULE.md / docs/* 同步到新结构与新闸门;
  裁决 96 → 98 条(P91 尺子自起设计、P92 官方端点覆盖账本)。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 11:33:25 +08:00

141 lines
4.6 KiB
Bash
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env bash
# smoke_backend.sh —— 契约尺子的「隔离后端」自启动助手
#
# 🔴 **被 source,不是独立可执行**(`perm-smoke.sh` / `perm-smoke-jnpf.sh` 各自 source 它)。
#
# 为什么需要它:两把契约尺子原先都要求「后端已经在 30010 起着」⇒
# ① 两把尺子**互相踩**(面 A 尺子改了库里的角色/菜单 ⇒ 面 B 尺子的前置状态被污染);
# ② 跑完尺子**留脏数据**在 `src/backend/data/lite.pg`(每次多一行 smoke_user / product / book);
# ③ **CI 里没法跑**(没人替你起后端)。
#
# 口径(刻意做成「能自起,但不强拆用户的开发环境」):
# - 用户**显式**给了 `B` ⇒ **不自起**(尊重外部后端);不可达 ⇒ 前置错误(退出码 2)。
# - 用户**没给** `B`(用默认 30010)⇒ 先探默认端口:
# · 通了 ⇒ 就用它(保留「跑开发中的后端」这个习惯);
# · 不通 ⇒ **自起一个隔离实例**:独立数据目录(临时目录,跑完删)+ 空闲端口。
#
# ⇒ 跑完尺子,库里的痕迹**随临时目录一起消失** ⇒ 断言可重复、两把尺子互不污染。
# 自起的后端进程(由 ensure_backend 设置)
BACKEND_PID=""
BACKEND_TMP=""
BACKEND_ISOLATED=0
# 🔴 变量名后紧跟中文时 bash 会把中文并进变量名 ⇒ 一律写 ${VAR}
smoke_backend_pick_port() {
# 优先用 python3(真正 bind 一下拿端口 ⇒ 不会撞)
if [ -n "${PY_BIN:-}" ]; then
"${PY_BIN}" - <<'PY' 2>/dev/null && return 0
import socket
s = socket.socket()
s.bind(("127.0.0.1", 0))
print(s.getsockname()[1])
s.close()
PY
fi
# 没有 python3 ⇒ 用 /dev/tcp 扫一段端口(连不上 ⇒ 当作空的)
local p
for p in $(seq 30110 30199); do
if ! (exec 3<>/dev/tcp/127.0.0.1/"${p}") 2>/dev/null; then
echo "${p}"
return 0
fi
done
echo ""
return 1
}
# 后端是否就绪(`/api/health` 返回 `{"ok":true,…}` ⇒ schema 已建好)
smoke_backend_ready() {
curl -s --noproxy '*' --max-time 2 "$1/api/health" 2>/dev/null | grep -q '"ok":true'
}
# ensure_backend <后端二进制> [显式给的 B]
# 成功后 ${B} 指向可用的后端;自起时 ${BACKEND_PID} 非空(退出时要 kill)。
smoke_backend_ensure() {
local bin="${1:-}"
local explicit_b="${2:-}"
if smoke_backend_ready "${B}"; then
return 0
fi
# 显式指定了 B 却不通 ⇒ 那是**用户自己的**后端 ⇒ 不自起,直接前置错误
if [ -n "${explicit_b}" ]; then
if [ -n "${pre_fail:-}" ]; then
pre_fail "后端不可达:${B}(${explicit_b} 是显式指定的 ⇒ 不自起隔离实例)。"
fi
echo "❌ 前置错误:后端不可达:${B}"
exit 2
fi
if [ -z "${bin}" ] || [ ! -x "${bin}" ]; then
if [ -n "${pre_fail:-}" ]; then
pre_fail "后端不可达且自起需要可执行文件(${bin})。"
fi
echo "❌ 前置错误:后端不可达且自起需要可执行文件(${bin})。"
exit 2
fi
local port
port="$(smoke_backend_pick_port)"
if [ -z "${port}" ]; then
if [ -n "${pre_fail:-}" ]; then
pre_fail "找不到空闲端口(自起隔离后端失败)。"
fi
echo "❌ 前置错误:找不到空闲端口(自起隔离后端失败)。"
exit 2
fi
BACKEND_TMP="$(mktemp -d)"
B="http://127.0.0.1:${port}"
# 🔴 数据目录必须是**绝对路径**(契约:PGLITE_DIR 只接受绝对路径或 memory://)
PORT="${port}" \
PGLITE_DIR="${BACKEND_TMP}/pg" \
BIND_ADDR="127.0.0.1" \
"${bin}" >"${BACKEND_TMP}/backend.log" 2>&1 &
BACKEND_PID=$!
BACKEND_ISOLATED=1
# 等就绪(最多 40 秒)
local i=0
while [ "${i}" -lt 80 ]; do
if ! kill -0 "${BACKEND_PID}" 2>/dev/null; then
break
fi
if smoke_backend_ready "${B}"; then
return 0
fi
sleep 0.5
i=$((i+1))
done
echo "❌ 前置错误:隔离后端起不来(日志:${BACKEND_TMP}/backend.log)"
sed 's/^/ /' "${BACKEND_TMP}/backend.log" 2>/dev/null || true
smoke_backend_kill
exit 2
}
# 停掉自起的后端(TERM ⇒ 等 ⇒ 兜底 KILL;SIGKILL 会漏 SysV 信号量 ⇒ 尽量走 TERM)
smoke_backend_kill() {
if [ -z "${BACKEND_PID}" ]; then
return 0
fi
kill -TERM "${BACKEND_PID}" 2>/dev/null || true
local i=0
while [ "${i}" -lt 60 ]; do
if ! kill -0 "${BACKEND_PID}" 2>/dev/null; then
break
fi
sleep 0.1
i=$((i+1))
done
if kill -0 "${BACKEND_PID}" 2>/dev/null; then
kill -KILL "${BACKEND_PID}" 2>/dev/null || true
fi
wait "${BACKEND_PID}" 2>/dev/null || true
BACKEND_PID=""
BACKEND_ISOLATED=0
}