Files
ssw-platform/docs/SSPF-PLATFORM-PACKAGE.md
admin dc051d485d docs: 平台仓改为公开 —— 消费方可匿名 clone / 拉 release 包
- Gitea 仓 private=false(API 改;实测匿名 GET repo/release/asset 均 200/206,gzip 正常)
- docs §6.2 与 CLAUDE §4.2 补「公开仓无需凭据;fetch-platform.sh 自动有凭据带凭据、无凭据走匿名」
2026-11-05 14:44:37 +08:00

489 lines
32 KiB
Markdown
Raw Permalink 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. 发布与消费方依赖写法(每版本出包,不依赖 git 仓)
> 🔴 **2026-11-05 依赖模型变更(两次迭代,最终形态 = 方案 C)**:
> - 原「发布期用 `git = { tag }` 锁版本」**已废弃**(见 §6.5)。
> - 「包内源码 + `path` 依赖(消费方重编 17 个平台 crate)」**已升级**。
> - **最终(方案 C)**:平台每版本打**自包含包**,内含**预编译 rlib 完整闭包** `lib/`;
> 消费方用 `--extern` + `-L dependency` 直接喂给 rustc,**零重编平台闭包、零重编
> axum/tokio/serde/**。消费方 `cargo build` 只编自己的 crate(技能仓实测 dev ≈5.7s、
> release ≈11s)。
### 6.1 方案 C 的机制与三条硬约束(务必理解,否则链接期/类型期炸)
**机制**:Cargo 原生不支持把预编译 rlib 当依赖,但消费方**可以不把 sspf 声明为 cargo 依赖**,
改用 `.cargo/config.toml` 的 `rustflags` 直接把 rlib 喂给 rustc:
```toml
[build]
rustflags = [
"--extern", "sspf=…/lib/libsspf-<hash>.rlib",
"--extern", "axum=…/lib/libaxum-<hash>.rlib", # 见约束 ③
"-L", "dependency=…/lib",
]
```
**三条硬约束**(全部实测踩过):
1. **编译器版本必须一致**:rlib 的 ABI 取决于产出它的 rustc。全仓锁 `rustc 1.95.0`
(包内 `rust-toolchain.toml`)。消费方必须同版本,否则链接失败。
2. **`lib/` 必须是构建产物 `deps/` 的完整副本**:不只是 `.rlib`,还必须含
`.rmeta`(类型元数据)和 **proc-macro 的 `.dylib`**(`serde_derive`/`tokio_macros`/…,
编译期展开宏要用)+ 原生 `.a`(pglite 等)。少一样就 `E0463 can't find crate for sspf`。
平台 `release.sh` 已按整目录拷贝(422 个文件)。
3. **公共 API 涉及的外部 crate 必须与消费方同源**:sspf 的签名里带 `axum::Json` /
`http::HeaderMap` / `bytes::Bytes` 等类型。若消费方自己再编一份 axum,就是「同名 crate
的两个实例」(同 version、不同 hash)→ 跨 sspf 边界传参必报 `E0308 mismatched types`
(`multiple different versions of crate 'axum'`)。⇒ 消费方对 **sspf + axum + tokio +
serde + serde_json + http + bytes** 全部走 `--extern` 取 `lib/` 里那一份,**不要在
Cargo.toml 声明这些依赖**。
**两个平台侧实现细节**(消费方不用管,但遇到报错要知道根因):
- `lib/` 的 rlib 是 **bitcode-free** 的(出包时 `--config profile.release.lto=false
--config profile.release.embed-bitcode=false`)。因为 macOS 的 `ld`(libLTO 21)解析不了
rustc 1.95 产出的 LLVM22 bitcode,带 bitcode 会 `could not parse bitcode object file`。
- 因此消费方 **release profile 必须 `lto = false`**(见 §6.4),否则 LTO 找不到 `__bitcode`
段报 `failed to get bitcode from object file for LTO`。
### 6.2 平台仓出包 + 发布(tag / Gitea Release)
**产物名带目标平台后缀**(rlib 与平台/架构绑定,同一版本不同平台是不同包):
```bash
TARGET=$(rustc -vV | sed -n 's/^host: //p') # 如 x86_64-apple-darwin
bash scripts/release.sh 0.5.1 # 出 dist/sspf-v0.5.1-${TARGET}.tar.gz
bash scripts/release.sh 0.5.1 --publish # 出包 + 推 Gitea Release(tag v0.5.1)
```
`--publish` 是**幂等**的:① 确认/创建 Gitea Release `vX.Y.Z`(tag 已存在则直接挂上);
② 删除同名旧 asset;③ 上传 `sspf-vX.Y.Z-<target>.tar.gz`。默认 Gitea `http://127.0.0.1:13300`、
repo `ssw/ssw-platform`,可用 `GITEA_URL` / `GITEA_REPO` / `GITEA_USER` / `GITEA_PASS` 覆盖
(凭据缺省取本机 `git credential`)。
🔓 **平台仓已设为公开**(2026-11-05,`private=false`)⇒ 消费方 clone 与下载 release asset
**均无需凭据**(实测匿名 `GET /releases/download/...` 返回 206、gzip 正常)。`fetch-platform.sh`
会自动「有凭据带凭据、没凭据走匿名」。
> ⚠️ Gitea 默认附件上限 100M,本包约 146M;本机已把 `[attachment] MAX_SIZE` 调到 500
> (`persist/gits/gitea/conf/app.ini`,备份 `app.ini.bak-*`)。换环境需同步调大,否则上传 413。
产物 `dist/sspf-vX.Y.Z-<target>.tar.gz` 内含(解包后为 `sspf-vX.Y.Z/`):
| 路径 | 用途 |
|---|---|
| `bin/sspf-admin` | 🔴 预编译二进制(字面,平台侧已 release 编译),可直接跑 |
| `lib/` | 🔴 **预编译产物完整闭包**(方案 C 核心):sspf 内部 crate + 16 个 registry 依赖 + 全部传递依赖,逐字节等同构建产物 `deps/`(`.rlib`+`.rmeta`+proc-macro `.dylib`+原生 `.a`,共 422 个)。**bitcode-free**,ABI 锁 rustc 1.95.0。消费方靠 `--extern` + `-L dependency` 直链,零重编 |
| `crates/*` | 平台 crate 自包含源码(sspf 门面 + 其 path 依赖闭包,共 17 个;dev 回退用) |
| `src/backend/` | 内核 lib(`ssw-platform`)—— sspf 的 path 依赖(dev 回退用) |
| `Cargo.toml` | workspace 根(`version.workspace = true` 继承靠它;dev 回退用) |
| `Cargo.lock` | 锁定整个闭包,消费方 `--offline` 也能编译(dev 回退用) |
| `rust-toolchain.toml` | 🔴 工具链版本(1.95.0;消费方**必须**复制到仓库根) |
| `docs/SSPF-PLATFORM-PACKAGE.md` | 本文件 |
| `README.md` | 包自述与消费步骤 |
| `frontend/` | 平台前端源码(不含 node_modules/dist,可选随包) |
脚本落盘前跑**两个自检**:
- **自检 A(dev 回退可用性)**:构造最小消费方,`cargo build --offline`,确认包内 path 依赖源码闭包能离线编译。
- **自检 B(方案 C 零重编)**:构造只声明自身直依赖、用 `--extern sspf` + `-L dependency=lib`
的最小消费方,`cargo build` 确认**平台闭包不重编、直接链接预编译 rlib**。
### 6.3 消费方怎么接(方案 C,推荐路径)
1. 取包:优先按 **tag + 目标平台** 从 Gitea Release 拉(`sspf-vX.Y.Z-<target>.tar.gz`),
解包到 `vendor/sspf-vX.Y.Z/`;**只需 `lib/` + `rust-toolchain.toml`**(不需要平台源码)。
(技能仓:`bash scripts/fetch-platform.sh vX.Y.Z` —— 自动从 Gitea Release 下载、只解 rlib+工具链、
生成 config、锁工具链;本地 `dist/` 与 `SSPF_TAR` 作离线回退。)
2. **复制工具链锁**:`cp vendor/sspf-vX.Y.Z/rust-toolchain.toml ./`(确保 rustc 1.95.0)。
3. **生成 `.cargo/config.toml`**(含本机绝对路径,**不要提交**,加进 `.gitignore`):
```toml
[build]
rustflags = [
"--extern", "sspf=vendor/sspf-vX.Y.Z/lib/libsspf-<hash>.rlib",
"--extern", "axum=vendor/sspf-vX.Y.Z/lib/libaxum-<hash>.rlib",
"--extern", "tokio=vendor/sspf-vX.Y.Z/lib/libtokio-<hash>.rlib",
"--extern", "serde=vendor/sspf-vX.Y.Z/lib/libserde-<hash>.rlib",
"--extern", "serde_json=vendor/sspf-vX.Y.Z/lib/libserde_json-<hash>.rlib",
"--extern", "http=vendor/sspf-vX.Y.Z/lib/libhttp-<hash>.rlib",
"--extern", "bytes=vendor/sspf-vX.Y.Z/lib/libbytes-<hash>.rlib",
"-L", "dependency=vendor/sspf-vX.Y.Z/lib",
]
```
`<hash>` 每版本会变(用 `ls lib/libsspf-*.rlib` 取实际名)。`fetch-platform.sh` 已自动生成。
4. **`Cargo.toml` 不要声明** `sspf` / `axum` / `tokio` / `serde` / `serde_json`(全部来自 `lib/`,
见 §6.1 约束 ③)。只声明自己仓库的 path 依赖;若确实需要 sspf 闭包里没有的第三方 crate,
才正常声明并编译它(它不会跨 sspf 边界,无实例冲突)。
5. `.gitignore` 加 `vendor/` 与 `.cargo/config.toml`。
6. release profile 设 **`lto = false`**(见 §6.4)。
7. `cargo build` —— 平台闭包与 axum/tokio 全部**不编译**,直接链接 `lib/` 预编译 rlib。
### 6.4 业务仓侧必须同步配合的 4 件事(仍适用)
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` / `strip="symbols"` / `codegen-units=16`,**不设** `panic`),
但 **`lto` 必须 `false`**(不是 `"thin"`):平台预编译 rlib 是 bitcode-free 的,
开 LTO 会因找不到 `__bitcode` 段直接失败(§6.1)。平台 rlib 已 opt-level=2,损失很小。
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 深链行为一字不改。
### 6.5 旧写法(已废弃,留作历史)
```toml
# ❌ 不再推荐:要求消费方构建时访问 git 服务、且每次重编整个 monorepo
# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }
```
git 依赖**仍可用**(cargo 能解析本仓 workspace 根,2026-11-04 实测 `cargo check` 37.95s 通过),
但**不再作为推荐路径**。新消费方一律走 §6.3 的包依赖。
---
## 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` |