Files
ssw-platform/scripts/check-boundary.sh
T
admin 98b93967da refactor(arch): M5 低代码执行层下沉 —— 4 模块 / 2,674 行迁入 sspf-lowcode-exec
把 src/backend/src/lowcode_{crud,ddl,check,seed}.rs 下沉到 crates/sspf-lowcode-exec/,
原路径全部变成 5 行转发壳 ⇒ CLI(--seed-lowcode-demo)与 MCP 适配器的调用路径零感知。

与 sspf-lowcode 的分工不变:前者纯计算(AR7 白名单不动),本 crate 是执行层
(连库 / 跑 SQL / 比对真实库列 / 事务 / 回写模型)。

依赖:sspf-lowcode + sspf-core + sspf-store + sspf-mcp + pglite-rs + chrono + serde_json
(比原计划多三个:pglite::ToSql/Error 是直接用的、now_iso() 用 chrono::Local::now()、JSON payload)

闸门改造:
- check-arch.sh 新增 AR13(两层:依赖白名单 + 源码不许 use sspf_pack_*)
- check-arch.sh 反自证 7→8(两处都注入:越界依赖 axum + 业务包引用,按路径分别验)
- check-boundary.sh 新增 LOWCODE_EXEC ⇒ CP1/CP2 纳入执行层真源
  (反向验证:插 LEAK_PROBE ⇒ CP1 报红;还原后 11/11)
- check-contract-scan.py 不用改 —— 契约里零 lowcode 端点(低代码是 MCP 工具不是 HTTP 路由)

🔴 踩坑:改写时把 use crate::lowcode_ddl; 一并改成 use crate::ddl; ⇒ 编译不过。
教训:搬 crate 只改跨 crate 的前缀(crate::platform:: → sspf_core::),
模块名一律不动;文档内链([`crate::lowcode_crud`])也不能跟着改(改了就变死链)。

数字:cargo build 零警告;cargo test 695/0(与 M1 基线完全一致);
check-arch 17/17;--self-test 8/8;check-boundary 11/11;check-contract 10/10;
check-module 123/123;check-citations 4/4;check-naming 3/0/1;
verify.sh --smoke 14 步全绿(377.6s)
2026-11-03 20:12:50 +08:00

306 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
# 🔴 **M5 起低代码执行层真源在 `crates/sspf-lowcode-exec/src/`**——
# 它也是「平台侧」(连库 / 跑 SQL / 校验),业务标识符泄漏同样要查。
# ⇒ 放进 CP1/CP2 的扫描范围(与契约面同款纪律)。
LOWCODE_EXEC="$ROOT/crates/sspf-lowcode-exec/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}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} "${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 包/** 与 lowcode-exec/** 不许 use crate::modules)"
# 🔴 四处都扫:平台核心真源 + 平台转发壳 + 契约面 7 个包的真源 + 低代码执行层真源(M5)。
CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" "${PLATFORM}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} 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)