Files
ssw-platform/docs/CRATES-MIGRATION.md
admin acf076df5a refactor: 内核瘦身 —— 示例搬成业务包 + 装配/测试各归其位
- 内核只有 lib:启动装配 → crates/sspf-admin(bin sspf-admin);37 个集成测试 → crates/tests(package sspf-tests)。
- demo/shop/books 的 spec/菜单/DDL/面 B 路由搬进 packs/{demo,shop,books};内核 modules/*.rs 只剩「面 A 适配器 + pub use」⇒ 内核零业务知识,示例可整目录搬走。面 A 与前端零改动。
- 示例表 DDL 按平台规则补 f_tenant_id + 复合主键(spec 不加 ⇒ JSON 键与响应逐字不变)。
- 修 is_builtin_table 只认 schema.sql 的漏洞:包表(含 asset_data_resource)此前可被建模页删除/改;现为「平台 DDL ∪ 包表」。
- sspf-compat-online_dev → onlinedev(包名/模块/文件/路由别名同步);6 个 5 行转发壳合并为 forward.rs。
- 新增 AR16 闸门 + lib.rs「30 秒地图」+ src/backend/README.md;pack-sync 补两处判据(module_key=None 的 urlAddress、apiFile 查存在性)。
- 回归:704 tests / 6 道静态闸门全绿;health 181 表;四个包面 A/面 B 运行时全部 200。
2026-11-04 14:46:12 +08:00

50 KiB
Raw Permalink Blame History

CRATES-MIGRATION —— 「只留壳装配,平台能力全部迁到 crates/」迁移计划

基线锚点:v0.1.0(commit b957a11,已推送到 origin) 制定时间:2026-11-03 状态:M5 已完成(tag v0.1.5-m5)—— 低代码执行层(4 个模块 / 2,674 行)下沉完成; 四个决策已拍板(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。 下一步 = M6(sspf-mcp-adapter)


0. 一句话目标

把 src/backend/ 里的 90,471 行平台能力全部搬进 crates/, 让 src/backend/ 只剩启动装配 + 路由注册(薄壳), 对齐 ssw-mvp/boot 的「薄壳 + 能力包」形态。


1. 现状盘点(v0.1.0 快照)

1.1 行数分布

位置 行数 占比 归属判断
crates/(7 个包) 17,174 16% ✅ 已是能力包形态
src/backend/src/platform/compat/ 48,980 54% ❌ 契约面 handler 压在内核
src/backend/src/platform/(非 compat) 6,598 7% ❌ 平台核心压在内核
src/backend/src/lowcode_*.rs 2,674 3% ❌ 执行层压在内核
src/backend/src/mcp_*.rs 3,283 4% ❌ 适配层压在内核
src/backend/src/{routes,main,bootstrap,lib,packs_gen}.rs 5,664 6% ✅ 这就是要保留的壳
src/backend/src/modules/ 900 1% ⚠️ 业务层,保留在壳侧
src/backend/tests/ 23,272 — 集成测试,随壳走

结论:壳只占 6%。目标是把这 6% 之外、且属于「平台能力」的部分(≈61,500 行)全部搬进 crates/。

1.2 基线绿灯(打 tag 时的实测值)

cargo test --workspace   → 695 passed / 0 failed
scripts/check-arch.sh     → 12 通过 / 0 失败 / 0 跳过
cargo build --workspace  → 成功

这三条是整个迁移的回归基准,任何一步做完都必须重跑并保持一致。

1.3 现有 crates 与职责

crate 行数(src) 依赖白名单 职责
sspf-contract 646 serde/serde_json/uuid/http 契约类型、码表、判别头、EntitySpec/Route
sspf-sdk 184 sspf-contract 业务包唯一入口(AR1)
sspf-store 1,685 pglite/tokio/serde/chrono 存储层:db + config(不认识 HTTP)
sspf-lowcode 6,261(+803 tests) sspf-contract/serde 低代码纯计算:解析/校验/SQL 生成
sspf-mcp 5,619 sspf-contract/serde/tokio MCP 协议 + 工具契约 + PlatformAdapter trait
sspf-plugin 780 sspf-sdk/sspf-contract 业务包装载器(L2 静态)
sspf-adapter-baseline 1,078 sspf-mcp/http/hyper 基线 Java 后端 HTTP 适配器

另:crates/sspf-lowcode/tests/ = 803 行(低代码 fixture 与单测)。


2. 🔴 三个必须先解开的循环依赖

这是整个迁移的技术核心。 crate 之间不允许循环依赖(Rust 编译器直接报错), 而当前代码里有 3 处 循环。不解开,第一步就会编译失败。

2.1 循环 A:platform/auth.rs ↔ platform/compat/helper.rs ⛔ 最难

auth.rs:336   crate::platform::compat::helper::is_face_b(&headers)
auth.rs:337   crate::platform::compat::helper::current_user(state, &headers).await
auth.rs:403   crate::platform::compat::helper::is_face_b(headers)

helper.rs:22  use crate::platform::auth::require_login_face_b;
helper.rs:23  use crate::platform::auth::resolve_user;

解法:面 B 判定已经在 contract 层了 —— 这是个好消息,改动量比预想小得多。

crates/sspf-contract/src/headers.rs:32
  pub fn is_face_b(headers: &HeaderMap) -> bool   # 已有,且带 3 条单测

当前 crates/sspf-compat-core/src/helper.rs:87-91(M3 起真源在此)只是一个转发壳:

pub fn is_face_b(headers: &HeaderMap) -> bool {
    sspf_contract::headers::is_face_b(headers)
}

⇒ auth.rs 改一行就能断环:

// auth.rs:336
- if crate::platform::compat::helper::is_face_b(&headers) {
+ if sspf_contract::headers::is_face_b(&headers) {

循环 A 至此只剩一半:auth 不再依赖 compat ✅,但 helper.rs 仍依赖 auth::{require_login_face_b, resolve_user}(反向单向,合法)。

⚠️ 仍需处理的残余:auth.rs:337 调用 compat::helper::current_user(面 B 形状)。 这是 auth → compat 的第二条边,断不掉 —— 除非把面 B 的 current_user 实现 下沉到 compat 包并让 auth 通过回调/trait取得,或反过来: 把 current_user 的面 B 分流逻辑改为「auth 提供通用骨架 + compat 提供形状适配」。

推荐解法:auth 侧只保留「判定 + 取 user」, 面 B 的 PcUserVO 形状组装整体搬进 compat 包(M4 时迁走), auth 侧的 current_user 改为按面分流:

  • 面 A ⇒ auth 内部实现(现状)
  • 面 B ⇒ 由 compat 包注册的 handler 提供

工程手法(避免 trait object 复杂度):把面 B 的 current_user 整体搬到 compat 包,auth 侧的 current_user 只留面 A 分支, 面 B 分支改为查一张「面 B current_user 处理器」注册表(OnceLock 静态表, 由壳在启动时注册)⇒ 运行时单向,编译期无环。

2.2 循环 B:compat/helper.rs ↔ compat/system.rs

helper.rs:31  use super::system::{menu_node, official_view_path};
system.rs:26  use super::helper::{EN_MENU, EN_USER, ..., guard, guard_any, ...};

解法:两者必须拆成两个 crate,或下沉公共部分。

  • system.rs(17,539 行):菜单树 / 字典 / 用户 / 日志 / 系统配置
  • helper.rs(902 行):公共底座(守卫 / 分页 / 参数解析 / VO 构造)

依赖广度证据(实测,14/14 个 compat 模块都依赖 helper):

ai.rs:1  extend.rs:1  message.rs:1  mobile.rs:1  msg_center.rs:1
onlinedev.rs:1   permission.rs:1  report.rs:1  res.rs:1
scheduletask.rs:1  system.rs:1  teamwork.rs:1  visualdata.rs:1  workflow.rs:1

⇒ helper 必须是所有 compat 包的公共底座 ⇒ 它必须独立成一个 crate。

helper.rs 依赖 platform/auth + platform/authorization + platform/crud + platform/db ⇒ 它不是纯契约层,得是一个能依赖 axum 的 crate。 决策:新建 crates/sspf-compat-core(依赖 axum + sspf-core + sspf-contract + sspf-store), 承载 helper + 通用守卫 + VO 构造。

注意:helper.rs 里的 menu_node / official_view_path(来自 system) 与 USER_DETAIL_COLUMNS / organize_name_of(来自 permission)要搬回各自的包 —— 否则 compat-core 反过来依赖 system/permission ⇒ 环只是换了个位置。

2.3 循环 C:compat/helper.rs ↔ compat/permission.rs

helper.rs:32        use super::permission::{USER_DETAIL_COLUMNS, organize_name_of};
permission.rs:29    use super::helper::{...};   // ← 22 个符号

解法:与 2.2 同源 —— helper 下沉成独立 crate 后, USER_DETAIL_COLUMNS(一个 SQL 列清单常量)与 organize_name_of(一个查询函数) 随 permission 留在 permission 包,helper 反过来依赖 permission ⇒ 单向。

⚠️ 这会让 helper → permission,而 permission → helper 的 22 个符号必须全部从 helper 侧消失 ⇒ 需要逐个确认它们各自归属哪个包。 本项是迁移中工作量最大的一步,建议单独排一个批次。

2.4 循环汇总与解法

环 涉及 解法 难度
A auth ↔ compat/helper ✅ sspf_contract::headers::is_face_b 已存在 ⇒ 判定边改一行断掉;面 B current_user 的分流点上移到装配根 routes.rs 🟡 中(比预想低)
B compat/helper ↔ compat/system ✅ menu_node / official_view_path 搬进 helper(它们只依赖 helper 自己的东西) 🟢 低(已解)
C compat/helper ↔ compat/permission ✅ USER_DETAIL_COLUMNS / organize_name_of 搬进 helper(helper 已有 Db 依赖) 🟢 低(已解)

✅ 三个环已于 M1 全部解开(详见 §4 M1 实际做法表)。 好消息:三个环全部集中在 compat/ 内部 + auth 一处, 而 platform/ 其它 17 个文件(auth/session/crud/sys/…)互相之间没有环 ⇒ M2(核心下沉)不受环影响,可以独立推进。


2.5 环的完整证据(实测,非推断)

# 循环 A(auth → compat)
auth.rs:336    if crate::platform::compat::helper::is_face_b(&headers) {
auth.rs:337        return crate::platform::compat::helper::current_user(state, &headers).await;
auth.rs:403    if crate::platform::compat::helper::is_face_b(headers) {
# compat → auth(反向边)
helper.rs:22   use crate::platform::auth::require_login_face_b;
helper.rs:23   use crate::platform::auth::resolve_user;

# 循环 B
helper.rs:31   use super::system::{menu_node, official_view_path};
system.rs:26   use super::helper::{EN_MENU, EN_USER, ..., guard, guard_any, ...};

# 循环 C
helper.rs:32   use super::permission::{USER_DETAIL_COLUMNS, organize_name_of};
permission.rs:29  use super::helper::{...22 个符号...};

已验证 platform/ 内部无环(实测依赖图):

auth → authorization/cipher/db/envelope/registry/session/state
session → cipher
authorization → db
crud → auth/authorization/db/entity/envelope/ids/registry/route/session/state
registry → authorization/db
state → config/db/session
sys → auth/cipher/db/envelope/ids/state
seed → cipher/db/ids/menu/registry

⇒ 全部单向向下,无回边 ✅ ⇒ M2 可独立推进。


3. 目标形态

ssw-platform/
├── Cargo.toml                     # workspace 根(members 自动含 crates/*)
├── crates/                        # 【平台能力包】全部在这里
│   ├── sspf-contract/             # 契约类型 + 面 B 判定(is_face_b)+ 码表
│   ├── sspf-sdk/                  # 业务包唯一入口(AR1 不变)
│   ├── sspf-store/                # 存储层(db + config)
│   ├── sspf-lowcode/              # 低代码纯计算
│   ├── sspf-mcp/                  # MCP 协议层
│   ├── sspf-plugin/               # 业务包装载器
│   ├── sspf-adapter-baseline/     # 基线 Java 适配器
│   │
│   ├── 🆕 sspf-core/              # 平台核心:auth/session/authorization/crud/sys/menu
│   │                               #   (依赖 axum + store + contract)
│   ├── 🆕 sspf-compat-core/       # 契约面公共底座:helper/守卫/VO/参数解析
│   ├── 🆕 sspf-compat-system/     # 契约面:system(菜单/字典/用户/日志)
│   ├── 🆕 sspf-compat-permission/ # 契约面:permission(用户/角色/机构/授权)
│   ├── 🆕 sspf-compat-workflow/   # 契约面:workflow + report + visualdata
│   ├── 🆕 sspf-compat-msg/        # 契约面:message + msg_center + scheduletask
│   ├── 🆕 sspf-compat-ext/        # 契约面:extend + teamwork + ai + mobile + core + res
│   └── 🆕 sspf-compat-onlinedev/  # 契约面:onlinedev(官方 onlineDev)
│
├── packs/                         # 【业务包】不变
└── src/backend/                   # 【薄壳】只剩这些
    ├── Cargo.toml
    ├── src/
    │   ├── main.rs                # 启动装配(1,108 行)
    │   ├── lib.rs                 # 模块清单
    │   ├── routes.rs              # 路由注册(3,249 行 —— 引用各 compat 包)
    │   ├── bootstrap.rs           # 装配根(320 行)
    │   ├── packs_gen.rs           # 生成物
    │   ├── modules/               # 业务层(900 行)
    │   └── platform/              # 🔴 只剩 re-export 转发壳(保持旧路径不破)
    └── tests/                     # 集成测试(跟着壳走)

壳的判定标准:能搬到 crates/ 且不属于业务的,全部搬走; src/backend/ 里保留的代码必须是「装配」或「转发」。


4. 迁移顺序(7 个批次,每批独立可交付、可回滚)

原则:每批次结束必须 cargo test --workspace 全绿 + check-arch.sh 全绿 + verify.sh --smoke 全绿。 不合批:编译不过的中间态不进主干(用 feature flag 或分支)。

批次 M1 —— 解开三个循环(不改目录结构,只改代码)

目标:消除 A/B/C 三个环,但代码仍在 src/backend/ 里(用模块重命名,不搬 crate)。

# 动作 文件:行 断掉的边 实际做法
1 auth.rs 改用 sspf_contract::headers::is_face_b(已存在) platform/auth.rs auth → compat(判定边) ✅ 直接调契约层,不绕 compat
2 同上(require_login_any) platform/auth.rs auth → compat(判定边) ✅ 同上
3 面 B current_user 的分流点上移到装配根 platform/auth.rs + routes.rs:77 auth → compat(形状边) ✅ 不用注册表 —— 分流点移到 routes.rs(壳)
4 resolve_user 提为 pub platform/auth.rs 供 compat 侧跨 crate 调用 ✅ pub(crate) → pub
5 menu_node 搬进 helper compat/system.rs → compat/helper.rs 环 B ✅ 它只依赖 helper 自己的 menu_value + MAX_TREE_DEPTH
6 official_view_path 搬进 helper compat/system.rs → compat/helper.rs 环 B ✅ 纯字符串函数,无依赖
7 USER_DETAIL_COLUMNS 搬进 helper compat/permission.rs → compat/helper.rs 环 C ✅ helper 已有 Db 依赖
8 organize_name_of 搬进 helper compat/permission.rs → compat/helper.rs 环 C ✅ 同上

✅ M1 已完成(2026-11-03):695 测试全绿 / 14 道闸门全绿 / verify.sh --smoke 14 步全绿。 tag = v0.1.1-m1。

🔴 实际做法与原计划的差异(两处,都是「更简单」):

  1. 不用运行期注册表(原计划第 3 项):改为把分流点上移到装配根 routes.rs。 这更好 —— CLAUDE.md §4 本来就写明「共用两条路由按判别头分流」, 分流点本就该在壳;而且没有 OnceLock 静态槽位、没有注册时机、没有漏注册的风险。 平台层与契约面从此互不知道对方,壳负责接线。
  2. 不用新建 compat_base/ 目录(原计划第 5 项):改为把 4 个符号搬进 helper 本身。 helper 已经是「底座」,把这 4 个纯函数/常量放进去不增不减; 而新建目录要多一层 crate 边界,M3 拆 crate 时再切更省事。

🔴 环 B/C 的方向修正:原计划说「把符号搬回 system / permission 侧」, 实际是搬进 helper —— 因为 helper 被 14 个模块依赖, 符号在 helper 里 ⇒ 所有模块都能用;符号在 system/permission 里 ⇒ helper 又得依赖它们 ⇒ 环还在。

出口判据(全部已达成):

  • cargo build --workspace 通过(零警告)
  • 695 测试仍全绿(cargo test --workspace = 695 passed / 0 failed)
  • grep -rn "crate::platform::compat" src/backend/src/platform/ → 仅剩注释命中
  • grep -rn "use super::system\|use super::permission" src/backend/src/platform/compat/helper.rs → 零命中
  • check-arch.sh → 14/14(新增 AR10/AR11)
  • check-arch.sh --self-test → 6/6 反自证通过
  • verify.sh --smoke → 14 步全绿

🆕 M1 顺带加的两条防回退闸门

判据 守护什么 反自证
AR10 platform/**(不含 compat/)不许 use crate::platform::compat ✅ 造 use crate::platform::compat::helper::current_user; 必被抓
AR11 compat/helper.rs 不许 use super::<别的模块> ✅ 造 use super::system::menu_node; 必被抓

🔴 为什么必须现在就钉:拆 crate 是渐进的 —— 在 M2 拆完之前, 把那行加回去照样编译通过、测试照样全绿,只有到 M2 那天才炸 ⇒ 那时已改了一堆东西。 ⇒ 现在就拦住。

批次 M2 —— 平台核心下沉:sspf-core ✅ 已完成(tag v0.1.2-m2)

迁入:platform/{auth,authorization,cipher,config,crud,db,entity,envelope,guard,ids,menu,monitor,registry,route,seed,session,state,sys,variate_catalog}.rs(19 个模块,全部 git mv 保留历史)

新 crate:crates/sspf-core(依赖 sspf-contract / sspf-store / axum / tokio / serde / serde_json / chrono / rand / libc)

保留转发壳:src/backend/src/platform/*.rs 全部改成 pub use sspf_core::<mod>::*; ⇒ 上层零感知(测试、routes、modules 全部不用改 import)。

🔴 state.rs(AppState)是关键:config/db/sessions/tickets 四个 Arc。 它必须跟着 core 走(compat 包也要用 AppState)⇒ 放在 sspf-core 最底部。

实际做法(与原计划的差异):

  1. pub(crate) → pub:跨 crate 后 pub(crate) 失效 —— crud::{handle_list,handle_save,handle_delete,handle_*_face_b,value_to_text}、auth::{client_ip,parse_user_agent}、sys::query_param 共 10 处提为 pub。
  2. 测试归属跟着依赖走:crud.rs 的 3 个测试原依赖 crate::modules::all_specs()(业务层)⇒ core 不能反向依赖业务层。解法:改用契约层合成 spec(同表结构、无业务知识)做参数化测试,断言强度不降;顺带发现 write_cast 的 numeric 映射是列名枚举(f_price/f_stock)而非 spec 声明 ⇒ 记为技术债(现有列名恰好都叫 f_price 未暴雷,新表带 f_amount 会静默出错)。
  3. registry.rs 测试自建库:不再经 bootstrap::ensure_base(那是装配根、认识业务层),改 seed::ensure_base(db, &[])(无业务菜单)⇒ 断言仍是主系统 5 条内置菜单(m_sys/m_user/m_role/m_org/m_menu)。
  4. test_support.rs 留壳层:它依赖 bootstrap::ensure_schema_all(认识业务 DDL)⇒ 不进 core。
  5. 路径改写:crate 内 crate::platform::X → crate::X(compat 除外,那是 M3/M4 的)。

闸门改造(🔴 本批次最大风险,不是代码是闸门): 搬迁后 platform/ 只剩转发壳(pub use,无函数体)⇒ 闸门扫空壳 = 虚假安全感。同步改造 5 处:

闸门 原路径(写死) 改造后
check-arch.sh AR9/AR10 $KERNEL/src/platform 两处都扫:crates/sspf-core/src(真源)+ platform/(壳)
check-arch.sh 反自证 2/6、5/6 只注入壳目录 两处都注入,且按路径分别验(单点注入会漏判)
check-boundary.sh CP1/CP2/CP6 $SRC/platform 新增 PLATFORM_CORE;CP6 的 seed.rs 改读真源
check-contract-scan.py plat_files 只收 platform/*.rs 两处都收,重名键拼接(否则守卫推不出 ⇒ CC6 退化成 WARN)
check-module.sh CRUD $BACKEND/src/platform/crud.rs 改读 crates/sspf-core/src/crud.rs(软删契约要看 SQL)
gen-function-catalog.py OUT platform/variate_catalog.rs 改写 crates/sspf-core/src/variate_catalog.rs(否则覆盖转发壳)

反向验证(证明闸门真在扫真源,不是碰巧通过):只往 crates/sspf-core/src/ 塞 use sspf_pack_asset::… / use crate::platform::compat::… ⇒ AR9/AR10 都报红;探针已清干净。

出口判据(全部达成):

  • src/backend/src/platform/*.rs 每个文件 ≤ 10 行(纯 re-export)
  • cargo build --workspace 零警告
  • cargo test --workspace 695 passed / 0 failed(与基线一致)
  • check-arch.sh 14/14;--self-test 6/6
  • check-boundary.sh 11/11;check-contract.sh 10/10(反自证 12 例全过)
  • check-module.sh 123/123;check-citations.sh 4/4
  • verify.sh --smoke 14 步全绿(512.3s)

批次 M3 —— 契约面公共底座:sspf-compat-core ✅ 已完成(tag v0.1.3-m3)

迁入:platform/compat/helper.rs(994 行)+ platform/compat/res.rs(460 行)→ crates/sspf-compat-core/src/

新 crate:crates/sspf-compat-core(依赖 sspf-core + sspf-contract + axum + serde + serde_json)

保留转发壳:src/backend/src/platform/compat/{helper,res}.rs = pub use sspf_compat_core::<mod>::*; ⇒ 14 个契约面模块的 use super::helper::{…} 零感知(M4 才统一改 import)。

实际做法:

  1. 路径改写:crate::platform::X → sspf_core::X(本 crate 是独立 crate,不能用 crate::X);res.rs 的 super::helper → crate::helper。
  2. pub(super) → pub(54 处):转发壳的 pub use …::* 只转发 pub 项 ⇒ 不提权则 14 个模块找不到 EN_USER/Paging/MenuRow 等(含 struct 字段)。
  3. 测试随迁:helper 的 8 个单测(判别头 / PageListVO / ListVO / Paging / 菜单 15 字段)自足(只用 super::*)⇒ 随文件进新 crate,总测试数不变 695。

闸门改造(同 M2 纪律 = 两处都扫):

闸门 改造
check-arch.sh AR11 扫真源 crates/sspf-compat-core/src/helper.rs + 壳;新增 Cargo.toml 级判据(sspf-compat-core 不许依赖 sspf-compat-*,M4 的 6 个包)
check-arch.sh 反自证 6/6 两处都注入探针(真源 + 壳),按路径分别验
check-contract-scan.py plat_files 的 compat__<mod> 收真源 + 壳同键拼接 —— 守卫常量(EN_ROLE 等)在 helper 真源里,漏收则 CC6 假漂移
docs/CRATES-MIGRATION.md 引文(旧壳 compat/helper.rs 89-92 行)→ crates/sspf-compat-core/src/helper.rs:87-91

反向验证:只往真源 helper 塞 use crate::res::Res; ⇒ AR11 报红;清理后恢复绿。

🔴 踩坑(已记入记忆):反向验证后用 git checkout -- <file> 清理探针 ⇒ 把 M3 的改写一并回退到暂存区(crate::platform×14、pub(super)×54 复活)。教训:有未暂存改动的文件绝不能用 git checkout -- 清理 ⇒ 用 Python 精确删探针行。

出口判据(全部达成):

  • cargo build --workspace 零警告
  • cargo test --workspace 695 passed / 0 failed(与基线一致)
  • check-arch.sh 14/14;--self-test 6/6
  • check-boundary.sh 11/11;check-contract.sh 10/10(守卫推导仍有效,CC6 零漂移)
  • check-module.sh 123/123;check-citations.sh 4/4
  • verify.sh --smoke 14 步全绿(561.3s)

批次 M4 —— 契约面业务包(6 个并行包)✅ 已完成(tag v0.1.4-m4)

按依赖顺序切,每个包 = 若干 compat/<模块>.rs:

新 crate 含文件 行数 依赖
sspf-compat-system system + scheduletask + core 17,505 + 1,163 + 1,096 compat-core + core + store + chrono
sspf-compat-permission permission 6,266 compat-core + core + system + store + chrono
sspf-compat-msg message + msg_center 2,662 + 3,391 compat-core + core + chrono
sspf-compat-workflow workflow + report + visualdata 4,171 + 1,438 + 3,120 compat-core + core + chrono + aes/ecb/hex
sspf-compat-ext extend + teamwork + ai + mobile 2,073 + 3,479 + 1,377 + 1,213 compat-core + core + system + msg + chrono
sspf-compat-onlinedev onlinedev 3,175 compat-core + core

合计 14 个模块 / ~49,000 行。原 src/backend/src/platform/compat/<模块>.rs 全部变成 5 行转发壳(pub use sspf_compat_<域>::<模块>::*;)。

⚠️ 实际做法与原计划的差异(实测依赖图得出,非拍脑袋):

计划 实际 为什么
system 只含 system.rs 追加 scheduletask + core 这两个模块不依赖任何其它契约面模块 ⇒ 与 system 同属「无跨包依赖」组,合并可少一条 crate 边
msg 含 scheduletask scheduletask 归 system 同上
ext 含 core core 归 system 同上
sspf-compat-online-dev sspf-compat-onlinedev 🔴 Rust 包名不能带连字符(use sspf-compat-online-dev::… 编译不过)⇒ 目录名与包名都去连字符。2026-11-04 二次改名:中间态曾叫 sspf-compat-online_dev(下划线版),与官方 onlineDev 拼写不一致、也与同族 sspf-compat-{system,ext} 的「去分隔符」惯例不符 ⇒ 统一为 onlinedev(模块名/文件名同步)
6 包互相独立 3 条单向跨包依赖 实测扫描得出:permission→system(4 符号)、mobile→system+mobile→msg(2 函数)。方向单一 ⇒ 不成环

新增 AR12(防环回流闸门):crates/sspf-compat-* 之间不许互相依赖,白名单只放那 3 条单向边(permission→system、ext→system、ext→msg)。判据在 Cargo.toml 级(不是 grep 源码)⇒ 改依赖即被抓。

🔴 本批踩的三个坑(都是「尺子是假的」):

  1. CC6 守卫推导静默失效:M4 搬迁后 check-contract.sh 首次跑就 10/10 全绿(M2/M3 都报红)⇒ 可疑。核实 check-contract-scan.py 的 compat_dirs 只收了 sspf-compat-core,六个域包真源没收 ⇒ 守卫推导读的是转发壳(无函数体)⇒ 尺子已废。 修复:动态收编所有 crates/sspf-compat-*/src(写死路径列表必然在某次新增包时漏掉 ⇒ 用 glob)。反向验证:把真源 permission.rs:135 的 EN_ROLE 改成 EN_ACTION ⇒ CC6 精确报出「GET /api/permission/Role:契约写 permission.role,代码是 permission.action」;还原后恢复 10/10。

  2. CP1 业务标识符未扫契约面包:check-boundary.sh 的 CP1/CP2 只扫 sspf-core + platform/。修复:新增动态 COMPAT_DIRS 并纳入。反向验证:往 crates/sspf-compat-msg/src/msg_center.rs 插入 const LEAK_PROBE: &str = "demo_item"; ⇒ CP1 精确报出该行;还原后恢复 11/11。

  3. 🔴 macOS 的 BSD grep 不支持 \s(POSIX ERE)—— AR11 的 Cargo.toml 级判据和 AR12 都写成 grep -E '^\s*sspf-compat-...' ⇒ 永远匹配不到 ⇒ 永远"通过"。这是 AR12 反自证第一次跑就失败暴露的("尺子是假的")。 修复:全部改成 POSIX 字符类 [[:space:]]。全仓扫了一遍 scripts/*.sh,只有这一处(注释里还有一处,不影响执行)。 🔴 教训:闸门判据里的正则必须用反自证验证过一次才敢信 —— grep 不报错、退出码 0、ok 打印 ⇒ 三重「看起来正常」。

出口判据(全部达成):

  • 6 个 crate 各自 cargo build -p 通过;cargo build --workspace 零警告
  • cargo test --workspace = 695 passed / 0 failed(与 M1 基线完全一致)
  • check-arch.sh = 15/15(新增 AR12);--self-test = 7/7(新增 AR12 反自证)
  • check-boundary.sh = 11/11
  • check-contract.sh = 10/10(反自证 12 例全过)
  • check-module.sh = 123/123
  • check-citations.sh = 4/4(引文路径改到新真源,行号 1:1 未变 ⇒ 迁移是纯搬运)
  • check-naming.sh = 3 通过 / 0 失败 / 1 提示
  • verify.sh --smoke 14 步全绿(300.9s)

批次 M5 —— 低代码执行层下沉 ✅ 已完成(tag v0.1.5-m5)

迁入:lowcode_{crud,ddl,check,seed}.rs(2,674 行)

新 crate:crates/sspf-lowcode-exec

依赖 为什么
sspf-lowcode 纯计算层(解析/校验/SQL 生成)—— AR7 白名单不动,它仍是纯计算
sspf-core Db / ids::new_uuid / config::Profile / registry::MAIN_SYSTEM_ID
sspf-store Db / pglite 的真源(sspf-core::db 只是转发壳)
sspf-mcp ToolError —— 执行失败要能变成给 AI 看懂的结构化错误
pglite-rs + chrono + serde_json 真实库 / 时间戳 / JSON

sspf-lowcode(纯计算)不动 —— AR7 白名单保持不变。 新 crate 是「执行层」,允许依赖 DB。

实际做法与原计划的差异:

计划 实际 为什么
依赖 {lowcode, core, store, mcp} 多了 pglite-rs + chrono + serde_json ① pglite::ToSql / pglite::Error 是直接用的(不是只经 Db);② now_iso() 用 chrono::Local::now();③ JSON payload 转换
— 未提权任何 pub(crate) 与 M3/M4 不同:这四个模块的对外接口本来就是 pub ⇒ 一行可见性改动都没有
— crate::platform::X → sspf_core::X(5 处) 独立 crate 不能用 crate::X 跨模块访问
— crate::lowcode_X 不改(8 处) ⚠️ 模块名在新 crate 里没变(仍是 lowcode_crud / lowcode_ddl / lowcode_check)⇒ 改了就编译不过

新增 AR13(两层判据):

  1. crates/sspf-lowcode-exec/Cargo.toml 的依赖 ⊆ {sspf-lowcode, sspf-core, sspf-store, sspf-mcp, pglite-rs, chrono, serde_json} —— 不许 axum(web 框架)⇒ 这层就还能被 CLI / MCP / 离线工具复用;
  2. 该 crate 源码里不许 use sspf_pack_*(业务知识不许漏进平台层)。

闸门改造:

  • check-arch.sh 新增 AR13(两层)+ 反自证 8/8(两处都注入:越界依赖 axum + 业务包引用 use sspf_pack_asset::…,且按路径分别验)。
  • check-boundary.sh 新增 LOWCODE_EXEC ⇒ CP1(业务标识符)/ CP2(use crate::modules)都纳入执行层真源。 反向验证:往 crates/sspf-lowcode-exec/src/lowcode_check.rs 插 const LEAK_PROBE: &str = "demo_item"; ⇒ CP1 报红(PASS=10/FAIL=1);还原后恢复 11/11。

🔴 本批的一个坑(比 M4 轻,但同一类):

  • 改写时把 use crate::lowcode_ddl; 一并改成了 use crate::ddl; ⇒ 编译报 cannot find module or crate lowcode_ddl。 教训:改写规则必须区分「路径前缀变了」与「模块名变了」 —— 本次只有 crate::platform:: → sspf_core:: 该改,crate::lowcode_* 的模块名没变不该改。 同理 [crate::lowcode_crud] 这种文档内链也不能跟着改(改了就变成死链)⇒ 已单独修回。

出口判据(全部达成):

  • cargo build --workspace 零警告;cargo test --workspace = 695 passed / 0 failed(与 M1 基线完全一致)
  • check-arch.sh = 17/17(新增 AR13);--self-test = 8/8(新增 AR13 反自证)
  • check-boundary.sh = 11/11(CP1/CP2 已覆盖执行层)
  • check-contract.sh = 10/10(反自证 12 例全过)—— 契约里零 lowcode 端点(低代码是 MCP 工具不是 HTTP 路由)⇒ 本批不受影响
  • check-module.sh = 123/123;check-citations.sh = 4/4(零条引文指向 lowcode 旧路径)
  • check-naming.sh = 3 通过 / 0 失败 / 1 提示
  • verify.sh --smoke 14 步全绿(377.6s)

批次 M6 —— MCP 适配层下沉 ✅ 已完成

迁入:mcp_adapter.rs(2,652 行)+ mcp_compat.rs(631 行)⇒ 共 3,283 行

新 crate:crates/sspf-mcp-adapter(依赖 sspf-mcp + sspf-core + sspf-compat-{system,permission,workflow,onlinedev} + sspf-lowcode + sspf-lowcode-exec + axum + pglite-rs)

🔴 mcp_compat.rs 直调 platform::compat::* 的 handler ⇒ 它依赖所有 compat 包。 这是唯一「知道全部包」的 crate ⇒ 它属于壳还是能力? 决策:放 crates/(它是「MCP 适配」这一项独立能力),但放在最后一批。

实际落地:

  • 壳侧 src/backend/src/mcp_{adapter,compat}.rs 变成转发壳(pub use sspf_mcp_adapter::<模块>::*) ⇒ main.rs 的 mcp_adapter::NativeAdapter::new(state) 与 tests/mcp_tools_it.rs 的 use ssw_platform::mcp_adapter::NativeAdapter 零改动。
  • 跨 crate 路径改写:crate::platform::… → sspf_core::… / sspf_compat_<域>::<域>::…; crate::lowcode_{crud,ddl}:: → sspf_lowcode_exec::lowcode_{crud,ddl}::。 🔴 只改路径前缀、模块名不变(M5 的教训:crate::lowcode_ddl 不能改成 crate::ddl)。

🔴 本批的一个发现(闸门暴露的既有问题): 把新 crate 纳入 CP1 扫描面后,CP1 立刻抓到 5 处业务标识符泄漏 (permission.asset.dataResource / asset/DataResource / asset_data_resource)—— 它们在 mcp_adapter.rs 的 hint 提示语与单测断言里,此前不在扫描面内所以一直隐形。 ⇒ 已全部改成通用形态(permission.<模块>.<资源> / <模块>/<资源> / data_resource)。 这正是「闸门必须与迁移同步改」的价值:不扩扫描面 ⇒ 这 5 处会跟着代码搬进 crates 继续潜伏。

出口判据:

  • cargo build --workspace 零警告
  • cargo test --workspace = 695 passed / 0 failed(与 M1 基线完全一致)
  • check-arch.sh = 19/19(新增 AR14);--self-test = 9/9(新增 AR14 反自证)
  • check-boundary.sh = 12/12(CP1/CP2 纳入适配层 + 新增 CP1'' 扫描面反自证)
  • check-contract.sh = 10/10(反自证 12 例全过)
  • check-module.sh = 123/123;check-citations.sh = 4/4
  • check-naming.sh = 3 通过 / 0 失败 / 1 提示

批次 M7 —— 收口:删转发壳 + 闸门去壳路径 ✅ 已完成(tag v0.1.7-m7)

改了什么

项 数量 说明
删除 src/backend/src/platform/ 38 个转发壳 平台能力只有真源(在 crates/),壳层不再存在
改写 crate::platform::X 44 处 / 9 文件 → sspf_core::X(compat / test_support 除外)
改写 ssw_platform::platform::X 229 处 / 38 文件 → sspf_core::X(含 37 个集成测试文件)
新增 src/backend/src/compat.rs 1 个别名表 16 个契约面域聚成 compat::<域>::<handler>
移动 platform/test_support.rs 1 个文件 → src/backend/src/test_support.rs(依赖装配根 ⇒ 留壳侧)

🔴 关键决策:为什么保留 compat::<域>:: 这条路径(而不是 1,010 处全改)

routes.rs 里 compat::<域>::<handler> 有 1,010 处。逐处改成 sspf_compat_system::system::<handler> 看着「更干净」,但代价是:

  • 契约扫描器的 plat_key 推导规则要跟着改(尺子的命脉);
  • 契约文档里的路径全部要改;
  • 风险面放大 10 倍。

⇒ 改用别名表(src/backend/src/compat.rs,16 个域各一条 pub use): 只改 1 个文件,1,010 处路由注册一字不动 ⇒ 尺子的推导规则不变。

🔴 M7 的核心技术风险(已提前修掉)

契约扫描器原本用「路径段数」判定「这是不是契约面」(两段 ⇒ 契约面,一段 ⇒ 平台核心)。 M7 把平台核心也变成两段(sspf_core::sys::user_list)⇒ 旧规则会把它误判成契约面 ⇒ plat_key 从 sys 变成 compat__sys ⇒ 守卫推不出来 ⇒ CC6 静默退化成「全是 WARN」 ⇒ 尺子变瞎(实测已验证:sspf_core::sys::user_list ⇒ plat_key=compat__sys)。

⇒ 新规则改为按 crate 名判定(derive_plat_key):第一段是 sspf_compat_* ⇒ 契约面, 否则 ⇒ 平台核心。⇒ 与路径深度无关 ⇒ 改写前后推导结果一致。

⇒ 并加了 20 条断言式反自证(推导自证 + 等价自证):证明 sys ≡ sspf_core::sys、compat::system ≡ sspf_compat_system::system。 (CC6 的反自证是「改契约」型的,证不到推导规则本身 ⇒ 必须直接断言。)

🔴 新增闸门 AR15(防删掉的东西复活)

删壳之后没有编译器兜底了:只要有人重建 platform/ 壳目录 + 把 import 改回去, ⇒ 一切照常编译、测试照常全绿,而 M2–M7 的架构收益全部蒸发,且无闸门报红。 ⇒ AR15 钉住三层:① 不许 crate::platform::;② 不许 ssw_platform::platform::; ③ src/backend/src/platform/ 目录不许有 .rs 文件。


5. 🔴 闸门改造(必须与迁移同步做,否则尺子失效)

🔴 这是最容易翻车的地方: 闸门脚本里写死了 src/backend/src/platform 路径。 代码搬走后,脚本会扫不到文件 ⇒ 永远"通过" ⇒ 虚假安全感。 check-arch.sh 的 AR9 自证注释里已经写明这一点(「这类尺子比没有更危险」)。

5.1 scripts/check-arch.sh

判据 现状 改造后
AR9(平台层不许认识业务包) grep src/backend/src/platform ✅ grep 所有 crates 平台包(PLAT_SRC_DIRS,动态 glob)
MEM1 / MEM2 walk src/backend/src + crates 保持(已覆盖 crates)✅
🆕 AR10 — ✅ crates/sspf-core 依赖 ⊆ {contract, store, axum, tokio, serde, serde_json}
🆕 AR11 — ✅ crates/sspf-compat-core(底座)不许依赖其它契约面模块 + Cargo.toml 级判据
🆕 AR12 — ✅ crates/sspf-compat-* 之间不许互相依赖(防环回流),白名单 3 条单向边
🆕 AR13 — ✅ crates/sspf-lowcode-exec 依赖 ⊆ {lowcode, core, store, mcp, pglite-rs, chrono, serde_json} + 源码不许 use sspf_pack_*
🆕 AR14 — ✅ crates/sspf-mcp-adapter 依赖 ⊆ {mcp, core, compat-, lowcode, axum, pglite-rs, serde*} + 源码不许 use sspf_pack_*
🆕 AR15 — ✅ M7:旧平台路径不许复活(全仓不许 crate::platform:: / ssw_platform::platform::;src/backend/src/platform/ 目录不许有 .rs)

🔴 AR11/AR12 的 Cargo.toml 级判据踩过 BSD grep 的坑:grep -E '^\s*...' 在 macOS 上永远匹配不到(BSD grep 是 POSIX ERE,不认 \s)⇒ 尺子永远"通过"。 正确写法:[[:space:]]。这个坑是 AR12 反自证第一次跑就失败暴露的 —— 没有反自证,就带着一把假尺子跑完了 M4。

5.2 scripts/check-contract-scan.py ✅ M2 已做(部分)

问题:plat_dir = os.path.join(src_dir, "platform") —— 代码搬走后只剩转发壳(无函数体)⇒ plat_files 推不出守卫 ⇒ CC6 静默退化成「全是 WARN」。M2 实测:反自证「守卫写错没被 CC6 抓到」当场报警 ⇒ 尺子没静默失效(自证起作用了)。

M2 改造(已做):plat_files 两处都收 —— crates/sspf-core/src/*.rs(真源)+ src/backend/src/platform/*.rs(壳),重名键拼接而非覆盖(否则一边的函数推不出守卫)。

M4 改造(已做):compat/ 搬走后要收 sspf-compat-* 各包 —— 动态收编(glob 扫 crates/sspf-compat-*/src,不写死列表):

