平台能力全迁 crates/ 迁移计划第 3 批(docs/CRATES-MIGRATION.md)。
本批次 = M3:被 14 个契约面模块共用的底座先下沉,M4 的 6 个包才能都依赖它。
搬迁:
- compat/helper.rs(994) + compat/res.rs(460) git mv 进 crates/sspf-compat-core/src/
- src/backend/src/platform/compat/{helper,res}.rs 改成 pub use sspf_compat_core::<mod>::*
⇒ 14 个契约面模块的 use super::helper::{…} 零感知
- 路径改写 crate::platform::X → sspf_core::X(独立 crate 不能用 crate::X)
- pub(super) → pub(54 处):转发壳的 pub use …::* 只转发 pub 项(含 struct 字段)
- helper 的 8 个单测自足 ⇒ 随迁,总测试数不变 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 假漂移)
- 修 1 条引文:compat/helper.rs:89-92 → crates/sspf-compat-core/src/helper.rs:87-91
反向验证:只往真源 helper 塞 use crate::res::Res; ⇒ AR11 报红;清理后恢复绿。
顺带落档四个决策(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。
影响:功能零变化(响应形状、路由、语义均未动),纯结构下沉。
验证: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(CC6 零漂移);
check-module 123/123;check-citations 4/4;verify --smoke 14 步全绿(561.3s)。
34 KiB
CRATES-MIGRATION —— 「只留壳装配,平台能力全部迁到 crates/」迁移计划
基线锚点:
v0.1.0(commitb957a11,已推送到origin) 制定时间:2026-11-03 状态:M3 已完成(tagv0.1.3-m3)—— 契约面公共底座sspf-compat-core下沉完成; 四个决策已拍板(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。 下一步 = M4(六个契约面包并行下沉)
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
online_dev.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-online-dev/ # 契约面:online_dev
│
├── 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 --smoke14 步全绿。 tag =v0.1.1-m1。🔴 实际做法与原计划的差异(两处,都是「更简单」):
- 不用运行期注册表(原计划第 3 项):改为把分流点上移到装配根
routes.rs。 这更好 ——CLAUDE.md§4 本来就写明「共用两条路由按判别头分流」, 分流点本就该在壳;而且没有OnceLock静态槽位、没有注册时机、没有漏注册的风险。 平台层与契约面从此互不知道对方,壳负责接线。- 不用新建
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最底部。
实际做法(与原计划的差异):
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。- 测试归属跟着依赖走:
crud.rs的 3 个测试原依赖crate::modules::all_specs()(业务层)⇒ core 不能反向依赖业务层。解法:改用契约层合成 spec(同表结构、无业务知识)做参数化测试,断言强度不降;顺带发现write_cast的 numeric 映射是列名枚举(f_price/f_stock)而非 spec 声明 ⇒ 记为技术债(现有列名恰好都叫f_price未暴雷,新表带f_amount会静默出错)。 registry.rs测试自建库:不再经bootstrap::ensure_base(那是装配根、认识业务层),改seed::ensure_base(db, &[])(无业务菜单)⇒ 断言仍是主系统 5 条内置菜单(m_sys/m_user/m_role/m_org/m_menu)。test_support.rs留壳层:它依赖bootstrap::ensure_schema_all(认识业务 DDL)⇒ 不进 core。- 路径改写: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 --workspace695 passed / 0 failed(与基线一致)check-arch.sh14/14;--self-test6/6check-boundary.sh11/11;check-contract.sh10/10(反自证 12 例全过)check-module.sh123/123;check-citations.sh4/4verify.sh --smoke14 步全绿(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)。
实际做法:
- 路径改写:
crate::platform::X→sspf_core::X(本 crate 是独立 crate,不能用crate::X);res.rs 的super::helper→crate::helper。 pub(super)→pub(54 处):转发壳的pub use …::*只转发pub项 ⇒ 不提权则 14 个模块找不到EN_USER/Paging/MenuRow等(含 struct 字段)。- 测试随迁: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 --workspace695 passed / 0 failed(与基线一致)check-arch.sh14/14;--self-test6/6check-boundary.sh11/11;check-contract.sh10/10(守卫推导仍有效,CC6 零漂移)check-module.sh123/123;check-citations.sh4/4verify.sh --smoke14 步全绿(561.3s)
批次 M4 —— 契约面业务包(6 个并行包)
按依赖顺序切,每个包 = 若干 compat/<模块>.rs:
| 新 crate | 含文件 | 行数 | 依赖 |
|---|---|---|---|
sspf-compat-system |
system.rs | 17,539 | compat-core + core |
sspf-compat-permission |
permission.rs | 6,300 | compat-core + core |
sspf-compat-msg |
message + msg_center + scheduletask | 6,053 | compat-core + core |
sspf-compat-workflow |
workflow + report + visualdata | 7,729 | compat-core + core |
sspf-compat-ext |
extend + teamwork + ai + mobile + core | 6,787 | compat-core + core |
sspf-compat-online-dev |
online_dev.rs | 3,175 | compat-core + core |
出口判据:每个包独立 cargo build 通过;check-contract.sh 10/10。
批次 M5 —— 低代码执行层下沉
迁入:lowcode_{crud,ddl,check,seed}.rs(2,674 行)
新 crate:crates/sspf-lowcode-exec(依赖 sspf-lowcode + sspf-core + sspf-store + sspf-mcp)
sspf-lowcode(纯计算)不动 —— AR7 白名单保持不变。 新 crate 是「执行层」,允许依赖 DB。
批次 M6 —— MCP 适配层下沉
迁入:mcp_adapter.rs(2,652 行)+ mcp_compat.rs(631 行)
新 crate:crates/sspf-mcp-adapter(依赖 sspf-mcp + sspf-core + sspf-compat-*)
🔴
mcp_compat.rs直调platform::compat::*的 handler ⇒ 它依赖所有 compat 包。 这是唯一「知道全部包」的 crate ⇒ 它属于壳还是能力? 决策:放crates/(它是「MCP 适配」这一项独立能力),但放在最后一批。
批次 M7 —— 收口:壳瘦身 + 闸门改造
src/backend/src/platform/只剩 re-export(如果 M2 决定保留旧路径)- 或直接删掉
platform/目录,全仓 import 改成sspf_core::…(更干净,但改动面大 ⇒ 建议保留转发壳一个版本) routes.rs的compat::xxx::yyy引用改成sspf_compat_xxx::yyycheck-arch.sh新增 AR10–AR13check-contract-scan.py/check-boundary-scan.py路径改造(见 §5)
5. 🔴 闸门改造(必须与迁移同步做,否则尺子失效)
🔴 这是最容易翻车的地方: 闸门脚本里写死了
src/backend/src/platform路径。 代码搬走后,脚本会扫不到文件 ⇒ 永远"通过" ⇒ 虚假安全感。check-arch.sh的 AR9 自证注释里已经写明这一点(「这类尺子比没有更危险」)。
5.1 scripts/check-arch.sh
| 判据 | 现状 | 改造后 |
|---|---|---|
| AR9(平台层不许认识业务包) | grep src/backend/src/platform |
改成 grep 所有 crates 平台包 |
| MEM1 / MEM2 | walk src/backend/src + crates |
保持(已覆盖 crates)✅ |
| 🆕 AR10 | — | crates/sspf-core 依赖 ⊆ {contract, store, axum, tokio, serde, serde_json} |
| 🆕 AR11 | — | crates/sspf-compat-* 依赖 ⊆ {compat-core, core, contract, store, axum, ...},不许依赖 packs/* |
| 🆕 AR12 | — | crates/sspf-compat-* 之间不许互相依赖(防环回流) |
| 🆕 AR13 | — | crates/sspf-lowcode-exec 依赖 ⊆ {lowcode, core, store, mcp} |
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-* 各包:
PLAT_CRATES = ["sspf-core", "sspf-compat-core", "sspf-compat-system", ...]
for c in PLAT_CRATES:
d = os.path.join(ROOT, "crates", c, "src")
... plat_files[f"{c}__{name}"] = (o, mask_rust(o))
必须在 M4 之后立刻做,并重跑 check-contract.sh --self-test 确认没退化。
5.3 scripts/check-boundary-scan.py / check-boundary.sh ✅ M2 已做
问题:扫 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 全绿。
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 随时可回滚 |
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 个循环) ← 不搬文件,只改代码,风险最高,最先做
↓
M2 sspf-core ← 平台核心下沉,保留 re-export 壳
↓
M3 sspf-compat-core ← 契约面底座
↓
M4 六个 compat 包 ← 🔴 同步改 check-contract-scan.py
↓
M5 sspf-lowcode-exec
↓
M6 sspf-mcp-adapter
↓
M7 壳收口 + 闸门补全 ← AR10–AR13 + 全量反自证
每一批的出口判据都相同:
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)
-
✅
platform/转发壳最后删掉(M7 执行)。- 影响:全仓 import 要改(测试 30+ 处、routes/modules)⇒ 是「大爆炸」改动。
- 缓解:M7 前转发壳一直保留(每批零感知),最后一次性改 import + 删壳;
删壳时 AR9/AR10/CP1/CP2 的「两处都扫」收敛为只扫
crates/(壳没了)。 - M7 出口判据:
src/backend/src/platform/目录整个删除;全仓无crate::platform::引用。
-
✅ compat 拆 6 个包(按官方模块名):
sspf-compat-{system,permission,msg,workflow,ext,online-dev}。- 边界清晰、与官方前端
api/目录一一对应。 - M4 必须同步:
check-contract-scan.py收编 6 个包 + 重跑--self-test。
- 边界清晰、与官方前端
-
✅
mcp_compat.rs放 crates(sspf-mcp-adapter)。- 接受它是依赖图里唯一的高扇入节点(依赖所有 compat 包)。
- 防回退:M6 加 AR 条目「
sspf-mcp-adapter之外不许依赖 compat 包」。
-
✅
tests/跟着拆到各 crate 的tests/。- 影响:
test_support.rs(进程级共享 pglite)目前依赖装配根bootstrap::ensure_schema_all(认识业务 DDL)⇒ 拆测试必须先把「测试建库」改成各 crate 自足(core 的测试用seed::ensure_base(db, &[]);compat 的测试建自己的契约面表;业务集成测试留壳侧测装配)。 - 分层:单元测试随代码进各 crate;集成测试(测「装配后的整体」,如
pack_smoke_it.rs)留壳侧。
- 影响:
12. 立即可做的下一步
执行 M4(六个契约面包并行下沉)。理由:
- M1(解环)/ M2(平台核心)/ M3(契约面底座)已完成并打 tag —— 地基与底座都稳了
- 决策 ② 已拍板:按官方模块名拆 6 个包(
sspf-compat-{system,permission,msg,workflow,ext,online-dev}) - 套路成熟:M2/M3 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用
M4 完成后打 tag v0.1.4-m4。
⚠️ M4 必须同步做 §5.2 的 check-contract-scan.py 六包收编 + 重跑 --self-test(守卫推导的存亡线)。
之后 = M5(sspf-lowcode-exec)→ M6(sspf-mcp-adapter,决策③放 crates)→ M7(收口:删壳 + tests 拆分 + AR12/AR13)。