- Gitea 仓 private=false(API 改;实测匿名 GET repo/release/asset 均 200/206,gzip 正常) - docs §6.2 与 CLAUDE §4.2 补「公开仓无需凭据;fetch-platform.sh 自动有凭据带凭据、无凭据走匿名」
32 KiB
SSPF 标准平台包 —— 给 ssw-platform 仓的 P0 需求
提出方:
tdc-rs(业务仓 / 依赖方) 日期:2026-11-04 状态:已实施 → tagv0.2.0实施落点(2026-11-04 交付):
crates/sspf(门面 +Platformbuilder +runtime); 内核 4 个示例包降为example-packsfeature;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 依赖 + 装配注入。
业务仓最终期望的入口(形状示意,签名可按实现调整,语义不可少):
// 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
[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 --offline13.23s 通过,workspace 根会沿路径向上解析回本仓)。 但门面自身显式写版本,让业务仓锁的是语义版本而不是本仓 workspace 版本。
3.2 必须公开的 API
四类,缺一不可:
-
契约与包类型(原样重导出,业务仓不直接依赖
sspf-contract/sspf-sdk)ActionResult/code/envelope、EntitySpec/ColumnSpec/MenuSpec、PackRoute/HttpMethod/RouteAction/RouteGuard、BusinessPack/Manifest/PackHooks、PackRegistry/PackSource/load_static/merge。 -
运行时类型(业务 handler 要能接平台会话与同一个库)
AppState(config/db/sessions/tickets四个Arc)、Db、Config/Profile、SessionStore、seed::ensure_base、crud::crud_router、guard、cipher。 -
装配 builder:
Platform::new()+ 下列注入点(名称可调整,语义不可少)注入点 语义 对应现状 .packs(reg)或.pack(...)外部业务包 / DDL 注册 packs_gen::registry()写死 4 包.ddl(sql)业务建表 SQL,幂等,注进同一个 Dbbootstrap::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 -
启动动作:把
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 出口,逐条可跑)
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(官方形状没被改坏)
外加三条外部性判据(不能只靠本仓自测):
cargo tree -p sspf | grep sspf-pack—— 默认 feature 下无输出;sspf里grep tdc无输出。- 外部探针:在仓外建最小项目,只写
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。 - 单进程烟测:探针
.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:
[build]
rustflags = [
"--extern", "sspf=…/lib/libsspf-<hash>.rlib",
"--extern", "axum=…/lib/libaxum-<hash>.rlib", # 见约束 ③
"-L", "dependency=…/lib",
]
三条硬约束(全部实测踩过):
- 编译器版本必须一致:rlib 的 ABI 取决于产出它的 rustc。全仓锁
rustc 1.95.0(包内rust-toolchain.toml)。消费方必须同版本,否则链接失败。 lib/必须是构建产物deps/的完整副本:不只是.rlib,还必须含.rmeta(类型元数据)和 proc-macro 的.dylib(serde_derive/tokio_macros/…, 编译期展开宏要用)+ 原生.a(pglite 等)。少一样就E0463 can't find crate for sspf。 平台release.sh已按整目录拷贝(422 个文件)。- 公共 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 与平台/架构绑定,同一版本不同平台是不同包):
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,推荐路径)
-
取包:优先按 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作离线回退。) -
复制工具链锁:
cp vendor/sspf-vX.Y.Z/rust-toolchain.toml ./(确保 rustc 1.95.0)。 -
生成
.cargo/config.toml(含本机绝对路径,不要提交,加进.gitignore):[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已自动生成。 -
Cargo.toml不要声明sspf/axum/tokio/serde/serde_json(全部来自lib/, 见 §6.1 约束 ③)。只声明自己仓库的 path 依赖;若确实需要 sspf 闭包里没有的第三方 crate, 才正常声明并编译它(它不会跨 sspf 边界,无实例冲突)。 -
.gitignore加vendor/与.cargo/config.toml。 -
release profile 设
lto = false(见 §6.4)。 -
cargo build—— 平台闭包与 axum/tokio 全部不编译,直接链接lib/预编译 rlib。
6.4 业务仓侧必须同步配合的 4 件事(仍适用)
- 补
rust-toolchain.toml锁1.95.0(rustup 按 cwd 选版本,平台侧代劳不了)。 - 删掉
[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,损失很小。 - 补
[profile.dev] incremental = false(本地已有未提交改动,勿覆盖)。 - 冻结对外契约基线: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 旧写法(已废弃,留作历史)
# ❌ 不再推荐:要求消费方构建时访问 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 与原稿的四处偏离(都是「更简单 / 更严格」,语义不变)
registry_from收Vec<PackRegistry>,不收Vec<PackSource>。PackSource里带的是未解析的manifest字段,合并它是「重复一遍装载器的校验」; 业务仓的正路是load_static(...)?得到PackRegistry再合并 ⇒ 门面merge一个即可。- 白名单自检留在内核(
ssw_platform::boot),门面只做编排。 那 123 张base_*表清单 + 与schema.sql双向对账是平台知识; 搬进门面等于让门面维护第二份平台表清单(必然漂)。门面只负责「把业务 spec / 包 DDL 传进去」。sspf::runtime仍然对外导出这几个函数(业务仓不必认识ssw_platform)。 .ddl(table, sql)要表名(原稿写的.ddl(sql))。 表名是受保护表登记(低代码建模页不许 ALTER / DROP)与白名单对账的判据; 从 SQL 里正则抠表名 = 把「一条 DDL 一句建表」这个约定变成隐式解析 ⇒ 不如明写。- 静态 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
sspf0.2.0:业务仓唯一依赖,Platformbuilder +runtime启动动作。 - 内核 4 个示例包降为
example-packsfeature ⇒ 默认依赖树里没有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 |