#!/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" # 🔴🔴 **M7 起平台层真源全在 `crates/`** —— `src/backend/src/platform/` 的 # 38 个转发壳**已整体删除** ⇒ 平台层**只有真源**,没有壳。 # ⇒ 所有「扫平台层」的判据**只需扫 crates/ 下的真源**(不再扫壳)。 # ⚠️ 「旧路径复活」由 `check-arch.sh` 的 **AR15** 单独钉住(防删掉的东西回来)。 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" # 🔴 **M6 起 MCP 适配层真源在 `crates/sspf-mcp-adapter/src/`**—— # 它也是「平台侧」(编排平台能力给 MCP 用),且它是**全仓唯一知道全部包的 # 汇聚点** ⇒ 业务标识符泄漏 / 反向依赖业务层更要查。 # ⇒ 放进 CP1/CP2 的扫描范围(与契约面、执行层同款纪律)。 MCP_ADAPTER="$ROOT/crates/sspf-mcp-adapter/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'' 反自证:扫描面必须**真覆盖**新 crate(M6 新增目录)---- # # 🔴 **为什么必须有这一条**:CP1 的扫描面是**显式列出来的目录**(`PLATFORM_CORE` / # `PLATFORM_CORE` / `COMPAT_DIRS` / `LOWCODE_EXEC` / `MCP_ADAPTER`)。 # 代码搬到新 crate 后,若忘了把新目录加进扫描面 ⇒ 尺子**扫不到** ⇒ # **永远"通过"** ⇒ 虚假安全感(AR9 自证注释里写明过这个坑)。 # ⇒ 往新 crate 注入一个**业务表名**,必须被抓到 —— 抓不到 = 扫描面漏了。 hdr "[CP1''] 扫描面反自证(往 M6 新 crate 注入业务表名 ⇒ 必须被抓到)" if [ -d "${MCP_ADAPTER}" ]; then CP1_PROBE="${MCP_ADAPTER}/__cp1_selftest.rs" # 🔴 探针用**业务包真实声明的表名**(从业务层派生 ⇒ 探针本身不含硬编码清单)。 CP1_PROBE_TOKEN="$(CP1_SCAN_PATH="${SCAN}" SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" - "${MODULES}" "${ROOT}/packs" <<'PYPROBE' import os, re, sys sys.path.insert(0, os.path.dirname(os.path.abspath(os.environ["CP1_SCAN_PATH"]))) modules_dir, packs_dir = sys.argv[1], sys.argv[2] spec = re.compile(r'table:\s*"([^"]+)"') for src in [os.path.join(packs_dir, p, "src", "lib.rs") for p in sorted(os.listdir(packs_dir)) if os.path.isdir(os.path.join(packs_dir, p))]: if not os.path.isfile(src): continue m = spec.search(open(src, encoding="utf-8").read()) if m: print(m.group(1)) break PYPROBE )" if [ -n "${CP1_PROBE_TOKEN}" ]; then printf 'const LEAK_PROBE: &str = "%s";\n' "${CP1_PROBE_TOKEN}" > "${CP1_PROBE}" CP1_PROBE_OUT="$(SSW_PACKS_DIR="${ROOT}/packs" "${PY_BIN}" "${SCAN}" "${MODULES}" "${MCP_ADAPTER}" 2>&1 || true)" rm -f "${CP1_PROBE}" if printf '%s\n' "${CP1_PROBE_OUT}" | grep -q "${CP1_PROBE_TOKEN}"; then ok "扫描面反自证通过:M6 新 crate(mcp-adapter)确实在 CP1 扫描面内(注入的 ${CP1_PROBE_TOKEN} 被抓到)" else no "扫描面反自证失败:往 mcp-adapter 注入 ${CP1_PROBE_TOKEN} 没被抓到 ⇒ 扫描面漏了新 crate(尺子已失效)" fi else no "扫描面反自证失败:业务层没解析出业务表名(探针无法构造)" fi else no "扫描面反自证失败:MCP_ADAPTER 目录不存在" 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}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} ${MCP_ADAPTER:+"${MCP_ADAPTER}"} "${SRC}/routes.rs" "${SRC}/main.rs" "${BOOTSTRAP}" "${SRC}/compat.rs" 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/** 与 mcp-adapter/** 不许 use crate::modules)" # 🔴 五处都扫:平台核心真源 + 平台转发壳 + 契约面 7 个包的真源 + 低代码执行层真源(M5) # + MCP 适配层真源(M6)。 CP2_HITS="$(grep -rn "use crate::modules" "${PLATFORM_CORE}" ${COMPAT_DIRS[@]+"${COMPAT_DIRS[@]}"} ${LOWCODE_EXEC:+"${LOWCODE_EXEC}"} ${MCP_ADAPTER:+"${MCP_ADAPTER}"} 2>/dev/null)" if [ -z "${CP2_HITS}" ]; then ok "平台核心 / 转发壳 / 契约面各包 / 低代码执行层 / MCP 适配层 都没有 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//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" 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)