## 影响 - 新增 docs/CRATES-MIGRATION.md:7 批次迁移计划(依赖图 / 三处循环依赖解法 / 闸门改造 / 风险 / 回滚) - CLAUDE.md / HANDOFF.md 挂上计划入口,HANDOFF 新增 §0-0-pre 交接段 - 纯文档,**零代码改动** ⇒ 695 测试 / 12 道闸门基线不变 ## 改动 - 打 tag v0.1.0(commit b957a11,已推 origin)= 迁移前可回滚锚点 - 计划含实测数据:壳 5,664 行(6%)vs 平台能力 61,500 行;crates 7 个 → 目标 15 个 - 定位三处跨 crate 循环依赖(auth↔compat/helper、helper↔system、helper↔permission)及各自解法 - 标注最大风险:check-contract-scan.py / check-boundary-scan.py 路径写死 ⇒ 搬迁后闸门静默失效 - 4 个待确认决策(转发壳删不删 / compat 包数 / mcp_compat 归属 / tests 是否拆) ## 设计(仅记录明确拒绝的方案) - ❌ 不按 ssw-mvp 的 biz/entity/controller 三件套切 —— 本仓 compat 是「契约面 handler」不是「业务实体」 - ❌ 不把 compat 做成不认 axum 的纯 crate —— 会与 AR6/AR7 纪律冲突;ssw-mvp 的 *-controller 本身就带 axum
25 KiB
CRATES-MIGRATION —— 「只留壳装配,平台能力全部迁到 crates/」迁移计划
基线锚点:
v0.1.0(commitb957a11,已推送到origin) 制定时间:2026-11-03 状态:计划已制定,尚未执行(第一步 = 解耦)
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 条单测
当前 compat/helper.rs:89-92 只是一个转发壳:
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 已存在 ⇒ auth.rs:336/403 改一行断掉一条边;面 B current_user 改为注册表回调 |
🟡 中(比预想低) |
| B | compat/helper ↔ compat/system | helper 下沉成 sspf-compat-core;menu_node/official_view_path 留在 system 包 |
🟡 中 |
| C | compat/helper ↔ compat/permission | 同 B;USER_DETAIL_COLUMNS/organize_name_of 留在 permission 包 |
🔴 高(22 个符号逐个归属) |
好消息:三个环全部集中在
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:336 |
auth → compat(判定边) |
| 2 | 同上 | platform/auth.rs:403 |
auth → compat(判定边) |
| 3 | 面 B current_user 改为注册表回调(壳启动时注册) |
platform/auth.rs:337 + compat/helper.rs:391 |
auth → compat(形状边) |
| 4 | resolve_user 提为 pub |
platform/auth.rs:436(pub(crate) → pub) |
供 compat 侧调用 |
| 5 | helper 的公共符号下沉 | platform/compat/helper.rs → 新 platform/compat_base/ |
环 B/C 的一半 |
| 6 | menu_node / official_view_path 搬回 system 侧 |
compat/system.rs:42,32 |
环 B |
| 7 | USER_DETAIL_COLUMNS / organize_name_of 搬回 permission 侧 |
compat/permission.rs:374,32 |
环 C |
| 8 | permission 的 22 个反向符号逐个归属 | compat/permission.rs:29 |
环 C 收尾 |
⚠️ 第 3 项是 M1 最关键的一步: 面 B 的
current_user(PcUserVO形状)必须从 auth 侧完全移出。 若保留在 auth 里调用 compat helper ⇒ auth 仍依赖 compat ⇒ 环还在。 手法:在 auth 侧建一个OnceLock<Option<fn(...)>>静态槽位, 由壳(bootstrap.rs)在启动时注册 compat 提供的面 B 实现。 运行期单向,编译期无环。
出口判据:
cargo build --workspace通过- 695 测试仍全绿
grep -rn "crate::platform::compat" src/backend/src/platform/auth.rs→ 零命中grep -rn "use super::system\|use super::permission" src/backend/src/platform/compat/helper.rs→ 零命中
批次 M2 —— 平台核心下沉:sspf-core
迁入:platform/{auth,session,authorization,crud,sys,menu,guard,monitor,registry,state,seed,variate_catalog}.rs + platform/{cipher,envelope,ids,config,db}.rs(后四个转 pub use sspf_store / sspf_contract 转发)
新 crate:crates/sspf-core
[dependencies]
sspf-contract = { path = "../sspf-contract" }
sspf-store = { path = "../sspf-store" }
axum = { workspace = true }
tokio = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
保留转发壳:src/backend/src/platform/*.rs 全部改成 pub use sspf_core::*;
⇒ 上层零感知(测试、routes、modules 全部不用改 import)。
🔴
state.rs(AppState)是关键:config/db/sessions/tickets四个Arc。 它必须跟着 core 走(compat 包也要用 AppState)⇒ 放在sspf-core最底部。
出口判据:src/backend/src/platform/ 每个文件 ≤ 10 行(纯 re-export);695 测试仍全绿。
批次 M3 —— 契约面公共底座:sspf-compat-core
迁入:platform/compat/helper.rs(902 行)+ platform/compat/res.rs(460 行)
新 crate:crates/sspf-compat-core(依赖 axum + sspf-core + sspf-contract + sspf-store)
出口判据:check-contract-scan.py 的守卫推导仍然有效(见 §5 闸门改造)。
批次 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
问题:第 827 行 plat_dir = os.path.join(src_dir, "platform")、第 839 行 compat_dir = ... ——
代码搬走后这两个目录不存在 ⇒ plat_files 为空 ⇒ 守卫推导全部推不出 ⇒ CC6 静默退化成「全是 WARN」。
改造:
# 改成扫描所有 crates 平台包
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
问题:扫 src/backend/src/platform/ 找业务标识符。代码搬走后扫不到 ⇒ 平台层混入业务知识不再被发现。
改造:扫目录改成「所有 crates 平台包」+ src/backend/src(薄壳也要扫)。
5.4 scripts/check-module.sh
BACKEND="$ROOT/src/backend" + src/backend/src/modules/<app>.rs ——
业务层留在壳里 ⇒ 不用改 ✅(除非 M7 决定把业务层也搬走,不建议)。
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. 待确认决策
-
M2 保留
platform/re-export 转发壳,还是直接删掉?- 保留 ⇒ 上层零感知、改动小,但壳里多 20 个转发文件
- 删除 ⇒ 壳更干净,但全仓 import 要改(测试 30+ 处)
- 建议:保留一个版本(M7 再决定删不删)
-
compat 包拆几个? 现在按「官方模块名」拆 6 个。 另一种拆法:按「业务域」拆 3 个(大系统/大流程/大消息)。 建议:按官方模块名(边界清晰、与官方前端
api/目录一一对应) -
mcp_compat.rs放 crates 还是留壳? 它依赖所有 compat 包 ⇒ 放 crates 会让「壳依赖能力」变成「能力依赖能力」。 建议:放 crates(它是独立能力),但接受它是依赖图里唯一的高扇入节点 -
src/backend/tests/要不要跟着拆到各 crate 的tests/?- 拆 ⇒ 测试与代码同域,但需要共享 pglite 单例(
test_support.rs)跨 crate 复用 - 不拆 ⇒ 留壳里(
tests/是壳的一部分,测的是「装配后的整体」⇒ 语义更对) - 建议:不拆(集成测试测的是装配结果,留在壳侧语义正确)
- 拆 ⇒ 测试与代码同域,但需要共享 pglite 单例(
12. 立即可做的下一步
执行 M1(解开三个循环)。理由:
- 不改目录结构 ⇒ 风险最低
- 是所有后续批次的前置(不解开,后面全部编译不过)
- 单独可验证(编译过 + 695 测试仍全绿)
M1 完成后打 tag v0.1.1-m1,再进 M2。