- 内核只有 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。
50 KiB
CRATES-MIGRATION —— 「只留壳装配,平台能力全部迁到 crates/」迁移计划
基线锚点:
v0.1.0(commitb957a11,已推送到origin) 制定时间:2026-11-03 状态:M5 已完成(tagv0.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 --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 个并行包)✅ 已完成(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 源码)⇒ 改依赖即被抓。
🔴 本批踩的三个坑(都是「尺子是假的」):
-
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。 -
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。 -
🔴 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/11check-contract.sh= 10/10(反自证 12 例全过)check-module.sh= 123/123check-citations.sh= 4/4(引文路径改到新真源,行号 1:1 未变 ⇒ 迁移是纯搬运)check-naming.sh= 3 通过 / 0 失败 / 1 提示verify.sh --smoke14 步全绿(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(两层判据):
crates/sspf-lowcode-exec/Cargo.toml的依赖 ⊆{sspf-lowcode, sspf-core, sspf-store, sspf-mcp, pglite-rs, chrono, serde_json}—— 不许 axum(web 框架)⇒ 这层就还能被 CLI / MCP / 离线工具复用;- 该 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 --smoke14 步全绿(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/4check-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)
-
✅
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,onlinedev}。- 边界清晰、与官方前端
api/目录一一对应。 - ⚠️ 实际落地时
online-dev→onlinedev—— Rust 包名不能带连字符(use sspf-compat-online-dev::…编译不过);官方拼写onlineDev去分隔符后即onlinedev。 - M4 已同步:
check-contract-scan.py动态收编 6 个包 + 重跑--self-test(12 例全过)。
- 边界清晰、与官方前端
-
✅
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)留壳侧。 ⚠️ 2026-11-04 修正:壳侧已经不够了 —— 集成测试有自己的宿主包crates/tests(packagesspf-tests), 不再挂在src/backend/tests/(理由见crates/tests/Cargo.toml顶部;由 AR16 钉住)。
- 影响:
12. 立即可做的下一步
执行 M6(sspf-mcp-adapter)。理由:
- M1–M5 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包、低代码执行层都稳了
- M6 是决策③的落地点(
mcp_compat.rs放 crates),也是唯一高扇入节点 ⇒ 越早做越早验证依赖网 - 套路成熟: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`])也不能跟着改。