Files
ssw-platform/docs/SSPF-PLATFORM-PACKAGE.md
T
admin 3f2d56be20 feat(release): 按 tag+目标平台发包到 Gitea Release(--publish)+ 修包内 README
- release.sh: 产物名带 target 后缀(sspf-vX.Y.Z-<target>.tar.gz,rlib 与平台绑定)
- 新增 --publish:幂等创建/复用 Gitea Release(tag vX.Y.Z) → 删同名 asset → 上传
  (GITEA_URL/REPO/USER/PASS 可覆盖;凭据缺省取本机 git credential)
- 修 README 模板:删掉「保留 axum/tokio 依赖、自己编一次」的旧说法(与 §6.3 矛盾),
  改为「全走 --extern 取 lib/、Cargo.toml 不声明、release 必须 lto=false、注明目标平台」
- docs §6.2/6.3 同步:--publish 用法、Gitea 附件上限 100M→本机已调 500 的告警
2026-11-05 13:45:17 +08:00

31 KiB
Raw Blame History

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 依赖 + 装配注入。

业务仓最终期望的入口(形状示意,签名可按实现调整,语义不可少):

// 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 --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 出口,逐条可跑)

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:

[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 与平台/架构绑定,同一版本不同平台是不同包):

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)。

⚠️ 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):

    [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 旧写法(已废弃,留作历史)

# ❌ 不再推荐:要求消费方构建时访问 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