- 内核只有 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。
782 lines
50 KiB
Markdown
782 lines
50 KiB
Markdown
# 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`]``)也不能跟着改。
|