Files
ssw-platform/scripts/check-boundary.sh
T
admin 94d05f4649 refactor(arch): M2 平台核心下沉 —— 19 模块迁入 crates/sspf-core + 闸门扫真源
平台能力全迁 crates/ 迁移计划第 2 批(docs/CRATES-MIGRATION.md,基线 tag v0.1.0)。
本批次 = M2:平台核心从 src/backend/src/platform/ 下沉到 crates/sspf-core/。

搬迁:
- 19 个模块 git mv 进 crates/sspf-core/src/(保留历史):
  auth/authorization/cipher/config/crud/db/entity/envelope/guard/ids/menu/
  monitor/registry/route/seed/session/state/sys/variate_catalog
- src/backend/src/platform/*.rs 全改成 pub use sspf_core::<mod>::* 转发壳(5 行/个)
  ⇒ 上层零感知:routes / modules / 695 个测试的 import 一个没改
- crate 内路径改写 crate::platform::X → crate::X(compat 除外,那是 M3/M4)
- pub(crate) → pub(10 处,跨 crate 后失效)

闸门改造(🔴 本批最大风险不是代码是闸门 —— 搬迁后闸门扫空壳 = 虚假安全感):
- 纪律 = 「两处都扫」:真源 crates/sspf-core/src/(管实现)+ 转发壳(防塞私货)
- check-arch.sh AR9/AR10 扫两处;反自证 2/6、5/6 两处注入探针且按路径分别验
- check-boundary.sh 新增 PLATFORM_CORE;CP1/CP2 两处扫;CP6 的 seed.rs 改读真源
- check-contract-scan.py 的 plat_files 两处都收、重名键拼接(覆盖会丢函数 ⇒ 推不出守卫)
- check-module.sh 的 CRUD 改读 crates/sspf-core/src/crud.rs(软删契约要看 SQL)
- gen-function-catalog.py 的 OUT 改写真源(否则覆盖转发壳 ⇒ 上层 import 全断)
- 反向验证:只往 crates/sspf-core/ 塞违规 ⇒ AR9/AR10 都报红(证明真在扫真源)

测试归属调整:crud.rs 3 个测试原依赖 crate::modules::all_specs()(业务层)
⇒ 改用契约层合成 spec 参数化测试;registry.rs 测试改自建库 + seed::ensure_base(db, &[])。
顺带记录技术债:write_cast 的 numeric 映射是列名枚举而非 spec 声明。

影响:功能零变化(路由、响应形状、语义均未动),纯结构下沉。
验证:cargo build 零警告;cargo test --workspace 695 passed / 0 failed(与基线一致);
check-arch 14/14;--self-test 6/6;check-boundary 11/11;check-contract 10/10(反自证 12 例全过);
check-module 123/123;check-citations 4/4;verify --smoke 14 步全绿(512.3s)。
2026-11-03 15:49:00 +08:00

295 lines
14 KiB
Bash
Executable File
Raw 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
# 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"
# 🔴 **M2 起平台层真源在 `crates/sspf-core/src/`**,`src/backend/src/platform/`
# 只剩转发壳(`pub use sspf_core::*`)+ 尚未搬走的 `compat/`(M3/M4)。
# ⇒ 所有「扫平台层」的判据必须**两处都扫**(真源管实现、壳防塞私货)。
PLATFORM_CORE="$ROOT/crates/sspf-core/src"
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] 平台层零业务标识符(扫字符串字面量;禁止清单从业务层派生)"
# 🔴 **业务层现在有两处**(批次 12 交付物 ②):`modules/*.rs`(面 A 内嵌)
# + `packs/*/src/lib.rs`(业务包)⇒ 两处都要进「禁止清单」,
# 否则包里的业务表名会从清单里消失 ⇒ 尺子变弱。
# 🔴 **M2 起平台层真源在 `crates/sspf-core/src/`** ⇒ 它必须进扫描面(否则扫空壳)。
SCAN_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${PLATFORM_CORE}" "${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] 平台层不反向依赖业务层(sspf-core/** 与 platform/** 不许 use crate::modules)"
# 🔴 两处都扫:真源 `crates/sspf-core/src/`(实现)+ 转发壳(防塞私货)。
CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" "${PLATFORM}" 2>/dev/null)"
if [ -z "${CP2_HITS}" ]; then
ok "sspf-core/** 与 platform/** 都没有 use crate::modules"
else
no "平台层引用了业务层:"
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 或从业务包 re-export)并被 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))
# 🔴 **两种形态都算数**(批次 12 交付物 ②「spec 单一真源」):
# ① 自己声明:`pub const XXX_MENU: MenuSpec = …`
# ② 从业务包转发:`pub use sspf_pack_xxx::XXX_MENU;`
# ⇒ 业务包的菜单住在包里(真源),内核只转发 ⇒ 不产生第二份拷贝。
consts="$(grep -oE "^pub const [A-Z_]*_MENU: MenuSpec" "$f" 2>/dev/null | sed 's/^pub const //; s/: MenuSpec$//')"
reexports="$(grep -oE "^pub use [a-z0-9_]+::[A-Z_]*_MENU;" "$f" 2>/dev/null | sed 's/^pub use [a-z0-9_]*:://; s/;$//')"
all_consts="$(printf '%s\n%s\n' "${consts}" "${reexports}" | grep -v '^$' | tr '\n' ' ')"
if [ -z "${all_consts}" ]; then
MENU_MISSING="${MENU_MISSING} ${base}"
continue
fi
for c in ${all_consts}; do
if ! grep -q "${c}," "${MODULES_MOD}" 2>/dev/null; then
MENU_UNREGISTERED="${MENU_UNREGISTERED} ${c}(${base})"
fi
done
# 🔴 声明的菜单 id 必须与**契约** `[MODULE].menuId` 一致(该模块的菜单是哪一条,
# 是契约说了算,不是代码自己说了算)。
# 🔴 菜单 id 在**包里**(re-export 形态)⇒ 从 `packs/<app>/src/lib.rs` 取。
C_MENU_ID="$(printf '%s\n' "${CE_MOD_ROWS}" | awk -F'\t' -v f="${base}" 'NR>1 && $8==f { print $6; exit }')"
if [ -n "${reexports}" ]; then
# 从业务包取菜单 id(包目录名 = app_code = 模块文件名去掉 .rs)
pack_app="${base%.rs}"
pack_lib="${ROOT}/packs/${pack_app}/src/lib.rs"
D_MENU_ID="$(awk '/^[ \t]*id:[ \t]*"/ { s = $0; sub(/^[ \t]*id:[ \t]*"/, "", s); sub(/".*/, "", s); print s; exit }' "${pack_lib}" 2>/dev/null)"
else
D_MENU_ID="$(awk '/^[ \t]*id:[ \t]*"/ { s = $0; sub(/^[ \t]*id:[ \t]*"/, "", s); sub(/".*/, "", s); print s; exit }' "$f")"
fi
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,也没有从业务包 re-export):${MENU_MISSING}"
else
ok "${MENU_FILES} 个业务模块都声明了菜单(自带 *_MENU 或从业务包 re-export)"
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
# 🔴 **数量对账**:业务模块文件里的菜单数 == 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 -cE "^pub const [A-Z_]*_MENU: MenuSpec|^pub use [a-z0-9_]+::[A-Z_]*_MENU;" "${MODULES}"/*.rs 2>/dev/null | awk '{ s += $1 } END { print s + 0 }')"
if [ "${ALL_MENUS_COUNT}" = "${DECLARED_COUNT}" ]; then
ok "ALL_MENUS 条目数 = 各模块声明的菜单个数(${ALL_MENUS_COUNT})"
else
no "ALL_MENUS 有 ${ALL_MENUS_COUNT} 条,各模块声明了 ${DECLARED_COUNT} 个菜单 ⇒ 对不上"
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] 推出来;业务菜单不许混进 seed.rs)"
# 🔴 M2 起 `seed.rs` 真源在 `crates/sspf-core/src/seed.rs`(转发壳里没有 BUILTIN_MENUS)。
SEED_RS="${PLATFORM_CORE}/seed.rs"
[ -f "${SEED_RS}" ] || SEED_RS="${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 }
' "${SEED_RS}")"
if [ "${PLATFORM_MENU_COUNT}" -eq "${CE_EXP_PLATFORM_MENUS}" ]; then
ok "seed.rs 的 BUILTIN_MENUS 恰好 ${CE_EXP_PLATFORM_MENUS} 条系统菜单(契约菜单 ${CE_MENU_COUNT} 条 − 业务模块 ${CE_MOD_COUNT} 个)"
else
no "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 }
' "${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)