crates_root = os.path.join(ROOT, "crates")
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)

🔴 为什么必须动态:写死路径列表必然在某次新增包时漏掉 ⇒ 尺子静默失效(本次实测踩过:首次跑 10/10 全绿就是尺子已废的信号)。

M4 收尾(已做):check-contract.sh --self-test 12 例全过 ⇒ 尺子没退化。

5.3 scripts/check-boundary-scan.py / check-boundary.sh ✅ M2/M4 已做

问题:扫 src/backend/src/platform/ 找业务标识符。代码搬走后扫不到 ⇒ 平台层混入业务知识不再被发现。

M2 改造(已做):新增 PLATFORM_CORE="$ROOT/crates/sspf-core/src",CP1(业务标识符)/ CP2(use crate::modules)两处都扫;CP6 的 seed.rs 改读真源(BUILTIN_MENUS 在 core 里)。实测:改前 CP6 报「BUILTIN_MENUS 有 0 条」(读空壳)⇒ 改后 11/11 全绿。

M4 改造(已做):新增动态 COMPAT_DIRS(glob 扫 crates/sspf-compat-*/src),CP1/CP2 都纳入。反向验证:往 crates/sspf-compat-msg/src/msg_center.rs 插 const LEAK_PROBE: &str = "demo_item"; ⇒ CP1 精确报出该行;还原后恢复 11/11。

