Files
ssw-platform/scripts/check-boundary.sh
T
admin e821770f58 refactor(arch): M4 契约面下沉 —— 14 模块 / ~49,000 行迁入 6 个 crate
把 src/backend/src/platform/compat/ 下的 14 个契约面模块拆进 6 个 crate,
原路径全部变成 5 行转发壳 ⇒ 上层 import 零感知,695 个测试一个没改。

新 crate(按官方模块名切,实测依赖图定分组):
- sspf-compat-system     system + scheduletask + core
- sspf-compat-permission permission(单向依赖 system,4 符号)
- sspf-compat-msg        message + msg_center
- sspf-compat-workflow   workflow + report + visualdata
- sspf-compat-ext        extend + teamwork + ai + mobile(单向依赖 system + msg)
- sspf-compat-online_dev online_dev(🔴 Rust 包名不能带连字符)

闸门改造:
- check-arch.sh 新增 PLAT_SRC_DIRS(动态 glob)⇒ AR9/AR10 扫真源
- check-arch.sh 新增 AR12(契约面各包彼此独立,Cargo.toml 级判据 + 3 条单向白名单)
- check-contract-scan.py 动态收编所有 crates/sspf-compat-*/src(不写死列表)
- check-boundary.sh 新增动态 COMPAT_DIRS ⇒ CP1/CP2 纳入契约面包
- 修 8 条引文路径(行号 1:1 未变 ⇒ 迁移是纯搬运)

🔴 三个「尺子是假的」的坑(都是反自证抓出来的):
1. CC6 守卫推导静默失效 —— compat_dirs 只收了 sspf-compat-core,六包真源没收
   ⇒ 改动态 glob;反向验证:改坏真源 EN_ROLE ⇒ CC6 精确报出
2. CP1 业务标识符未扫契约面包 ⇒ 加 COMPAT_DIRS;反向验证:插 LEAK_PROBE ⇒ 精确报出
3. macOS 的 BSD grep 不支持 \s(POSIX ERE)⇒ AR11/AR12 的 Cargo.toml 级判据
   永远匹配不到 ⇒ 永远「通过」(AR11 从 M3 起就没真正生效过)
   ⇒ 改 [[:space:]];全仓扫过 scripts/*.sh 确认只有这一处

数字:cargo build 零警告;cargo test 695/0(与 M1 基线完全一致);
check-arch 15/15;--self-test 7/7;check-boundary 11/11;check-contract 10/10
(反自证 12 例全过);check-module 123/123;check-citations 4/4;
check-naming 3/0/1;verify.sh --smoke 14 步全绿(300.9s)
2026-11-03 18:57:00 +08:00

302 lines
15 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"
# 🔴 **M4 起契约面真源分散在 7 个 crate**(`sspf-compat-core` + 6 个域包)——
# 契约面也是「平台侧」⇒ 业务标识符泄漏 / 反向依赖业务层同样要查。
# ⇒ 动态收集 `crates/sspf-compat-*/src`,**新增包时不会漏扫**(写死列表必然漏)。
COMPAT_DIRS=()
for d in "$ROOT"/crates/sspf-compat-*/src; do
[ -d "$d" ] && COMPAT_DIRS+=("$d")
done
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}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} "${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/** 与 compat 包/** 不许 use crate::modules)"
# 🔴 三处都扫:平台核心真源 + 平台转发壳 + 契约面 7 个包的真源。
CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} 2>/dev/null)"
if [ -z "${CP2_HITS}" ]; then
ok "平台核心 / 转发壳 / 契约面各包 都没有 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)