Files
ssw-platform/docs/CRATES-MIGRATION.md
T
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

782 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`](crates/sspf-compat-core/src/helper.rs)(M3 起真源在此)只是一个**转发壳**:
```rust
pub fn is_face_b(headers: &HeaderMap) -> bool {
sspf_contract::headers::is_face_b(headers)
}
```
⇒ **`auth.rs` 改一行就能断环**:
```rust
// 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 又得依赖它们 ⇒ 环还在。
**出口判据**(全部已达成):
- [x] `cargo build --workspace` 通过(**零警告**)
- [x] 695 测试仍全绿(`cargo test --workspace` = 695 passed / 0 failed)
- [x] `grep -rn "crate::platform::compat" src/backend/src/platform/` → **仅剩注释命中**
- [x] `grep -rn "use super::system\|use super::permission" src/backend/src/platform/compat/helper.rs` → **零命中**
- [x] `check-arch.sh` → **14/14**(新增 AR10/AR11)
- [x] `check-arch.sh --self-test` → **6/6 反自证通过**
- [x] `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 **都报红**;探针已清干净。
**出口判据(全部达成)**:
- [x] `src/backend/src/platform/*.rs` 每个文件 ≤ 10 行(纯 re-export)
- [x] `cargo build --workspace` 零警告
- [x] `cargo test --workspace` **695 passed / 0 failed**(与基线一致)
- [x] `check-arch.sh` 14/14;`--self-test` 6/6
- [x] `check-boundary.sh` 11/11;`check-contract.sh` 10/10(反自证 12 例全过)
- [x] `check-module.sh` 123/123;`check-citations.sh` 4/4
- [x] `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 精确删探针行。
**出口判据(全部达成)**:
- [x] `cargo build --workspace` 零警告
- [x] `cargo test --workspace` **695 passed / 0 failed**(与基线一致)
- [x] `check-arch.sh` 14/14;`--self-test` 6/6
- [x] `check-boundary.sh` 11/11;`check-contract.sh` 10/10(守卫推导仍有效,CC6 零漂移)
- [x] `check-module.sh` 123/123;`check-citations.sh` 4/4
- [x] `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` 打印 ⇒ 三重「看起来正常」。
**出口判据(全部达成)**:
- [x] 6 个 crate 各自 `cargo build -p` 通过;`cargo build --workspace` 零警告
- [x] `cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致)
- [x] `check-arch.sh` = **15/15**(新增 AR12);`--self-test` = **7/7**(新增 AR12 反自证)
- [x] `check-boundary.sh` = 11/11
- [x] `check-contract.sh` = 10/10(反自证 12 例全过)
- [x] `check-module.sh` = 123/123
- [x] `check-citations.sh` = 4/4(引文路径改到新真源,行号 1:1 未变 ⇒ 迁移是纯搬运)
- [x] `check-naming.sh` = 3 通过 / 0 失败 / 1 提示
- [x] `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`]` 这种**文档内链**也不能跟着改(改了就变成死链)⇒ 已单独修回。
**出口判据(全部达成)**:
- [x] `cargo build --workspace` 零警告;`cargo test --workspace` = **695 passed / 0 failed**(与 M1 基线完全一致)
- [x] `check-arch.sh` = **17/17**(新增 AR13);`--self-test` = **8/8**(新增 AR13 反自证)
- [x] `check-boundary.sh` = 11/11(CP1/CP2 已覆盖执行层)
- [x] `check-contract.sh` = 10/10(反自证 12 例全过)—— 契约里**零 lowcode 端点**(低代码是 MCP 工具不是 HTTP 路由)⇒ 本批不受影响
- [x] `check-module.sh` = 123/123;`check-citations.sh` = 4/4(**零条引文**指向 lowcode 旧路径)
- [x] `check-naming.sh` = 3 通过 / 0 失败 / 1 提示
- [x] `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 继续潜伏。
**出口判据**:
- [x] `cargo build --workspace` 零警告
- [x] `cargo test --workspace` = 695 passed / 0 failed(与 M1 基线完全一致)
- [x] `check-arch.sh` = **19/19**(新增 AR14);`--self-test` = **9/9**(新增 AR14 反自证)
- [x] `check-boundary.sh` = **12/12**(CP1/CP2 纳入适配层 + 新增 **CP1'' 扫描面反自证**)
- [x] `check-contract.sh` = 10/10(反自证 12 例全过)
- [x] `check-module.sh` = 123/123;`check-citations.sh` = 4/4
- [x] `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`,**不写死列表**):
```python
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. 回滚策略
```bash
# 任意批次失败 ⇒ 一条命令回到基线
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/
```
**每一批的出口判据都相同**:
```bash
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`]``)也不能跟着改。