Files
ssw-platform/docs/SSPF-BUSINESS-COMPOSITION.md
T
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

591 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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」的终局形态:
```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<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`:
```rust
#[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` 是一条完整且经过五把尺子验证的装配链:
```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<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`:
```rust
#[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)]` 保持):
```rust
/// 一层业务 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` 新增(**不动任何现有方法签名**):
```rust
/// 平台已就绪、路由尚未终结的装配句柄(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())`」,保证默认路径逐字等价。
业务仓最终写法(**评审后定稿**:引导结果自行持有,三道门只挂业务子树):
```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<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` 改造后:
```text
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 现有基线不回退
```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<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` + 单测:
```rust
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` |