refactor(arch): M1 解耦 —— 拆掉三处跨 crate 循环依赖 + 加 AR10/AR11 闸门

平台能力全迁 crates/ 的迁移计划见 docs/CRATES-MIGRATION.md(基线 tag v0.1.0)。
本批次 = M1:先把三处跨 crate 循环依赖解开,否则后续拆 crate 时编译器直接报错。

断环(实测定位,非推断):
- 环 A(平台层 → 契约面):auth.rs 的面 B 判据改走契约层唯一真源
  sspf_contract::headers::is_face_b;面 B 分流点上移到装配根 routes.rs,
  平台层与契约面互不知道对方;resolve_user 由 pub(crate) 提为 pub。
- 环 B(契约面底座 helper ↔ system):menu_node / official_view_path 搬进 helper。
- 环 C(契约面底座 helper ↔ permission):USER_DETAIL_COLUMNS / organize_name_of 搬进 helper。

闸门:
- 新增 AR10「平台层不许反向依赖契约面」(拆 crate 的前置条件)。
- 新增 AR11「契约面底座 helper 不许依赖其它契约面模块」(14 个模块依赖它 ⇒ 反向依赖即成环)。
- 反自证由 4 条扩到 6 条(新增 AR10/AR11 两条真实违规注入),确认尺子能抓到。

影响:功能零变化(面 A / 面 B 的响应形状、路由、语义均未动),仅为依赖方向解耦。
验证: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;
check-module 123/123;check-citations 4/4;verify --smoke 14 步全绿。
This commit is contained in:
admin committed 2026-11-03 13:25:06 +08:00
1 parent 1694e77324
commit 215b5e8fcf
10 files changed
+385 -131

No files matched your search

