From 6d6e0ee32941167c51e1a7ca7872d2e7ab982a5b Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 4 Nov 2026 18:20:03 +0800 Subject: [PATCH] =?UTF-8?q?feat(platform):=20=E6=A0=87=E5=87=86=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=E5=8C=85=20v0.3.0=20=E2=80=94=E2=80=94=20=E4=B8=9A?= =?UTF-8?q?=E5=8A=A1=E8=87=AA=E5=B8=A6=E7=8A=B6=E6=80=81=E7=9A=84=E5=8F=AF?= =?UTF-8?q?=E7=BB=84=E5=90=88=E8=A3=85=E9=85=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Db 暴露同一个 Arc(Db::pg());Platform 两阶段装配 Assembled/Finish - Extras 加自带状态路由 / 可替换兜底 / 全局层,with_state 前移;默认路径行为不变 - 新增探针 business_composition_it 与闸门 AR19(反自证 14/14) - 文档:CHANGELOG / known-limitations / 需求稿实施记录与勘误 --- .workbuddy/memory/2026-11-04.md | 22 + CHANGELOG.md | 15 + Cargo.lock | 2 +- HANDOFF.md | 20 + crates/sspf-store/src/db.rs | 19 +- crates/sspf/Cargo.toml | 4 +- crates/sspf/src/lib.rs | 34 +- crates/sspf/src/platform.rs | 120 +++- crates/tests/tests/business_composition_it.rs | 252 ++++++++ docs/SSPF-BUSINESS-COMPOSITION.md | 573 ++++++++++++++++++ docs/SSPF-PLATFORM-PACKAGE.md | 4 + docs/known-limitations.md | 11 + scripts/check-arch.sh | 106 +++- src/backend/src/routes.rs | 117 +++- 14 files changed, 1217 insertions(+), 82 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 crates/tests/tests/business_composition_it.rs create mode 100644 docs/SSPF-BUSINESS-COMPOSITION.md diff --git a/.workbuddy/memory/2026-11-04.md b/.workbuddy/memory/2026-11-04.md index 63cf369..3f48532 100644 --- a/.workbuddy/memory/2026-11-04.md +++ b/.workbuddy/memory/2026-11-04.md @@ -179,3 +179,25 @@ CannotCache(incremental): ["--crate-name", "probe", ..., "-C", "incremental=..." **发布(16:50)**:注记标签 `v0.2.0` → commit `9083394`,`main` + tag 都已推 `origin`(127.0.0.1:13300)。 需求 §6 那个「git 依赖要实测」已消:仓外项目写 `sspf = { git = "...", tag = "v0.2.0" }`, `cargo check` 37.95s 通过,依赖全标 `?tag=v0.2.0#9083394b` ⇒ git 依赖与 path 依赖等价。 + + +## v0.3.0 业务自带状态的可组合装配(P1,17:34–) + +- 评审 `docs/SSPF-BUSINESS-COMPOSITION.md`:方向成立,四项存疑由苏苏拍板 —— + A 全局层只放无差别件(业务鉴权走业务 Router 的 `route_layer`); + B `assemble()` 后自行引导(`on_ready` 签名不动);C 双 DB 锁本轮接受并记档; + D 只 commit + 本地 annotated tag,不 push。 +- 实现:`Db.pg: Arc` + `pub fn pg()`;`Extras` 加 `router_owned/fallback/layers`, + `build_app_with` 前移 `with_state`(`build_router_with` 里原有那次**保留**,两次都在); + `Assembled/Finish/assemble/finish/serve`,`build_app/serve/serve_mcp` 内部统一走两阶段。 +- 踩到/修掉的坑:`lib.rs` 版本断言硬编码 0.2.0 必须同步;AR19 判据原写「fallback 只出现一次」 + 与可替换兜底矛盾,实现为 if/else 互斥的 2 处;AR19 注释判据要从字段**往上**找注释块。 +- 事实核准:tdc 的 405 body 与平台 `envelope::fail(405,..)` 逐字相同(叠加幂等); + 真正变化的是 413。`docs/contract.md` 里没有「with_state 在链尾」表述,无需改。 +- 闸门:`check-arch.sh` 30/30、`--self-test` 14/14;探针 `business_composition_it.rs` 1 passed。 +- 文档:需求稿补 §11 实施记录、新建 `CHANGELOG.md`、`known-limitations.md` 加章节 L。 +- 全量验收:`cargo test --offline --workspace` 711 passed / 0 failed / 7 ignored; + `verify.sh --fast` 8 步全绿、`--smoke` 14 步全绿(面 B 23/23); + `cargo tree -p sspf` 零示例包。 +- 新踩的坑:`check-citations` CIT1 按「仓根+相对路径」解析 ⇒ 需求稿里跨仓引文要写 + `../tdc-rs/...`、本仓引文**不要**带 `ssw-platform/` 前缀,否则 21 条引文判红。 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..792b050 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,15 @@ +# CHANGELOG + +## v0.3.0(2026-11-04) + +- 新增两阶段装配 `Platform::assemble()` / `Assembled::finish()` / `serve()` 与 `Finish` 注入点:自带状态类型的业务路由可挂进平台唯一装配链,业务状态可在开库后构造。 +- `Db` 改用 `Arc` 并公开 `pg()` ⇒ 业务仓与平台共用一个库句柄,不必另开 PGlite;`Db::clone()` 语义不变。 +- `Extras` 新增自带状态路由 / 可替换兜底 / 全局 middleware 层三个注入点;`with_state` 前移到 merge 之前,`build_app()` 默认路径行为不变。 +- 面 A / 面 B、`base_*` 表、cipher、602 码、panic ⇒ 200 + `code=400` 全部保持不变;`v0.2.0` 的公开签名未改。 +- 新增集成探针 `business_composition_it.rs` 与闸门 AR19(唯一装配链,反自证 14/14);`sspf` 版本 0.3.0。 +- 已知局限:`Db::pg()` 绕过 `Db.lock` 时,平台与业务各自的多语句事务可能交错;业务 413 响应由平台改写为信封。见 `docs/known-limitations.md`。 + +## v0.2.0(2026-11-04) + +- 新增门面 crate `sspf`:业务仓唯一依赖,`Platform` builder + `runtime` 启动动作;`sspf-admin` 退化为 CLI 薄壳。 +- 4 个示例包降为 `example-packs` feature ⇒ 默认依赖树不含 `sspf-pack-*`;新增 AR17 / AR18 与仓外消费探针。 diff --git a/Cargo.lock b/Cargo.lock index 319bec1..26fd8fe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1069,7 +1069,7 @@ dependencies = [ [[package]] name = "sspf" -version = "0.2.0" +version = "0.3.0" dependencies = [ "axum", "libc", diff --git a/HANDOFF.md b/HANDOFF.md index 78182c9..8681e4e 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -9,6 +9,26 @@ --- +## 0-bis. 2026-11-04 `v0.3.0`:业务自带状态的可组合装配(P1 交付,**本地 tag,未 push**) + +需求与实施记录:`docs/SSPF-BUSINESS-COMPOSITION.md`(含 §11 四项评审决策)。 + +1. **`Db.pg` 改 `Arc` + `pub fn pg()`**(`crates/sspf-store/src/db.rs`):业务仓拿**同一个**库句柄造自己的状态层,不必另开 PGlite。`begin()` 里改 `self.pg.as_ref().transaction()`;其余 `self.pg.*` 调用经 Deref 一行没动。 +2. **两阶段装配**(`crates/sspf/src/platform.rs`):`Platform::assemble() → Assembled::{finish, serve}`,`Finish { router, fallback, layers }`。`build_app()` / `serve()` / `serve_mcp()` 内部统一走 `assemble() → finish(Finish::default())` ⇒ **v0.2.0 签名与默认行为逐字不变**。 +3. **`Extras` 三个注入点 + 前移 `with_state`**(`src/backend/src/routes.rs`):`router_owned: Option>` / `fallback: Option>` / `layers: Vec`;唯一兜底由 if/else 互斥两分支挂。S25 的 `fallback` 仍在两个平台 layer 之前。 +4. **探针 + 闸门**:`crates/tests/tests/business_composition_it.rs`(1 个测试 / 7 组断言,两个监听共用同一个 AppState);`check-arch.sh` 加 AR19(唯一装配链),反自证 13 → 14 条。 +5. **文档**:新建 `CHANGELOG.md`;`docs/known-limitations.md` 加章节 L;P0 需求稿加 v0.3.0 注记;`docs/contract.md` 核查后无需改(没有「with_state 在链尾」的表述)。 + +**🔴 三条必须记住的结论**: + +- **`with_state` 现在有两次,都要保留**:`build_router_with` 末尾原有一次(状态烤进平台 endpoint、类型仍标 `Router`),`build_app_with` 里前移的是**第二次**(只做类型降级到 `Router<()>`)。删任何一处都会让默认路径偏移。 +- **`Finish.layers` 是全局层**(挂在 merge 完成后的总 Router)⇒ 只许放 CORS / 日志等无差别件;业务鉴权、405 改写必须挂在业务 Router 的 `route_layer`(merge 之前),否则面 B 登录会被业务三道门拦住。探针用 `x-biz-guard` / `x-global` 两个响应头钉住这条边界。 +- **`on_ready` 不回传产出**(返回 `Result<(), String>`):业务引导身份要在 `assemble()` 之后用 `state.db.pg()` 自己跑,结果直接进业务状态。 +- 已知局限(本轮接受):`Db::pg()` 绕过 `Db.lock` ⇒ 两把锁并行,跨平台/业务的多语句事务可能交错;业务 413 会被平台 `m_status_rewrite` 改成信封。见 `docs/known-limitations.md` §L。 +- **发布范围**:只 `commit` + 本地 annotated tag `v0.3.0`,**没有 push**。业务仓切 tag 前需自行 `git push origin main && git push origin v0.3.0`。 + +--- + ## 0. 2026-11-04 标准平台包 `v0.2.0`:门面 crate `sspf` + 示例包选装(P0 交付) **做了什么**(需求原文 `docs/SSPF-PLATFORM-PACKAGE.md`,实施记录见其 §10): diff --git a/crates/sspf-store/src/db.rs b/crates/sspf-store/src/db.rs index 6f53648..0cc7b75 100644 --- a/crates/sspf-store/src/db.rs +++ b/crates/sspf-store/src/db.rs @@ -198,7 +198,9 @@ const OID_INT8: u32 = 20; /// ⇒ 集成测试必须全文件共用一个实例。 #[derive(Clone)] pub struct Db { - pg: PGlite, + /// 🔴 **`Arc` 是刻意的**:自带状态类型的业务仓要拿**同一个** `PGlite` 句柄 + /// 构造自己的状态层(见 [`Db::pg`])。`Db::clone()` 必须只是多一个 Arc 引用。 + pg: Arc, /// 进程级业务锁(S3)。`Arc` 是因为 `Db` 需要 `Clone`。 lock: Arc>, } @@ -223,11 +225,22 @@ impl Db { fn new(pg: PGlite) -> Db { Db { - pg, + pg: Arc::new(pg), lock: Arc::new(Mutex::new(())), } } + /// 平台内部**同一个** `Arc` —— 自带状态的业务仓用它构造自己的状态层。 + /// + /// 🔴 返回的是 `Arc::clone`,不是 `PGlite::clone()`:`Arc` 的共享可用 + /// `Arc::ptr_eq` 钉住,`PGlite` 自己的 `Clone` 语义不对外承诺。 + /// 🔴 这个句柄**绕过本层的 `Db.lock`**:单次 SQL 有 pglite 的 `serial_guard` + /// 兜着,但「一次业务操作跨多条 SQL」的串行化要业务仓自己保证 + /// (见 `docs/known-limitations.md` 的「双锁」条)。 + pub fn pg(&self) -> Arc { + Arc::clone(&self.pg) + } + /// schema 初始化(**只在 `base_user` 不存在时**整体执行一次)。 /// /// - 探测用 `to_regclass('public.base_user')`(一次 round-trip,S5)。 @@ -370,7 +383,7 @@ impl Db { /// 事务内的一切查询都要走 [`DbTransaction`] 自己的方法。 pub async fn begin(&self) -> Result, pglite::Error> { let guard = self.lock.lock().await; - let tx = self.pg.transaction().await?; + let tx = self.pg.as_ref().transaction().await?; Ok(DbTransaction { tx, _guard: guard, diff --git a/crates/sspf/Cargo.toml b/crates/sspf/Cargo.toml index 39375ab..c8f06bb 100644 --- a/crates/sspf/Cargo.toml +++ b/crates/sspf/Cargo.toml @@ -1,12 +1,12 @@ [package] name = "sspf" -version = "0.2.0" +version = "0.3.0" edition = "2021" rust-version = "1.85" description = "SSPF 标准平台包 —— 业务仓唯一依赖的门面(平台能力 + 装配注入)" # 🔴 **为什么显式写 version,不用 `version.workspace = true`**: -# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.2"` / tag `v0.2.0`), +# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.3"` / tag `v0.3.0`), # 而本仓 workspace 版本(0.1.0)跟的是内核实现节奏。两者独立演进 —— 混用会让 # 「业务仓能不能升级」变成「内核发了几个 commit」。 # diff --git a/crates/sspf/src/lib.rs b/crates/sspf/src/lib.rs index c943c27..1062800 100644 --- a/crates/sspf/src/lib.rs +++ b/crates/sspf/src/lib.rs @@ -7,7 +7,7 @@ //! 它不该知道平台内部拆了 19 个 crate,也不该被拖进本仓的 4 个示例包。 //! //! ```ignore -//! // 业务仓 src/main.rs +//! // 业务仓 src/main.rs(薄业务:路由用平台状态) //! sspf::Platform::new() //! .packs(my_packs::registry()?) // 业务包 / 业务 DDL(同一个 Db) //! .menus(my_packs::MENUS) // 业务菜单注入两段式种子 @@ -16,23 +16,32 @@ //! .serve().await //! ``` //! +//! ```ignore +//! // 厚业务仓(自带状态类型):两阶段装配 +//! let boot = sspf::Platform::new().config(cfg).assemble().await?; +//! let pg = boot.state.db.pg(); // 同一个 Arc +//! let biz = my_router(my_state(pg)).route_layer(my_auth); +//! boot.serve(Finish { router: Some(biz), ..Default::default() }).await +//! ``` +//! //! ## 三条硬约束(本 crate 的存在理由) //! //! 1. **单进程只有一个 PGlite 实例** —— `pglite-rs 0.2` 内部是进程级 `static OPEN`, -//! 第二次 `PGlite::open()` 直接失败。⇒ 平台与业务**必须共用同一个 [`AppState`]**。 -//! 门面提供的注入点全都在**同一个库**上执行,业务仓不许自己开库。 -//! 2. **装配链只有一条** —— `fallback` 必须在两个 `layer` 之前、`with_state` 在链尾 -//! (S25)。业务仓**不能**自己抄一遍,只能把路由交给 [`Platform::router`], -//! 由内核的 [`kernel::routes::build_app_with`] 装配。 +//! 第二次 `PGlite::open()` 直接失败。⇒ 平台与业务必须共用**同一个 `Db` / +//! `Arc` 句柄**([`Db::pg`])。业务路由可以自带状态类型,但**不许自己开库**。 +//! 2. **装配链只有一条** —— `fallback` 必须在平台两个 `layer` 之前;`with_state` +//! 在 merge 自带状态业务路由**之前**完成(v0.3.0 起),且之后不再新增需要 +//! `AppState` 的路由。业务仓**不能**自己抄一遍,只能把路由交给 +//! [`Platform::router`] 或 [`Finish::router`]。 //! 3. **平台包里零业务** —— 默认 feature 下本 crate 的依赖树里**没有** `sspf-pack-*` //! (`check-arch.sh` 的 AR17 钉住);本 crate 源码里没有业务表名 / 端点字面量 -//! (AR18)。 +//! (AR18)。AR19 钉住「唯一 fallback / 唯一装配链」。 //! //! ## 版本号有三套,别混 //! //! | 版本 | 值 | 谁看 | //! |---|---|---| -//! | 本 crate(cargo) | `0.2.0` | 业务仓锁依赖 / git tag | +//! | 本 crate(cargo) | `0.3.0` | 业务仓锁依赖 / git tag | //! | 契约版本 | `0.4.0` | 业务包 `pack.toml` 的 `kernel_req` | //! | workspace(cargo) | `0.1.0` | 内核实现节奏 | //! @@ -46,7 +55,8 @@ pub mod platform; pub mod runtime; -pub use platform::Platform; +pub use platform::{Assembled, Finish, Platform}; +pub use ssw_platform::routes::LayerFn; // ---------------------------------------------------------------- 契约与包类型 // @@ -71,6 +81,9 @@ pub use sspf_core::seed; pub use sspf_core::session::{SessionStore, TicketStore}; pub use sspf_core::state::AppState; pub use sspf_store::db::Db; +// 🔴 业务仓要能命名 `Arc`(构造自己的状态层)⇒ 从门面拿同一个 crate, +// 避免自己声明一个版本可能漂的 `pglite` 依赖。 +pub use sspf_store::db::pglite; /// 内核装配面(排障与高级用法)。 /// @@ -103,9 +116,10 @@ pub const VERSION: &str = env!("CARGO_PKG_VERSION"); #[cfg(test)] mod tests { /// 🔴 门面版本必须与 `Cargo.toml` 一字不差(业务仓按它锁依赖)。 + /// **改版本时这里必须同步改**,否则测试当场红 —— 这是有意的护栏。 #[test] fn version_matches_the_manifest() { - assert_eq!(super::VERSION, "0.2.0"); + assert_eq!(super::VERSION, "0.3.0"); } /// 🔴 **默认 feature 下不得装任何示例包** —— 这条与 AR17 的静态判据互补: diff --git a/crates/sspf/src/platform.rs b/crates/sspf/src/platform.rs index 3e76177..cd099de 100644 --- a/crates/sspf/src/platform.rs +++ b/crates/sspf/src/platform.rs @@ -14,6 +14,13 @@ //! 业务 DDL 必须在种子之前(种子要往业务表写东西);守卫必须在 `AppState` 之前 //! (生产档弱口令不许起来,哪怕只起了一秒)。 //! +//! 🔴 **两阶段装配(v0.3.0)**:厚业务仓的状态类型要等开库之后才能构造 +//! (引导身份要往库里写)⇒ [`Platform::assemble`] 先跑完 boot 的 1–6 步并返回 +//! [`Assembled`],业务仓用 `Assembled::state.db.pg()` 拿同一个库句柄造自己的状态, +//! 再把自带状态的 `Router<()>` 交给 [`Assembled::finish`] / [`Assembled::serve`]。 +//! `build_app()` / `serve()` / `serve_mcp()` 内部一律走 +//! `assemble() → finish(Finish::default())` ⇒ 默认路径逐字等价。 +//! //! 🔴 **不碰 `bootstrap::packs()` 那个 `OnceLock`**:它是 `first-call-wins`, //! 一旦被默认空注册表占住,外部注入就**静默失效**。⇒ 门面全程用**显式传入**的 //! [`PackRegistry`]([`Platform::packs`]),内核的 `ensure_schema_all_with` / @@ -97,6 +104,30 @@ impl std::fmt::Debug for Platform { } } +/// 两阶段装配的**第一阶段产物**:boot 的 1–6 步全部跑完,路由尚未终结。 +/// +/// 🔴 业务仓在这一步用 `state.db.pg()` 拿**同一个** `Arc` 造自己的状态, +/// 自行跑引导(引导结果不必回传平台);`on_ready` 只适合无返回值的预热。 +pub struct Assembled { + /// 平台状态(同一个库 / 同一张会话表)。 + pub state: AppState, + config: Config, + extras: Extras, +} + +/// 两阶段装配的**第二阶段注入点**(默认 ⇒ 与 v0.2.0 的 `build_app()` 逐字等价)。 +#[derive(Default)] +pub struct Finish { + /// 业务自带状态的路由(已 `with_state` 成 `Router<()>`)。 + /// 🔴 不许自带 fallback;业务鉴权请挂在它自己的 `route_layer` 上。 + pub router: Option, + /// 业务兜底(`ServeDir` + 决策层组成的 `Router<()>`);`None` ⇒ 平台信封 404。 + pub fallback: Option, + /// **全局** middleware(按 Vec 顺序挂,最后挂的最外层)。 + /// 🔴 面 B 也会经过 ⇒ 只许放 CORS / 通用日志这类无差别层。 + pub layers: Vec, +} + impl Platform { /// 全新装配器(**零业务**:没有包、没有菜单、没有路由)。 pub fn new() -> Self { @@ -158,7 +189,9 @@ impl Platform { /// 注入业务自定义路由(**不要自带 `fallback`** —— `Router::merge` 遇到两个会 panic)。 /// /// 🔴 中间件 / 守卫由业务仓自己挂在**这个** Router 上:平台不认识业务权限, - /// 但装配顺序(fallback → 405/413 改写 → catch-all → `with_state`)由平台保证。 + /// 但装配顺序(fallback → 405/413 改写 → catch-all)由平台保证。 + /// 🔴 这个注入点收 `Router`;**自带状态类型**的业务路由请走 + /// [`Platform::assemble`] + [`Finish::router`]。 pub fn router(mut self, router: Router) -> Self { self.router = Some(match self.router { Some(prev) => prev.merge(router), @@ -170,6 +203,7 @@ impl Platform { /// 静态 SPA 托管:非 `/api/**` 的未命中路径回退 `index.html`(前端 history 路由)。 /// /// 🔴 `/api/**` 永远是**信封 404** —— 静态托管不许吞掉接口契约。 + /// 🔴 `Finish::fallback` 给了值时本项被忽略。 pub fn static_dir(mut self, dir: impl Into) -> Self { self.static_dir = Some(dir.into()); self @@ -177,6 +211,10 @@ impl Platform { /// 启动钩子(`AppState` 已就绪、路由尚未对外)。 /// + /// 🔴 返回值只有 `Result<(), String>`(预热成功 / 失败),**不回传业务数据**。 + /// 要拿引导结果构造业务状态 ⇒ 用 [`Platform::assemble`],在 `Assembled::state` + /// 上自己跑引导。 + /// /// ```ignore /// .on_ready(|state| async move { /// // 用 state.db 做业务预热;Err ⇒ 启动失败(进程不对外) @@ -199,42 +237,31 @@ impl Platform { /// 走完整装配,返回**可 `axum::serve` 的 Router**(不绑端口)。 /// /// 🔴 主要给测试 / 嵌入场景用;生产用 [`Platform::serve`](含优雅停机 + 关库)。 - pub async fn build_app(mut self) -> Result { - let config = self.config.take().unwrap_or_else(|| { - Config::from_env(boot::resolve_project_dir()) - }); - let state = self.boot(&config).await?; - let extras = self.extras(); - Ok(routes::build_app_with(state, extras)) + /// 🔴 v0.3.0 起内部是 `assemble() → finish(Finish::default())`; + /// 签名与行为都不变(默认 Finish 与旧的 `build_app_with` 逐字等价)。 + pub async fn build_app(self) -> Result { + Ok(self.assemble().await?.finish(Finish::default())) } /// 起 HTTP 服务(**完整进程级动作**:绑端口 → 优雅停机 → 关库 → 退出)。 /// /// 🔴 返回 `Ok` 只可能发生在「优雅停机之后」;关库完直接 `exit(0)` /// (pglite 的收尾线程可能卡死,不许它吊住进程)。 - pub async fn serve(mut self) -> Result<(), String> { - let config = self - .config - .take() - .unwrap_or_else(|| Config::from_env(boot::resolve_project_dir())); - let state = self.boot(&config).await?; - let app = routes::build_app_with(state.clone(), self.extras()); - runtime::serve_http(app, &config, state.db.clone()).await + pub async fn serve(self) -> Result<(), String> { + self.assemble().await?.serve(Finish::default()).await } /// 起 **MCP stdio** 服务(可选同进程 HTTP)。 /// /// 🔴 标准流要在**开库之前**让给内嵌 PG(`boot::detach_stdio_for_mcp`)。 - pub async fn serve_mcp(mut self, with_http: bool) -> Result<(), String> { + pub async fn serve_mcp(self, with_http: bool) -> Result<(), String> { let io = runtime::detach_stdio_for_mcp()?; - let config = self - .config - .take() - .unwrap_or_else(|| Config::from_env(boot::resolve_project_dir())); - let state = self.boot(&config).await?; + let assembled = self.assemble().await?; + let config = assembled.config.clone(); + let state = assembled.state.clone(); if with_http { - let app = routes::build_app_with(state.clone(), self.extras()); + let app = assembled.finish(Finish::default()); runtime::spawn_http(app, &config).await?; } @@ -250,6 +277,29 @@ impl Platform { .map_err(|e| format!("MCP stdio 服务异常退出: {e}")) } + /// **两阶段装配第一步**:走完 `boot()`(开库 / DDL / 种子 / 守卫 / 钩子), + /// **不绑端口、不终结路由**。 + /// + /// ```ignore + /// let boot = Platform::new().config(cfg).assemble().await?; + /// let pg = boot.state.db.pg(); // 同一个 Arc + /// let biz = my_router(my_state(pg)).route_layer(my_auth); // 自带状态 + /// boot.serve(Finish { router: Some(biz), ..Default::default() }).await + /// ``` + pub async fn assemble(mut self) -> Result { + let config = self + .config + .take() + .unwrap_or_else(|| Config::from_env(boot::resolve_project_dir())); + let state = self.boot(&config).await?; + let extras = self.extras(); + Ok(Assembled { + state, + config, + extras, + }) + } + // ------------------------------------------------------------ 内部 /// 七步启动的 1–5 步 + `AppState` + 钩子(**不含**绑定端口)。 @@ -336,12 +386,34 @@ impl Platform { Ok(state) } - /// 组装注入点(业务路由 / 包路由 / 静态目录)。 + /// 组装注入点(业务路由 / 包路由 / 静态目录);第二阶段字段由 `finish` 覆盖。 fn extras(&mut self) -> Extras { Extras { pack_router: Some(bootstrap::pack_router(&self.packs)), router: self.router.take(), static_dir: self.static_dir.clone(), + ..Default::default() } } } + +impl Assembled { + /// **两阶段装配第二步**:唯一权威装配链的入口,返回可 `axum::serve` 的 `Router<()>`。 + pub fn finish(self, opts: Finish) -> Router { + let Assembled { + state, mut extras, .. + } = self; + extras.router_owned = opts.router; + extras.fallback = opts.fallback; + extras.layers = opts.layers; + routes::build_app_with(state, extras) + } + + /// `finish` + `runtime::serve_http`(绑端口 / 优雅停机 / 关库,与 `Platform::serve()` 一致)。 + pub async fn serve(self, opts: Finish) -> Result<(), String> { + let config = self.config.clone(); + let db = self.state.db.clone(); + let app = self.finish(opts); + runtime::serve_http(app, &config, db).await + } +} diff --git a/crates/tests/tests/business_composition_it.rs b/crates/tests/tests/business_composition_it.rs new file mode 100644 index 0000000..a551ea3 --- /dev/null +++ b/crates/tests/tests/business_composition_it.rs @@ -0,0 +1,252 @@ +//! business_composition —— v0.3.0「业务自带状态的可组合装配」出口探针。 +//! +//! ## 这条测试在证明什么 +//! +//! 厚业务仓的 132 条端点绑在**自己的状态类型**上,不认平台的 `AppState`。 +//! 这条探针只依赖门面 `sspf`,一次钉住: +//! +//! 1. `Db::pg()` 给的是**同一个** `Arc`,经它建的表平台 `Db` 能查到; +//! 2. `assemble() → finish(Finish)` 两阶段装配:业务 `Router<()>` 自带状态, +//! 面 B 与业务端点**同一个端口**; +//! 3. 业务 `route_layer`(三道门)**只作用于业务子树**,面 B 不带业务守卫头; +//! `Finish.layers` 是**全局层**,面 B 与业务端点都带; +//! 4. 兜底可替换且只有一个:`Some` 走业务、`None` 走平台信封 404; +//! 5. 前移 `with_state` 后 catch-all / 405 改写仍覆盖 merge 进来的业务路由; +//! 6. `Finish::default()` 与默认装配对面 B 逐字等价;平台包零示例业务包。 +//! +//! ## 🔴 pglite 是进程级单例 +//! +//! 全文件**只有一个测试函数**(一次 `PGlite::open`)。两个监听、两个 Router +//! 共用**同一个** `AppState`,不许再 `assemble()` 第二次。 + +use std::path::PathBuf; +use std::sync::Arc; + +use axum::extract::{Request, State}; +use axum::http::HeaderValue; +use axum::middleware::Next; +use axum::response::Response; +use axum::routing::get; +use axum::{Json, Router}; +use serde_json::{json, Value}; +use sspf::{Config, Finish, Platform}; +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::TcpStream; + +/// 业务自己的状态类型(**不是** `sspf::AppState`)。 +#[derive(Clone)] +struct MyState { + tag: &'static str, +} + +async fn biz_ping(State(s): State) -> Json { + Json(json!({ "tag": s.tag })) +} + +/// 故意 panic ⇒ 必须被**平台** catch-all 接住(契约 §6.5)。 +async fn biz_panic() -> Json { + panic!("业务端点故意 panic(由平台 catch-all 接住)") +} + +/// 业务三道门(模拟):只挂在业务 Router 的 `route_layer` 上 ⇒ 面 B 不受影响。 +async fn biz_guard(req: Request, next: Next) -> Response { + let mut res = next.run(req).await; + res.headers_mut() + .insert("x-biz-guard", HeaderValue::from_static("on")); + res +} + +/// 无差别全局层(CORS 的位置):挂在 `Finish.layers` ⇒ 面 B 也会经过。 +async fn global_layer(req: Request, next: Next) -> Response { + let mut res = next.run(req).await; + res.headers_mut() + .insert("x-global", HeaderValue::from_static("on")); + res +} + +/// 业务兜底(`ServeDir` + 决策层的形状):任何未命中路径都回业务标记。 +fn biz_fallback() -> Router { + Router::new().fallback(|| async { Json(json!({ "from": "biz-fallback" })) }) +} + +/// 起监听并返回端口。 +async fn serve(app: Router) -> u16 { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0") + .await + .expect("绑定本地端口失败"); + let port = listener.local_addr().expect("取本地地址失败").port(); + let server = tokio::spawn(async move { + let _ = axum::serve(listener, app).await; + }); + tokio::task::yield_now().await; + // 🔴 服务要活到测试结束(drop 掉 JoinHandle 会 abort 掉 task)。 + std::mem::forget(server); + port +} + +/// 发一次请求,返回**完整响应文本**(要断言 header,不能只留 body)。 +async fn request(port: u16, method: &str, path: &str, body: &str) -> String { + let req = if body.is_empty() { + format!("{method} {path} HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n") + } else { + format!( + "{method} {path} HTTP/1.1\r\n\ + Host: 127.0.0.1\r\n\ + Content-Type: application/x-www-form-urlencoded\r\n\ + Content-Length: {}\r\n\ + Connection: close\r\n\r\n{body}", + body.len() + ) + }; + let mut stream = TcpStream::connect(("127.0.0.1", port)) + .await + .expect("连接失败"); + stream.write_all(req.as_bytes()).await.expect("写请求失败"); + let mut buf = Vec::new(); + tokio::time::timeout( + std::time::Duration::from_secs(20), + stream.read_to_end(&mut buf), + ) + .await + .expect("读响应超时") + .expect("读响应失败"); + String::from_utf8_lossy(&buf).to_string() +} + +fn status(raw: &str) -> u16 { + raw.lines() + .next() + .and_then(|l| l.split_whitespace().nth(1)) + .and_then(|s| s.parse::().ok()) + .expect("响应首行必须是 HTTP/1.1 ...") +} + +fn head(raw: &str) -> &str { + raw.split_once("\r\n\r\n").map(|(h, _)| h).unwrap_or(raw) +} + +fn has_header(raw: &str, name: &str) -> bool { + let needle = format!("{name}:"); + head(raw) + .lines() + .skip(1) + .any(|l| l.to_ascii_lowercase().starts_with(&needle)) +} + +fn json_of(raw: &str) -> Value { + let (_, body) = raw.split_once("\r\n\r\n").expect("响应必须有头体分隔"); + serde_json::from_str(body.trim()).unwrap_or(Value::Null) +} + +#[tokio::test] +async fn owned_state_business_router_composes_on_one_port() { + // ---- 配置:临时库(进程级单例 ⇒ 全文件只有这一个测试)---- + let mut config = Config::from_env(PathBuf::from("/tmp/sspf-business-composition")); + config.pg_dir = PathBuf::from("memory://"); + config.seed_admin_password = "123456".to_string(); + + // ---- 判据 ①:两阶段装配第一步 + 同一个 Arc ---- + let boot = Platform::new() + .config(config) + .assemble() + .await + .expect("外部消费方必须能 assemble()(开库 / DDL / 种子 / 钩子)"); + + let db = boot.state.db.clone(); + let pg = db.pg(); + assert!( + Arc::ptr_eq(&pg, &db.pg()), + "Db::pg() 每次必须返回同一个 Arc 分配" + ); + pg.exec("CREATE TABLE IF NOT EXISTS probe_compose (f_id text)") + .await + .expect("业务侧要能直接用同一个 PGlite 句柄建表"); + let seen = db + .scalar_text( + "SELECT count(*) FROM information_schema.tables \ + WHERE table_schema = 'public' AND table_name = 'probe_compose'", + ) + .await + .expect("平台 Db 查询不该失败") + .expect("count(*) 必有值"); + assert_eq!(seen.trim(), "1", "业务句柄建的表必须落在同一个库里"); + + let state = boot.state.clone(); + + // ---- 业务 Router:自带状态 + 只作用于业务子树的三道门 ---- + let biz: Router = Router::new() + .route("/api/biz/Ping", get(biz_ping)) + .route("/api/biz/Panic", get(biz_panic)) + .route_layer(axum::middleware::from_fn(biz_guard)) + .with_state(MyState { tag: "owned" }); + + let app = boot.finish(Finish { + router: Some(biz), + fallback: Some(biz_fallback()), + layers: vec![Box::new(|r: Router| { + r.layer(axum::middleware::from_fn(global_layer)) + })], + }); + let port = serve(app).await; + + // 默认装配(`Finish::default()` 的形态):同一个 AppState、不再开库。 + let default_app = sspf::kernel::routes::build_app_with(state, Default::default()); + let default_port = serve(default_app).await; + + // ---- 判据 ②:业务端点 200,且 handler 从**自己的** State 取值 ---- + let raw = request(port, "GET", "/api/biz/Ping", "").await; + assert_eq!(status(&raw), 200, "业务端点必须 200: {raw}"); + assert_eq!(json_of(&raw)["tag"], "owned", "自带状态没生效: {raw}"); + assert!(has_header(&raw, "x-biz-guard"), "业务 route_layer 没生效: {raw}"); + assert!(has_header(&raw, "x-global"), "Finish.layers 是全局层: {raw}"); + + // ---- 判据 ③:面 B 同端口 200;业务三道门**不得**污染面 B ---- + let enc = sspf::cipher::encrypt_password("123456"); + let raw = request( + port, + "POST", + "/api/oauth/Login", + &format!("account=admin&password={enc}"), + ) + .await; + assert_eq!(status(&raw), 200, "面 B 登录必须 200: {raw}"); + assert_eq!(json_of(&raw)["code"], 200, "登录必须成功: {raw}"); + assert!( + json_of(&raw)["data"]["token"] + .as_str() + .is_some_and(|t| !t.is_empty()), + "登录必须返回 token: {raw}" + ); + assert!( + !has_header(&raw, "x-biz-guard"), + "业务 route_layer 只作用于业务子树,面 B 不该带业务守卫头: {raw}" + ); + assert!(has_header(&raw, "x-global"), "全局层必须覆盖面 B: {raw}"); + + // ---- 判据 ④:兜底可替换,且只有一个 ---- + let raw = request(port, "GET", "/some/deep/link", "").await; + assert_eq!(status(&raw), 200, "未命中路径应走业务兜底: {raw}"); + assert_eq!(json_of(&raw)["from"], "biz-fallback", "业务兜底没生效: {raw}"); + let raw = request(default_port, "GET", "/some/deep/link", "").await; + assert_eq!(status(&raw), 404, "None ⇒ 平台信封 404: {raw}"); + assert_eq!(json_of(&raw)["code"], 404, "404 必须是信封形状: {raw}"); + + // ---- 判据 ⑤:前移 with_state 后 catch-all / 405 仍覆盖业务路由 ---- + let raw = request(port, "GET", "/api/biz/Panic", "").await; + assert_eq!(status(&raw), 200, "panic 必须被接住并返 200: {raw}"); + assert_eq!(json_of(&raw)["code"], 400, "panic ⇒ code=400: {raw}"); + let raw = request(port, "POST", "/api/biz/Ping", "").await; + assert_eq!(status(&raw), 405, "405 状态码要保留: {raw}"); + assert_eq!(json_of(&raw)["code"], 405, "405 必须是信封 body: {raw}"); + + // ---- 判据 ⑥:默认路径对面 B 逐字等价 ---- + let a = request(port, "GET", "/api/health", "").await; + let b = request(default_port, "GET", "/api/health", "").await; + assert_eq!(status(&a), status(&b), "两个装配的 health 状态码必须一致"); + assert_eq!(json_of(&a), json_of(&b), "注入业务不得改变面 B 响应: {a} / {b}"); + + // ---- 判据 ⑦:平台包零示例业务包(默认装配上断言,避免被业务兜底吃掉)---- + let raw = request(default_port, "GET", "/api/demo/DemoItem", "").await; + assert_eq!(status(&raw), 404, "示例包路由不该存在: {raw}"); + assert_eq!(json_of(&raw)["code"], 404, "404 必须是信封形状: {raw}"); +} diff --git a/docs/SSPF-BUSINESS-COMPOSITION.md b/docs/SSPF-BUSINESS-COMPOSITION.md new file mode 100644 index 0000000..9d1fac8 --- /dev/null +++ b/docs/SSPF-BUSINESS-COMPOSITION.md @@ -0,0 +1,573 @@ +# SSPF 平台包 v0.3.0 —— 给 `ssw-platform` 仓的 P1 需求:业务自带状态的可组合装配 + +> 提出方:`tdc-rs`(业务仓 / 依赖方) 日期:2026-11-04 状态:**已实施 → annotated tag `v0.3.0`(本地,未 push)** +> +> **实施落点(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 = "file:///Users/xs/Desktop/workspace/ssw-platform", +tag = "v0.3.0" }`(**决策 D:只打本地 tag、不 push** ⇒ 用 `file://` 验证 tag 解析, +不依赖远端),`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-*`;远端 tag 待用户自行 push 后再按 `http://127.0.0.1:13300/...` 复核一次。 + +### 7.5 发布 + +`git commit` + annotated tag `v0.3.0`(**本地**),`git tag -l` 与 `git show v0.3.0` 可见。 +**决策 D:本轮不 push** ⇒ `origin` 上暂时没有 `v0.3.0`;业务仓切 tag 前需用户自行 +`git push origin main && git push origin v0.3.0`,再复核 `git ls-remote --tags origin`。 +`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 远端 | 只 `commit` + 本地 annotated tag,**不 push** | §7.5 | + +### 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` 探针结果见 §11.5 后记(发布动作之后补)。 + +### 11.5 与 tdc-rs 的边界 + +本轮**只改平台仓**;tdc-rs 的 `main.rs` 切换、三条 `/api` 404 路由搬迁、 +`build_router` 返回类型改动仍属 P2(§8),不在本 tag 内。 + +--- + +## 附录:本需求依据的文件出处(均可在两仓内核查) + +| 结论 | 出处 | +|---|---| +| `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` | diff --git a/docs/SSPF-PLATFORM-PACKAGE.md b/docs/SSPF-PLATFORM-PACKAGE.md index 07f70f1..eb4fbca 100644 --- a/docs/SSPF-PLATFORM-PACKAGE.md +++ b/docs/SSPF-PLATFORM-PACKAGE.md @@ -280,6 +280,10 @@ P1 的准备工作可与本 P0 **并行**,但 `main.rs` 换装配必须等 `v0 ## 10. 实施记录(2026-11-04,tag `v0.2.0`) +> ⚠️ **v0.3.0 起装配顺序有变**:`with_state` 已从链尾**前移**到 merge 自带状态业务路由之前 +> (`fallback` 仍在两个平台 `layer` 之前)。本文记的是 `v0.2.0` 当时的历史形态, +> 现行链见 `docs/SSPF-BUSINESS-COMPOSITION.md` §5 / §11.3。 + ### 10.1 交付物落点 | # | 交付物 | 实际位置 | diff --git a/docs/known-limitations.md b/docs/known-limitations.md index c678444..c512c46 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -165,3 +165,14 @@ | (bo) | **大屏「地图懒加载」不按 `parentId` 过滤时返全量** | 官方 `VisualMapServiceImpl.getListWithColnums` 用 `parentId` 过滤 + `hasChild` 标记。本仓照抄了 `hasChildren` / `parentName`,但**根节点**(无 `parentId`)与「全部」两种语义靠前端区分。代价:一次懒加载可能拿到多于一层的节点 | | (bp) | **大屏权限码只到 `onlineDev.dataScreen`**:官方**没挂** `@SaCheckPermission` 的端点(`assets/list`、`component/list`、`map/lazy-list`、`map/detail`)本仓也**只要求登录** | 照抄官方注解的**有无**(不是照抄语义)。代价:这些端点任何登录用户可读(大屏配置本身不是敏感数据) | + + +## L. 单进程双 DB 锁与 413 改写(v0.3.0,2026-11-04) + +> 需求与决策见 `docs/SSPF-BUSINESS-COMPOSITION.md` §10.3 / §10.4 / §11.1。 +> 这两条都是「平台包承载自带状态的厚业务仓」时**主动接受**的边界,不是缺陷回归。 + +| # | 限制 | 为什么接受 / 代价 | +|---|---|---| +| (bq) | **平台与业务各有一把 DB 锁**:业务仓经 `Db::pg()` 拿 `Arc` 后绕过 `sspf_store::Db::lock`,自己的 `process_db_lock()` 与平台那把互不覆盖 ⇒ 并发下「一次业务操作跨多条 SQL」可能与平台 SQL 交错 | 单次 SQL 有 pglite 的 `serial_guard()` 串行化,不会破坏单条查询;本轮只求「同一个库、同一个端口」,统一到 `Db::begin()` 或暴露共享锁出口属 P3。代价:跨平台 / 业务的**多语句事务**不保证整体串行,业务仓需自行持锁;暂不暴露 `Db::lock()` 也避免了「业务持锁误调 `db.*` 死锁」 | +| (br) | **业务侧的 413 / 非空体 405 会被平台改写成信封**:`m_status_rewrite()` 挂在总 Router 上,对任何 405 / 413 无条件改写;tdc 原来的 413 是 axum 默认 `text/plain` | 保持 S25「fallback 在两个平台 layer 之前、catch-all 覆盖面 B 与业务路由」这条硬约束,不给 `Extras` 加「跳过平台层」开关。405 两边形状逐字相同(`code/msg/data`),改写幂等;**413 与带 body 的 405 形状会变**。代价:业务契约里若钉死 413 的裸响应,需在业务 Router 自己的 `route_layer` 上抢先处理 | diff --git a/scripts/check-arch.sh b/scripts/check-arch.sh index 14546ba..d030a8f 100755 --- a/scripts/check-arch.sh +++ b/scripts/check-arch.sh @@ -60,7 +60,12 @@ # 的成本最低,而这类代码**不会让任何测试变红** # # 🔴 AR1–AR5 是 PLAN.md §3.2 的分层纪律;MEM1–MEM2 是判断 ⑥ 的四条内存红线的静态部分。 +# AR19 唯一装配链:`routes.rs` 只允许一个 `pub fn build_app_with`、一处 +# `.layer(catch_all())` 与恰好 2 处互斥的 fallback 调用;`Extras.router_owned` +# 注释必须写明「不许自带 fallback」—— 业务自带状态路由若抄第二遍链, +# 404 兜底会静默错位且测试全绿(S25)。 # 🔴 AR17/AR18 是「sspf 标准平台包」(2026-11-04 P0)的边界:平台包里零业务。 +# 🔴 AR19 是「业务自带状态的可组合装配」(2026-11-04 P1)的边界:装配链仍然只有一份。 set -u @@ -96,7 +101,7 @@ skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; } usage() { echo "用法: bash scripts/check-arch.sh [--self-test]" - echo " 静态检查 crate 依赖纪律(AR1–AR18)与内存红线(MEM1–MEM2)" + echo " 静态检查 crate 依赖纪律(AR1–AR19)与内存红线(MEM1–MEM2)" echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错" } @@ -871,12 +876,60 @@ PY fi } +# ---------------------------------------------------------------- AR19 +# **唯一装配链**(2026-11-04 v0.3.0 两阶段装配)。 +# +# 🔴 **为什么需要**:业务自带状态的 `Router<()>` 现在能在 merge 点注入, +# 「自己再抄一遍 fallback + layer + with_state」的诱惑变大了 —— 抄错顺序时 +# axum 不报编译错,404 兜底只是悄悄失去 catch-all 保护,且**测试全绿**。 +# +# 判据(只看 `src/backend/src/routes.rs` 的**非注释**代码行): +# - `pub fn build_app_with` 恰好 1 处; +# - `.layer(catch_all())` 恰好 1 处; +# - `.fallback(` / `.fallback_service(` 恰好 2 处(`if/else` 互斥分支 ⇒ 恒只有一个生效); +# - `Extras.router_owned` 的文档注释必须含「不许自带 fallback」。 +check_ar19() { + local file="$KERNEL/src/routes.rs" + [ -f "$file" ] || { skip "AR19 routes.rs 不存在"; return; } + local hits + hits="$(python3 - "$file" <<'PY' +import re, sys +lines = open(sys.argv[1], encoding='utf-8').read().splitlines() +code = [(i, l) for i, l in enumerate(lines, 1) if not l.lstrip().startswith('//')] +def hits(pat): + return [(i, l) for i, l in code if re.search(pat, l)] +bad = [] +n = hits(r'pub fn build_app_with\b') +if len(n) != 1: + bad.append(f'unique-chain: pub fn build_app_with 应恰好 1 处,实际 {len(n)} 处') +n = hits(r'\.layer\(catch_all\(\)\)') +if len(n) != 1: + bad.append(f'unique-catch-all: .layer(catch_all()) 应恰好 1 处,实际 {len(n)} 处') +n = hits(r'\.fallback(_service)?\(') +if len(n) != 2: + bad.append(f'single-fallback: fallback 调用点应恰好 2 处(互斥分支),实际 {len(n)} 处') +doc = '\n'.join(lines) +m = re.search(r'((?:^\s*///.*\n)+)\s*pub router_owned:', doc, re.M) +if not m or '不许自带 fallback' not in m.group(1): + bad.append('router_owned-doc: Extras.router_owned 注释缺「不许自带 fallback」约定') +for b in bad: + print(b) +PY +)" + if [ -z "$hits" ]; then + ok "AR19 唯一装配链(build_app_with / catch_all / 单兜底 / 自带状态路由注释)" + else + bad "AR19 装配链被抄了第二遍(或兜底挂法退化):" + printf '%s\n' "$hits" | sed 's/^/ /' + fi +} + # ---------------------------------------------------------------- 反自证 # 🔴 永远返回「干净」的尺子 = 没有尺子。造明知违规的输入,必须被抓到。 self_test() { local rc=0 - echo "── 反自证 1/13:造一个依赖越界的假 pack,AR2 必须报 ❌ ──" + echo "── 反自证 1/14:造一个依赖越界的假 pack,AR2 必须报 ❌ ──" local tmp="$ROOT/packs/__arch_selftest__" mkdir -p "$tmp" cat > "$tmp/Cargo.toml" <<'TOML' @@ -902,7 +955,7 @@ TOML rc=1 fi - echo "── 反自证 2/13:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──" + echo "── 反自证 2/14:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──" # # 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。 # 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。 @@ -941,7 +994,7 @@ TOML rc=1 fi - echo "── 反自证 3/13:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──" + echo "── 反自证 3/14:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──" # # 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_` # 和 `= EntitySpec {`,PACK1 就必须红。 @@ -967,7 +1020,7 @@ RS echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)" fi - echo "── 反自证 4/13:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──" + echo "── 反自证 4/14:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──" local pfile="$CRATES/sspf-plugin/Cargo.toml" if [ -f "$pfile" ]; then cp "$pfile" "$pfile.bak" @@ -988,7 +1041,7 @@ RS echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)" fi - echo "── 反自证 5/13:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──" + echo "── 反自证 5/14:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──" # # 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。 # 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。 @@ -1024,7 +1077,7 @@ RS rc=1 fi - echo "── 反自证 6/13:往契约面底座塞 use super::system,AR11 必须报 ❌ ──" + echo "── 反自证 6/14:往契约面底座塞 use super::system,AR11 必须报 ❌ ──" # # 🔴🔴 **M7 起底座只有一处**:真源 `crates/sspf-compat-core/src/helper.rs` # (转发壳 `src/backend/src/platform/compat/helper.rs` 已随 M7 删除)。 @@ -1047,7 +1100,7 @@ RS rc=1 fi - echo "── 反自证 7/13:往壳里写 crate::platform::,AR15 必须报 ❌ ──" + echo "── 反自证 7/14:往壳里写 crate::platform::,AR15 必须报 ❌ ──" # # 🔴 **必须自证 AR15**:删掉 `platform/` 转发壳之后,旧路径就**没有编译器**兜底了 # —— 只要有人重建壳目录并把 import 改回去,**一切照常编译、测试照常全绿**, @@ -1089,7 +1142,7 @@ RS rc=1 fi - echo "── 反自证 8/13:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──" + echo "── 反自证 8/14:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──" # # 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。 # 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒ @@ -1116,7 +1169,7 @@ RS rc=1 fi - echo "── 反自证 9/13:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──" + echo "── 反自证 9/14:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──" # # 🔴 **必须自证 AR13**:它的判据是「读 Cargo.toml + grep 源码」。 # 两种失效模式都得堵: @@ -1149,7 +1202,7 @@ RS rc=1 fi - echo "── 反自证 10/13:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──" + echo "── 反自证 10/14:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──" # # 🔴 **必须自证 AR14**:它是 M6 新增的判据,守护的是「全仓唯一知道全部包的 # 汇聚点」的依赖面。两种失效模式都得堵: @@ -1182,7 +1235,7 @@ RS rc=1 fi - echo "── 反自证 11/13:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──" + echo "── 反自证 11/14:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──" # # 🔴 **必须自证 AR16**:它的三条判据全是「文件/目录在不在」—— # 路径写错(比如把 $KERNEL 拼成别的名字)⇒ 永远判「没问题」⇒ @@ -1216,7 +1269,7 @@ RS rc=1 fi - echo "── 反自证 12/13:把内核一条示例包依赖改成非 optional,AR17 必须报 ❌ ──" + echo "── 反自证 12/14:把内核一条示例包依赖改成非 optional,AR17 必须报 ❌ ──" # # 🔴 **为什么自证 AR17**:它的判据是「grep 依赖行里有没有 optional」。 # grep 的模式写错 ⇒ 永远匹配不到 ⇒ **永远"通过"**(与 AR9 同一类风险)。 @@ -1254,7 +1307,7 @@ PY rc=1 fi - echo "── 反自证 13/13:往门面里塞一句业务字面量,AR18 必须报 ❌ ──" + echo "── 反自证 13/14:往门面里塞一句业务字面量,AR18 必须报 ❌ ──" # # 🔴 **为什么自证 AR18**:它扫的是「门面源码里的业务名」。目录写错 / 正则写错 # ⇒ 永远空 ⇒ 永远"通过"。这条自证保证「平台包里零业务」不是一句口号。 @@ -1277,6 +1330,30 @@ PY rc=1 fi + echo "── 反自证 14/14:往 routes.rs 塞第二处 .layer(catch_all()),AR19 必须报 ❌ ──" + # + # 🔴 **为什么自证 AR19**:它数的是「非注释代码里 catch_all 层的条数」。 + # 正则写错 / 扫描面写错 ⇒ 永远数到 1 ⇒ 永远"通过"。 + local a19file="$KERNEL/src/routes.rs" + local a19ok=0 + if [ -f "$a19file" ]; then + cp "$a19file" "$a19file.ar19bak" + printf '\nfn __ar19_selftest() { let _ = axum::Router::new().layer(catch_all()); }\n' >> "$a19file" + local a19before=$FAIL + check_ar19 >/dev/null 2>&1 + local a19caught=0 + [ "$FAIL" -gt "$a19before" ] && a19caught=1 + mv "$a19file.ar19bak" "$a19file" + FAIL=$a19before + [ "$a19caught" -eq 1 ] && a19ok=1 + fi + if [ "$a19ok" -eq 1 ]; then + echo "✅ 反自证通过:AR19 抓到了第二处 catch_all 层" + else + echo "❌ 反自证失败:AR19 没抓到重复的装配链层 ⇒ 尺子是假的" + rc=1 + fi + return $rc } @@ -1302,6 +1379,7 @@ check_ar15 check_ar16 check_ar17 check_ar18 +check_ar19 check_pack1 check_mem1 check_mem2 diff --git a/src/backend/src/routes.rs b/src/backend/src/routes.rs index 468ba3d..a87020f 100644 --- a/src/backend/src/routes.rs +++ b/src/backend/src/routes.rs @@ -2,15 +2,20 @@ //! //! 契约:`docs/contract.md` §9(`routes.rs` 接口)、§6.5(兜底三条)、§R1.2(业务失败恒 HTTP 200)。 //! -//! 🔴 **三层兜底的挂法**(控制器裁决 S25)—— **唯一真源**是 [`build_app`]: +//! 🔴 **三层兜底的挂法**(控制器裁决 S25)—— **唯一真源**是 [`build_app_with`]: //! ```text -//! build_app(state) // ← 生产(crates/sspf-admin/src/main.rs)与单测都调它 -//! build_router(state.clone()) -//! .fallback(not_found_handler) // 404 兜底 +//! build_router_with(state.clone(), extras) +//! .with_state(state) // ← v0.3.0 前移:类型降级 Router → Router<()> +//! .merge(extras.router_owned) // 业务自带状态路由(自己的 route_layer 只管业务子树) +//! .fallback[_service](...) // 404 兜底(业务优先,否则平台信封 / SPA 深链) +//! .layer(extras.layers) // 业务全局层(按 Vec 顺序,只许无差别中间件) //! .layer(m_status_rewrite()) // 405 / 413 改写中间件 //! .layer(catch_all()) // panic 捕获中间件 -//! .with_state(state) // ← 链尾(唯一一次把类型落成 Router<()>) //! ``` +//! 请求实际顺序:`catch_all → m_status_rewrite → 业务 layers(逆序)→ 路由 / fallback`。 +//! +//! 🔴 **S25 的要害 unchanged**:`.fallback()` 仍在两个平台 `.layer()` **之前**; +//! 两个平台 layer 的状态类型是 `()` ⇒ 前移 `with_state` 不改变它们的行为。 //! `Router::layer` 是**后进先出** ⇒ 最后挂的最外层 ⇒ 请求**先**撞 `catch_all`, //! **再**撞 `m_status_rewrite`,**最后**才进 handler / 404 兜底。 //! @@ -62,6 +67,14 @@ async fn panic_handler() -> Json { /// /// 🔴 **`router` / `pack_router` 里不许自带 `fallback`** —— axum 的 `Router::merge` /// 遇到两个 fallback 会 panic。深链回退是装配链的事([`Extras::static_dir`])。 +/// 一层业务 middleware:`Router<()>` 进、`Router<()>` 出(`FnOnce` ⇒ 可捕获状态)。 +/// +/// 🔴 **全局层**:按顺序挂在 merge 完成后的总 Router 上 ⇒ 面 B 也会经过。 +/// 只许放 CORS / 通用日志这类**无差别**中间件;业务鉴权、405 改写等 +/// 「只该作用于业务子树」的层必须挂在业务 Router 自己的 `route_layer` 上 +/// (在 merge 之前),否则面 B 的登录会被业务三道门拦住。 +pub type LayerFn = Box axum::Router + Send + Sync>; + #[derive(Default)] pub struct Extras { /// 业务包声明的面 B 路由(由 `crud_router` 或业务方自己生成)。 @@ -72,6 +85,17 @@ pub struct Extras { /// /// 🔴 `/api/**` 永远走信封 404 —— 静态托管不许吞掉接口的 404 契约。 pub static_dir: Option, + /// 业务自带状态的路由(**已 `with_state` 成 `Router<()>`**,自带 `route_layer` 守卫)。 + /// + /// 🔴 **不许自带 fallback** —— 一个 Router 只允许一个 fallback, + /// `Router::merge` 遇到两个会 panic。兜底只能由下面这个 `fallback` 统一挂。 + pub router_owned: Option, + /// 业务兜底(通常是 `ServeDir` + 决策层组成的 `Router<()>`)。 + /// `None` ⇒ 平台默认 `fallback_response`;`Some` ⇒ `fallback_service(...)`, + /// 且此时 `static_dir` 被忽略(业务兜底自己负责 `/api/**` 的 404 形状)。 + pub fallback: Option, + /// 业务 middleware,按 Vec 顺序挂(最后挂的最外层)。 + pub layers: Vec, } impl Extras { @@ -82,25 +106,24 @@ impl Extras { Extras { pack_router: Some(crate::bootstrap::pack_router_or_empty()), router: Some(modules::router()), - static_dir: None, + ..Default::default() } } } /// 装配全部路由(27 条,见 S15 的路由表)。 /// -/// 🔴 **不在这里终结状态** —— 契约 §9 的括注与 §10 第 6 步都要求 -/// `with_state` 由调用方在**链尾**调用(axum 0.8 的 `Router` 的 `S` -/// 是「还缺什么状态」,`with_state` 必须是**链条最后一步**)。 -/// ⇒ **完整的装配链只有一份**,在 [`build_app`](生产与单测都调它)。 +/// 🔴 **完整的装配链只有一份**,在 [`build_app_with`](生产与单测都经 [`build_app`] 调它)。 /// -/// 这里末尾的 `.with_state(state)` 是**类型层面**的 no-op(`S2` 显式落在 `AppState` -/// ⇒ 返回类型仍是 `Router`):它只是让契约 §9 的 `state` 参数**有去处** -/// (否则 `unused_variables` warning ⇒ 验收门① 破),**并不**把状态喂给 handler。 -/// 🔴 **真正把状态喂给 handler 的是链尾那次 `with_state`**(在 [`build_app`] 里)。 -/// 🔴 两次拿到的是**同一个 `AppState` 的两个 clone** —— 而 `AppState` 的三个字段 -/// (`config` / `db` / `sessions`)**全是 `Arc`** ⇒ 两份 clone **共享同一份底层状态** -/// ⇒ 行为完全等价,**不是**两个独立状态。 +/// 这里末尾的 `.with_state(state)` 把状态喂给**当前已注册**的 endpoint,返回类型仍 +/// 显式标成 `Router`(`S2 = AppState`);[`build_app_with`] 里那次 +/// `.with_state(state)` 传的是同一个 `AppState` 的 clone,作用是**类型降级** +/// (`Router → Router<()>`),好在 merge 自带状态的业务路由。 +/// +/// 🔴 `AppState` 的字段全是 `Arc` ⇒ 两份 clone **共享同一份底层状态**, +/// **不是**两个独立状态。 +/// 🔴 v0.3.0 起 `with_state` **不再是链尾**:它在 merge 业务路由**之前**完成, +/// 且之后不再新增需要 `AppState` 的路由(业务路由自带状态,已是 `Router<()>`)。 pub fn build_router(state: AppState) -> axum::Router { build_router_with(state, Extras::kernel()) } @@ -2569,7 +2592,7 @@ pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router router.merge(r), @@ -2597,6 +2620,8 @@ pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router axum::Router { build_app_with(state, Extras::kernel()) } @@ -2604,22 +2629,58 @@ pub fn build_app(state: AppState) -> axum::Router { /// 完整装配(**可注入版**)—— 外部业务仓 / 门面的唯一入口。 /// /// 🔴 **装配链仍然只有这一份**:与 [`build_app`] 的区别只在「路由里多 merge 什么」 -/// 和「fallback 是信封 404 还是 SPA 深链回退」。顺序(S25)一字不改。 +/// 和「fallback 是信封 404 还是业务兜底」。顺序(S25)一字不改。 /// -/// 🔴 **`extras.static_dir` 只影响 fallback**: +/// ```text +/// build_router_with(state, extras) → Router(平台 + 包 + 旧 router 注入) +/// .with_state(state) → Router<()>(前移:类型降级,好在 merge 之前完成) +/// .merge(extras.router_owned) → 业务自带状态路由(含它自己的 route_layer) +/// .fallback[_service](...) → 唯一兜底:extras.fallback 优先,否则平台 404 +/// .layer(extras.layers,按 Vec 顺序) → 全局层,最后挂的最外层 +/// .layer(m_status_rewrite()) +/// .layer(catch_all()) → 请求最先撞 catch_all +/// ``` +/// +/// 🔴 **`extras.static_dir` 只影响平台默认 fallback**: /// - `None` ⇒ 未命中就是信封 404(与历史行为**逐字一致**); /// - `Some(dir)` ⇒ `/api/**` 仍是信封 404;其它未命中路径先找静态文件, -/// 找不到再回退 `index.html`(前端 history 路由的深链)。 -pub fn build_app_with(state: AppState, extras: Extras) -> axum::Router { +/// 找不到再回退 `index.html`(前端 history 路由的深链); +/// - `extras.fallback` 给了值 ⇒ 用 `fallback_service`,**忽略** `static_dir`。 +pub fn build_app_with(state: AppState, mut extras: Extras) -> axum::Router { + // 🔴 第二阶段的三个注入点先 take 出来;剩下的 Extras 整体交给 build_router_with。 let static_dir = extras.static_dir.clone(); - build_router_with(state.clone(), extras) - .fallback(move |req: Request| { + let router_owned = extras.router_owned.take(); + let fallback = extras.fallback.take(); + let layers = std::mem::take(&mut extras.layers); + + // `build_router_with` 末尾那次 `with_state` 已经把状态烤进平台 endpoint + // (只是类型仍标 `Router`)⇒ 这里这次只做**类型降级**, + // 好在 merge 自带状态的业务路由(两侧必须同为 `Router<()>`)。 + let mut app = build_router_with(state.clone(), extras).with_state(state); + + // 业务自带状态路由:它自己的 `route_layer` 只作用于业务子树,面 B 不受影响。 + if let Some(biz) = router_owned { + app = app.merge(biz); + } + + // 🔴 **唯一兜底**(一个 Router 只允许一个 fallback)—— 两个分支互斥,不会挂两次。 + if let Some(f) = fallback { + app = app.fallback_service(f); + } else { + app = app.fallback(move |req: Request| { let dir = static_dir.clone(); async move { fallback_response(dir, req).await } - }) - .layer(m_status_rewrite()) - .layer(catch_all()) - .with_state(state) + }); + } + + // 业务**全局**层(按 Vec 顺序挂;最后挂的最外层 ⇒ 请求逆序经过)。 + for layer in layers { + app = layer(app); + } + + // S25 要害:fallback 仍在两个平台 `.layer()` **之前**;catch_all 最后挂 ⇒ + // 请求先撞 catch_all,再撞 m_status_rewrite,最后才是业务层与路由 / 兜底。 + app.layer(m_status_rewrite()).layer(catch_all()) } /// 未命中路径的兜底(唯一的 fallback 实现)。