# SSPF 平台包 v0.3.0 —— 给 `ssw-platform` 仓的 P1 需求:业务自带状态的可组合装配 > 提出方:`tdc-rs`(业务仓 / 依赖方) 日期:2026-11-04 状态:**已实施并发布 → `main` + annotated tag `v0.3.0` 已推送 `origin`** > > ⚠️ **决策 D 于 18:2x 变更**:评审时定的是「只打本地 tag、不 push」,交付后提出方要求 > **直接推送** ⇒ §7.4 / §7.5 / §11.1 / §11.6 与 `HANDOFF.md` 0-bis 均按已发布口径同步。 > > **实施落点(2026-11-04 交付)**:`crates/sspf`(`Assembled` / `Finish` / 两阶段装配)、 > `crates/sspf-store/src/db.rs`(`Arc` + `Db::pg()`)、`src/backend/src/routes.rs` > (`Extras` 三注入点 + 前移 `with_state`)、探针 `business_composition_it.rs`、 > 闸门 AR19(含反自证 14/14)。**四项评审决策与勘误见 §11**。 > > 前置:P0 已交付并验证(`v0.2.0`,门面 `crates/sspf`、示例包选装、AR17/AR18)。 > 业务仓已按 `sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }` 接入, > 提交 `8a351b7`,`cargo test` **280 passed / 0 failed / 1 ignored**,五把尺子全绿,对外行为零变化。 > > 适用范围:本仓(`ssw-platform`)。本轮**不改面 A / 面 B 的任何对外行为**,不改 `v0.2.0` 已发布 API 的签名。 > 结论先行:平台包现在能「被依赖、被启动」,但**还不能承载已有厚业务仓的路由**——业务仓的 132 条端点 > 绑在自己的状态类型上,而 `Platform::router()` 只收 `Router`。缺的是「**自带状态的业务路由** > + **同一个库句柄** + **可替换兜底**」三个注入点,都是平台包内部的小改,不需要重写业务。 --- ## 0. 背景与目标 「sspf 作为 JNPF 替代品、tdc-rs 作为业务项目、单进程部署、兼容 JNPF」的终局形态: ```text 一个进程 · 一个 PGlite 实例 · 一个 Router · 一个端口 ├── 面 B(JNPF 官方形状,346 端点 / base_* 181 张表 / cipher / 602 码)—— 平台包提供 └── /api/ssw/tdc/**(132 条,六件套 + 三道门 + 裸三键 401/403 + SPA)—— 业务仓提供 ``` P0 解决的是「平台包可被外部仓依赖」;**P1 要解的是「业务仓已有装配链能挂进平台包」**。这条一旦通, tdc-rs 的 `src/main.rs` 才能从「自开 PGlite + 自建 AppState + 自抄 fallback/layer/with_state」 切成 `sspf::Platform` 单进程装配,自研 `src/platform/` 才有退场路径。 **出口判据**:tdc-rs 能在不修改任何 handler、不改 132 条端点响应形状的前提下,把整套业务路由 注入平台装配链,单端口同时提供面 B 与 tdc 契约。 --- ## 1. 交付物(做完打 annotated tag `v0.3.0`,并 push) | # | 交付物 | 落点 | |---|---|---| | R1 | `Db` 暴露**同一个** `Arc` 句柄 | `crates/sspf-store/src/db.rs` | | R2 | `assemble()` / `Assembled::finish()` / `Assembled::serve()` 两阶段装配 | `crates/sspf/src/platform.rs` | | R3 | `Extras` 三个注入点(自带状态路由 / 可替换兜底 / 业务 middleware 层) | `src/backend/src/routes.rs` | | R4 | 装配链**仍只有一份**,S25 顺序不变,`build_app()` 行为逐字不变 | `src/backend/src/routes.rs` | | R5 | 新增集成探针 `business_composition_it.rs` + 闸门 AR19(含反自证) | `crates/tests/`、`scripts/check-arch.sh` | | R6 | 仓外 git-tag 探针实测 + `CHANGELOG.md`(P0 缺的那份一起补) | 仓库根 / `/tmp` 探针 | 版本:`crates/sspf/Cargo.toml` 的 `version` 由 `0.2.0` → `0.3.0`(继续**显式写死**,不用 `version.workspace`,否则 git tag 依赖会解析成 workspace 根版本)。 --- ## 2. 硬约束(不可协商) 1. **一个进程只允许一个 `PGlite` 实例**(pglite-rs 内部 `static OPEN`)。平台与业务必须共用 **同一个** `Arc`,不许业务仓再 `PGlite::open()` 或另起 `Db::open_temp()`。 2. **装配链只有一份**。`fallback → m_status_rewrite → catch_all` 的 S25 顺序不许在业务仓里再抄一遍; 业务仓拿到的必须是平台组装完成的 `Router<()>`。 3. **一个 Router 只允许一个 fallback**。axum `Router::merge` 遇到两个 fallback 直接 panic。 业务 Router 不许自带 fallback,兜底只能由 `Finish.fallback` 统一挂。 4. **`v0.2.0` 的公开签名不动**:`Platform::router(Router)`、`Platform::build_app()`、 `Platform::serve()`、runtime 四个函数全部保持原样。新增能力一律走**新入口**。 5. **默认路径逐字等价**:`Finish::default()` 装配出的 Router 与 `v0.2.0` 的 `build_app()` 完全一样 (710 测试 + 面 B 尺子是现成的钉子)。 6. **面 B 不许裁**。Java 版 `ssw-tdc-biz/pom.xml` 引的是全量 JNPF jar,「兼容 JNPF」不等于只做登录; 346 端点 / `base_*` / cipher / 602 码一个都不能少。 --- ## 3. 四条类型级冲突(本轮实测,都是可核查的行号) ### 3.1 状态类型不同 ⇒ 132 条端点注入不了(最硬的一条) - 平台侧:`crates/sspf/src/platform.rs:162` `pub fn router(mut self, router: Router)`; `src/backend/src/routes.rs:70` `Extras.router: Option>`; `src/backend/src/routes.rs:109` `build_router_with(...) -> axum::Router`。 - 业务侧:`../tdc-rs/src/tdc/controller/mod.rs:27` `pub fn build_router(state: TdcState) -> Router`。 axum 的 `merge` 要求两侧 `S` 同型 ⇒ `Router` 与 `Router` 不能直接 merge。 把 tdc 的 handler 全量改成 `State` + `Extension` 是重写级(12k 行 / 132 端点), **不采纳**。 ### 3.2 库句柄不通用 `crates/sspf-store/src/db.rs:200-204`: ```rust #[derive(Clone)] pub struct Db { pg: PGlite, // ← 私有,无 Deref / inner() / pg() lock: Arc>, } ``` `Db` 的公开方法只有 `open / open_temp / ensure_schema / query_json* / exec* / scalar_text / shutdown / begin`(`db.rs:206-371`),业务仓拿不到 `PGlite`。而 tdc 的平台层是 `../tdc-rs/src/platform/state.rs:33` `pub db: Arc`,`ensure_schema(&PGlite)` (`../tdc-rs/src/platform/db.rs:320`),且 `query_json` 自带 `f_` ↔ camelCase 归一逻辑 (与 sspf `Db::query_json` 的「SQL 必须自带 `AS camelCase` 别名」不同)⇒ **不能**让 tdc 改用 `Db::query_json`,那会改响应形状、破契约。 ⇒ 结论:必须让业务仓复用**同一个 `PGlite` 句柄**,各自保留自己的查询封装。 ### 3.3 兜底与 middleware 也是两套(P0 文档没覆盖,这次核准新发现) `../tdc-rs/src/main.rs:192-229` 是一条完整且经过五把尺子验证的装配链: ```rust let app: Router = build_router(state.clone()) .route("/api", any(api_not_found)).route("/api/{*rest}", any(api_not_found)) .route("/migrate.sql", any(api_not_found)) .fallback_service(spa_fallback(static_dir)) // ServeDir + ddl_guard + 深链决策 .layer(from_fn(json_method_not_allowed)) // 405 → 裸三键 .layer(from_fn_with_state(auth_state, auth_middleware)) // 三道门 .layer(CorsLayer::permissive()) .with_state(state); ``` 其中 `api_not_found`(`../tdc-rs/src/platform/fallback.rs:96`)返回 **裸三键** `{"success":false,"code":404,"msg":"接口不存在"}`,与 sspf 的信封 404 形状不同; `spa_fallback()`(`../tdc-rs/src/platform/fallback.rs:120`,返回 `Router<()>`)还带 `ddl_guard` 前置守卫。 平台侧 `routes.rs:2626` 的 `fallback_response` 不认识这些 ⇒ **不能**用平台默认 fallback 覆盖业务兜底, 也不能让业务 Router 自带 fallback(约束 3)。 ### 3.4 业务状态在开库之后才能构造(鸡生蛋) tdc 的 `TdcState` 依赖 `BootstrapIdentity`,而引导要跑 DB 写 (`../tdc-rs/src/main.rs:119-144`:`AppState::new` → `bootstrap_identity` → `TdcState::new`)。 ⇒ 业务 Router **必须等平台 boot 完**(库已开、表已建、种子已种)才能构造。 `v0.2.0` 的 builder 全部在 `boot()` 之前求值(`.router(...)`、`build_app()` 一步到位), 单独加一个 `router_owned(Router<()>)` builder 方法**不够用**。 > ✅ 这是本次核准最关键的约束:**必须用两阶段装配**(先 `assemble()` 拿 `AppState`, > 再 `finish()` 传业务路由),不是给 builder 加个字段就能了事。 ### 3.5 一个有利条件(决定了改动可以很小) `src/backend/src/routes.rs:2770,2816`: ```rust pub fn m_status_rewrite() -> axum::middleware::FromFnLayer pub fn catch_all() -> axum::middleware::FromFnLayer ``` 两个中间件的状态类型都是 `()`(`catch_all_inner` 只 `next.run(req)` + `catch_unwind`, 不碰 `State`)⇒ **在 `Router<()>` 上挂与在 `Router` 上挂完全等价**。 所以「平台路由先 `with_state` 降成 `Router<()>`、再 merge 业务路由、最后挂 fallback + layer」 在类型与行为上都成立,S25 的 `fallback` 在两个 `.layer()` **之前**这一要害仍能保住。 ### 3.6 类型链已实测(不是纸上推演) 在 `/tmp/sspf-compose-probe` 用 **axum 0.8.9** 建了独立最小 crate,把 §5 的完整顺序编译并跑通: `cargo test --offline` → **1 passed / 0 failed / exit 0**(22.12s)。验证四件事: 1. `Router.with_state(ps)` 与 `Router.with_state(bs)` 各自降成 `Router<()>` 后可以 `merge` —— 业务 handler 仍从**自己的** `State` 取值; 2. `Router<()>` 可以直接作为 `fallback_service(...)` 的参数(tdc 的 `spa_fallback()` 返回的正是这个类型); 3. `Vec) -> Router<()> + Send + Sync>>` 这种 layers 注入形状能编译; 4. 链尾返回 `Router<()>`(`axum::serve` 唯一接受的类型)。 ⇒ §5 的顺序在类型层面**没有障碍**;剩下的只是把它落进 `build_app_with`,并用 §7.2 的探针 钉住运行时行为(catch-all / 405 / 双契约)。探针源码可按需索取,不在本仓内。 --- ## 4. 推荐 API(可照抄) ### 4.1 R1 —— `Db` 暴露同一个句柄 `crates/sspf-store/src/db.rs`: ```rust #[derive(Clone)] pub struct Db { pg: Arc, // 由 PGlite 改为 Arc lock: Arc>, } impl Db { /// 与平台内部**同一个** Arc —— 业务仓用它构造自己的状态层。 /// 🔴 不许返回 `PGlite::clone()`:pglite 的 Clone 语义是深是浅未钉死, /// `Arc::ptr_eq` 才是可验证的共享。 pub fn pg(&self) -> Arc { Arc::clone(&self.pg) } fn new(pg: PGlite) -> Db { Db { pg: Arc::new(pg), .. } } } ``` `db.rs` 里现有的 `self.pg.exec(..)` / `self.pg.query(..)` / `self.pg.transaction()` (`begin()` 在 `db.rs:371`)全是方法调用,经 `Deref` 自动生效 ⇒ **`Arc` 化后这些调用点一行都不用改**; 只有显式把 `&self.pg` 当 `&PGlite` 传参时才需要 `.as_ref()`(本仓现有代码没有这种写法)。 门面 `crates/sspf/src/lib.rs:73` 已 `pub use sspf_store::db::Db`,无需再导出。 ### 4.2 R2/R3 —— 两阶段装配 + 三个注入点 `src/backend/src/routes.rs:66` 扩展 `Extras`(`#[derive(Default)]` 保持): ```rust /// 一层业务 middleware:`Router<()>` 进、`Router<()>` 出。 pub type LayerFn = Box) -> Router<()> + Send + Sync>; pub struct Extras { pub pack_router: Option>, pub router: Option>, pub static_dir: Option, /// 业务 Router(**已 `with_state` 成 `Router<()>`**,自带状态与 `route_layer` 守卫)。 /// 🔴 不许自带 fallback(约束 3)。 pub router_owned: Option>, /// 业务兜底(通常是 `ServeDir` + 决策层组成的 `Router<()>`)。 /// `None` ⇒ 平台默认 `fallback_response`;`Some` ⇒ `fallback_service(...)`, /// 且此时 `static_dir` 被忽略。 pub fallback: Option>, /// 业务 middleware,按 Vec 顺序挂(见 §5)。 pub layers: Vec, } ``` `crates/sspf/src/platform.rs` 新增(**不动任何现有方法签名**): ```rust /// 平台已就绪、路由尚未终结的装配句柄(boot 的 1–6 步全部跑完)。 pub struct Assembled { pub state: AppState, config: Config, extras: Extras, } #[derive(Default)] pub struct Finish { pub router: Option>, pub fallback: Option>, pub layers: Vec, } impl Platform { /// 走完 `boot()`(开库 / DDL / 种子 / 守卫 / 钩子),**不绑端口、不终结路由**。 pub async fn assemble(self) -> Result; } impl Assembled { /// 唯一权威装配链的入口,返回可 `axum::serve` 的 `Router<()>`。 pub fn finish(self, opts: Finish) -> Router; /// `finish` + `runtime::serve_http`(绑端口 / 优雅停机 / 关库,与 `serve()` 一致)。 pub async fn serve(self, opts: Finish) -> Result<(), String>; } ``` `Platform::build_app()` / `serve()` / `serve_mcp()` 保持签名,内部统一改成 「`assemble().await?` → `finish(Finish::default())`」,保证默认路径逐字等价。 业务仓最终写法(**评审后定稿**:引导结果自行持有,三道门只挂业务子树): ```rust // ① 平台 boot 完成:库已开、表已建、种子已种、钩子已跑 let boot = sspf::Platform::new() .config(config) .ddl("tdc_xxx", include_str!("../schema/001_init.sql")) .assemble().await?; // ② 业务在 **assemble 之后**自行引导:结果直接进业务状态,不必回传平台 let pg = boot.state.db.pg(); // R1:同一个 Arc let bootstrap = bootstrap_identity(&tdc_platform_state(pg.clone()), &tdc_config).await; let tdc_state = TdcState::new(tdc_platform_state(pg), tdc_config, bootstrap); // ③ 业务自带状态;三道门/405 改写只作用于业务子树(面 B 不受影响) let biz = tdc::controller::build_router(tdc_state) // 返回类型改为 Router<()> .route_layer(from_fn(json_method_not_allowed)) .route_layer(from_fn_with_state(auth_state, auth_middleware)); boot.serve(Finish { router: Some(biz), fallback: Some(spa_fallback(static_dir)), // 🔴 Finish.layers 是**全局层**(面 B 也会经过)⇒ 只放无差别件 layers: vec![Box::new(|r| r.layer(CorsLayer::permissive()))], }).await ``` > **决策 A(全局层只放无差别件)**:`Finish.layers` 挂在 merge 完成后的**总 Router** 上; > 放业务鉴权会让面 B 的 `/api/oauth/Login` 过 tdc 三道门 ⇒ 破「面 B 行为不变」。 > 业务鉴权 / 405 改写必须挂在业务 Router 自己的 `route_layer`(merge 之前)。 > 原稿示例同时在 `route_layer` 与 `Finish.layers` 挂了 `auth_middleware`(重复挂载),已删。 > **决策 B(assemble 后自行引导)**:`on_ready` 返回 `Result<(), String>`,产出会被丢弃; > `bootstrap_identity` 的结果是构造 `TdcState` 的必需输入,只能在 `assemble()` 之后自己跑。 > `on_ready` 保持「无返回值的预热」语义,签名不动。 ### 4.3 备选路线(若不愿引入 `Assembled`) 把三个注入点做成 `Platform` 上的**闭包式** builder: `router_owned_with(Box Router<()> + Send + 'static>)`, 在 `boot()` 之后、装配之前调用一次。改动更小,但 `Extras` 仍要加字段,且 `on_ready` 与 `router_owned_with` 两个钩子的先后语义容易混淆。**推荐 §4.2**,把「业务状态构造」显式留给业务仓。 --- ## 5. 装配顺序(写死在 `build_app_with`,业务仓不许抄) `src/backend/src/routes.rs:2613` 改造后: ```text build_router_with(state, extras) → Router(平台 + 包 + 旧 router 注入) .with_state(state) → Router<()> ← 原先在链尾,现前移到 merge 之前 .merge(extras.router_owned) → 业务自带状态路由(含它自己的 route_layer) .fallback[_service](...) → 唯一兜底:extras.fallback 优先,否则 fallback_response .layer(业务 layers,按 Vec 顺序) → 最后挂的最外层 .layer(m_status_rewrite()) .layer(catch_all()) → 请求最先撞 catch_all ``` 请求实际顺序:`catch_all → m_status_rewrite → 业务 layers(逆序) → 路由 / fallback`。 **S25 要害 unchanged**:`.fallback()` 仍在两个平台 `.layer()` 之前;两个平台 layer 状态类型是 `()` (§3.5)⇒ 前移 `with_state` 不改变它们的行为。 🔴 **`Finish.layers` 是全局层,不是业务子树层**:它按 Vec 顺序挂在 merge **之后**的总 Router 上, 面 B 也会经过 ⇒ 只许放 CORS / 通用日志这类无差别中间件。业务三道门、405 改写必须挂在 业务 Router 的 `route_layer` 上(在 merge 之前)。`business_composition_it` 用 `x-biz-guard`(只在业务端点)/ `x-global`(面 B + 业务都有)两个响应头把这条边界钉住。 ⚠️ 三点必须同步处理: - `build_router_with` 里 `let Extras { pack_router, router, static_dir: _ } = extras;` (`routes.rs:2569`)是**显式解构**,加字段后要补 `router_owned: _, fallback: _, layers: _` (或在 `build_app_with` 里先 `take` 出来再传一份干净的 `Extras`)。 - `routes.rs:90-103, 2591-2599` 与契约 §9 / §10 第 6 步里「`with_state` 是链尾」的表述 **要改**:新语义是「`with_state` 在 merge 自带状态路由之前,且之后不再新增需要 `AppState` 的路由」。 - 新增测试钉住:前移之后 fallback 仍被 catch-all 保护、405 改写仍生效、 panic ⇒ 200 + `code=400`(`panic_handler` 那条 `#[cfg(test)]` 路由覆盖不到业务路由, 建议探针里再故意 panic 一条业务端点)。 --- ## 6. 逐文件改造清单 | 文件 | 动作 | |---|---| | `crates/sspf-store/src/db.rs:199-230` | `pg` 改 `Arc`;加 `pub fn pg()`;`begin()` 里改 `self.pg.as_ref().transaction()`(`DbTransaction` 结构未动) | | `src/backend/src/routes.rs:66-87` | `Extras` 加 3 字段;`Extras::kernel()` 补 `Default` 值;加 `LayerFn` 别名 | | `src/backend/src/routes.rs:2569-2588` | 解构补字段;末尾 `with_state` 保留(返回 `Router`) | | `src/backend/src/routes.rs:2600-2623` | `build_app_with` 按 §5 重排;`build_app` 改走 `Extras::kernel()` + 默认 Finish | | `src/backend/src/routes.rs:90-103, 2591-2599` | 注释同步「`with_state` 位置」的新语义 | | `crates/sspf/src/platform.rs:55-70, 202-251, 340-346` | 加 `Assembled` / `Finish` / `assemble()`;`build_app`/`serve`/`serve_mcp` 内部改走两阶段;`extras()` 补字段 | | `crates/sspf/src/lib.rs:46-101` | 导出 `Assembled` / `Finish` / `LayerFn`;`VERSION` 随 `0.3.0` 自动变 | | `crates/sspf/Cargo.toml` | `version = "0.3.0"`(显式写死) | | `crates/tests/tests/business_composition_it.rs` | 新增探针(§7.2) | | `scripts/check-arch.sh` | 新增 AR19 + 反自证用例 | | `docs/contract.md` / `HANDOFF.md` / `CHANGELOG.md` | 同步 S25 表述、发布说明(**核查后 `contract.md` 无「`with_state` 在链尾」表述,无需改**) | | `crates/sspf/src/lib.rs:108` | `version_matches_the_manifest` **硬编码 `0.2.0` ⇒ 必须同步 `0.3.0`**,否则 `cargo test --workspace` 当场红 | | `crates/sspf/src/lib.rs` / `platform.rs` / `routes.rs` | 同步「`with_state` 在链尾」的注释、版本号表、`pglite` 重导出与 `LayerFn` 导出 | | `docs/known-limitations.md` | 记「双 DB 锁」与「413 被平台改写」两条 | --- ## 7. 验收判据(v0.3.0 出口,逐条可跑) ### 7.1 现有基线不回退 ```bash cargo test --workspace # 710 passed / 0 failed / 5 ignored,只许增不许减 bash scripts/check-arch.sh # 29/29 → 加 AR19 后 30/30 bash scripts/check-arch.sh --self-test # 13/13 → 加反自证用例后 14/14 bash scripts/verify.sh --fast # 8 步全绿 python3 scripts/pack-sync.py --check # 4 处派生一致 bash scripts/verify.sh --smoke # 运行时 6 把尺子 bash scripts/perm-smoke-jnpf.sh # 面 B 23/23(不裁面 B 的硬证据) ``` `cargo tree -p sspf` 仍 **0 个** `sspf-pack-*`;本仓 `sspf-admin`(开 `example-packs`)的 `/api/health` 仍是 `tables=181`;**平台包默认装配是 177**(+ 业务注入的表), 两者是不同判据,别混(P0 §5 的实测口径)。 ### 7.2 新增探针 `business_composition_it.rs`(一个 `#[tokio::test]`,pglite 进程级单例) 必须同时断言: 1. `Arc::ptr_eq(&db.pg(), &db.pg())`,且经 `db.pg().exec()` 建的表能被 `db.scalar_text()` 查到 ⇒ **同一个库、同一个句柄**。⚠️ `ptr_eq` 对 `Arc::clone` 恒真、只验证「两次调用返回同一 Arc 分配」;**有效判据是 SQL 可见性**(探针两条都留,后者才是钉子)。 2. `assemble().await?` 后 `finish(Finish { router: Some(biz), .. })`: 业务端点 200,且 handler 从**自己的** `State` 取到值 ⇒ 自带状态成立。 3. 面 B `/api/oauth/Login` 同端口 200 + token ⇒ 双契约单端口。 4. `Finish::fallback = Some(自定义 Router<()>)` 时,未命中路径走业务兜底; `None` 时走平台信封 404 ⇒ 两种兜底都可用且只有一个 fallback。 5. 业务端点故意 panic ⇒ 200 + `code=400`;405 ⇒ 改写仍生效 ⇒ **前移 `with_state` 后 catch-all / 405 改写仍覆盖 merge 进来的业务路由**。 6. `Finish::default()` 与**同仓 `build_app()`**:对同一组面 B 请求逐字比对响应。 仓内拿不到旧二进制 ⇒ 用 `build_app_with(state, Extras::default())` 作参照 Router, 共用同一个 `AppState`、不再开库(探针起第二个监听比 `/api/health` 的 status + body)。 7. 默认 feature 下依赖树 0 个 `sspf-pack-*`。 ### 7.3 AR19(静态闸门 + 反自证) 只扫 `src/backend/src/routes.rs` 的**非注释**代码行(注释里的装配顺序示意不计): - `pub fn build_app_with` 恰好 **1** 处(唯一装配链); - `.layer(catch_all())` 恰好 **1** 处; - `.fallback(` / `.fallback_service(` 恰好 **2** 处 —— `if/else` 互斥分支,恒只有一个生效; ⚠️ 原稿写「`fallback(` 只出现一次」与「可替换兜底」自相矛盾,已按实现修正; - `Extras.router_owned` 的文档注释必须含「不许自带 fallback」。 - 反自证 14/14:临时往 `routes.rs` 追加第二处 `.layer(catch_all())` ⇒ 闸门必须红,随即恢复文件。 - 「平台包内不出现业务字面量」由 **AR18** 负责,AR19 不重复该规则。 ### 7.4 仓外 git-tag 探针(P0 那次的 ⚠️ 这次照做) `/tmp` 新建最小 crate,只写 `sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.3.0" }`(**决策 D 已变更:tag 已 push 到 `origin`** ⇒ 直接用业务仓真实会写的 URL), `cargo check` + 单测: ```rust use sspf::{Assembled, Finish, Platform, VERSION}; fn probe(p: Platform) -> Result { /* 只验编译 */ } ``` `cargo tree` 解析来源必须是 `(git?tag=v0.3.0#)`、`sspf v0.3.0`、0 个 `sspf-pack-*`。 推送前另用 `file:///Users/xs/Desktop/workspace/ssw-platform` 跑过一轮(同一判据),两轮结果见 §11.4 / §11.6。 ### 7.5 发布 `git commit` + annotated tag `v0.3.0` → `git push origin main` + `git push origin v0.3.0` → `git ls-remote --tags origin` 可见 `refs/tags/v0.3.0` 与 `^{}`(annotated tag 解引用)。 **决策 D 变更**:原为「只打本地 tag、不 push」,交付后提出方要求直接推送 ⇒ 已执行。 `CHANGELOG.md` 补 5–8 行(P0 那次只落在文档 §10.4 / HANDOFF §0,这次一并补上独立文件)。 --- ## 8. tdc-rs 侧 P2 对照改造(信息性,不要求本仓配合) `v0.3.0` 到位后,业务仓按 §4.2 的写法切 `src/main.rs`,改动面: - `Cargo.toml`:`sspf` 的 `tag` → `v0.3.0`。 - `src/main.rs`:删掉自开 `PGlite` / `ensure_schema` / `AppState::new` / `auth_state` 那段, 改成 `assemble → 用 db.pg() 造 tdc AppState → build_router → finish/serve`。 - `main.rs` 里的 `.route("/api", any(api_not_found))` / `.route("/api/{*rest}", any(api_not_found))` / `.route("/migrate.sql", any(api_not_found))` 三条要**搬进业务 Router**(`with_state` 之前), 不要散落在 `main.rs`;`Finish.fallback` 接管 SPA 后,它们仍是「`/api/**` 404 裸三键」的显式保险。 - `../tdc-rs/src/tdc/controller/mod.rs:27`:`build_router` 返回类型 `Router` → `Router<()>` (内部已有 `.with_state(state)`,只改返回类型标注;**132 个 handler 一行不动**)。 - 三道门从 `main.rs` 的全局 `.layer()` 改成业务 Router 的 `.route_layer()` (只作用于业务子树,面 B 不受影响)。🔴 **不要**塞进 `Finish.layers` —— 那是全局层, 会让面 B 登录过业务鉴权(决策 A);`Finish.layers` 只留 CORS 这类无差别件。 - `src/platform/` 的 `db.rs` / `session.rs` / `state.rs` 退场或降为薄适配层(保留 `query_json` 的 `f_` ↔ camelCase 归一,这是契约的一部分)。 出口:`cargo test` ≥ 280、五把尺子全绿(`smoke.sh` 80/80、`check-contract.sh` 132 条端点一致)、 401/403 裸三键、SPA 深链、`/api/**` 404 裸三键、面 B 登录同端口 200。 --- ## 9. 明确不做(P1 边界) - ❌ 不要求 tdc 改成声明式 `EntitySpec` / RESTful 三件套(会改掉 132 条端点契约,属 P3)。 - ❌ 不把 132 个 handler 改成 `State` + `Extension`(重写级,不可接受)。 - ❌ 不让业务仓自己抄 `fallback + layer + with_state`(P0 §2 那条原则继续有效)。 - ❌ 不改 `Platform::router()` 的签名,不删 `build_app()` / `serve()`(`v0.2.0` 兼容)。 - ❌ 不裁面 B、不动 `base_*` 表、不改 cipher / 602 码 / 信封形状。 - ❌ 不统一两套会话层 / 两套 `query_json` 归一(P3 再谈;本轮只求「同一个库、同一个端口」)。 - ❌ 不改 `panic` 策略:业务仓已在 `8a351b7` 删掉 `panic = "abort"`,平台侧继续依赖 unwind。 --- ## 10. 风险与已知坑(都是踩过或本轮核准出来的) 1. **`OnceLock` first-call-wins**:`bootstrap::packs()` 一旦被默认空注册表占住,注入静默失效。 P0 的解法(门面全程显式 `PackRegistry`)在 `assemble()` 里必须继续遵守。 2. **feature unification**:平台仓内测试构建可能把 `example-packs` 渗进门面。 ⇒ 新增探针要在**仓外**用 git tag 再跑一遍(§7.4),别只信仓内测试。 3. **405 改写叠加(核准后降级为「幂等」)**:tdc `method_not_allowed_body()` 是 `{"code":405,"msg":"方法不被允许","data":null}`,与平台 `envelope::fail(405, ...)` **逐字相同** ⇒ 外层平台改写再跑一次结果不变,业务 405 形状不会被破坏。原稿「优先让业务 layers 自己吃掉 405」在 `m_status_rewrite` 位于外层时**做不到**,已删除该缓解措施。 ⚠️ **真正会变的是 413**:平台把它改写成信封,tdc 原本是 axum 默认 `text/plain`; 与「非空体 405 也被平台改写」一并记入 `docs/known-limitations.md`。 业务 405 改写应挂在业务 `route_layer`(决策 A),不要塞进 `Finish.layers`。 4. **`Arc` 与 `Db::lock`**:业务仓绕过 `Db` 直接用 `pg()` 时不受 sspf 的 `lock` 保护。 tdc 自己有 `process_db_lock()`(`../tdc-rs/src/platform/state.rs:19`),两把锁互不覆盖 ⇒ 并发下可能出现「平台 SQL 与业务 SQL 交错」。单次 SQL 有 pglite 的 `serial_guard` 兜着。 **决策 C:本轮接受**,已在 `docs/known-limitations.md` 记一条;P3 统一到 `Db::begin()` 或暴露共享锁出口(暂不做,避免业务持锁误调 `db.*` 死锁)。 5. **rustc 1.95.0**:本仓 `rust-toolchain.toml` 锁 1.95.0(L3 dylib ABI 前提); 门面 `rust-version = "1.85"` 只是 MSRV。业务仓已按 **1.95.0** 补了同名文件,别照 1.85 改。 6. **发布前先 push 再打 tag**:P0 第一次交付时代码在工作区未提交、tag 也没打,业务仓的 git 依赖拉不到;这次请按 §7.5 顺序做,并保留 `git tag -l` / `ls-remote` 的实测输出。 --- ## 11. 实施记录(2026-11-04,tag `v0.3.0`) ### 11.1 评审结论与四项决策 需求的三条核心判断核对代码后**全部成立**(状态类型不同 / 库句柄不通用 / 业务状态须等开库), 两阶段装配的方向正确。评审提出的存疑点由提出方逐项拍板: | # | 存疑 | 决策 | 落点 | |---|---|---|---| | A | `Finish.layers` 是**全局层**,原稿误称「只作用业务子树」,示例还重复挂 auth | 全局层只放 CORS / 日志等无差别件;业务鉴权与 405 改写走业务 Router 的 `route_layer` | §4.2 / §5 / 探针的双响应头断言 | | B | `on_ready` 产出被丢弃,`bootstrap` 变量凭空出现 | 不改 `on_ready` 签名;业务在 `assemble()` 后用 `state.db.pg()` 自行引导 | §4.2 | | C | `Db::pg()` 绕过 `Db.lock`,两把锁并行 | 本轮接受,记入 `docs/known-limitations.md` | §10.4 | | D | 发布要 push 远端 | 原决策「只打本地 tag」;**提出方随后改为直接推送** ⇒ `main` + annotated tag `v0.3.0` 均已到 `origin` | §7.5 / §11.6 | ### 11.2 交付物落点 | # | 交付物 | 实际位置 | |---|---|---| | R1 | `Db.pg: Arc` + `pub fn pg()` | `crates/sspf-store/src/db.rs`(`begin()` 改 `as_ref().transaction()`) | | R2 | `Assembled` / `Finish` / `assemble()` / `finish()` / `serve()` | `crates/sspf/src/platform.rs`;`build_app` / `serve` / `serve_mcp` 内部统一走两阶段 | | R3 | `Extras` 三注入点 + `LayerFn` | `src/backend/src/routes.rs`(`router_owned` / `fallback` / `layers`) | | R4 | 唯一装配链、`with_state` 前移 | 同上 `build_app_with`;`build_app` 仍走 `Extras::kernel()`,`Finish::default()` 逐字等价 | | R5 | 探针 + AR19 | `crates/tests/tests/business_composition_it.rs`(1 个测试 / 7 组断言)、`scripts/check-arch.sh` | | R6 | CHANGELOG / 局限记档 | 仓库根 `CHANGELOG.md`(新建)、`docs/known-limitations.md` | **另补的遗漏**(原稿 §6 清单没列):`lib.rs` 的 `version_matches_the_manifest` 硬编码断言、 门面重导出 `pglite` 与 `LayerFn`、`lib.rs` / `platform.rs` / `routes.rs` 的「链尾」注释与版本号表。 核查后 `docs/contract.md` **没有**「`with_state` 在链尾」的表述 ⇒ 无需改。 ### 11.3 装配顺序(实现版) ``` build_router_with(state, extras) → Router(内部已烤入状态) .with_state(state) → Router<()>(前移:类型降级) .merge(router_owned) → 业务自带状态路由(含它自己的 route_layer) .fallback[_service](...) → 唯一兜底(if/else 互斥两分支) .layer(业务 layers,Vec 顺序) → 全局层 .layer(m_status_rewrite()) .layer(catch_all()) → 请求最先撞它 ``` ⚠️ `build_router_with` 末尾**原有一次** `with_state`(`routes.rs` 的「类型层面 no-op」注释), 新链里是**第二次**(只做类型降级),两处都保留;删任何一处都会让默认路径偏移。 ### 11.4 实测数字(2026-11-04) - 核心三 crate `cargo check --offline` 通过(17.92s);新探针 `cargo check` 通过(4.61s)。 - `business_composition_it` **1 passed / 0 failed**(2.41s):同句柄建表可见、自带状态、 双契约单端口、业务层只作用业务子树、两种兜底、业务 panic ⇒ 200 + `code=400`、 405 信封、默认路径 `/api/health` 逐字等价、零示例包。 - `check-arch.sh` **30/30**、`--self-test` **14/14**(新增 AR19 反自证)。 - `cargo test --offline --workspace` **711 passed / 0 failed / 7 ignored**(基线 710 + 新探针 1)。 - `pack-sync.py --check` 4 处派生一致;`cargo tree -p sspf` **0 个** `sspf-pack-*`。 - `verify.sh --fast` **8 步全绿**(70.6s);`verify.sh --smoke` **14 步全绿**(189.3s), 其中 `perm-smoke`(43 条断言尺子自证)、`perm-smoke-jnpf` **面 B 23/23**、 `lowcode-smoke` / `baseline-smoke` / `mcp-smoke` 全绿。 - `check-citations` CIT1–CIT3 全绿(1374 条引文):需求稿的 21 条跨仓引文已统一成 `../tdc-rs/...` / 本仓相对路径写法,尺子才认得(这是本次新增文档踩的坑)。 - 仓外 `file://` + tag `v0.3.0` 探针:`cargo check` 通过(43.73s)、单测 **3 passed / 0 failed**、 `cargo tree` 解析为 `sspf v0.3.0 (file://...?tag=v0.3.0#6d6e0ee3)`、**0 个** `sspf-pack-*`。 ⚠️ `cargo --offline` 会拒绝 checkout `file://` git 依赖 ⇒ 探针要去掉 `--offline`(registry 依赖仍走本地缓存)。 - 推送与远端 URL 复核见 §11.6。 ### 11.5 与 tdc-rs 的边界 本轮**只改平台仓**;tdc-rs 的 `main.rs` 切换、三条 `/api` 404 路由搬迁、 `build_router` 返回类型改动仍属 P2(§8),不在本 tag 内。 ### 11.6 发布与仓外复核(决策 D 变更后) - `git push origin main` + `git push origin v0.3.0` 已完成,`git ls-remote --tags origin` 可见 `refs/tags/v0.3.0` 与 `^{}`;`origin/main` 与 tag 指向同一个提交。 - 业务仓可直接写 `sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.3.0" }`; §7.4 的仓外探针按此 URL 复核:`cargo tree` 来源为 `sspf v0.3.0 (...?tag=v0.3.0#)`、 单测 3 passed、依赖树 0 个 `sspf-pack-*`。 - 本地 tag 因发布前重建过一次(把文档同步提交纳入 tag)⇒ tag 的 sha 与 §11.4 里 `file://` 探针那轮的 `6d6e0ee3` 不同,属预期,不是两套代码。 --- ## 附录:本需求依据的文件出处(均可在两仓内核查) | 结论 | 出处 | |---|---| | `Platform::router` 收 `Router` | `crates/sspf/src/platform.rs:162` | | `Extras` 三个字段 / 显式解构 | `src/backend/src/routes.rs:66-87, 2569-2580` | | 唯一装配链 / S25 顺序 | `src/backend/src/routes.rs:2591-2623` | | 平台两中间件状态类型为 `()` | `src/backend/src/routes.rs:2770, 2816-2827` | | `Db.pg` 私有、无访问器 | `crates/sspf-store/src/db.rs:199-230` | | 门面导出 `Db` | `crates/sspf/src/lib.rs:73` | | `runtime::serve_http` 已公开 | `crates/sspf/src/runtime.rs:30` | | AR17/AR18 现状 | `scripts/check-arch.sh` | | tdc 业务路由返回 `Router` | `../tdc-rs/src/tdc/controller/mod.rs:27` | | tdc 完整装配链 | `../tdc-rs/src/main.rs:188-229` | | tdc 兜底 `spa_fallback` / `api_not_found` | `../tdc-rs/src/platform/fallback.rs:96, 120` | | tdc `Arc` 状态与进程级锁 | `../tdc-rs/src/platform/state.rs:19-45` | | tdc `ensure_schema(&PGlite)` | `../tdc-rs/src/platform/db.rs:320` | | tdc 接入探针(可照抄扩展) | `../tdc-rs/tests/sspf_platform_package.rs` | | P0 需求与实施记录 | `docs/SSPF-PLATFORM-PACKAGE.md` |