5.4 scripts/check-module.sh ✅ M2 已做(CRUD 路径)

业务层(modules/<app>.rs)留在壳里 ⇒ 主体不用改;但软删契约(WHERE f_delete_mark = 0 / SET f_delete_mark = 1)读 crud.rs ⇒ CRUD 变量改读 crates/sspf-core/src/crud.rs(转发壳里没有 SQL)。实测:改前 8 项软删检查全 ❌(读不到 SQL)⇒ 改后 123/123 全绿。

5.5 scripts/check-naming.sh

第 128 行已经扫 crates/*/Cargo.toml ⇒ 不用改 ✅。

5.6 scripts/pack-sync.py

生成 src/backend/src/packs_gen.rs + src/backend/Cargo.toml 的包依赖段 —— 业务包留在壳侧 ⇒ 不用改 ✅。


6. 风险清单

# 风险 等级 缓解
R1 闸门静默失效(扫不到文件 ⇒ 永远通过) 🔴 极高 每批次后跑 --self-test;M4 之后必须重跑 check-contract.sh --self-test
R2 三处循环解不干净 ⇒ 编译失败 🔴 高 M1 单独一批,不与其他混;解不干净就停手回滚
R3 694+ 测试的 import 路径全断 🟡 中 M2 保留 platform/ re-export 转发壳 ⇒ 上层零感知
R4 mcp_compat.rs 依赖所有 compat 包 ⇒ 依赖网爆炸 🟡 中 放最后一批(M6)
R5 crate 数量爆炸(7 → 15)⇒ 编译变慢 🟡 中 cargo 增量编译按 crate 隔离,实际可能变快(改一个包不必重编全仓)
R6 AR 白名单要重写 ⇒ 纪律放松 🟡 中 每次新增 crate 必须同时加 AR 条目 + 反自证
R7 合并冲突(多人并行) 🟢 低 按包切分文件,冲突面小
R8 迁移期间功能退化 🔴 高 每批次必须全绿才进下一批;tag v0.1.0 随时可回滚
R9 🔴 闸门正则本身是坏的(\s 在 BSD grep 上不生效 ⇒ 永远"通过") 🔴 极高 每个新判据必须先跑一次反自证;M4 的 AR12 反自证第一次就失败并暴露了 AR11 的同类缺陷
R10 🔴 写死的路径列表漏掉新包 ⇒ 尺子静默失效 🔴 极高 收编目录一律用 glob(crates/sspf-compat-*/src),不写死清单;M4 的 CC6 就是这么废的

