#!/usr/bin/env bash # ssw-platform 分层红线自检 —— 「平台层 / 业务层」不许互相渗透 # # 目的:把 CLAUDE.md **红线 12**(「加一个业务模块只碰业务层」)变成**可执行的尺子**。 # 这条红线靠人读代码守不住 —— 加模块的人不会主动去看平台层 ⇒ 必须自动查。 # # 🔴 **纯静态**:不启动后端、不发请求。只需要 `python3`(macOS 自带)。 # # 用法: # bash scripts/check-boundary.sh # 无参 ⇒ 全查 # bash scripts/check-boundary.sh --help # 本用法 # # 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错 # # ── 判据 ── # CP1 平台层零业务标识符(业务表名 / 实体名 / 路由前缀 / 菜单 id / url / en_code) # —— 只扫**字符串字面量**(注释里举例说明业务名是文档行为,允许) # —— 禁止清单**从业务层自己派生** ⇒ 加模块时这把尺子自动变严 # CP1' 扫描器**反自证**:造一个明知存在的泄漏 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子) # CP2 平台层**不反向依赖**业务层:`platform/**` 不许 `use crate::modules` # CP3 业务层**不直接调**平台层的种子:`modules/**` 不许 `platform::seed` # (接线只在装配根 `bootstrap.rs`) # CP4 每个业务模块必须声明自己的菜单(`*_MENU: MenuSpec`)⇒ 且被 `modules/mod.rs` # 的 `ALL_MENUS` 收编(漏一处 ⇒ 菜单不显示 / admin 少一条授权) # ⇒ 且声明的菜单 id 与**契约** `[MENU]` 里该模块那一行一致 # CP5 `platform::seed::ensure_base` 的调用点**只有** `bootstrap.rs` # (应用与测试都走装配根 ⇒ 测到的库 == 上线的库) # CP6 平台层自带菜单**恰好 N 条**(N 由**契约**推出来:契约菜单数 − 业务模块数) # ⇒ 且平台层那几条的 id **逐条**等于契约里「非业务」的那些菜单 # # 🔴 **期望值来自 `docs/contract.md` 附录 A**(机器可读)⇒ 加业务模块时 # 「契约加一行」自动把 CP4/CP6 的期望值也带上了(脚本不硬编码 5 / 3 / 8)。 set -u ROOT="$(cd "$(dirname "$0")/.." && pwd)" BACKEND="$ROOT/src/backend" SRC="$BACKEND/src" PLATFORM="$SRC/platform" MODULES="$SRC/modules" MODULES_MOD="$MODULES/mod.rs" BOOTSTRAP="$SRC/bootstrap.rs" SCAN="$ROOT/scripts/check-boundary-scan.py" usage() { echo "用法: bash scripts/check-boundary.sh" echo " 纯静态检查「平台层 / 业务层」分层红线(CLAUDE.md 红线 12)" echo "退出码: 0 全过 / 1 有 ❌ 项 / 2 用法错" } if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then usage exit 0 fi if [ "$#" -ne 0 ]; then echo "❌ 未知参数: ${1}" usage exit 2 fi # ---- 前置:python3 必须在(扫描器靠它)---- PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" if [ -z "${PY_BIN}" ]; then echo "❌ 找不到 python3(扫描器需要它)" exit 2 fi if [ ! -f "${SCAN}" ]; then echo "❌ 缺扫描器: ${SCAN}" exit 2 fi # ---- 契约期望值(唯一真源:docs/contract.md 附录 A)---- CE_PY="$ROOT/scripts/contract_expect.py" if [ ! -f "${CE_PY}" ]; then echo "❌ 缺契约期望值读取器: ${CE_PY}" exit 2 fi ce() { "${PY_BIN}" "${CE_PY}" "$@"; } CE_MENU_ROWS="$(ce rows MENU 2>/dev/null)" || CE_MENU_ROWS="" CE_MOD_ROWS="$(ce rows MODULE 2>/dev/null)" || CE_MOD_ROWS="" CE_RULER_ROWS="$(ce rows RULER 2>/dev/null)" || CE_RULER_ROWS="" if [ -z "${CE_MENU_ROWS}" ] || [ -z "${CE_MOD_ROWS}" ] || [ -z "${CE_RULER_ROWS}" ]; then echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)" exit 2 fi CE_MENU_COUNT="$(printf '%s\n' "${CE_MENU_ROWS}" | awk -F'\t' 'NR>1 { n++ } END { print n + 0 }')" CE_MOD_COUNT="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' 'NR>1 { n++ } END { print n + 0 }')" # 平台层该有几条菜单 = 契约菜单总数 − 业务模块数(每个业务模块恰好一条业务菜单) CE_EXP_PLATFORM_MENUS=$((CE_MENU_COUNT - CE_MOD_COUNT)) # 契约里「属于业务模块的那些菜单 id」(= [MODULE] 的 menuId 列) CE_BUSINESS_MENU_IDS="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' 'NR>1 { print $6 }' | tr '\n' ' ')" PASS=0; FAIL=0 ok() { echo " ✅ $1"; PASS=$((PASS+1)); } no() { echo " ❌ $1"; FAIL=$((FAIL+1)); } hdr() { echo; echo "── $1 ──"; } # ---- CP1' 反自证:扫描器自己必须能抓到泄漏 ---- hdr "[CP1'] 扫描器反自证(--self-test 必须过)" SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)" if [ "$?" -eq 0 ]; then ok "扫描器自证通过:${SELFTEST_OUT}" else no "扫描器自证失败:${SELFTEST_OUT}" fi # ---- CP1 平台层零业务标识符 ---- hdr "[CP1] 平台层零业务标识符(扫字符串字面量;禁止清单从业务层派生)" SCAN_OUT="$("${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM}" "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" 2>&1)" if [ "$?" -eq 0 ]; then ok "平台层没有业务标识符($(printf '%s\n' "${SCAN_OUT}" | tail -1))" else no "平台层出现业务标识符:" printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /' fi # ---- CP2 平台层不反向依赖业务层 ---- hdr "[CP2] 平台层不反向依赖业务层(platform/** 不许 use crate::modules)" CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM}" 2>/dev/null)" if [ -z "${CP2_HITS}" ]; then ok "platform/** 没有 use crate::modules" else no "platform/** 引用了业务层:" printf '%s\n' "${CP2_HITS}" | sed 's/^/ /' fi # ---- CP3 业务层不直接调平台层的种子 ---- hdr "[CP3] 业务层不直接调平台层种子(modules/** 不许 platform::seed)" CP3_HITS="$(grep -rn "platform::seed" "${MODULES}" 2>/dev/null)" if [ -z "${CP3_HITS}" ]; then ok "modules/** 没有 platform::seed(接线只在装配根)" else no "modules/** 调了平台层的种子:" printf '%s\n' "${CP3_HITS}" | sed 's/^/ /' fi # ---- CP4 每个业务模块声明自己的菜单 + 被 ALL_MENUS 收编 ---- hdr "[CP4] 每个业务模块声明自己的菜单(*_MENU: MenuSpec)并被 ALL_MENUS 收编" MENU_FILES=0 MENU_MISSING="" MENU_UNREGISTERED="" MENU_MISMATCH="" for f in "${MODULES}"/*.rs; do base="$(basename "$f")" [ "${base}" = "mod.rs" ] && continue MENU_FILES=$((MENU_FILES+1)) consts="$(grep -o "^pub const [A-Z_]*_MENU: MenuSpec" "$f" 2>/dev/null | sed 's/^pub const //; s/: MenuSpec$//')" if [ -z "${consts}" ]; then MENU_MISSING="${MENU_MISSING} ${base}" continue fi for c in ${consts}; do if ! grep -q "${c}," "${MODULES_MOD}" 2>/dev/null; then MENU_UNREGISTERED="${MENU_UNREGISTERED} ${c}(${base})" fi done # 🔴 声明的菜单 id 必须与**契约** `[MODULE].menuId` 一致(该模块的菜单是哪一条, # 是契约说了算,不是代码自己说了算)。 C_MENU_ID="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' -v f="${base}" 'NR>1 && $8==f { print $6; exit }')" D_MENU_ID="$(awk '/^[ \t]*id:[ \t]*"/ { s = $0; sub(/^[ \t]*id:[ \t]*"/, "", s); sub(/".*/, "", s); print s; exit }' "$f")" if [ -z "${C_MENU_ID}" ]; then MENU_MISMATCH="${MENU_MISMATCH} ${base}(契约 [MODULE] 里没有它)" elif [ "${C_MENU_ID}" != "${D_MENU_ID}" ]; then MENU_MISMATCH="${MENU_MISMATCH} ${base}(声明=${D_MENU_ID:-无} 契约=${C_MENU_ID})" fi done if [ -n "${MENU_MISSING}" ]; then no "这些业务模块没声明菜单(缺 *_MENU: MenuSpec):${MENU_MISSING}" else ok "${MENU_FILES} 个业务模块都声明了 *_MENU: MenuSpec" fi if [ -n "${MENU_UNREGISTERED}" ]; then no "这些菜单没被 modules/mod.rs 的 ALL_MENUS 收编(菜单不会被种、admin 少一条授权):${MENU_UNREGISTERED}" else ok "全部业务菜单都被 ALL_MENUS 收编" fi if [ -n "${MENU_MISMATCH}" ]; then no "这些业务模块声明的菜单 id 与契约 [MODULE] 对不上:${MENU_MISMATCH}" else ok "业务模块声明的菜单 id 与契约 [MODULE] 逐条一致" fi # 🔴 **数量对账**:业务模块文件里的 *_MENU 个数 == ALL_MENUS 里的条目数。 ALL_MENUS_COUNT="$(awk ' /pub const ALL_MENUS: &\[MenuSpec\] = &\[/ { inb = 1; next } inb && /^\];/ { inb = 0; next } inb && /_MENU,/ { n++ } END { print n + 0 } ' "${MODULES_MOD}")" DECLARED_COUNT="$(grep -h -c "^pub const [A-Z_]*_MENU: MenuSpec" "${MODULES}"/*.rs 2>/dev/null | awk '{ s += $1 } END { print s + 0 }')" if [ "${ALL_MENUS_COUNT}" = "${DECLARED_COUNT}" ]; then ok "ALL_MENUS 条目数 = 各模块声明的 *_MENU 个数(${ALL_MENUS_COUNT})" else no "ALL_MENUS 有 ${ALL_MENUS_COUNT} 条,各模块声明了 ${DECLARED_COUNT} 个 *_MENU ⇒ 对不上" fi # ---- CP5 ensure_base 的调用点只有装配根 ---- hdr "[CP5] platform::seed::ensure_base 的调用点只有装配根 bootstrap.rs" CP5_HITS="$(grep -rn "seed::ensure_base" "${SRC}" 2>/dev/null | grep -v "^${BOOTSTRAP}:" )" if [ -z "${CP5_HITS}" ]; then ok "只有 bootstrap.rs 调 seed::ensure_base(应用与测试走同一条路)" else no "这些地方绕过装配根调了 seed::ensure_base:" printf '%s\n' "${CP5_HITS}" | sed 's/^/ /' fi # ---- CP6 平台层自带菜单:条数与 id 都由**契约**推出来 ---- hdr "[CP6] 平台层自带菜单(条数与 id 都由契约 [MENU] 推出来;业务菜单不许混进 platform/seed.rs)" PLATFORM_MENU_COUNT="$(awk ' /const BUILTIN_MENUS: \[MenuSpec; / { inb = 1; next } inb && /^\];/ { inb = 0; next } inb && /^[[:space:]]*id: "/ { n++ } END { print n + 0 } ' "${PLATFORM}/seed.rs")" if [ "${PLATFORM_MENU_COUNT}" -eq "${CE_EXP_PLATFORM_MENUS}" ]; then ok "platform/seed.rs 的 BUILTIN_MENUS 恰好 ${CE_EXP_PLATFORM_MENUS} 条系统菜单(契约菜单 ${CE_MENU_COUNT} 条 − 业务模块 ${CE_MOD_COUNT} 个)" else no "platform/seed.rs 的 BUILTIN_MENUS 有 ${PLATFORM_MENU_COUNT} 条(契约推出应为 ${CE_EXP_PLATFORM_MENUS} 条 = 契约菜单 ${CE_MENU_COUNT} − 业务模块 ${CE_MOD_COUNT})" fi # 平台层那几条的 id,必须**逐条**等于契约 [MENU] 里「不属于任何业务模块」的那些 id PLATFORM_MENU_IDS="$(awk ' /const BUILTIN_MENUS: \[MenuSpec; / { inb = 1; next } inb && /^\];/ { inb = 0; next } inb && /^[[:space:]]*id: "/ { s = $0; sub(/^[ \t]*id: "/, "", s); sub(/".*/, "", s); print s } ' "${PLATFORM}/seed.rs" | sort | tr '\n' ' ')" CE_PLATFORM_MENU_IDS="$(printf '%s\n' "${CE_MENU_ROWS}" | awk -F'\t' -v biz="${CE_BUSINESS_MENU_IDS}" ' NR > 1 { skip = 0 n = split(biz, ids, " ") for (i = 1; i <= n; i++) if (ids[i] != "" && ids[i] == $1) skip = 1 if (!skip) print $1 } ' | sort | tr '\n' ' ')" if [ "${PLATFORM_MENU_IDS}" = "${CE_PLATFORM_MENU_IDS}" ]; then ok "平台层菜单 id 与契约逐条一致:${PLATFORM_MENU_IDS}" else no "平台层菜单 id 与契约不一致:平台=${PLATFORM_MENU_IDS:-无} 契约=${CE_PLATFORM_MENU_IDS:-无}" fi # -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 -------- # # 🔴 尺子自己知道它断言了几条(PASS+FAIL)。哪天有人删掉几条断言、或者某个分支提前 # return 了,尺子照样「全绿」—— 变弱的尺子比没有尺子更危险 ⇒ 条数由**契约**钉死。 CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-boundary.sh" { print $2; exit }')" hdr "[自证] 尺子条数与契约登记一致" if [ -n "${CE_EXP_ASSERTIONS}" ]; then CE_ACT_ASSERTIONS=$((PASS + FAIL)) if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then # 自证**不计入** PASS/FAIL(它是元断言,不是业务断言) echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条" else echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)" FAIL=$((FAIL + 1)) fi fi # -------- 总结 -------- echo echo "── 总结 ──" echo "PASS=$PASS FAIL=$FAIL" if [ "$FAIL" -eq 0 ]; then echo "全 ✅ 分层红线没被打破" else echo "有 ❌,请按上面修复" fi exit $([ "$FAIL" -eq 0 ] && echo 0 || echo 1)