Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ca8abf9cc9 | ||
|
|
6d6e0ee329 | ||
|
|
2b4f4d15b4 | ||
|
|
3d3fd69c1d |
No files matched your search
@@ -149,3 +149,65 @@ CannotCache(incremental): ["--crate-name", "probe", ..., "-C", "incremental=..."
|
||||
|
||||
**回归**:`cargo test --workspace` 704 passed / 0 failed(+9 条包内单测);
|
||||
`verify.sh --fast` 全绿;health 181 张表不变;四个包面 A/面 B 运行时全 200。
|
||||
|
||||
## 2026-11-04 下午:标准平台包 P0(门面 `sspf` v0.2.0 + 示例包选装)
|
||||
|
||||
**做了什么**(需求 `docs/SSPF-PLATFORM-PACKAGE.md`,实施记录见其 §10)
|
||||
|
||||
1. 新增 `crates/sspf`(0.2.0)= 业务仓唯一依赖:`Platform::new().packs/ddl/menus/router/static_dir/on_ready`
|
||||
+ `build_app/serve/serve_mcp`;契约与运行时类型全部原样重导出。
|
||||
2. 内核 4 个示例包降为 `example-packs` feature(依赖 `optional = true` + 生成段 `[features]`);
|
||||
`packs_gen.rs` / `modules/mod.rs` 生成段改成 **feature / not-feature 两份同名定义**。
|
||||
3. 七步启动搬到 `crates/sspf/src/{platform,runtime}.rs`;平台表清单与白名单对账留在内核新模块
|
||||
`src/backend/src/boot.rs`(参数化:spec 与包 DDL 由调用方给)。`sspf-admin` 1111 → 381 行。
|
||||
4. `routes::build_app_with(state, extras)` + `bootstrap::{ensure_base_with, ensure_schema_all_with}`;
|
||||
旧签名保留 ⇒ 704 个测试一行没改。静态 SPA 托管手写在 `routes.rs`(不引 tower-http)。
|
||||
5. 探针 `crates/tests/tests/external_consumer_it.rs`;闸门 AR17(平台包零业务依赖)/ AR18(门面零业务字面量),
|
||||
反自证 11 → 13 条。
|
||||
|
||||
**踩到的两个坑**
|
||||
|
||||
- **feature unification 比 OnceLock 更危险**:`sspf-tests` 开 `example-packs` 时,同一构建图里内核也带着示例包
|
||||
⇒ 门面若读 `bootstrap::packs()` 单例就会**静默**把示例包带进业务仓进程,而测试全绿。
|
||||
⇒ 门面全程用显式注入的 `PackRegistry`(默认空),默认装配**恒零业务**。
|
||||
- `\btdc\b` 匹配不到 `tdc_order`(`\w` 含下划线)⇒ AR18 正则去掉尾边界;`#[cfg]` 只能加在项上,
|
||||
`ALL_SPECS` 的数组元素不能单独 cfg ⇒ 生成器产两份同名定义(整段 cfg 会让 `all_specs()` 在默认 feature 下不存在)。
|
||||
|
||||
**回归**:`cargo test --workspace` 704 passed(+外部探针等新增 6 条,总数持平后再补回 CLI 被删的 4 条);
|
||||
`cargo tree -p sspf | grep sspf-pack` 无输出;`check-arch.sh` 29/29、`--self-test` 13/13;`verify.sh --fast` 全绿。
|
||||
|
||||
**发布(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<PGlite>` + `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 条引文判红。
|
||||
|
||||
## 18:2x 决策 D 变更:v0.3.0 直接推送
|
||||
|
||||
- 用户改口「直接推送」⇒ 决策 D 由「只打本地 tag、不 push」改为推送 `main` + `v0.3.0`。
|
||||
需求稿 §7.4/§7.5/§11.1/§11.4/§11.6 与 HANDOFF 0-bis 全部按已发布口径同步。
|
||||
- 仓外 `file://` + tag 探针:`sspf v0.3.0 (...?tag=v0.3.0#6d6e0ee3)`、3 passed、0 个示例包。
|
||||
**新坑**:`cargo --offline` 会拒绝 checkout `file://` git 依赖(`can't checkout ... you are in the offline mode`),
|
||||
探针去掉 `--offline` 即可,registry 依赖仍命中本地缓存(43.73s)。
|
||||
- 本地 tag 未发布过 ⇒ 文档同步提交后删除并在 HEAD 重建 annotated tag,再一起 push,
|
||||
避免 tag 落后一个纯文档 commit。
|
||||
@@ -0,0 +1,15 @@
|
||||
# CHANGELOG
|
||||
|
||||
## v0.3.0(2026-11-04)
|
||||
|
||||
- 新增两阶段装配 `Platform::assemble()` / `Assembled::finish()` / `serve()` 与 `Finish` 注入点:自带状态类型的业务路由可挂进平台唯一装配链,业务状态可在开库后构造。
|
||||
- `Db` 改用 `Arc<PGlite>` 并公开 `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 与仓外消费探针。
|
||||
Generated
+1
-1
@@ -1069,7 +1069,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "sspf"
|
||||
version = "0.2.0"
|
||||
version = "0.3.0"
|
||||
dependencies = [
|
||||
"axum",
|
||||
"libc",
|
||||
|
||||
+27
@@ -9,6 +9,28 @@
|
||||
|
||||
---
|
||||
|
||||
## 0-bis. 2026-11-04 `v0.3.0`:业务自带状态的可组合装配(P1 交付,**已推送 `origin`:`main` + tag**)
|
||||
|
||||
需求与实施记录:`docs/SSPF-BUSINESS-COMPOSITION.md`(含 §11 四项评审决策)。
|
||||
|
||||
1. **`Db.pg` 改 `Arc<PGlite>` + `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<Router<()>>` / `fallback: Option<Router<()>>` / `layers: Vec<LayerFn>`;唯一兜底由 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<AppState>`),`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。
|
||||
- **发布范围(决策 D 变更)**:原定「只打本地 tag、不 push」,交付后提出方要求**直接推送** ⇒
|
||||
`main` 与 annotated tag `v0.3.0` 均已到 `origin`,`git ls-remote --tags origin` 可见 `v0.3.0` 与 `^{}`。
|
||||
业务仓按 `http://127.0.0.1:13300/ssw/ssw-platform.git` + `tag = "v0.3.0"` 锁依赖(仓外探针实测通过)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 2026-11-04 标准平台包 `v0.2.0`:门面 crate `sspf` + 示例包选装(P0 交付)
|
||||
|
||||
**做了什么**(需求原文 `docs/SSPF-PLATFORM-PACKAGE.md`,实施记录见其 §10):
|
||||
@@ -48,6 +70,11 @@
|
||||
🔴 **177 不是 181**:181 = 177 张平台表 + 4 张示例包表(asset/books/demo/shop);平台包默认不带示例包
|
||||
⇒ 业务仓看到 177 + 自己的表。本仓 `sspf-admin`(开 `example-packs`)仍是 **181**,别把 181 写进业务仓的断言。
|
||||
|
||||
**已发布**:注记标签 `v0.2.0` → commit `9083394`,`main` 与 tag 都已推 `origin`。
|
||||
**git 依赖实测过**(需求 §6 那个 ⚠️ 已消):仓外项目只写
|
||||
`sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }`,
|
||||
`cargo check` **37.95s 通过**,依赖全标 `?tag=v0.2.0#9083394b` ⇒ 与 path 依赖等价,workspace 根解析正常。
|
||||
|
||||
**⏭ 业务仓(tdc-rs)P1 必做**(平台侧代劳不了):① 自带 `rust-toolchain.toml` 锁 1.95.0;② **删掉
|
||||
`[profile.release] panic = "abort"`**(否则 catch-all 失效、契约 §6.5 破);③ `[profile.dev] incremental = false`;
|
||||
④ 依赖写 `sspf = { path = "../ssw-platform/crates/sspf" }`(发布期换 git tag `v0.2.0`)。
|
||||
|
||||
@@ -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<PGlite>,
|
||||
/// 进程级业务锁(S3)。`Arc` 是因为 `Db` 需要 `Clone`。
|
||||
lock: Arc<Mutex<()>>,
|
||||
}
|
||||
@@ -223,11 +225,22 @@ impl Db {
|
||||
|
||||
fn new(pg: PGlite) -> Db {
|
||||
Db {
|
||||
pg,
|
||||
pg: Arc::new(pg),
|
||||
lock: Arc::new(Mutex::new(())),
|
||||
}
|
||||
}
|
||||
|
||||
/// 平台内部**同一个** `Arc<PGlite>` —— 自带状态的业务仓用它构造自己的状态层。
|
||||
///
|
||||
/// 🔴 返回的是 `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<PGlite> {
|
||||
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<DbTransaction<'_>, 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,
|
||||
|
||||
@@ -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」。
|
||||
#
|
||||
|
||||
+24
-10
@@ -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<PGlite>
|
||||
//! 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<PGlite>` 句柄**([`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<PGlite>`(构造自己的状态层)⇒ 从门面拿同一个 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 的静态判据互补:
|
||||
|
||||
+96
-24
@@ -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<PGlite>` 造自己的状态,
|
||||
/// 自行跑引导(引导结果不必回传平台);`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<Router>,
|
||||
/// 业务兜底(`ServeDir` + 决策层组成的 `Router<()>`);`None` ⇒ 平台信封 404。
|
||||
pub fallback: Option<Router>,
|
||||
/// **全局** middleware(按 Vec 顺序挂,最后挂的最外层)。
|
||||
/// 🔴 面 B 也会经过 ⇒ 只许放 CORS / 通用日志这类无差别层。
|
||||
pub layers: Vec<routes::LayerFn>,
|
||||
}
|
||||
|
||||
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<AppState>`;**自带状态类型**的业务路由请走
|
||||
/// [`Platform::assemble`] + [`Finish::router`]。
|
||||
pub fn router(mut self, router: Router<AppState>) -> 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<std::path::PathBuf>) -> 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<Router, String> {
|
||||
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<Router, String> {
|
||||
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<PGlite>
|
||||
/// 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<Assembled, String> {
|
||||
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
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,252 @@
|
||||
//! business_composition —— v0.3.0「业务自带状态的可组合装配」出口探针。
|
||||
//!
|
||||
//! ## 这条测试在证明什么
|
||||
//!
|
||||
//! 厚业务仓的 132 条端点绑在**自己的状态类型**上,不认平台的 `AppState`。
|
||||
//! 这条探针只依赖门面 `sspf`,一次钉住:
|
||||
//!
|
||||
//! 1. `Db::pg()` 给的是**同一个** `Arc<PGlite>`,经它建的表平台 `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<MyState>) -> Json<Value> {
|
||||
Json(json!({ "tag": s.tag }))
|
||||
}
|
||||
|
||||
/// 故意 panic ⇒ 必须被**平台** catch-all 接住(契约 §6.5)。
|
||||
async fn biz_panic() -> Json<Value> {
|
||||
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::<u16>().ok())
|
||||
.expect("响应首行必须是 HTTP/1.1 <code> ...")
|
||||
}
|
||||
|
||||
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<PGlite> ----
|
||||
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<MyState> 取值 ----
|
||||
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}");
|
||||
}
|
||||
@@ -0,0 +1,590 @@
|
||||
# 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` |
|
||||
@@ -225,8 +225,10 @@ sspf = { path = "../ssw-platform/crates/sspf" }
|
||||
# sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }
|
||||
```
|
||||
|
||||
⚠️ **git 依赖要实测一次**:path 依赖已验证,但 git 依赖下 cargo 是否仍能正确解析本仓 workspace 根,
|
||||
请用一个仓外 `cargo check` 探针确认,别假定等价。
|
||||
✅ **git 依赖已实测(2026-11-04 打 tag 当场验的)**:仓外最小项目只写
|
||||
`sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.2.0" }`,
|
||||
`cargo check` **37.95s 通过** —— cargo 正确解析了本仓 workspace 根,全部依赖都标注
|
||||
`?tag=v0.2.0#9083394b`,`sspf 0.2.0` 可 `use`,与 path 依赖等价。
|
||||
|
||||
业务仓(tdc-rs)侧必须同步配合的 4 件事,**属于 P1,不阻塞 P0**:
|
||||
|
||||
@@ -278,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 交付物落点
|
||||
|
||||
| # | 交付物 | 实际位置 |
|
||||
@@ -331,7 +337,8 @@ P1 的准备工作可与本 P0 **并行**,但 `main.rs` 换装配必须等 `v0
|
||||
lowcode-smoke 15/15、baseline-smoke 10/10、mcp-smoke 14/14;
|
||||
仓外探针(`/tmp/sspf-ext-probe`,只依赖 `sspf`)`cargo build --offline` 通过,
|
||||
`PGLITE_DIR=memory:// PORT=30999 ./probe` 起服务后 `GET /api/health` =
|
||||
`{"ok":true,"tables":177,"version":"0.1.0"}`(177 = 平台表,不含 4 张示例包表)。
|
||||
`{"ok":true,"tables":177,"version":"0.1.0"}`(177 = 平台表,不含 4 张示例包表);
|
||||
**git tag 依赖**(`/tmp/sspf-git-probe`,`tag = "v0.2.0"`)`cargo check` 通过(37.95s)。
|
||||
|
||||
### 10.5 实施时踩到的两个坑(留给下一次)
|
||||
|
||||
|
||||
@@ -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<PGlite>` 后绕过 `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` 上抢先处理 |
|
||||
+92
-14
@@ -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
|
||||
|
||||
+89
-28
@@ -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<AppState> → 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<ActionResult> {
|
||||
///
|
||||
/// 🔴 **`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<dyn FnOnce(axum::Router) -> 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<PathBuf>,
|
||||
/// 业务自带状态的路由(**已 `with_state` 成 `Router<()>`**,自带 `route_layer` 守卫)。
|
||||
///
|
||||
/// 🔴 **不许自带 fallback** —— 一个 Router 只允许一个 fallback,
|
||||
/// `Router::merge` 遇到两个会 panic。兜底只能由下面这个 `fallback` 统一挂。
|
||||
pub router_owned: Option<axum::Router>,
|
||||
/// 业务兜底(通常是 `ServeDir` + 决策层组成的 `Router<()>`)。
|
||||
/// `None` ⇒ 平台默认 `fallback_response`;`Some` ⇒ `fallback_service(...)`,
|
||||
/// 且此时 `static_dir` 被忽略(业务兜底自己负责 `/api/**` 的 404 形状)。
|
||||
pub fallback: Option<axum::Router>,
|
||||
/// 业务 middleware,按 Vec 顺序挂(最后挂的最外层)。
|
||||
pub layers: Vec<LayerFn>,
|
||||
}
|
||||
|
||||
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>` 的 `S`
|
||||
/// 是「还缺什么状态」,`with_state` 必须是**链条最后一步**)。
|
||||
/// ⇒ **完整的装配链只有一份**,在 [`build_app`](生产与单测都调它)。
|
||||
/// 🔴 **完整的装配链只有一份**,在 [`build_app_with`](生产与单测都经 [`build_app`] 调它)。
|
||||
///
|
||||
/// 这里末尾的 `.with_state(state)` 是**类型层面**的 no-op(`S2` 显式落在 `AppState`
|
||||
/// ⇒ 返回类型仍是 `Router<AppState>`):它只是让契约 §9 的 `state` 参数**有去处**
|
||||
/// (否则 `unused_variables` warning ⇒ 验收门① 破),**并不**把状态喂给 handler。
|
||||
/// 🔴 **真正把状态喂给 handler 的是链尾那次 `with_state`**(在 [`build_app`] 里)。
|
||||
/// 🔴 两次拿到的是**同一个 `AppState` 的两个 clone** —— 而 `AppState` 的三个字段
|
||||
/// (`config` / `db` / `sessions`)**全是 `Arc`** ⇒ 两份 clone **共享同一份底层状态**
|
||||
/// ⇒ 行为完全等价,**不是**两个独立状态。
|
||||
/// 这里末尾的 `.with_state(state)` 把状态喂给**当前已注册**的 endpoint,返回类型仍
|
||||
/// 显式标成 `Router<AppState>`(`S2 = AppState`);[`build_app_with`] 里那次
|
||||
/// `.with_state(state)` 传的是同一个 `AppState` 的 clone,作用是**类型降级**
|
||||
/// (`Router<AppState> → Router<()>`),好在 merge 自带状态的业务路由。
|
||||
///
|
||||
/// 🔴 `AppState` 的字段全是 `Arc` ⇒ 两份 clone **共享同一份底层状态**,
|
||||
/// **不是**两个独立状态。
|
||||
/// 🔴 v0.3.0 起 `with_state` **不再是链尾**:它在 merge 业务路由**之前**完成,
|
||||
/// 且之后不再新增需要 `AppState` 的路由(业务路由自带状态,已是 `Router<()>`)。
|
||||
pub fn build_router(state: AppState) -> axum::Router<AppState> {
|
||||
build_router_with(state, Extras::kernel())
|
||||
}
|
||||
@@ -2569,7 +2592,7 @@ pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router<AppSta
|
||||
let Extras {
|
||||
pack_router,
|
||||
router: biz_router,
|
||||
static_dir: _,
|
||||
..
|
||||
} = extras;
|
||||
let mut router = match pack_router {
|
||||
Some(r) => router.merge(r),
|
||||
@@ -2597,6 +2620,8 @@ pub fn build_router_with(state: AppState, extras: Extras) -> axum::Router<AppSta
|
||||
///
|
||||
/// 🔴 **这条链在仓库里只有这一份** —— 生产与测试共用 ⇒ 改顺序时两边一起变,
|
||||
/// 测试永远钉得住(不要在 `crates/sspf-admin/src/main.rs` 或测试里再抄一遍)。
|
||||
/// 🔴 `build_app()` = `build_app_with(state, Extras::kernel())`,即 `Finish::default()`
|
||||
/// ⇒ v0.3.0 之前的行为逐字不变。
|
||||
pub fn build_app(state: AppState) -> 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<AppState>(平台 + 包 + 旧 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<AppState>`)⇒ 这里这次只做**类型降级**,
|
||||
// 好在 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 实现)。
|
||||
|
||||
Reference in new issue
Block a user