# 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::::*;` ⇒ **上层零感知**(测试、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::::*;` ⇒ **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__` **收真源 + 壳同键拼接** —— 守卫常量(`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 -- ` 清理探针 ⇒ **把 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::<域>::` | | 移动 `platform/test_support.rs` | 1 个文件 | → `src/backend/src/test_support.rs`(依赖装配根 ⇒ 留壳侧) | **🔴 关键决策:为什么保留 `compat::<域>::` 这条路径(而不是 1,010 处全改)** `routes.rs` 里 `compat::<域>::` 有 **1,010 处**。逐处改成 `sspf_compat_system::system::` 看着「更干净」,但代价是: - 契约扫描器的 `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/.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`]``)也不能跟着改。