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:
1 parent
94d05f4649
commit
eea3d0329f
13 files changed
+1688
-1517
No files matched your search
+58
-29
@@ -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)。
|
||||
Reference in new issue
Block a user