refactor(arch): M2 平台核心下沉 —— 19 模块迁入 crates/sspf-core + 闸门扫真源
平台能力全迁 crates/ 迁移计划第 2 批(docs/CRATES-MIGRATION.md,基线 tag v0.1.0)。
本批次 = M2:平台核心从 src/backend/src/platform/ 下沉到 crates/sspf-core/。
搬迁:
- 19 个模块 git mv 进 crates/sspf-core/src/(保留历史):
auth/authorization/cipher/config/crud/db/entity/envelope/guard/ids/menu/
monitor/registry/route/seed/session/state/sys/variate_catalog
- src/backend/src/platform/*.rs 全改成 pub use sspf_core::<mod>::* 转发壳(5 行/个)
⇒ 上层零感知:routes / modules / 695 个测试的 import 一个没改
- crate 内路径改写 crate::platform::X → crate::X(compat 除外,那是 M3/M4)
- pub(crate) → pub(10 处,跨 crate 后失效)
闸门改造(🔴 本批最大风险不是代码是闸门 —— 搬迁后闸门扫空壳 = 虚假安全感):
- 纪律 = 「两处都扫」:真源 crates/sspf-core/src/(管实现)+ 转发壳(防塞私货)
- check-arch.sh AR9/AR10 扫两处;反自证 2/6、5/6 两处注入探针且按路径分别验
- check-boundary.sh 新增 PLATFORM_CORE;CP1/CP2 两处扫;CP6 的 seed.rs 改读真源
- check-contract-scan.py 的 plat_files 两处都收、重名键拼接(覆盖会丢函数 ⇒ 推不出守卫)
- check-module.sh 的 CRUD 改读 crates/sspf-core/src/crud.rs(软删契约要看 SQL)
- gen-function-catalog.py 的 OUT 改写真源(否则覆盖转发壳 ⇒ 上层 import 全断)
- 反向验证:只往 crates/sspf-core/ 塞违规 ⇒ AR9/AR10 都报红(证明真在扫真源)
测试归属调整:crud.rs 3 个测试原依赖 crate::modules::all_specs()(业务层)
⇒ 改用契约层合成 spec 参数化测试;registry.rs 测试改自建库 + seed::ensure_base(db, &[])。
顺带记录技术债:write_cast 的 numeric 映射是列名枚举而非 spec 声明。
影响:功能零变化(路由、响应形状、语义均未动),纯结构下沉。
验证: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(反自证 12 例全过);
check-module 123/123;check-citations 4/4;verify --smoke 14 步全绿(512.3s)。
This commit is contained in:
1 parent
215b5e8fcf
commit
94d05f4649
52 files changed
+7085
-6643
No files matched your search
+50
-31
@@ -2,8 +2,9 @@
|
||||
|
||||
> **基线锚点**:`v0.1.0`(commit `b957a11`,已推送到 `origin`)
|
||||
> **制定时间**:2026-11-03
|
||||
> **状态**:**M1 已完成**(tag `v0.1.1-m1`)—— 三处循环依赖全部解开;
|
||||
> 下一步 = M2(`sspf-core` 平台核心下沉)
|
||||
> **状态**:**M2 已完成**(tag `v0.1.2-m2`)—— 平台核心 19 个模块下沉到 `crates/sspf-core/`,
|
||||
> `platform/*.rs` 只剩转发壳;闸门同步改造(扫真源而非空壳)。
|
||||
> 下一步 = M3(`sspf-compat-core` 契约面公共底座)
|
||||
|
||||
---
|
||||
|
||||
@@ -309,28 +310,46 @@ ssw-platform/
|
||||
> 把那行加回去**照样编译通过、测试照样全绿**,只有到 M2 那天才炸 ⇒ 那时已改了一堆东西。
|
||||
> ⇒ 现在就拦住。
|
||||
|
||||
### 批次 M2 —— 平台核心下沉:`sspf-core`
|
||||
### 批次 M2 —— 平台核心下沉:`sspf-core` ✅ 已完成(tag `v0.1.2-m2`)
|
||||
|
||||
**迁入**:`platform/{auth,session,authorization,crud,sys,menu,guard,monitor,registry,state,seed,variate_catalog}.rs` + `platform/{cipher,envelope,ids,config,db}.rs`(后四个转 `pub use sspf_store` / `sspf_contract` 转发)
|
||||
**迁入**:`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`
|
||||
```toml
|
||||
[dependencies]
|
||||
sspf-contract = { path = "../sspf-contract" }
|
||||
sspf-store = { path = "../sspf-store" }
|
||||
axum = { workspace = true }
|
||||
tokio = { workspace = true }
|
||||
serde = { workspace = true }
|
||||
serde_json = { workspace = true }
|
||||
```
|
||||
**新 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::*;`
|
||||
**保留转发壳**:`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` 最底部。
|
||||
|
||||
**出口判据**:`src/backend/src/platform/` 每个文件 ≤ 10 行(纯 re-export);695 测试仍全绿。
|
||||
**实际做法(与原计划的差异)**:
|
||||
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`
|
||||
|
||||
@@ -402,14 +421,14 @@ serde_json = { workspace = true }
|
||||
| 🆕 AR12 | — | `crates/sspf-compat-*` 之间**不许**互相依赖(防环回流) |
|
||||
| 🆕 AR13 | — | `crates/sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp} |
|
||||
|
||||
### 5.2 `scripts/check-contract-scan.py`
|
||||
### 5.2 `scripts/check-contract-scan.py` ✅ M2 已做(部分)
|
||||
|
||||
**问题**:第 827 行 `plat_dir = os.path.join(src_dir, "platform")`、第 839 行 `compat_dir = ...` ——
|
||||
代码搬走后这两个目录**不存在** ⇒ `plat_files` 为空 ⇒ **守卫推导全部推不出** ⇒ CC6 静默退化成「全是 WARN」。
|
||||
**问题**:`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-*` 各包:
|
||||
```python
|
||||
# 改成扫描所有 crates 平台包
|
||||
PLAT_CRATES = ["sspf-core", "sspf-compat-core", "sspf-compat-system", ...]
|
||||
for c in PLAT_CRATES:
|
||||
d = os.path.join(ROOT, "crates", c, "src")
|
||||
@@ -417,16 +436,15 @@ for c in PLAT_CRATES:
|
||||
```
|
||||
**必须**在 M4 之后立刻做,并**重跑 `check-contract.sh --self-test`** 确认没退化。
|
||||
|
||||
### 5.3 `scripts/check-boundary-scan.py` / `check-boundary.sh`
|
||||
### 5.3 `scripts/check-boundary-scan.py` / `check-boundary.sh` ✅ M2 已做
|
||||
|
||||
**问题**:扫 `src/backend/src/platform/` 找业务标识符。代码搬走后**扫不到** ⇒ 平台层混入业务知识**不再被发现**。
|
||||
|
||||
**改造**:扫目录改成「所有 crates 平台包」+ `src/backend/src`(薄壳也要扫)。
|
||||
**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 全绿。
|
||||
|
||||
### 5.4 `scripts/check-module.sh`
|
||||
### 5.4 `scripts/check-module.sh` ✅ M2 已做(CRUD 路径)
|
||||
|
||||
`BACKEND="$ROOT/src/backend"` + `src/backend/src/modules/<app>.rs` ——
|
||||
业务层**留在壳里** ⇒ **不用改** ✅(除非 M7 决定把业务层也搬走,**不建议**)。
|
||||
业务层(`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`
|
||||
|
||||
@@ -561,9 +579,10 @@ bash scripts/verify.sh --smoke # 14 步全绿
|
||||
|
||||
## 12. 立即可做的下一步
|
||||
|
||||
**执行 M1(解开三个循环)**。理由:
|
||||
1. 不改目录结构 ⇒ 风险最低
|
||||
2. 是所有后续批次的**前置**(不解开,后面全部编译不过)
|
||||
3. 单独可验证(编译过 + 695 测试仍全绿)
|
||||
**执行 M3(契约面公共底座 `sspf-compat-core`)**。理由:
|
||||
1. M1(解环)/ M2(平台核心下沉)已完成并打 tag —— 地基已稳
|
||||
2. `compat/helper.rs`(902 行)+ `res.rs`(460 行)是 **14 个契约面模块**的公共底座 ⇒ 先下沉它,M4 的 6 个包才都能依赖它
|
||||
3. 有现成套路可复用:M2 的「转发壳 + 闸门扫真源 + 反自证两处注入」直接套用
|
||||
|
||||
M1 完成后打 tag `v0.1.1-m1`,再进 M2。
|
||||
M3 完成后打 tag `v0.1.3-m3`,再进 M4(6 个契约面包并行)。
|
||||
⚠️ M4 之后**必须**做 §5.2 的 `check-contract-scan.py` 兼容包收编 + 重跑 `--self-test`。
|
||||
Reference in new issue
Block a user