7. 回滚策略

# 任意批次失败 ⇒ 一条命令回到基线
git reset --hard v0.1.0

# 或回到上一个绿批次(每批次一个 tag)
git tag -a v0.1.1-m1 -m "M1 解耦完成"
git reset --hard v0.1.1-m1

纪律:

  • 每个批次单独 commit,message 写清批次号
  • 每批次单独 tag(v0.1.N-mX)
  • 任何一批不合绿,不进下一批

8. 验收标准(最终态)

指标 现状 目标
src/backend/src 行数 90,471 ≤ 8,000(壳:routes + main + bootstrap + modules + 转发壳)
crates/ 包数 7 15
src/backend/src/platform/ 内容 55,578 行真实实现 纯 re-export(每文件 ≤ 10 行)
cargo test --workspace 695 passed 695 passed(数不许减少)
check-arch.sh 12/12 17/17(新增 AR10–AR13 + 反自证)
check-contract.sh 10/10 10/10(不得退化)
check-boundary.sh 11/11 11/11(不得退化)
verify.sh --smoke 14 步全绿 14 步全绿
mem-budget.sh 8MB / 40MB ≤ 40MB(拆 crate 不应增加)
586 探针 0 个 404/405/500 0 个

🔴 断言数不许写死:拆 crate 后测试数会变(集成测试可能要重新归位到各 crate 的 tests/), 跑一遍看实际值再更新文档(CLAUDE.md §6 已明确这条纪律)。


