refactor(arch): M3 契约面公共底座下沉 —— helper/res 进 crates/sspf-compat-core

平台能力全迁 crates/ 迁移计划第 3 批(docs/CRATES-MIGRATION.md)。
本批次 = M3:被 14 个契约面模块共用的底座先下沉,M4 的 6 个包才能都依赖它。

搬迁:
- compat/helper.rs(994) + compat/res.rs(460) git mv 进 crates/sspf-compat-core/src/
- src/backend/src/platform/compat/{helper,res}.rs 改成 pub use sspf_compat_core::<mod>::*
  ⇒ 14 个契约面模块的 use super::helper::{…} 零感知
- 路径改写 crate::platform::X → sspf_core::X(独立 crate 不能用 crate::X)
- pub(super) → pub(54 处):转发壳的 pub use …::* 只转发 pub 项(含 struct 字段)
- helper 的 8 个单测自足 ⇒ 随迁,总测试数不变 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 假漂移)
- 修 1 条引文:compat/helper.rs:89-92 → crates/sspf-compat-core/src/helper.rs:87-91

反向验证:只往真源 helper 塞 use crate::res::Res; ⇒ AR11 报红;清理后恢复绿。

顺带落档四个决策(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。

影响:功能零变化(响应形状、路由、语义均未动),纯结构下沉。
验证:cargo build 零警告;cargo test --workspace 695 passed / 0 failed(与基线一致);
check-arch 14/14;--self-test 6/6;check-boundary 11/11;check-contract 10/10(CC6 零漂移);
check-module 123/123;check-citations 4/4;verify --smoke 14 步全绿(561.3s)。
This commit is contained in:
admin committed 2026-11-03 17:48:41 +08:00
1 parent 94d05f4649
commit eea3d0329f
13 files changed
+1688 -1517

No files matched your search

+58 -29
View File
@@ -2,9 +2,9 @@
> **基线锚点**:`v0.1.0`(commit `b957a11`,已推送到 `origin`)
> **制定时间**:2026-11-03
> **状态**:**M2 已完成**(tag `v0.1.2-m2`)—— 平台核心 19 个模块下沉到 `crates/sspf-core/`,
> `platform/*.rs` 只剩转发壳;闸门同步改造(扫真源而非空壳)。
> 下一步 = M3(`sspf-compat-core` 契约面公共底座)
> **状态**:**M3 已完成**(tag `v0.1.3-m3`)—— 契约面公共底座 `sspf-compat-core` 下沉完成;
> 四个决策已拍板(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。
> 下一步 = M4(六个契约面包并行下沉)
---
@@ -82,7 +82,7 @@ crates/sspf-contract/src/headers.rs:32
pub fn is_face_b(headers: &HeaderMap) -> bool # 已有,且带 3 条单测
```
当前 `compat/helper.rs:89-92` 只是一个**转发壳**:
当前 [`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)
@@ -351,13 +351,39 @@ ssw-platform/
- [x] `check-module.sh` 123/123;`check-citations.sh` 4/4
- [x] `verify.sh --smoke` 14 步全绿(512.3s)
### 批次 M3 —— 契约面公共底座:`sspf-compat-core`
### 批次 M3 —— 契约面公共底座:`sspf-compat-core` ✅ 已完成(tag `v0.1.3-m3`)
**迁入**:`platform/compat/helper.rs`(902 行)+ `platform/compat/res.rs`(460 行)
**迁入**:`platform/compat/helper.rs`(994 行)+ `platform/compat/res.rs`(460 行)→ `crates/sspf-compat-core/src/`
**新 crate**:`crates/sspf-compat-core`(依赖 axum + sspf-core + sspf-contract + sspf-store)
**新 crate**:`crates/sspf-compat-core`(依赖 sspf-core + sspf-contract + axum + serde + serde_json)
**出口判据**:`check-contract-scan.py` 的守卫推导**仍然有效**(见 §5 闸门改造)。
**保留转发壳**:`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 个并行包)
@@ -555,34 +581,37 @@ bash scripts/verify.sh --smoke # 14 步全绿
---
## 11. 待确认决策
## 11. 决策(✅ 已拍板 2026-11-03)
1. **M2 保留 `platform/` re-export 转发壳,还是直接删掉?**
- 保留 ⇒ 上层零感知、改动小,但壳里多 20 个转发文件
- 删除 ⇒ 壳更干净,但全仓 import 要改(测试 30+ 处)
- **建议**:保留一个版本(M7 再决定删不删)
1. ✅ **`platform/` 转发壳最后删掉**(M7 执行)。
- **影响**:全仓 import 要改(测试 30+ 处、routes/modules)⇒ 是「大爆炸」改动。
- **缓解**:M7 前转发壳一直保留(每批零感知),**最后一次性**改 import + 删壳;
删壳时 AR9/AR10/CP1/CP2 的「两处都扫」收敛为只扫 `crates/`(壳没了)。
- **M7 出口判据**:`src/backend/src/platform/` 目录整个删除;全仓无 `crate::platform::` 引用。
2. **compat 包拆几个?** 现在按「官方模块名」拆 6 个。
另一种拆法:按「业务域」拆 3 个(大系统/大流程/大消息)。
**建议**:按官方模块名(边界清晰、与官方前端 `api/` 目录一一对应)
2. ✅ **compat 拆 6 个包**(按官方模块名):`sspf-compat-{system,permission,msg,workflow,ext,online-dev}`。
- 边界清晰、与官方前端 `api/` 目录一一对应。
- **M4 必须同步**:`check-contract-scan.py` 收编 6 个包 + 重跑 `--self-test`。
3. **`mcp_compat.rs` 放 crates 还是留壳?**
它依赖**所有** compat 包 ⇒ 放 crates 会让「壳依赖能力」变成「能力依赖能力」。
**建议**:放 crates(它是独立能力),但**接受**它是依赖图里唯一的高扇入节点
3. ✅ **`mcp_compat.rs` 放 crates**(`sspf-mcp-adapter`)。
- 接受它是依赖图里唯一的高扇入节点(依赖所有 compat 包)。
- **防回退**:M6 加 AR 条目「`sspf-mcp-adapter` 之外不许依赖 compat 包」。
4. **`src/backend/tests/` 要不要跟着拆到各 crate 的 `tests/`?**
- 拆 ⇒ 测试与代码同域,但需要共享 pglite 单例(`test_support.rs`)跨 crate 复用
- 不拆 ⇒ 留壳里(`tests/` 是壳的一部分,测的是「装配后的整体」⇒ 语义更对)
- **建议**:不拆(集成测试测的是装配结果,留在壳侧语义正确)
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`)**留壳侧**。
---
## 12. 立即可做的下一步
**执行 M3(契约面公共底座 `sspf-compat-core`)**。理由:
1. M1(解环)/ M2(平台核心下沉)已完成并打 tag —— 地基已稳
2. `compat/helper.rs`(902 行)+ `res.rs`(460 行)是 **14 个契约面模块**的公共底座 ⇒ 先下沉它,M4 的 6 个包才都能依赖它
3. 有现成套路可复用:M2 的「转发壳 + 闸门扫真源 + 反自证两处注入」直接套用
**执行 M4(六个契约面包并行下沉)**。理由:
1. M1(解环)/ M2(平台核心)/ M3(契约面底座)已完成并打 tag —— 地基与底座都稳了
2. 决策 ② 已拍板:按官方模块名拆 **6 个包**(`sspf-compat-{system,permission,msg,workflow,ext,online-dev}`)
3. 套路成熟:M2/M3 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用
M3 完成后打 tag `v0.1.3-m3`,再进 M4(6 个契约面包并行)。
⚠️ M4 之后**必须**做 §5.2 的 `check-contract-scan.py` 兼容包收编 + 重跑 `--self-test`。
M4 完成后打 tag `v0.1.4-m4`。
⚠️ **M4 必须同步做** §5.2 的 `check-contract-scan.py` 六包收编 + 重跑 `--self-test`(守卫推导的存亡线)。
之后 = M5(`sspf-lowcode-exec`)→ M6(`sspf-mcp-adapter`,决策③放 crates)→ M7(收口:删壳 + tests 拆分 + AR12/AR13)。