Files
ssw-platform/docs/SSPF-BUSINESS-COMPOSITION.md
admin ca8abf9cc9 docs: v0.3.0 发布口径同步 —— 决策 D 变更为直接推送
- 需求稿 §7.4/§7.5/§11.1/§11.4/§11.6 改按已发布口径,补仓外 tag 探针实测
- HANDOFF 0-bis 同步发布范围;工作日志记离线模式无法 checkout file:// git 依赖
2026-11-04 18:27:56 +08:00

35 KiB
Raw Permalink Blame History

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<PGlite> + 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<AppState>。缺的是「自带状态的业务路由

  • 同一个库句柄 + 可替换兜底」三个注入点,都是平台包内部的小改,不需要重写业务。

0. 背景与目标

「sspf 作为 JNPF 替代品、tdc-rs 作为业务项目、单进程部署、兼容 JNPF」的终局形态:

一个进程 · 一个 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<PGlite> 句柄 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>,不许业务仓再 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<AppState>)、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<AppState>); src/backend/src/routes.rs:70 Extras.router: Option<Router<AppState>>; src/backend/src/routes.rs:109 build_router_with(...) -> axum::Router<AppState>。
  • 业务侧:../tdc-rs/src/tdc/controller/mod.rs:27 pub fn build_router(state: TdcState) -> Router<TdcState>。

axum 的 merge 要求两侧 S 同型 ⇒ Router<TdcState> 与 Router<AppState> 不能直接 merge。 把 tdc 的 handler 全量改成 State<AppState> + Extension<TdcState> 是重写级(12k 行 / 132 端点), 不采纳。

3.2 库句柄不通用

crates/sspf-store/src/db.rs:200-204:

#[derive(Clone)]
pub struct Db {
    pg: PGlite,                 // ← 私有,无 Deref / inner() / pg()
    lock: Arc<Mutex<()>>,
}

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<PGlite>,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 是一条完整且经过五把尺子验证的装配链:

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:

pub fn m_status_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)>
pub fn catch_all()       -> axum::middleware::FromFnLayer<MwFn, (), (Request,)>

两个中间件的状态类型都是 ()(catch_all_inner 只 next.run(req) + catch_unwind, 不碰 State<AppState>)⇒ 在 Router<()> 上挂与在 Router<AppState> 上挂完全等价。 所以「平台路由先 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<PlatformState>.with_state(ps) 与 Router<BizState>.with_state(bs) 各自降成 Router<()> 后可以 merge —— 业务 handler 仍从自己的 State<BizState> 取值;
  2. Router<()> 可以直接作为 fallback_service(...) 的参数(tdc 的 spa_fallback() 返回的正是这个类型);
  3. Vec<Box<dyn FnOnce(Router<()>) -> 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:

#[derive(Clone)]
pub struct Db {
    pg: Arc<PGlite>,            // 由 PGlite 改为 Arc<PGlite>
    lock: Arc<Mutex<()>>,
}

impl Db {
    /// 与平台内部**同一个** Arc —— 业务仓用它构造自己的状态层。
    /// 🔴 不许返回 `PGlite::clone()`:pglite 的 Clone 语义是深是浅未钉死,
    ///    `Arc::ptr_eq` 才是可验证的共享。
    pub fn pg(&self) -> Arc<PGlite> { 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)] 保持):

/// 一层业务 middleware:`Router<()>` 进、`Router<()>` 出。
pub type LayerFn = Box<dyn FnOnce(Router<()>) -> Router<()> + Send + Sync>;

pub struct Extras {
    pub pack_router: Option<Router<AppState>>,
    pub router: Option<Router<AppState>>,
    pub static_dir: Option<PathBuf>,

    /// 业务 Router(**已 `with_state` 成 `Router<()>`**,自带状态与 `route_layer` 守卫)。
    /// 🔴 不许自带 fallback(约束 3)。
    pub router_owned: Option<Router<()>>,
    /// 业务兜底(通常是 `ServeDir` + 决策层组成的 `Router<()>`)。
    /// `None` ⇒ 平台默认 `fallback_response`;`Some` ⇒ `fallback_service(...)`,
    /// 且此时 `static_dir` 被忽略。
    pub fallback: Option<Router<()>>,
    /// 业务 middleware,按 Vec 顺序挂(见 §5)。
    pub layers: Vec<LayerFn>,
}

crates/sspf/src/platform.rs 新增(不动任何现有方法签名):

/// 平台已就绪、路由尚未终结的装配句柄(boot 的 1–6 步全部跑完)。
pub struct Assembled {
    pub state: AppState,
    config: Config,
    extras: Extras,
}

#[derive(Default)]
pub struct Finish {
    pub router: Option<Router<()>>,
    pub fallback: Option<Router<()>>,
    pub layers: Vec<routes::LayerFn>,
}

impl Platform {
    /// 走完 `boot()`(开库 / DDL / 种子 / 守卫 / 钩子),**不绑端口、不终结路由**。
    pub async fn assemble(self) -> Result<Assembled, String>;
}

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())」,保证默认路径逐字等价。

业务仓最终写法(评审后定稿:引导结果自行持有,三道门只挂业务子树):

// ① 平台 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<PGlite>
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<dyn FnOnce(AppState) -> Router<()> + Send + 'static>), 在 boot() 之后、装配之前调用一次。改动更小,但 Extras 仍要加字段,且 on_ready 与 router_owned_with 两个钩子的先后语义容易混淆。推荐 §4.2,把「业务状态构造」显式留给业务仓。


5. 装配顺序(写死在 build_app_with,业务仓不许抄)

src/backend/src/routes.rs:2613 改造后:

build_router_with(state, extras)        → Router<AppState>(平台 + 包 + 旧 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<PGlite>;加 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<AppState>)
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 现有基线不回退

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<MyState> 取到值 ⇒ 自带状态成立。
  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 + 单测:

use sspf::{Assembled, Finish, Platform, VERSION};
fn probe(p: Platform) -> Result<Assembled, String> { /* 只验编译 */ }

cargo tree 解析来源必须是 (git?tag=v0.3.0#<sha>)、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<TdcState> → 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<sspf::AppState> + Extension<TdcState>(重写级,不可接受)。
  • ❌ 不让业务仓自己抄 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<PGlite> 与 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<PGlite> + 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<AppState>(内部已烤入状态)
  .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#<sha>)、 单测 3 passed、依赖树 0 个 sspf-pack-*。
  • 本地 tag 因发布前重建过一次(把文档同步提交纳入 tag)⇒ tag 的 sha 与 §11.4 里 file:// 探针那轮的 6d6e0ee3 不同,属预期,不是两套代码。

附录:本需求依据的文件出处(均可在两仓内核查)

结论 出处
Platform::router 收 Router<AppState> 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<TdcState> ../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<PGlite> 状态与进程级锁 ../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