9. 执行顺序建议

M1 解耦(3 个循环)        ← ✅ v0.1.1-m1
  ↓
M2 sspf-core              ← ✅ v0.1.2-m2(19 模块 / 6,664 行)
  ↓
M3 sspf-compat-core       ← ✅ v0.1.3-m3(helper/res / 1,454 行)
  ↓
M4 六个 compat 包          ← ✅ v0.1.4-m4(14 模块 / ~49,000 行)
  │                          🔴 同步改 check-contract-scan.py + check-boundary.sh + 新增 AR12
  ↓
M5 sspf-lowcode-exec      ← ✅ v0.1.5-m5(4 模块 / 2,674 行)
  │                          🔴 同步加 AR13 + check-boundary.sh 纳入执行层
  ↓
M6 sspf-mcp-adapter        ← 决策③:mcp_compat 放 crates
  ↓
M7 壳收口 + 闸门补全        ← 全量反自证 + 删 platform/ 转发壳 + 拆 tests/

每一批的出口判据都相同:

cargo build --workspace &&
cargo test --workspace &&              # 695 全绿,0 failed
bash scripts/check-arch.sh &&           # 全绿
bash scripts/check-contract.sh &&       # 全绿,且 --self-test 通过
bash scripts/check-boundary.sh &&       # 全绿
bash scripts/verify.sh --smoke          # 14 步全绿

