Files
ssw-platform/docs/SSPF-PLATFORM-PACKAGE.md
T
admin ecb77b230f 平台包零业务:示例移到技能仓、解绑 example-packs、闸门全部改防回流
- 物理移出 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 按要求保留。
2026-11-04 21:54:22 +08:00

374 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` |