Files
ssw-platform/docs/CRATES-MIGRATION.md
T
admin 639ade7923 docs(migration): 打 v0.1.0 基线 tag + 制定「平台能力全迁 crates/」迁移计划
## 影响

- 新增 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
2026-11-03 12:16:08 +08:00

25 KiB
Raw Blame History

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

基线锚点:v0.1.0(commit b957a11,已推送到 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::yyy
  • check-arch.sh 新增 AR10–AR13
  • check-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. 待确认决策

  1. M2 保留 platform/ re-export 转发壳,还是直接删掉?

    • 保留 ⇒ 上层零感知、改动小,但壳里多 20 个转发文件
    • 删除 ⇒ 壳更干净,但全仓 import 要改(测试 30+ 处)
    • 建议:保留一个版本(M7 再决定删不删)
  2. compat 包拆几个? 现在按「官方模块名」拆 6 个。 另一种拆法:按「业务域」拆 3 个(大系统/大流程/大消息)。 建议:按官方模块名(边界清晰、与官方前端 api/ 目录一一对应)

  3. mcp_compat.rs 放 crates 还是留壳? 它依赖所有 compat 包 ⇒ 放 crates 会让「壳依赖能力」变成「能力依赖能力」。 建议:放 crates(它是独立能力),但接受它是依赖图里唯一的高扇入节点

  4. src/backend/tests/ 要不要跟着拆到各 crate 的 tests/?

    • 拆 ⇒ 测试与代码同域,但需要共享 pglite 单例(test_support.rs)跨 crate 复用
    • 不拆 ⇒ 留壳里(tests/ 是壳的一部分,测的是「装配后的整体」⇒ 语义更对)
    • 建议:不拆(集成测试测的是装配结果,留在壳侧语义正确)

12. 立即可做的下一步

执行 M1(解开三个循环)。理由:

  1. 不改目录结构 ⇒ 风险最低
  2. 是所有后续批次的前置(不解开,后面全部编译不过)
  3. 单独可验证(编译过 + 695 测试仍全绿)

M1 完成后打 tag v0.1.1-m1,再进 M2。