- 需求稿 §7.4/§7.5/§11.1/§11.4/§11.6 改按已发布口径,补仓外 tag 探针实测 - HANDOFF 0-bis 同步发布范围;工作日志记离线模式无法 checkout file:// git 依赖
591 lines
35 KiB
Markdown
591 lines
35 KiB
Markdown
# 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` |
|