- Gitea 仓 private=false(API 改;实测匿名 GET repo/release/asset 均 200/206,gzip 正常) - docs §6.2 与 CLAUDE §4.2 补「公开仓无需凭据;fetch-platform.sh 自动有凭据带凭据、无凭据走匿名」
489 lines
32 KiB
Markdown
489 lines
32 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. 发布与消费方依赖写法(每版本出包,不依赖 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` |
|