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)
This commit is contained in:
admin committed 2026-11-03 18:57:00 +08:00
1 parent eea3d0329f
commit e821770f58
51 files changed
+48289 -47571

No files matched your search

+103 -14
View File
@@ -51,6 +51,19 @@ CRATES="$ROOT/crates"
KERNEL="$ROOT/src/backend"
MODULES_DIR="$KERNEL/src/modules"
# 🔴 **平台侧真源目录表**(M2/M3/M4 逐步扩):
# - `sspf-core/src` 平台核心(M2)
# - `sspf-compat-*/src` 契约面 7 个包(M3 底座 + M4 六个域包)
# - `platform/` 转发壳(防塞私货)
# 🔴 **动态收集**(`crates/sspf-compat-*/src`)⇒ 新增契约面包时**不会漏扫** ——
# 写死列表必然在某次新增包时漏掉 ⇒ 尺子静默失效(实测踩过)。
PLAT_SRC_DIRS=()
[ -d "$CRATES/sspf-core/src" ] && PLAT_SRC_DIRS+=("$CRATES/sspf-core/src")
for d in "$CRATES"/sspf-compat-*/src; do
[ -d "$d" ] && PLAT_SRC_DIRS+=("$d")
done
[ -d "$KERNEL/src/platform" ] && PLAT_SRC_DIRS+=("$KERNEL/src/platform")
PASS=0
FAIL=0
SKIP=0
@@ -215,13 +228,12 @@ check_ar8() {
# 只扫壳 = 尺子量空壳 = 虚假安全感。
check_ar9() {
local dirs=()
[ -d "$CRATES/sspf-core/src" ] && dirs+=("$CRATES/sspf-core/src")
[ -d "$KERNEL/src/platform" ] && dirs+=("$KERNEL/src/platform")
[ "${#dirs[@]}" -gt 0 ] || { skip "AR9 平台层目录不存在"; return; }
[ "${#PLAT_SRC_DIRS[@]}" -gt 0 ] || { skip "AR9 平台层目录不存在"; return; }
dirs=("${PLAT_SRC_DIRS[@]}")
local hits
hits="$(grep -rnE '^[[:space:]]*(pub )?use[[:space:]]+sspf_pack_' "${dirs[@]}" 2>/dev/null || true)"
if [ -z "$hits" ]; then
ok "AR9 平台层没有 use sspf_pack_*(业务知识没漏进 sspf-core/ 或 platform/)"
ok "AR9 平台层没有 use sspf_pack_*(业务知识没漏进 sspf-core/ / compat 各包 / platform/)"
else
bad "AR9 平台层出现了业务包引用(业务知识漏进平台层 ⇒ 加包要改平台层):"
printf '%s\n' "$hits" | sed 's/^/ /'
@@ -245,9 +257,8 @@ check_ar9() {
# **不含 compat/**)里都不许出现 `crate::platform::compat` / `super::compat` / `crate::compat`。
check_ar10() {
local dirs=()
[ -d "$CRATES/sspf-core/src" ] && dirs+=("$CRATES/sspf-core/src")
[ -d "$KERNEL/src/platform" ] && dirs+=("$KERNEL/src/platform")
[ "${#dirs[@]}" -gt 0 ] || { skip "AR10 平台层目录不存在"; return; }
[ "${#PLAT_SRC_DIRS[@]}" -gt 0 ] || { skip "AR10 平台层目录不存在"; return; }
dirs=("${PLAT_SRC_DIRS[@]}")
local hits
# 🔴 **必须排除注释行**(`//` / `//!` / `///`)—— 文档注释里的路径引用是
# **给人看的**(如 `//! (见 crate::platform::compat::helper::load_menus])`),
@@ -320,7 +331,7 @@ check_ar11() {
local toml="$CRATES/sspf-compat-core/Cargo.toml"
if [ -f "$toml" ]; then
local dep_hits
dep_hits="$(grep -nE '^\s*sspf-compat-[a-z-]+\s*=' "$toml" 2>/dev/null || true)"
dep_hits="$(grep -nE '^[[:space:]]*sspf-compat-[a-z_-]+[[:space:]]*=' "$toml" 2>/dev/null || true)"
if [ -n "$dep_hits" ]; then
hits="${hits:+$hits$'\n'}${dep_hits}"
fi
@@ -333,6 +344,56 @@ check_ar11() {
fi
}
# ---------------------------------------------------------------- AR12
# **契约面各包之间不许互相依赖**(M4 拆 6 个包时的防环回流闸门)。
#
# 🔴 **为什么需要**:M4 把 49,000 行契约面拆成 7 个 crate。各包本应**彼此独立**
# (都只依赖 `sspf-compat-core` 底座 + `sspf-core` 平台核心)。
# 一旦 A 包 `use sspf_compat_b::…` 而 B 包又 `use sspf_compat_a::…`
# ⇒ **循环依赖** ⇒ 编译器直接报错(但那时已经改了一堆东西,回滚成本高)。
#
# 🔴 **唯一允许的两条单向依赖**(方向单一 ⇒ 不成环,已核实被依赖方不反向依赖):
# · `sspf-compat-permission` → `sspf-compat-system`
# (权限域用系统域的 `SYSTEM_LIST_PROJECTION` / `load_system_tops` /
# `log_page` / `shape_system_list_item`)
# · `sspf-compat-ext` → `sspf-compat-system` + `sspf-compat-msg`
# (移动端复用系统域 `home_data` 控制台卡片 + 消息域 `send_config_select_list`)
#
# 判据:每个 `crates/sspf-compat-*/Cargo.toml` 里出现的 `sspf-compat-*` 依赖,
# 必须在白名单内,且**白名单方向要反过来核实**(被依赖方不许依赖依赖方)。
check_ar12() {
local hits=""
local dir
for dir in "$CRATES"/sspf-compat-*; do
[ -d "$dir" ] || continue
local toml="$dir/Cargo.toml"
[ -f "$toml" ] || continue
local self_name
self_name="$(basename "$dir")"
local dep
for dep in $(grep -oE '^[[:space:]]*sspf-compat-[a-z_-]+[[:space:]]*=' "$toml" 2>/dev/null | grep -oE 'sspf-compat-[a-z_-]+' | sort -u); do
# 底座(sspf-compat-core)永远允许
[ "$dep" = "sspf-compat-core" ] && continue
# 白名单:按「依赖方 → 被依赖方」判定
local allowed=0
case "${self_name}:${dep}" in
sspf-compat-permission:sspf-compat-system) allowed=1 ;;
sspf-compat-ext:sspf-compat-system) allowed=1 ;;
sspf-compat-ext:sspf-compat-msg) allowed=1 ;;
esac
if [ "$allowed" -eq 0 ]; then
hits="${hits:+$hits$'\n'}${toml}: ${self_name} → ${dep}(不在白名单)"
fi
done
done
if [ -z "$hits" ]; then
ok "AR12 契约面各包彼此独立(只依赖底座 + 两条单向白名单 ⇒ 不会成环)"
else
bad "AR12 契约面包之间出现了未授权依赖(跨包依赖易成环):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- PACK1
# **spec 单一真源**:`modules/<app>.rs` 只许做转发,不许自己写 spec。
#
@@ -466,7 +527,7 @@ PY
self_test() {
local rc=0
echo "── 反自证 1/6:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
echo "── 反自证 1/7:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
local tmp="$ROOT/packs/__arch_selftest__"
mkdir -p "$tmp"
cat > "$tmp/Cargo.toml" <<'TOML'
@@ -492,7 +553,7 @@ TOML
rc=1
fi
echo "── 反自证 2/6:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
echo "── 反自证 2/7:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。
@@ -530,7 +591,7 @@ TOML
rc=1
fi
echo "── 反自证 3/6:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
echo "── 反自证 3/7:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
#
# 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_`
# 和 `= EntitySpec {`,PACK1 就必须红。
@@ -556,7 +617,7 @@ RS
echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)"
fi
echo "── 反自证 4/6:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
echo "── 反自证 4/7:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
local pfile="$CRATES/sspf-plugin/Cargo.toml"
if [ -f "$pfile" ]; then
cp "$pfile" "$pfile.bak"
@@ -577,7 +638,7 @@ RS
echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)"
fi
echo "── 反自证 5/6:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
echo "── 反自证 5/7:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
#
# 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。
# 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。
@@ -610,7 +671,7 @@ RS
rc=1
fi
echo "── 反自证 6/6:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
echo "── 反自证 6/7:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
#
# 🔴 **M3 起底座有两处**:真源 `crates/sspf-compat-core/src/helper.rs`(实现)
# + 转发壳 `src/backend/src/platform/compat/helper.rs`。**两处都注入、
@@ -637,6 +698,33 @@ RS
rc=1
fi
echo "── 反自证 7/7:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。
# 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒
# **永远"通过"** ⇒ 虚假安全感。而 AR12 守的正是「契约面各包不会成环」。
# 🔴 **注入必须避开白名单**:挑 `sspf-compat-msg`(它不在任何白名单里,
# 反向依赖 `sspf-compat-workflow` ⇒ 立刻成环)⇒ 必须被抓到。
local a12ok=0
local a12toml="$CRATES/sspf-compat-msg/Cargo.toml"
if [ -f "$a12toml" ]; then
cp "$a12toml" "$a12toml.bak"
printf '\nsspf-compat-workflow = { path = "../sspf-compat-workflow" }\n' >> "$a12toml"
local a12out
a12out="$(check_ar12 2>&1 || true)"
mv "$a12toml.bak" "$a12toml"
# 🔴 必须**按路径验**:输出里要明确出现被注入的那个包 + 那个依赖
if echo "$a12out" | grep -q "sspf-compat-msg → sspf-compat-workflow"; then
a12ok=1
fi
fi
if [ "$a12ok" -eq 1 ]; then
echo "✅ 反自证通过:AR12 抓到了 msg → workflow 的未授权跨包依赖"
else
echo "❌ 反自证失败:AR12 没抓到未授权的跨包依赖 ⇒ 尺子是假的"
rc=1
fi
return $rc
}
@@ -655,6 +743,7 @@ check_ar8
check_ar9
check_ar10
check_ar11
check_ar12
check_pack1
check_mem1
check_mem2
+12 -5
View File
@@ -42,6 +42,13 @@ PLATFORM="$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"
@@ -115,7 +122,7 @@ hdr "[CP1] 平台层零业务标识符(扫字符串字面量;禁止清单从
# + `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)"
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
@@ -124,11 +131,11 @@ else
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)"
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 "sspf-core/** 与 platform/** 都没有 use crate::modules"
ok "平台核心 / 转发壳 / 契约面各包 都没有 use crate::modules"
else
no "平台层引用了业务层:"
printf '%s\n' "${CP2_HITS}" | sed 's/^/ /'
+14
View File
@@ -858,10 +858,24 @@ def scan_code(src_dir, packs_dir=None):
# 否则守卫推导**全部推不出**(CC6 退化成「全是 WARN」⇒ 静默失效)。
# 🔴 **M3 起契约面底座真源在 `crates/sspf-compat-core/src/`**(`helper.rs` 装守卫常量
# `EN_ROLE` 等)⇒ 必须一并收(与壳同键拼接),否则守卫常量找不到 ⇒ CC6 假漂移。
# 🔴 **M4 起六个域包的真源也分散在 `crates/sspf-compat-*/src/`** —— 必须**逐包收**,
# 否则守卫推导读到的全是转发壳(`pub use …` 无函数体)⇒ **CC6 静默失效**
# (实测:漏收时 check-contract 照样 10/10 全绿,但尺子已经废了)。
compat_dirs = [
os.path.join(ROOT, "crates", "sspf-compat-core", "src"), # M3 真源(helper/res)
os.path.join(plat_dir, "compat"), # 壳 + 尚未搬走的模块
]
# 🔴 **M4:六个契约面域包的真源**(按包名遍历 ⇒ 新增包时不会漏收)
crates_root = os.path.join(ROOT, "crates")
if os.path.isdir(crates_root):
for cname in sorted(os.listdir(crates_root)):
if not cname.startswith("sspf-compat-"):
continue
if cname == "sspf-compat-core":
continue # 已在上面收过
cdir = os.path.join(crates_root, cname, "src")
if os.path.isdir(cdir):
compat_dirs.append(cdir)
for d in compat_dirs:
if os.path.isdir(d):
for name in sorted(os.listdir(d)):