+148 -4
View File
@@ -28,6 +28,14 @@
# —— 适配器只认工具契约层;依赖内核 store 就等于把第二种后端钉死在本进程旁
# AR7 `crates/sspf-lowcode` 依赖 ⊆ {sspf-contract, serde, serde_json}
# —— 低代码引擎是纯计算;依赖 DB/HTTP 会让它只能在内核里跑,且测试必须起库
# AR9 `src/backend/src/platform/**` 里不许出现 `use sspf_pack_*`
# —— 平台层不许认识任何业务包(业务知识隔离)
# AR10 `src/backend/src/platform/**`(不含 compat/)里不许出现
# `crate::platform::compat` —— 平台层不许**反向依赖**契约面
# —— M1 解开的环 A;拆 crate 时它就是循环依赖(编译器当天才报错 ⇒ 必须提前钉住)
# AR11 `src/backend/src/platform/compat/helper.rs` 里不许 `use super::<别的模块>`
# —— 契约面底座不许反向依赖契约面业务模块(helper 被 14 个模块依赖 ⇒ 即成环)
# —— M1 解开的环 B/C
# MEM1 非注释代码里不许出现 `SELECT *`
# —— 终端产品内存预算 ≤ 120MB(PLAN.md 判断 ⑥)⇒ 全表读进 Vec 直接爆
# MEM2 `crates/**` 与 `src/backend/src/platform/**` 里不许出现无界 `HashMap` 缓存
@@ -213,6 +221,90 @@ check_ar9() {
fi
}
# ---------------------------------------------------------------- AR10
# **平台层不许反向依赖契约面**(M1 解开的环 A,防回退)。
#
# 🔴 **背景**:M1 之前 `platform/auth.rs` 里写着
# `crate::platform::compat::helper::current_user(...)` —— 平台层反过来调契约面。
# 同 crate 内这只是「层间倒挂」(能编译),但**拆 crate 时就是循环依赖**,
# 编译器直接报错 ⇒ 整个迁移(M2–M6)全部卡死。
# M1 已把分流点上移到装配根(`routes.rs`),平台层不再认识契约面。
#
# 🔴 **为什么必须钉住**:拆 crate 是**渐进**的 —— 在拆完之前,加回这一行
# **照样编译通过、测试照样全绿**,只有到 M2 那天才炸 ⇒ 那时候已经改了一堆东西,
# 回滚成本高得多。⇒ 现在就把它拦住。
#
# 判据:`src/backend/src/platform/**`(**不含 compat/**)里不许出现
# `crate::platform::compat` / `super::compat` / `crate::compat`。
check_ar10() {
local dir="$KERNEL/src/platform"
[ -d "$dir" ] || { skip "AR10 平台层目录不存在"; return; }
local hits
# 🔴 **必须排除注释行**(`//` / `//!` / `///`)—— 文档注释里的路径引用是
# **给人看的**(如 `//! (见 crate::platform::compat::helper::load_menus])`),
# 不是依赖 ⇒ 不该判红。
# 🔴 纯 grep 过滤不了:`//!` 前面**没有空格** ⇒ `^\s*//` 漏掉它。
# 这里用 python3 逐行判(与 MEM1/MEM2 同一套路)。
hits="$(python3 - "$dir" <<'PY'
import os, re, sys
root = sys.argv[1]
pat = re.compile(r'(crate::platform::compat|crate::compat|super::compat)')
bad = []
for dirpath, dirnames, files in os.walk(root):
dirnames[:] = [d for d in dirnames if d != 'compat'] # 契约面自己互引合法
for fn in files:
if not fn.endswith('.rs'):
continue
p = os.path.join(dirpath, fn)
try:
lines = open(p, encoding='utf-8').read().splitlines()
except OSError:
continue
for i, line in enumerate(lines, 1):
s = line.strip()
# 整行注释(含 `//!` / `///`)⇒ 跳过
if s.startswith('//'):
continue
# 行尾注释:把 `//` 之后截掉再判(`use x::y; // 说明` 里的说明不算)
code = line.split('//', 1)[0]
if pat.search(code):
bad.append(f'{p}:{i}: {s}')
for b in bad:
print(b)
PY
)"
if [ -z "$hits" ]; then
ok "AR10 平台层没有反向依赖契约面(拆 crate 的前置条件仍成立)"
else
bad "AR10 平台层反向依赖契约面(拆 crate 时就是循环依赖 ⇒ 必须把调用点上移到装配根):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- AR11
# **契约面底座(helper)不许依赖契约面业务模块**(M1 解开的环 B/C,防回退)。
#
# 🔴 **背景**:`compat/helper.rs` 被 **14 个**契约面模块依赖(实测)⇒ 它是底座。
# 若它反过来 `use super::system` / `use super::permission` ⇒
# 拆 crate 时 helper ↔ system / helper ↔ permission 都是**循环依赖**。
# M1 已把 `menu_node` / `official_view_path` / `USER_DETAIL_COLUMNS` /
# `organize_name_of` 搬进 helper,切断了这两条边。
#
# 判据:`compat/helper.rs` 里不许 `use super::` 指向**非 helper 的模块**。
check_ar11() {
local f="$KERNEL/src/platform/compat/helper.rs"
[ -f "$f" ] || { skip "AR11 compat/helper.rs 不存在"; return; }
local hits
hits="$(grep -nE '^[[:space:]]*(pub )?use[[:space:]]+super::[a-z_]+' "$f" 2>/dev/null \
| grep -v 'super::helper' || true)"
if [ -z "$hits" ]; then
ok "AR11 契约面底座(helper)不依赖其它契约面模块(14 个模块依赖它 ⇒ 反向依赖即成环)"
else
bad "AR11 契约面底座(helper)反向依赖契约面业务模块(拆 crate 时即成环):"
printf '%s\n' "$hits" | sed 's/^/ /'
fi
}
# ---------------------------------------------------------------- PACK1
# **spec 单一真源**:`modules/<app>.rs` 只许做转发,不许自己写 spec。
#
@@ -346,7 +438,7 @@ PY
self_test() {
local rc=0
echo "── 反自证 1/4:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
echo "── 反自证 1/6:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
local tmp="$ROOT/packs/__arch_selftest__"
mkdir -p "$tmp"
cat > "$tmp/Cargo.toml" <<'TOML'
@@ -372,7 +464,7 @@ TOML
rc=1
fi
echo "── 反自证 2/4:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
echo "── 反自证 2/6:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
#
# 🔴 **为什么必须自证 AR9**:它的判据是 `grep platform/`。
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。
@@ -396,7 +488,7 @@ TOML
echo "⏭ 跳过 AR9 反自证(平台层目录不存在)"
fi
echo "── 反自证 3/4:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
echo "── 反自证 3/6:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
#
# 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_`
# 和 `= EntitySpec {`,PACK1 就必须红。
@@ -422,7 +514,7 @@ RS
echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)"
fi
echo "── 反自证 4/4:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
echo "── 反自证 4/6:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
local pfile="$CRATES/sspf-plugin/Cargo.toml"
if [ -f "$pfile" ]; then
cp "$pfile" "$pfile.bak"
@@ -443,6 +535,56 @@ RS
echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)"
fi
echo "── 反自证 5/6:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
#
# 🔴 **必须自证 AR10**:它的判据是 `grep platform/`。
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。
# 而且这条判据守护的是**拆 crate 的前置条件** —— 它一旦失效,M2 当天才炸。
local a10probe="$KERNEL/src/platform/__ar10_selftest.rs"
if [ -d "$KERNEL/src/platform" ]; then
printf 'use crate::platform::compat::helper::current_user;\n' > "$a10probe"
before=$FAIL
check_ar10 >/dev/null 2>&1
caught=0
[ "$FAIL" -gt "$before" ] && caught=1
rm -f "$a10probe"
FAIL=$before
if [ "$caught" -eq 1 ]; then
echo "✅ 反自证通过:AR10 抓到了平台层里的 crate::platform::compat"
else
echo "❌ 反自证失败:AR10 没抓到平台层的契约面反向依赖 ⇒ 尺子是假的"
rc=1
fi
else
echo "⏭ 跳过 AR10 反自证(平台层目录不存在)"
fi
echo "── 反自证 6/6:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
#
# 🔴 造在**临时副本**上:不动真文件(helper.rs 是 900+ 行的活文件)。
local a11dir="$KERNEL/src/platform/compat"
local a11probe="$a11dir/__ar11_selftest.rs"
if [ -d "$a11dir" ] && [ -f "$a11dir/helper.rs" ]; then
# 🔴 AR11 只扫 `helper.rs` ⇒ 探针必须是 helper.rs 本身。
# 做法:备份真文件 → 追加违规行 → 跑判据 → 还原。
cp "$a11dir/helper.rs" "$a11dir/helper.rs.bak"
printf '\nuse super::system::menu_node;\n' >> "$a11dir/helper.rs"
before=$FAIL
check_ar11 >/dev/null 2>&1
caught=0
[ "$FAIL" -gt "$before" ] && caught=1
mv "$a11dir/helper.rs.bak" "$a11dir/helper.rs"
FAIL=$before
if [ "$caught" -eq 1 ]; then
echo "✅ 反自证通过:AR11 抓到了契约面底座里的 use super::system"
else
echo "❌ 反自证失败:AR11 没抓到底座的反向依赖 ⇒ 尺子是假的"
rc=1
fi
else
echo "⏭ 跳过 AR11 反自证(契约面目录或 helper.rs 不存在)"
fi
return $rc
}
@@ -459,6 +601,8 @@ check_ar6
check_ar7
check_ar8
check_ar9
check_ar10
check_ar11
check_pack1
check_mem1
check_mem2