10. 与 ssw-mvp/boot 的对应关系

ssw-mvp/boot 本仓目标 说明
ssw-common/(biz/entity/controller) crates/sspf-core + crates/sspf-contract 本仓多一层 contract(因为要兼容官方 JNPF 契约)
ssw-sswflow/(biz/entity/controller) crates/sspf-compat-workflow 同款三件套思路,但本仓是「契约面 handler」不是「业务实体」
ssw-tdc/、ssw-tds/ crates/sspf-compat-* 其余包 按官方模块名切,边界最清晰
ssw-admin/(聚合入口) src/backend/(薄壳) 启动装配 + 路由注册,与 ssw-admin 同款定位

⚠️ 一处差异:ssw-mvp 的 *-controller 自带 axum 依赖(它就是 web 层); 本仓的 crates/sspf-compat-* 也依赖 axum ⇒ 两者同款, 不违反 AR6(AR6 管的是 sspf-plugin 装载器不许拖 web 框架,不是管 compat 包)。


11. 决策(✅ 已拍板 2026-11-03)

  1. ✅ platform/ 转发壳最后删掉(M7 执行)。

    • 影响:全仓 import 要改(测试 30+ 处、routes/modules)⇒ 是「大爆炸」改动。
    • 缓解:M7 前转发壳一直保留(每批零感知),最后一次性改 import + 删壳; 删壳时 AR9/AR10/CP1/CP2 的「两处都扫」收敛为只扫 crates/(壳没了)。
    • M7 出口判据:src/backend/src/platform/ 目录整个删除;全仓无 crate::platform:: 引用。
  2. ✅ compat 拆 6 个包(按官方模块名):sspf-compat-{system,permission,msg,workflow,ext,onlinedev}。

    • 边界清晰、与官方前端 api/ 目录一一对应。
    • ⚠️ 实际落地时 online-dev → onlinedev —— Rust 包名不能带连字符(use sspf-compat-online-dev::… 编译不过);官方拼写 onlineDev 去分隔符后即 onlinedev。
    • M4 已同步:check-contract-scan.py 动态收编 6 个包 + 重跑 --self-test(12 例全过)。
  3. ✅ mcp_compat.rs 放 crates(sspf-mcp-adapter)。

    • 接受它是依赖图里唯一的高扇入节点(依赖所有 compat 包)。
    • 防回退:M6 加 AR 条目「sspf-mcp-adapter 之外不许依赖 compat 包」。
  4. ✅ tests/ 跟着拆到各 crate 的 tests/。

    • 影响:test_support.rs(进程级共享 pglite)目前依赖装配根 bootstrap::ensure_schema_all (认识业务 DDL)⇒ 拆测试必须先把「测试建库」改成各 crate 自足(core 的测试用 seed::ensure_base(db, &[]);compat 的测试建自己的契约面表;业务集成测试留壳侧测装配)。
    • 分层:单元测试随代码进各 crate;集成测试(测「装配后的整体」,如 pack_smoke_it.rs)留壳侧。 ⚠️ 2026-11-04 修正:壳侧已经不够了 —— 集成测试有自己的宿主包 crates/tests(package sspf-tests), 不再挂在 src/backend/tests/(理由见 crates/tests/Cargo.toml 顶部;由 AR16 钉住)。

