refactor(arch): M5 低代码执行层下沉 —— 4 模块 / 2,674 行迁入 sspf-lowcode-exec

把 src/backend/src/lowcode_{crud,ddl,check,seed}.rs 下沉到 crates/sspf-lowcode-exec/,
原路径全部变成 5 行转发壳 ⇒ CLI(--seed-lowcode-demo)与 MCP 适配器的调用路径零感知。

与 sspf-lowcode 的分工不变:前者纯计算(AR7 白名单不动),本 crate 是执行层
(连库 / 跑 SQL / 比对真实库列 / 事务 / 回写模型)。

依赖:sspf-lowcode + sspf-core + sspf-store + sspf-mcp + pglite-rs + chrono + serde_json
(比原计划多三个:pglite::ToSql/Error 是直接用的、now_iso() 用 chrono::Local::now()、JSON payload)

闸门改造:
- check-arch.sh 新增 AR13(两层:依赖白名单 + 源码不许 use sspf_pack_*)
- check-arch.sh 反自证 7→8(两处都注入:越界依赖 axum + 业务包引用,按路径分别验)
- check-boundary.sh 新增 LOWCODE_EXEC ⇒ CP1/CP2 纳入执行层真源
  (反向验证:插 LEAK_PROBE ⇒ CP1 报红;还原后 11/11)
- check-contract-scan.py 不用改 —— 契约里零 lowcode 端点(低代码是 MCP 工具不是 HTTP 路由)

🔴 踩坑:改写时把 use crate::lowcode_ddl; 一并改成 use crate::ddl; ⇒ 编译不过。
教训:搬 crate 只改跨 crate 的前缀(crate::platform:: → sspf_core::),
模块名一律不动;文档内链([`crate::lowcode_crud`])也不能跟着改(改了就变死链)。

数字:cargo build 零警告;cargo test 695/0(与 M1 基线完全一致);
check-arch 17/17;--self-test 8/8;check-boundary 11/11;check-contract 10/10;
check-module 123/123;check-citations 4/4;check-naming 3/0/1;
verify.sh --smoke 14 步全绿(377.6s)
This commit is contained in:
admin committed 2026-11-03 20:12:50 +08:00
1 parent e821770f58
commit 98b93967da
18 files changed
+3006 -2698

No files matched your search

+62 -15
View File
@@ -2,9 +2,9 @@
> **基线锚点**:`v0.1.0`(commit `b957a11`,已推送到 `origin`)
> **制定时间**:2026-11-03
> **状态**:**M4 已完成**(tag `v0.1.4-m4`)—— 六个契约面包(14 个模块 / ~49,000 行)下沉完成;
> **状态**:**M5 已完成**(tag `v0.1.5-m5`)—— 低代码执行层(4 个模块 / 2,674 行)下沉完成;
> 四个决策已拍板(§11):壳最后删 / compat 拆 6 包 / mcp_compat 放 crates / tests 跟着拆。
> 下一步 = M5(`sspf-lowcode-exec`)
> 下一步 = M6(`sspf-mcp-adapter`)
---
@@ -434,15 +434,56 @@ ssw-platform/
- [x] `check-naming.sh` = 3 通过 / 0 失败 / 1 提示
- [x] `verify.sh --smoke` 14 步全绿(300.9s)
### 批次 M5 —— 低代码执行层下沉
### 批次 M5 —— 低代码执行层下沉 ✅ 已完成(tag v0.1.5-m5)
**迁入**:`lowcode_{crud,ddl,check,seed}.rs`(2,674 行)
**新 crate**:`crates/sspf-lowcode-exec`(依赖 sspf-lowcode + sspf-core + sspf-store + sspf-mcp)
**新 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 行)
@@ -479,7 +520,7 @@ ssw-platform/
| 🆕 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}(M5 加) |
| 🆕 AR13 | — | ✅ `crates/sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp, pglite-rs, chrono, serde_json} + 源码不许 `use sspf_pack_*` |
> 🔴 **AR11/AR12 的 Cargo.toml 级判据踩过 BSD grep 的坑**:`grep -E '^\s*...'` 在 macOS 上**永远匹配不到**(BSD grep 是 POSIX ERE,不认 `\s`)⇒ 尺子永远"通过"。
> 正确写法:`[[:space:]]`。**这个坑是 AR12 反自证第一次跑就失败暴露的** —— 没有反自证,就带着一把假尺子跑完了 M4。
@@ -593,11 +634,12 @@ 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 ← 🔴 同步加 AR13
M5 sspf-lowcode-exec ← ✅ v0.1.5-m5(4 模块 / 2,674 行)
│ 🔴 同步加 AR13 + check-boundary.sh 纳入执行层
↓
M6 sspf-mcp-adapter ← 决策③:mcp_compat 放 crates
↓
M7 壳收口 + 闸门补全 ← AR13 + 全量反自证 + 删 platform/ 转发壳 + 拆 tests/
M7 壳收口 + 闸门补全 ← 全量反自证 + 删 platform/ 转发壳 + 拆 tests/
```
**每一批的出口判据都相同**:
@@ -654,16 +696,21 @@ bash scripts/verify.sh --smoke # 14 步全绿
## 12. 立即可做的下一步
**执行 M5(`sspf-lowcode-exec`)**。理由:
1. M1/M2/M3/M4 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包都稳了
2. M5 规模最小(2,674 行,4 个模块),是 M6/M7 前最后的低风险批次
3. 套路成熟:M2/M3/M4 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用
**执行 M6(`sspf-mcp-adapter`)**。理由:
1. M1–M5 已完成并打 tag —— 地基、平台核心、契约面底座、六个契约面包、低代码执行层都稳了
2. M6 是**决策③的落地点**(`mcp_compat.rs` 放 crates),也是**唯一高扇入节点** ⇒ 越早做越早验证依赖网
3. 套路成熟:M2–M5 的「转发壳 + 闸门两处扫 + 反自证两处注入」直接复用
M5 完成后打 tag `v0.1.5-m5`。
⚠️ **M5 必须同步做**:① `check-arch.sh` 加 **AR13**(`sspf-lowcode-exec` 依赖 ⊆ {lowcode, core, store, mcp});② `check-boundary.sh` 的 CP6/软删检查若涉及 `lowcode_*.rs` 也要纳入真源;③ 重跑全部 `--self-test`。
之后 = M6(`sspf-mcp-adapter`,决策③放 crates)→ M7(收口:删壳 + tests 拆分 + AR13)。
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 必须继承**:
> 🔴 **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`]``)也不能跟着改。