- 物理移出 packs/{asset,books,demo,shop}、modules/ 四个面 A 适配器、纯技能副本、
纯业务测试 crud_it.rs 与 new-pack 脚手架(v0.3.0 tag 完整保留旧形态)。
- 删 example-packs feature / example_packs() / sspf-pack-* 依赖 / packs/* member;
packs_gen.rs 与 modules/mod.rs 生成段降级为恒空的注入点,装配链一条不删;
pack-sync.py 把「零包」钉成合法目标态。
- 尺子不再「跳过」:CP1 防回流清单、check-module 三条、AR2/PACK1 正向断言、
AR17 升级为零业务依赖判据(含注入式反自证)、契约反自证换平台锚点、FACE 零包重算。
- 面 A 冒烟 43→21 条(17 条平台权限闭环 + 4 条业务端点 404);pack_smoke_it 改
运行时防回流探针;auth/db/batch7/permission/seed/routes 单测换平台内置夹具。
- 契约 [MENU_TREE] 收成 5 条系统菜单、[RULER] 改 21/3;README/CLAUDE/HANDOFF/
CHANGELOG/contract §5.1/schema.sql/db.rs 注释同步。
验收:cargo test --workspace --no-fail-fast 649 passed / 0 failed / 6 ignored;
verify.sh --smoke 14/14;check-arch 24/24 + 反自证 14/14;
cargo tree -p sspf 无 sspf-pack-*。前端 src/frontend 按要求保留。
374 lines
24 KiB
Markdown
374 lines
24 KiB
Markdown
# SSPF 标准平台包 —— 给 `ssw-platform` 仓的 P0 需求
|
||
|
||
> 提出方:`tdc-rs`(业务仓 / 依赖方) 日期:2026-11-04 状态:**已实施 → tag `v0.2.0`**
|
||
>
|
||
> **实施落点(2026-11-04 交付)**:`crates/sspf`(门面 + `Platform` builder + `runtime`);
|
||
> 内核 4 个示例包降为 `example-packs` feature;`sspf-admin` 退化为 CLI 薄壳;
|
||
> 探针 `crates/tests/tests/external_consumer_it.rs`;闸门 AR17/AR18(含反自证 13/13)。
|
||
> 与原稿的三处**有意偏离**见 §10。
|
||
>
|
||
> 适用范围:本仓(`ssw-platform`)。本轮**不碰 tdc-rs 代码**,也不改面 A / 面 B 的任何对外行为。
|
||
>
|
||
> ⚠️ 本稿 §2–§6 的「现状」行号是 **v0.2.0 交付前**的快照。2026-11-04 的零业务清理
|
||
> 已把 `packs/` 与 `modules/*.rs` 搬到技能仓,这几处源码的行号与结构均已变化 ⇒
|
||
> 引文改为**不带行号的路径**(保留文件级定位,不再对失效的旧行号做核对)。
|
||
> 结论先行:sspf 已有的平台能力(面 B 全套、`base_*` 181 张表、cipher、602 码、704 测试)都不用重做,
|
||
> **缺的只有一层「可被外部仓依赖 + 可被业务仓装配」的门面**。
|
||
|
||
---
|
||
|
||
## 0. 背景与目标
|
||
|
||
架构方向(用户已定):
|
||
|
||
- **sspf = JNPF 替代品**,作为**可版本锁定的标准平台包**发布;
|
||
- **tdc-rs = 一个依赖 sspf 的业务项目**(18 实体 / 35 张 `tdc_*` 表 / 132 条 `/api/ssw/tdc/**` 端点);
|
||
- 两者编成**一个二进制、一个进程、一个库、一个端口**交付;
|
||
- **兼容 JNPF**:官方 jweb 前端直接指着这个进程跑,tdc 现有前端也照旧跑。
|
||
|
||
分界线在 Java 版现成就有(调研自 `ssw-mvp`):平台 jar ↔ `boot/ssw-tdc` 业务源码、
|
||
`j7.base_*` ↔ `tdc.tdc_*`、`/api/oauth|permission|system` ↔ `/api/ssw/**`。
|
||
本 P0 就是把这条分界线在 Rust 侧变成 **Cargo 依赖 + 装配注入**。
|
||
|
||
业务仓最终期望的入口(形状示意,签名可按实现调整,语义不可少):
|
||
|
||
```rust
|
||
// tdc-rs/src/main.rs(P1 才写,本轮只是给平台侧看目标形态)
|
||
sspf::Platform::new()
|
||
.packs(tdc::packs()) // 业务包 / 业务 DDL(同一个 Db)
|
||
.menus(tdc::menus()) // 业务菜单注入两段式种子
|
||
.router(tdc::router()) // 132 条自定义端点(含三道门中间件)
|
||
.static_dir("static") // 上游 jweb 构建产物 + 深链回退
|
||
.serve().await // 一个库、一个 Router、一个端口
|
||
```
|
||
|
||
---
|
||
|
||
## 1. P0 交付物(做完打 tag `v0.2.0`)
|
||
|
||
| # | 交付物 | 位置 |
|
||
|---|---|---|
|
||
| 1 | 门面 crate `sspf`(业务仓**唯一**依赖,不直接碰 19 个 `sspf-*` crate) | `crates/sspf/`(新增) |
|
||
| 2 | 内核的**业务层清单注入化**,4 个示例包降为默认关闭的 feature | `src/backend/**` |
|
||
| 3 | 进程级启动动作从 `sspf-admin` 抽到门面;`sspf-admin` 退化为 CLI 薄壳 | `crates/sspf-admin/src/main.rs` |
|
||
| 4 | 外部消费探针测试:只依赖 `sspf` 就能起一个服务 | `crates/tests/tests/` |
|
||
| 5 | 两条新闸门 AR17 / AR18(带 `--self-test` 反自证) | `scripts/check-arch.sh` |
|
||
| 6 | 发布说明 + 业务仓依赖写法 | `docs/` 或 `HOWTO_MODULE.md` |
|
||
|
||
---
|
||
|
||
## 2. 硬约束(不可协商,违反会在链接期或运行期炸)
|
||
|
||
**C1 · 单进程只有一个 PGlite 实例。**
|
||
`pglite-rs 0.2` 内部有进程级 `static OPEN`,`../tdc-rs/src/main.rs:111` 已实测:一进程第二次 `PGlite::open()` 直接失败。
|
||
⇒ 平台与业务**必须共用同一个 `Db` / `AppState`**;门面必须提供「把业务 DDL 注进同一个库」的注入点;
|
||
**禁止**让业务仓自己开库,也别把「业务库独立」写进任何设计。tdc 的 35 张 `tdc_*` 表与 181 张 `base_*` 表同库。
|
||
|
||
**C2 · 装配链只有一条。**
|
||
`src/backend/src/routes.rs:2542` 的 `build_app` 是唯一权威链(`fallback` 在两个 `layer` 之前、`with_state` 在链尾,S25)。
|
||
业务 Router、业务中间件、SPA fallback 必须由门面**注入后 merge**;业务仓不得自己抄一遍 `fallback + layer + with_state`,
|
||
否则 404 兜底与 catch-all 保护范围会静默错位。
|
||
|
||
**C3 · 面 A / 面 B 行为一字不改。**
|
||
`Vue-Version: 3` 判别(`JNPF_COMPAT_SURFACE.md` §2.2)、`base_*` 表逐字、cipher、602 码、
|
||
契约 §6.5「panic ⇒ HTTP 200 + `code=400`」全部保持。
|
||
⇒ `[profile.release] panic = "unwind"` 必须保留(见 C6 的业务仓配套)。
|
||
⇒ **JNPF 兼容面不许裁剪成「只做登录」**:`ssw-mvp/boot/ssw-tdc/ssw-tdc-biz/pom.xml` V1.5.9 的注释写明,
|
||
独立 TDC 节点为自闭环引的是**全量 JNPF jar** ⇒ 面 B 全套平台能力要随平台包一起进业务二进制。
|
||
|
||
**C4 · 平台包里零业务。**
|
||
`ssw_platform` 现在编译期依赖 `packs/{asset,demo,shop,books}`(`src/backend/Cargo.toml`(生成段))
|
||
+ `modules/mod.rs` 生成段。业务仓一依赖门面就会被拖进四个示例包 ⇒ 改为 **builder 注入**。
|
||
默认 feature 下 `cargo tree -p sspf | grep sspf-pack` 必须**无输出**;这正是 AR9 想要的终局。
|
||
|
||
**C5 · 工具链与契约版本。**
|
||
全仓锁 `rustc 1.95.0`(`rust-toolchain.toml`,L3 dylib 的 ABI 前提)。
|
||
⚠️ rustup 按**当前工作目录**选 toolchain ⇒ 业务仓必须自带同名 toolchain 文件,平台侧无法代劳(已在 §6 列为业务仓配套)。
|
||
契约版本仍为 `CONTRACT_VERSION = "0.4.0"`,业务包 `kernel_req = ">=0.4,<0.5"` 不变;
|
||
`crates/sspf` 的 cargo 版本独立取 `0.2.0`,两者不要混。
|
||
|
||
**C6 · 依赖纪律不破。**
|
||
AR1(`sspf-sdk` 只依赖 `sspf-contract`)、AR2(`packs/*` ⊆ `{sspf-sdk, serde}`)、
|
||
AR9 / AR10 / AR15 / AR16 全绿。门面 crate 是汇聚点,但**不得出现 `tdc` / 任何业务表名或端点字面量**。
|
||
新增 `tower-http`(`fs` feature)用于 SPA 托管是允许的,但只挂在门面,不进 `sspf-sdk`。
|
||
|
||
**C7 · 不强求业务走声明式 CRUD。**
|
||
tdc 现有 132 条端点是自造六件套形状(含子表聚合、账号层、TDS 出向),**不是**官方 RESTful 每实体 3 条。
|
||
P0 只需提供「自定义 `Router` 注入 + DDL 注入 + 会话/DB 复用」;
|
||
把 tdc 改成 `EntitySpec` 声明是 P2 的事,**本轮不要顺手改业务契约**。
|
||
|
||
---
|
||
|
||
## 3. 门面 crate 规格
|
||
|
||
### 3.1 `crates/sspf/Cargo.toml`
|
||
|
||
```toml
|
||
[package]
|
||
name = "sspf"
|
||
version = "0.2.0" # 显式版本,不用 version.workspace = true(业务仓要锁它)
|
||
edition = "2021"
|
||
rust-version = "1.85"
|
||
|
||
[features]
|
||
default = []
|
||
example-packs = [] # 只给 sspf-admin 与 crates/tests 用;业务仓不开
|
||
|
||
[dependencies]
|
||
ssw-platform = { path = "../../src/backend" }
|
||
sspf-contract = { path = "../sspf-contract" }
|
||
sspf-sdk = { path = "../sspf-sdk" }
|
||
sspf-core = { path = "../sspf-core" }
|
||
sspf-store = { path = "../sspf-store" }
|
||
sspf-plugin = { path = "../sspf-plugin" }
|
||
sspf-mcp = { path = "../sspf-mcp" }
|
||
axum = { workspace = true }
|
||
tokio = { workspace = true }
|
||
tower-http = { version = "0.6", features = ["fs"] }
|
||
pglite-rs = { workspace = true }
|
||
libc = { workspace = true }
|
||
```
|
||
|
||
> `version.workspace = true` 跨仓 path 依赖已实测可行(`/tmp/sspf-probe` 引 `sspf-contract` + `sspf-sdk`,
|
||
> `cargo check --offline` 13.23s 通过,workspace 根会沿路径向上解析回本仓)。
|
||
> 但**门面自身显式写版本**,让业务仓锁的是语义版本而不是本仓 workspace 版本。
|
||
|
||
### 3.2 必须公开的 API
|
||
|
||
四类,缺一不可:
|
||
|
||
1. **契约与包类型**(原样重导出,业务仓不直接依赖 `sspf-contract` / `sspf-sdk`)
|
||
`ActionResult` / `code` / `envelope`、`EntitySpec` / `ColumnSpec` / `MenuSpec`、
|
||
`PackRoute` / `HttpMethod` / `RouteAction` / `RouteGuard`、`BusinessPack` / `Manifest` / `PackHooks`、
|
||
`PackRegistry` / `PackSource` / `load_static` / `merge`。
|
||
2. **运行时类型**(业务 handler 要能接平台会话与同一个库)
|
||
`AppState`(`config` / `db` / `sessions` / `tickets` 四个 `Arc`)、`Db`、`Config` / `Profile`、
|
||
`SessionStore`、`seed::ensure_base`、`crud::crud_router`、`guard`、`cipher`。
|
||
3. **装配 builder**:`Platform::new()` + 下列注入点(名称可调整,语义不可少)
|
||
|
||
| 注入点 | 语义 | 对应现状 |
|
||
|---|---|---|
|
||
| `.packs(reg)` 或 `.pack(...)` | 外部业务包 / DDL 注册 | `packs_gen::registry()` 写死 4 包 |
|
||
| `.ddl(sql)` | 业务建表 SQL,幂等,注进**同一个 `Db`** | `bootstrap::ensure_pack_schema` |
|
||
| `.menus(&[MenuSpec])` | 业务菜单注入种子 | `bootstrap::ensure_base(db, modules::all_menus())` |
|
||
| `.router(Router<AppState>)` | 业务自定义路由(含自己的中间件/守卫) | `routes.rs:1252` 的 `modules::router()` |
|
||
| `.static_dir(path)` | 静态 SPA 托管 + 深链回退 | 平台侧目前没有,tdc 侧有 `tower_http` |
|
||
| `.on_ready(async fn)` | 业务启动钩子(tdc 的引导身份/TDS 预热) | 无 |
|
||
| `.build(state) -> Router` | 走**唯一** `build_app` 链 | `routes::build_app` |
|
||
| `.serve()` / `runtime::serve()` | 完整进程级动作 | `crates/sspf/src/runtime.rs:30` |
|
||
|
||
4. **启动动作**:把 `run()` 的 7 步整体搬进 `sspf::runtime`:
|
||
定位项目根 → 读配置 → 标识符白名单自检(**开库前**)→ 业务包装载自检(**开库前**)
|
||
→ 开库 + 平台/业务建表 → 两段式种子 → 生产档弱密钥守卫 → 路由装配 → 绑端口 → 优雅停机 → `shutdown_pg`。
|
||
`whitelist_self_check` / `open_db` / `shutdown_pg` / `shutdown_signal` 一并迁出。
|
||
`sspf-admin` 只留 `parse_args` / `--enc` / `--mcp [--with-http]` stdio 接管 /
|
||
`--seed-lowcode-demo` 子命令,全部调门面。
|
||
|
||
### 3.3 装配顺序(写死,别让业务仓自己排)
|
||
|
||
```
|
||
开库前自检 → 开库 → 平台 DDL(schema.sql) → 业务 DDL(包/注入) → 平台种子 ensure_base(平台+业务菜单)
|
||
→ first_seed → 生产档守卫 → 构 AppState → 启动钩子 → build_app(平台路由 + 业务路由 + SPA fallback)
|
||
→ bind → graceful shutdown → shutdown_pg
|
||
```
|
||
|
||
⚠️ `bootstrap.rs:45` 的 `PACKS: OnceLock<...>` 是 **first-call-wins**:builder 注入必须在**第一次 `packs()` 调用之前**完成,
|
||
或改成构建期确定。别让「业务仓注入了包,但单例已被空注册表占了」这种静默失败发生。
|
||
|
||
---
|
||
|
||
## 4. 逐文件改造清单
|
||
|
||
| 文件 | 现状 | P0 改法 |
|
||
|---|---|---|
|
||
| `src/backend/Cargo.toml` | 生成段写死 4 个 `sspf-pack-*` 依赖 | 改为 `optional = true` + `[features] example-packs = [...]`;**同步改 `scripts/pack-sync.py`**,否则下次生成会覆盖回去 |
|
||
| `src/backend/src/packs_gen.rs` | `registry()` 硬编码 4 次 `load_static` | 提供 `registry_from(Vec<PackSource>)`;`registry()` 在 `#[cfg(feature="example-packs")]` 下才装 4 包,否则返回空注册表 |
|
||
| `src/backend/src/modules/mod.rs` | 生成段 `ALL_SPECS/ROUTES/MENUS/router()` | `all_menus()` / `router()` 改为「默认空 + 由 builder 注入」;`modules` 测试里断言 4 个基准模块的用例迁到示例包自身或加 `cfg`,**别让闸门变假** |
|
||
| `src/backend/src/routes.rs` | `.merge(modules::router())`、`pack_router_or_empty()` | 新增 `build_app_with(state, extras)` 承载注入;`build_app(state)` 保留为「extras 为空」的薄封装 ⇒ 704 个测试一行不用改 |
|
||
| `src/backend/src/bootstrap.rs` | `ensure_base(db, modules::all_menus())`、`ensure_schema_all(db)` | 参数化:`ensure_base(db, menus)`、`ensure_schema_all(db, reg, extra_ddls)`;保留旧签名薄封装 |
|
||
| `crates/sspf-admin/src/main.rs:1-46` | `run()` 含全部进程级动作 | 抽到 `sspf::runtime::serve`;本文件只留 CLI(实施后 381 行,启动动作见 `crates/sspf/src/platform.rs:251`) |
|
||
| `crates/tests/tests/` | 37 个集成测试 | 新增 `external_consumer_it.rs`:只 `use sspf::Platform`,断言①示例包路由/表不存在②面 B 全套仍 200③一个 `Db` 一个端口 |
|
||
| `scripts/check-arch.sh` | AR1–AR16 + MEM1/2 | 新增 **AR17**(内核默认 feature 下不得编译期依赖 `packs/*`)、**AR18**(门面 crate 不得出现 `tdc` / 业务表名 / 端点字面量);两条都要 `--self-test` 反自证注入 |
|
||
| `scripts/pack-sync.py` / `new-pack.sh` | 生成 4 处派生位置 | 适配 optional feature 与注入式清单;`verify.sh` 第一步 `--check` 必须绿 |
|
||
| `scripts/verify.sh` | 6 把静态闸门 + 6 把运行时尺子 | 把新 `sspf` crate 纳入 `--workspace` 与闸门扫描面(**别只扫旧目录**,HANDOFF 里「尺子变瞎」踩过三次) |
|
||
|
||
---
|
||
|
||
## 5. 验收判据(P0 出口,逐条可跑)
|
||
|
||
```bash
|
||
cargo test --workspace # ≥ 704 passed / 0 failed(新增探针测试只增不减)
|
||
bash scripts/verify.sh --fast # 6 把静态闸门全绿
|
||
bash scripts/check-arch.sh --self-test # 含新 AR17/AR18 反自证,21/21 → 23/23
|
||
bash scripts/verify.sh --smoke # 运行时 6 把尺子全绿
|
||
bash scripts/perm-smoke-jnpf.sh # 面 B 18/18(官方形状没被改坏)
|
||
```
|
||
|
||
外加三条**外部性**判据(不能只靠本仓自测):
|
||
|
||
1. `cargo tree -p sspf | grep sspf-pack` —— 默认 feature 下**无输出**;`sspf` 里 `grep tdc` 无输出。
|
||
2. 外部探针:在仓外建最小项目,只写 `sspf = { path = ".../ssw-platform/crates/sspf" }`,
|
||
`cargo check --offline` 通过且能 `use sspf::Platform`;启动后 `GET /api/health` 返回
|
||
**`ok:true`**。⚠️ 实测 **`tables=177`**(不是 181):181 = 177 张平台表 + 4 张示例包表,
|
||
而平台包默认**不带**示例包 ⇒ 业务仓看到的就是 177 + 它自己注入的表。
|
||
本仓 `sspf-admin`(开了 `example-packs`)仍是 181。
|
||
3. 单进程烟测:探针 `.pack(...).router(...).serve()` 起**一个**端口,面 B 端点与注入的业务端点同时 200,
|
||
且 `/api/health` 里业务表已建(证明业务 DDL 走的是同一个 `Db`)。
|
||
⇒ 已固化为 `crates/tests/tests/external_consumer_it.rs`(一条测试覆盖 ①②③)。
|
||
|
||
---
|
||
|
||
## 6. 发布与业务仓依赖写法
|
||
|
||
打 tag **`v0.2.0`**;CHANGELOG 只写「改了什么 / 什么影响」,5–8 行,不写过程与 commit hash。
|
||
|
||
```toml
|
||
# tdc-rs/Cargo.toml —— 开发期
|
||
sspf = { path = "../ssw-platform/crates/sspf" }
|
||
# 发布期(换成 git tag 锁版本,路径按内网 Gitea 实际仓库改)
|
||
# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }
|
||
```
|
||
|
||
✅ **git 依赖已实测(2026-11-04 打 tag 当场验的)**:仓外最小项目只写
|
||
`sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }`,
|
||
`cargo check` **37.95s 通过** —— cargo 正确解析了本仓 workspace 根,全部依赖都标注
|
||
`?tag=v0.2.0#9083394b`,`sspf 0.2.0` 可 `use`,与 path 依赖等价。
|
||
|
||
业务仓(tdc-rs)侧必须同步配合的 4 件事,**属于 P1,不阻塞 P0**:
|
||
|
||
1. 补 `rust-toolchain.toml` 锁 `1.95.0`(rustup 按 cwd 选版本,平台侧代劳不了)。
|
||
2. **删掉 `[profile.release] panic = "abort"`**:单进程链接后 release profile 由业务仓根决定,
|
||
`abort` 会让 `catch_unwind` 抓不到 panic ⇒ 契约 §6.5 破、进程直接死。同时照抄本仓 release 设置
|
||
(`opt-level=2` / `lto="thin"` / `strip="symbols"` / `codegen-units=16`,**不设** `panic`)。
|
||
3. 补 `[profile.dev] incremental = false`(本地已有未提交改动,勿覆盖)。
|
||
4. 冻结对外契约基线:132 条端点(`docs/contract.md`)、12 个测试二进制、五把尺子
|
||
(`smoke.sh` / `check-boundary.sh` / `check-contract.sh` / `check-entity.sh` / `check-upstream-tests.sh`),
|
||
401/403 裸三键与静态 SPA 深链行为一字不改。
|
||
|
||
---
|
||
|
||
## 7. 明确不做(P0 边界)
|
||
|
||
- 不改面 A / 面 B 任何端点形状、码表、表结构;不裁剪面 B 能力。
|
||
- 不迁 tdc 业务代码,不在本仓建 `packs/tdc`,不要求 tdc 改成 `EntitySpec` 声明式 CRUD(C7)。
|
||
- 不引入真实 PG / 不改 pglite 单实例前提;不要求 L3 dylib(单进程静态链接即可)。
|
||
- 不把 4 个示例包删掉(它们仍是 `new-pack.sh` 样板),只是**默认不链接进依赖方**。
|
||
|
||
---
|
||
|
||
## 8. tdc-rs 侧并行计划(信息性,不要求本仓配合)
|
||
|
||
| 批次 | 动作 | 出口 |
|
||
|---|---|---|
|
||
| P1 | 补 toolchain / 修 profile / 建 `packs/tdc` 骨架 / 契约冻结测试 | 12 个测试二进制与五把尺子全绿,对外行为零变化 |
|
||
| P2 | 18 实体 → `EntitySpec` + DDL 跟包走;132 条自定义端点归扩展 crate | 平台层零业务知识 |
|
||
| P3 | 面 B 与 tdc 契约双跑 | 一个端口同时接 jweb 官方页与 tdc 业务页 |
|
||
|
||
P1 的准备工作可与本 P0 **并行**,但 `main.rs` 换装配必须等 `v0.2.0` tag。
|
||
|
||
---
|
||
|
||
## 9. 风险与已知坑(都是踩过的)
|
||
|
||
| 坑 | 说明 |
|
||
|---|---|
|
||
| `OnceLock` first-call-wins | `bootstrap::packs()` 一旦被空注册表占住,外部注入静默失效(§3.3) |
|
||
| pglite 单实例 | 业务仓另开一次 `PGlite::open()` 直接失败;必须共用 `AppState.db`(C1) |
|
||
| 装配链被抄第二遍 | `fallback` 与两个 `layer` 的顺序错位 ⇒ 404 兜底失去保护,且测试全绿看不出来(C2) |
|
||
| `panic = "abort"` | release 下 catch-all 失效;profile 由**业务仓根**决定,不在平台控制范围(§6) |
|
||
| 生成段覆盖 | `pack-sync.py` 会重写 `Cargo.toml` / `packs_gen.rs` / `modules/mod.rs`;P0 改法必须落进生成器 |
|
||
| 闸门「尺子变瞎」 | HANDOFF §M2/M4/M7 三次踩到:搬迁后闸门扫空壳 ⇒ 全绿反而是坏信号。新增 crate 必须扩扫描面 + 反自证 |
|
||
| 数字会漂 | 704 测试 / 181 张表 / 面 B 18 条尺子是 2026-11-04 的基线;断言写「≥」或用结构性判据,别写死条数 |
|
||
|
||
---
|
||
|
||
## 10. 实施记录(2026-11-04,tag `v0.2.0`)
|
||
|
||
> ⚠️ **v0.3.0 起装配顺序有变**:`with_state` 已从链尾**前移**到 merge 自带状态业务路由之前
|
||
> (`fallback` 仍在两个平台 `layer` 之前)。本文记的是 `v0.2.0` 当时的历史形态,
|
||
> 现行链见 `docs/SSPF-BUSINESS-COMPOSITION.md` §5 / §11.3。
|
||
|
||
### 10.1 交付物落点
|
||
|
||
| # | 交付物 | 实际位置 |
|
||
|---|---|---|
|
||
| 1 | 门面 crate `sspf`(0.2.0) | `crates/sspf/`:`lib.rs`(重导出)/ `platform.rs`(builder)/ `runtime.rs`(启动动作) |
|
||
| 2 | 内核业务层选装化 | `src/backend/Cargo.toml` 的 `[features] example-packs` + `packs_gen.rs` / `modules/mod.rs` 的 `cfg` 双份生成 |
|
||
| 3 | 进程级启动动作 | `crates/sspf/src/{platform,runtime}.rs` + 内核 `src/backend/src/boot.rs`(平台表清单等原语) |
|
||
| 4 | 外部消费探针 | `crates/tests/tests/external_consumer_it.rs`(一个测试函数,`use sspf::{Config, Db, Platform}`) |
|
||
| 5 | 闸门 AR17 / AR18 | `scripts/check-arch.sh`(反自证 11 → 13 条) |
|
||
| 6 | 发布说明 / 依赖写法 | 本文 §6 + §10.3 |
|
||
|
||
### 10.2 与原稿的四处偏离(都是「更简单 / 更严格」,语义不变)
|
||
|
||
1. **`registry_from` 收 `Vec<PackRegistry>`,不收 `Vec<PackSource>`。**
|
||
`PackSource` 里带的是**未解析**的 `manifest` 字段,合并它是「重复一遍装载器的校验」;
|
||
业务仓的正路是 `load_static(...)?` 得到 `PackRegistry` 再合并 ⇒ 门面 `merge` 一个即可。
|
||
2. **白名单自检留在内核(`ssw_platform::boot`),门面只做编排。**
|
||
那 123 张 `base_*` 表清单 + 与 `schema.sql` 双向对账是**平台知识**;
|
||
搬进门面等于让门面维护第二份平台表清单(必然漂)。门面只负责「把业务 spec /
|
||
包 DDL 传进去」。`sspf::runtime` 仍然对外导出这几个函数(业务仓不必认识 `ssw_platform`)。
|
||
3. **`.ddl(table, sql)` 要表名**(原稿写的 `.ddl(sql)`)。
|
||
表名是**受保护表登记**(低代码建模页不许 ALTER / DROP)与白名单对账的判据;
|
||
从 SQL 里正则抠表名 = 把「一条 DDL 一句建表」这个约定变成隐式解析 ⇒ 不如明写。
|
||
4. **静态 SPA 托管手写在内核 `routes.rs`,没有引 `tower-http`。**
|
||
需求只有「非 `/api/**` 未命中 ⇒ 文件 / `index.html`」一条,`tokio::fs` + 一张 MIME 表
|
||
就够(且 `Content-Type` 完全可控)。少一个依赖 = 少一处业务仓要跟着升级的版本。
|
||
|
||
### 10.3 还有一处**加强**(不是偏离,是比原稿更硬)
|
||
|
||
原稿 §3.3 的提醒是「builder 注入必须在第一次 `packs()` 之前」。
|
||
实施时发现更危险的形态:**feature 统一(feature unification)**。
|
||
`sspf-tests` 为了测示例包必须开 `example-packs`,同一个构建图里门面拿到的内核
|
||
**也是开着的**。若门面去读 `bootstrap::packs()` 那个 `OnceLock`,示例包就会
|
||
**静默**跟着进业务仓的进程 —— 而且测试全绿(因为测试也期望它在)。
|
||
|
||
⇒ 门面**一次都不读**那个单例:全程用显式传入的 `PackRegistry`(默认空)。
|
||
结果是更强的保证:**默认装配恒零业务**,连「开了 feature 的构建」也一样 ——
|
||
`external_consumer_it` 正是这么断言的(该构建里 feature 是开的)。
|
||
|
||
### 10.4 发布说明(v0.2.0)
|
||
|
||
- 新增门面 crate `sspf` 0.2.0:业务仓唯一依赖,`Platform` builder + `runtime` 启动动作。
|
||
- 内核 4 个示例包降为 `example-packs` feature ⇒ 默认依赖树里没有 `sspf-pack-*`。
|
||
- `build_app_with(state, extras)` 承载业务路由 / 包路由 / SPA 目录注入;`build_app` 行为不变(零迁移)。
|
||
- `sspf-admin` 从 1111 行降到 381 行:只解析命令行,启动全交门面。
|
||
- 新增 AR17(平台包零业务依赖)/ AR18(门面零业务字面量),反自证 13/13。
|
||
|
||
**实测数字(2026-11-04)**:`cargo test --workspace` **710 passed / 0 failed**(基线 704);
|
||
`cargo tree -p sspf | grep sspf-pack` 无输出;`check-arch.sh` 29/29、`--self-test` 13/13;
|
||
`verify.sh --fast` 八步全绿;运行时尺子 perm-smoke 43/43、perm-smoke-jnpf 23/23、
|
||
lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14;
|
||
仓外探针(`/tmp/sspf-ext-probe`,只依赖 `sspf`)`cargo build --offline` 通过,
|
||
`PGLITE_DIR=memory:// PORT=30999 ./probe` 起服务后 `GET /api/health` =
|
||
`{"ok":true,"tables":177,"version":"0.1.0"}`(177 = 平台表,不含 4 张示例包表);
|
||
**git tag 依赖**(`/tmp/sspf-git-probe`,`tag = "v0.2.0"`)`cargo check` 通过(37.95s)。
|
||
|
||
### 10.5 实施时踩到的两个坑(留给下一次)
|
||
|
||
| 坑 | 说明 |
|
||
|---|---|
|
||
| `\btdc\b` 匹配不到 `tdc_order` | Python 的 `\w` 含下划线 ⇒ 尾边界失效。AR18 的正则**去掉了尾边界**(宁可多报,不许漏报) |
|
||
| `#[cfg]` 只能加在**项**上 | `ALL_SPECS` 的数组元素不能单独 cfg ⇒ 生成器改成「同名常量 / 函数各生成两份(feature / not feature)」。整段 cfg 会让 `all_specs()` / `router()` 在默认 feature 下**不存在** ⇒ `routes.rs` / `bootstrap.rs` 编译不过 |
|
||
| **`.packs()` 不等于「业务都进去了」** | 面 A(`/api/ssw/**`)来自内核 `modules::router()`,门面不认识它 ⇒ `sspf-admin` 必须**显式** `.router(modules::router())`,否则面 A 全 404(`perm-smoke` 29 条红) |
|
||
| **包菜单必须自动种** | 只种 `.menus()` 而漏掉 `PackRegistry.menus` ⇒ `module_key` 守卫查不到菜单 ⇒ 该 403 的请求**静默 200**(`perm-smoke` 6 条红)。现在 `.packs()` 自动带菜单进种子 |
|
||
|
||
---
|
||
|
||
## 附录:本需求依据的文件出处(均在本仓或业务仓内可核查)
|
||
|
||
| 事实 | 出处 |
|
||
|---|---|
|
||
| 内核编译期依赖 4 包 | `src/backend/Cargo.toml`、`src/backend/src/packs_gen.rs` |
|
||
| 业务层清单生成段 | `src/backend/src/modules/mod.rs` |
|
||
| 唯一装配链 / 业务 merge 点 | `src/backend/src/routes.rs` |
|
||
| 两段种子 / 建库 / 包单例 | `src/backend/src/bootstrap.rs:45, 86, 177` |
|
||
| 进程级 7 步启动 | `crates/sspf/src/platform.rs:251`(`boot` 的 1–6 步)+ `crates/sspf/src/runtime.rs:30`(绑端口 / 停机 / 关库) |
|
||
| `load_static` 签名 | `crates/sspf-plugin/src/lib.rs:492-517` |
|
||
| `BusinessPack` trait / AR1·AR2 | `crates/sspf-sdk/src/lib.rs:100-142`、`scripts/check-arch.sh:16-19` |
|
||
| 面 B 判别与规格 | `JNPF_COMPAT_SURFACE.md` §2.2、§3 |
|
||
| 工具链 1.95.0 / release 约定 | `rust-toolchain.toml`、`Cargo.toml` `[profile.release]` |
|
||
| 704 测试 / 181 张表基线 | `HANDOFF.md:18, 30` |
|
||
| pglite 单实例 | `../tdc-rs/src/main.rs:111-114` |
|
||
| tdc 132 端点 / 五把尺子 | `../tdc-rs/CLAUDE.md:162-184, 234` |
|