12. 立即可做的下一步

执行 M6(sspf-mcp-adapter)。理由:

  1. M1–M5 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包、低代码执行层都稳了
  2. M6 是决策③的落地点(mcp_compat.rs 放 crates),也是唯一高扇入节点 ⇒ 越早做越早验证依赖网
  3. 套路成熟:M2–M5 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用

M6 完成后打 tag v0.1.6-m6。 ⚠️ M6 必须同步做: ① check-arch.sh 加 AR14(sspf-mcp-adapter 是唯一允许依赖 compat 各包的 crate —— 决策③的「防回退」条款:sspf-mcp-adapter 之外不许依赖 compat 包); ② check-contract-scan.py 的 plat_files 必须收 crates/sspf-mcp-adapter/src/(MCP 适配层里有守卫常量 ⇒ 漏收 ⇒ CC6 假漂移); ③ check-boundary.sh 的 CP1/CP2 纳入 MCP 适配层真源; ④ 重跑全部 --self-test。 之后 = M7(收口:删 platform/ 转发壳 + 拆 tests/ + 全量反自证)。

🔴 M4/M5 留下的教训,M6 必须继承: ① 闸门判据里的正则要用反自证验证过一次才敢信 —— grep 不报错 + 退出码 0 + 打印 ok = 三重「看起来正常」,但 BSD grep 的 \s 让 AR11/AR12 一直空转。 ② 收编新目录要用 glob,不要写死路径列表 —— 写死列表必然在某次新增包时漏掉 ⇒ 尺子静默失效(M4 的 CC6 就是这么废的)。 ③ 搬迁后第一反应不该是「全绿」而是「可疑」 —— M2/M3 搬迁后闸门都报红(正常),M4 首次跑就 10/10 ⇒ 反而是尺子坏了的信号。 ④ 改写规则要区分「路径前缀变了」与「模块名变了」 —— M5 把 use crate::lowcode_ddl; 误改成 use crate::ddl; ⇒ 编译不过。搬 crate 只改跨 crate 的前缀(crate::platform:: → sspf_core::),模块名一律不动;文档内链([`crate::xxx`])也不能跟着改。