- 需求稿 §7.4/§7.5/§11.1/§11.4/§11.6 改按已发布口径,补仓外 tag 探针实测 - HANDOFF 0-bis 同步发布范围;工作日志记离线模式无法 checkout file:// git 依赖
35 KiB
SSPF 平台包 v0.3.0 —— 给 ssw-platform 仓的 P1 需求:业务自带状态的可组合装配
提出方:
tdc-rs(业务仓 / 依赖方) 日期:2026-11-04 状态:已实施并发布 →main+ annotated tagv0.3.0已推送origin⚠️ 决策 D 于 18:2x 变更:评审时定的是「只打本地 tag、不 push」,交付后提出方要求 直接推送 ⇒ §7.4 / §7.5 / §11.1 / §11.6 与
HANDOFF.md0-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 test280 passed / 0 failed / 1 ignored,五把尺子全绿,对外行为零变化。适用范围:本仓(
ssw-platform)。本轮不改面 A / 面 B 的任何对外行为,不改v0.2.0已发布 API 的签名。 结论先行:平台包现在能「被依赖、被启动」,但还不能承载已有厚业务仓的路由——业务仓的 132 条端点 绑在自己的状态类型上,而Platform::router()只收Router<AppState>。缺的是「自带状态的业务路由
- 同一个库句柄 + 可替换兜底」三个注入点,都是平台包内部的小改,不需要重写业务。
0. 背景与目标
「sspf 作为 JNPF 替代品、tdc-rs 作为业务项目、单进程部署、兼容 JNPF」的终局形态:
一个进程 · 一个 PGlite 实例 · 一个 Router · 一个端口
├── 面 B(JNPF 官方形状,346 端点 / base_* 181 张表 / cipher / 602 码)—— 平台包提供
└── /api/ssw/tdc/**(132 条,六件套 + 三道门 + 裸三键 401/403 + SPA)—— 业务仓提供
P0 解决的是「平台包可被外部仓依赖」;P1 要解的是「业务仓已有装配链能挂进平台包」。这条一旦通,
tdc-rs 的 src/main.rs 才能从「自开 PGlite + 自建 AppState + 自抄 fallback/layer/with_state」
切成 sspf::Platform 单进程装配,自研 src/platform/ 才有退场路径。
出口判据:tdc-rs 能在不修改任何 handler、不改 132 条端点响应形状的前提下,把整套业务路由 注入平台装配链,单端口同时提供面 B 与 tdc 契约。
1. 交付物(做完打 annotated tag v0.3.0,并 push)
| # | 交付物 | 落点 |
|---|---|---|
| R1 | Db 暴露同一个 Arc<PGlite> 句柄 |
crates/sspf-store/src/db.rs |
| R2 | assemble() / Assembled::finish() / Assembled::serve() 两阶段装配 |
crates/sspf/src/platform.rs |
| R3 | Extras 三个注入点(自带状态路由 / 可替换兜底 / 业务 middleware 层) |
src/backend/src/routes.rs |
| R4 | 装配链仍只有一份,S25 顺序不变,build_app() 行为逐字不变 |
src/backend/src/routes.rs |
| R5 | 新增集成探针 business_composition_it.rs + 闸门 AR19(含反自证) |
crates/tests/、scripts/check-arch.sh |
| R6 | 仓外 git-tag 探针实测 + CHANGELOG.md(P0 缺的那份一起补) |
仓库根 / /tmp 探针 |
版本:crates/sspf/Cargo.toml 的 version 由 0.2.0 → 0.3.0(继续显式写死,不用
version.workspace,否则 git tag 依赖会解析成 workspace 根版本)。
2. 硬约束(不可协商)
- 一个进程只允许一个
PGlite实例(pglite-rs 内部static OPEN)。平台与业务必须共用 同一个Arc<PGlite>,不许业务仓再PGlite::open()或另起Db::open_temp()。 - 装配链只有一份。
fallback → m_status_rewrite → catch_all的 S25 顺序不许在业务仓里再抄一遍; 业务仓拿到的必须是平台组装完成的Router<()>。 - 一个 Router 只允许一个 fallback。axum
Router::merge遇到两个 fallback 直接 panic。 业务 Router 不许自带 fallback,兜底只能由Finish.fallback统一挂。 v0.2.0的公开签名不动:Platform::router(Router<AppState>)、Platform::build_app()、Platform::serve()、runtime 四个函数全部保持原样。新增能力一律走新入口。- 默认路径逐字等价:
Finish::default()装配出的 Router 与v0.2.0的build_app()完全一样 (710 测试 + 面 B 尺子是现成的钉子)。 - 面 B 不许裁。Java 版
ssw-tdc-biz/pom.xml引的是全量 JNPF jar,「兼容 JNPF」不等于只做登录; 346 端点 /base_*/ cipher / 602 码一个都不能少。
3. 四条类型级冲突(本轮实测,都是可核查的行号)
3.1 状态类型不同 ⇒ 132 条端点注入不了(最硬的一条)
- 平台侧:
crates/sspf/src/platform.rs:162pub fn router(mut self, router: Router<AppState>);src/backend/src/routes.rs:70Extras.router: Option<Router<AppState>>;src/backend/src/routes.rs:109build_router_with(...) -> axum::Router<AppState>。 - 业务侧:
../tdc-rs/src/tdc/controller/mod.rs:27pub fn build_router(state: TdcState) -> Router<TdcState>。
axum 的 merge 要求两侧 S 同型 ⇒ Router<TdcState> 与 Router<AppState> 不能直接 merge。
把 tdc 的 handler 全量改成 State<AppState> + Extension<TdcState> 是重写级(12k 行 / 132 端点),
不采纳。
3.2 库句柄不通用
crates/sspf-store/src/db.rs:200-204:
#[derive(Clone)]
pub struct Db {
pg: PGlite, // ← 私有,无 Deref / inner() / pg()
lock: Arc<Mutex<()>>,
}
Db 的公开方法只有 open / open_temp / ensure_schema / query_json* / exec* / scalar_text / shutdown / begin(db.rs:206-371),业务仓拿不到 PGlite。而 tdc 的平台层是
../tdc-rs/src/platform/state.rs:33 pub db: Arc<PGlite>,ensure_schema(&PGlite)
(../tdc-rs/src/platform/db.rs:320),且 query_json 自带 f_ ↔ camelCase 归一逻辑
(与 sspf Db::query_json 的「SQL 必须自带 AS camelCase 别名」不同)⇒ 不能让 tdc 改用
Db::query_json,那会改响应形状、破契约。
⇒ 结论:必须让业务仓复用同一个 PGlite 句柄,各自保留自己的查询封装。
3.3 兜底与 middleware 也是两套(P0 文档没覆盖,这次核准新发现)
../tdc-rs/src/main.rs:192-229 是一条完整且经过五把尺子验证的装配链:
let app: Router = build_router(state.clone())
.route("/api", any(api_not_found)).route("/api/{*rest}", any(api_not_found))
.route("/migrate.sql", any(api_not_found))
.fallback_service(spa_fallback(static_dir)) // ServeDir + ddl_guard + 深链决策
.layer(from_fn(json_method_not_allowed)) // 405 → 裸三键
.layer(from_fn_with_state(auth_state, auth_middleware)) // 三道门
.layer(CorsLayer::permissive())
.with_state(state);
其中 api_not_found(../tdc-rs/src/platform/fallback.rs:96)返回 裸三键
{"success":false,"code":404,"msg":"接口不存在"},与 sspf 的信封 404 形状不同;
spa_fallback()(../tdc-rs/src/platform/fallback.rs:120,返回 Router<()>)还带 ddl_guard 前置守卫。
平台侧 routes.rs:2626 的 fallback_response 不认识这些 ⇒ 不能用平台默认 fallback 覆盖业务兜底,
也不能让业务 Router 自带 fallback(约束 3)。
3.4 业务状态在开库之后才能构造(鸡生蛋)
tdc 的 TdcState 依赖 BootstrapIdentity,而引导要跑 DB 写
(../tdc-rs/src/main.rs:119-144:AppState::new → bootstrap_identity → TdcState::new)。
⇒ 业务 Router 必须等平台 boot 完(库已开、表已建、种子已种)才能构造。
v0.2.0 的 builder 全部在 boot() 之前求值(.router(...)、build_app() 一步到位),
单独加一个 router_owned(Router<()>) builder 方法不够用。
✅ 这是本次核准最关键的约束:必须用两阶段装配(先
assemble()拿AppState, 再finish()传业务路由),不是给 builder 加个字段就能了事。
3.5 一个有利条件(决定了改动可以很小)
src/backend/src/routes.rs:2770,2816:
pub fn m_status_rewrite() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)>
pub fn catch_all() -> axum::middleware::FromFnLayer<MwFn, (), (Request,)>
两个中间件的状态类型都是 ()(catch_all_inner 只 next.run(req) + catch_unwind,
不碰 State<AppState>)⇒ 在 Router<()> 上挂与在 Router<AppState> 上挂完全等价。
所以「平台路由先 with_state 降成 Router<()>、再 merge 业务路由、最后挂 fallback + layer」
在类型与行为上都成立,S25 的 fallback 在两个 .layer() 之前这一要害仍能保住。
3.6 类型链已实测(不是纸上推演)
在 /tmp/sspf-compose-probe 用 axum 0.8.9 建了独立最小 crate,把 §5 的完整顺序编译并跑通:
cargo test --offline → 1 passed / 0 failed / exit 0(22.12s)。验证四件事:
Router<PlatformState>.with_state(ps)与Router<BizState>.with_state(bs)各自降成Router<()>后可以merge—— 业务 handler 仍从自己的State<BizState>取值;Router<()>可以直接作为fallback_service(...)的参数(tdc 的spa_fallback()返回的正是这个类型);Vec<Box<dyn FnOnce(Router<()>) -> Router<()> + Send + Sync>>这种 layers 注入形状能编译;- 链尾返回
Router<()>(axum::serve唯一接受的类型)。
⇒ §5 的顺序在类型层面没有障碍;剩下的只是把它落进 build_app_with,并用 §7.2 的探针
钉住运行时行为(catch-all / 405 / 双契约)。探针源码可按需索取,不在本仓内。
4. 推荐 API(可照抄)
4.1 R1 —— Db 暴露同一个句柄
crates/sspf-store/src/db.rs:
#[derive(Clone)]
pub struct Db {
pg: Arc<PGlite>, // 由 PGlite 改为 Arc<PGlite>
lock: Arc<Mutex<()>>,
}
impl Db {
/// 与平台内部**同一个** Arc —— 业务仓用它构造自己的状态层。
/// 🔴 不许返回 `PGlite::clone()`:pglite 的 Clone 语义是深是浅未钉死,
/// `Arc::ptr_eq` 才是可验证的共享。
pub fn pg(&self) -> Arc<PGlite> { Arc::clone(&self.pg) }
fn new(pg: PGlite) -> Db { Db { pg: Arc::new(pg), .. } }
}
db.rs 里现有的 self.pg.exec(..) / self.pg.query(..) / self.pg.transaction()
(begin() 在 db.rs:371)全是方法调用,经 Deref 自动生效 ⇒ Arc 化后这些调用点一行都不用改;
只有显式把 &self.pg 当 &PGlite 传参时才需要 .as_ref()(本仓现有代码没有这种写法)。
门面 crates/sspf/src/lib.rs:73 已 pub use sspf_store::db::Db,无需再导出。
4.2 R2/R3 —— 两阶段装配 + 三个注入点
src/backend/src/routes.rs:66 扩展 Extras(#[derive(Default)] 保持):
/// 一层业务 middleware:`Router<()>` 进、`Router<()>` 出。
pub type LayerFn = Box<dyn FnOnce(Router<()>) -> Router<()> + Send + Sync>;
pub struct Extras {
pub pack_router: Option<Router<AppState>>,
pub router: Option<Router<AppState>>,
pub static_dir: Option<PathBuf>,
/// 业务 Router(**已 `with_state` 成 `Router<()>`**,自带状态与 `route_layer` 守卫)。
/// 🔴 不许自带 fallback(约束 3)。
pub router_owned: Option<Router<()>>,
/// 业务兜底(通常是 `ServeDir` + 决策层组成的 `Router<()>`)。
/// `None` ⇒ 平台默认 `fallback_response`;`Some` ⇒ `fallback_service(...)`,
/// 且此时 `static_dir` 被忽略。
pub fallback: Option<Router<()>>,
/// 业务 middleware,按 Vec 顺序挂(见 §5)。
pub layers: Vec<LayerFn>,
}
crates/sspf/src/platform.rs 新增(不动任何现有方法签名):
/// 平台已就绪、路由尚未终结的装配句柄(boot 的 1–6 步全部跑完)。
pub struct Assembled {
pub state: AppState,
config: Config,
extras: Extras,
}
#[derive(Default)]
pub struct Finish {
pub router: Option<Router<()>>,
pub fallback: Option<Router<()>>,
pub layers: Vec<routes::LayerFn>,
}
impl Platform {
/// 走完 `boot()`(开库 / DDL / 种子 / 守卫 / 钩子),**不绑端口、不终结路由**。
pub async fn assemble(self) -> Result<Assembled, String>;
}
impl Assembled {
/// 唯一权威装配链的入口,返回可 `axum::serve` 的 `Router<()>`。
pub fn finish(self, opts: Finish) -> Router;
/// `finish` + `runtime::serve_http`(绑端口 / 优雅停机 / 关库,与 `serve()` 一致)。
pub async fn serve(self, opts: Finish) -> Result<(), String>;
}
Platform::build_app() / serve() / serve_mcp() 保持签名,内部统一改成
「assemble().await? → finish(Finish::default())」,保证默认路径逐字等价。
业务仓最终写法(评审后定稿:引导结果自行持有,三道门只挂业务子树):
// ① 平台 boot 完成:库已开、表已建、种子已种、钩子已跑
let boot = sspf::Platform::new()
.config(config)
.ddl("tdc_xxx", include_str!("../schema/001_init.sql"))
.assemble().await?;
// ② 业务在 **assemble 之后**自行引导:结果直接进业务状态,不必回传平台
let pg = boot.state.db.pg(); // R1:同一个 Arc<PGlite>
let bootstrap = bootstrap_identity(&tdc_platform_state(pg.clone()), &tdc_config).await;
let tdc_state = TdcState::new(tdc_platform_state(pg), tdc_config, bootstrap);
// ③ 业务自带状态;三道门/405 改写只作用于业务子树(面 B 不受影响)
let biz = tdc::controller::build_router(tdc_state) // 返回类型改为 Router<()>
.route_layer(from_fn(json_method_not_allowed))
.route_layer(from_fn_with_state(auth_state, auth_middleware));
boot.serve(Finish {
router: Some(biz),
fallback: Some(spa_fallback(static_dir)),
// 🔴 Finish.layers 是**全局层**(面 B 也会经过)⇒ 只放无差别件
layers: vec![Box::new(|r| r.layer(CorsLayer::permissive()))],
}).await
决策 A(全局层只放无差别件):
Finish.layers挂在 merge 完成后的总 Router 上; 放业务鉴权会让面 B 的/api/oauth/Login过 tdc 三道门 ⇒ 破「面 B 行为不变」。 业务鉴权 / 405 改写必须挂在业务 Router 自己的route_layer(merge 之前)。 原稿示例同时在route_layer与Finish.layers挂了auth_middleware(重复挂载),已删。 决策 B(assemble 后自行引导):on_ready返回Result<(), String>,产出会被丢弃;bootstrap_identity的结果是构造TdcState的必需输入,只能在assemble()之后自己跑。on_ready保持「无返回值的预热」语义,签名不动。
4.3 备选路线(若不愿引入 Assembled)
把三个注入点做成 Platform 上的闭包式 builder:
router_owned_with(Box<dyn FnOnce(AppState) -> Router<()> + Send + 'static>),
在 boot() 之后、装配之前调用一次。改动更小,但 Extras 仍要加字段,且 on_ready 与
router_owned_with 两个钩子的先后语义容易混淆。推荐 §4.2,把「业务状态构造」显式留给业务仓。
5. 装配顺序(写死在 build_app_with,业务仓不许抄)
src/backend/src/routes.rs:2613 改造后:
build_router_with(state, extras) → Router<AppState>(平台 + 包 + 旧 router 注入)
.with_state(state) → Router<()> ← 原先在链尾,现前移到 merge 之前
.merge(extras.router_owned) → 业务自带状态路由(含它自己的 route_layer)
.fallback[_service](...) → 唯一兜底:extras.fallback 优先,否则 fallback_response
.layer(业务 layers,按 Vec 顺序) → 最后挂的最外层
.layer(m_status_rewrite())
.layer(catch_all()) → 请求最先撞 catch_all
请求实际顺序:catch_all → m_status_rewrite → 业务 layers(逆序) → 路由 / fallback。
S25 要害 unchanged:.fallback() 仍在两个平台 .layer() 之前;两个平台 layer 状态类型是 ()
(§3.5)⇒ 前移 with_state 不改变它们的行为。
🔴 Finish.layers 是全局层,不是业务子树层:它按 Vec 顺序挂在 merge 之后的总 Router 上,
面 B 也会经过 ⇒ 只许放 CORS / 通用日志这类无差别中间件。业务三道门、405 改写必须挂在
业务 Router 的 route_layer 上(在 merge 之前)。business_composition_it 用
x-biz-guard(只在业务端点)/ x-global(面 B + 业务都有)两个响应头把这条边界钉住。
⚠️ 三点必须同步处理:
build_router_with里let Extras { pack_router, router, static_dir: _ } = extras;(routes.rs:2569)是显式解构,加字段后要补router_owned: _, fallback: _, layers: _(或在build_app_with里先take出来再传一份干净的Extras)。routes.rs:90-103, 2591-2599与契约 §9 / §10 第 6 步里「with_state是链尾」的表述 要改:新语义是「with_state在 merge 自带状态路由之前,且之后不再新增需要AppState的路由」。- 新增测试钉住:前移之后 fallback 仍被 catch-all 保护、405 改写仍生效、
panic ⇒ 200 +
code=400(panic_handler那条#[cfg(test)]路由覆盖不到业务路由, 建议探针里再故意 panic 一条业务端点)。
6. 逐文件改造清单
| 文件 | 动作 |
|---|---|
crates/sspf-store/src/db.rs:199-230 |
pg 改 Arc<PGlite>;加 pub fn pg();begin() 里改 self.pg.as_ref().transaction()(DbTransaction 结构未动) |
src/backend/src/routes.rs:66-87 |
Extras 加 3 字段;Extras::kernel() 补 Default 值;加 LayerFn 别名 |
src/backend/src/routes.rs:2569-2588 |
解构补字段;末尾 with_state 保留(返回 Router<AppState>) |
src/backend/src/routes.rs:2600-2623 |
build_app_with 按 §5 重排;build_app 改走 Extras::kernel() + 默认 Finish |
src/backend/src/routes.rs:90-103, 2591-2599 |
注释同步「with_state 位置」的新语义 |
crates/sspf/src/platform.rs:55-70, 202-251, 340-346 |
加 Assembled / Finish / assemble();build_app/serve/serve_mcp 内部改走两阶段;extras() 补字段 |
crates/sspf/src/lib.rs:46-101 |
导出 Assembled / Finish / LayerFn;VERSION 随 0.3.0 自动变 |
crates/sspf/Cargo.toml |
version = "0.3.0"(显式写死) |
crates/tests/tests/business_composition_it.rs |
新增探针(§7.2) |
scripts/check-arch.sh |
新增 AR19 + 反自证用例 |
docs/contract.md / HANDOFF.md / CHANGELOG.md |
同步 S25 表述、发布说明(核查后 contract.md 无「with_state 在链尾」表述,无需改) |
crates/sspf/src/lib.rs:108 |
version_matches_the_manifest 硬编码 0.2.0 ⇒ 必须同步 0.3.0,否则 cargo test --workspace 当场红 |
crates/sspf/src/lib.rs / platform.rs / routes.rs |
同步「with_state 在链尾」的注释、版本号表、pglite 重导出与 LayerFn 导出 |
docs/known-limitations.md |
记「双 DB 锁」与「413 被平台改写」两条 |
7. 验收判据(v0.3.0 出口,逐条可跑)
7.1 现有基线不回退
cargo test --workspace # 710 passed / 0 failed / 5 ignored,只许增不许减
bash scripts/check-arch.sh # 29/29 → 加 AR19 后 30/30
bash scripts/check-arch.sh --self-test # 13/13 → 加反自证用例后 14/14
bash scripts/verify.sh --fast # 8 步全绿
python3 scripts/pack-sync.py --check # 4 处派生一致
bash scripts/verify.sh --smoke # 运行时 6 把尺子
bash scripts/perm-smoke-jnpf.sh # 面 B 23/23(不裁面 B 的硬证据)
cargo tree -p sspf 仍 0 个 sspf-pack-*;本仓 sspf-admin(开 example-packs)的
/api/health 仍是 tables=181;平台包默认装配是 177(+ 业务注入的表),
两者是不同判据,别混(P0 §5 的实测口径)。
7.2 新增探针 business_composition_it.rs(一个 #[tokio::test],pglite 进程级单例)
必须同时断言:
Arc::ptr_eq(&db.pg(), &db.pg()),且经db.pg().exec()建的表能被db.scalar_text()查到 ⇒ 同一个库、同一个句柄。⚠️ptr_eq对Arc::clone恒真、只验证「两次调用返回同一 Arc 分配」;有效判据是 SQL 可见性(探针两条都留,后者才是钉子)。assemble().await?后finish(Finish { router: Some(biz), .. }): 业务端点 200,且 handler 从自己的State<MyState>取到值 ⇒ 自带状态成立。- 面 B
/api/oauth/Login同端口 200 + token ⇒ 双契约单端口。 Finish::fallback = Some(自定义 Router<()>)时,未命中路径走业务兜底;None时走平台信封 404 ⇒ 两种兜底都可用且只有一个 fallback。- 业务端点故意 panic ⇒ 200 +
code=400;405 ⇒ 改写仍生效 ⇒ 前移with_state后 catch-all / 405 改写仍覆盖 merge 进来的业务路由。 Finish::default()与同仓build_app():对同一组面 B 请求逐字比对响应。 仓内拿不到旧二进制 ⇒ 用build_app_with(state, Extras::default())作参照 Router, 共用同一个AppState、不再开库(探针起第二个监听比/api/health的 status + body)。- 默认 feature 下依赖树 0 个
sspf-pack-*。
7.3 AR19(静态闸门 + 反自证)
只扫 src/backend/src/routes.rs 的非注释代码行(注释里的装配顺序示意不计):
pub fn build_app_with恰好 1 处(唯一装配链);.layer(catch_all())恰好 1 处;.fallback(/.fallback_service(恰好 2 处 ——if/else互斥分支,恒只有一个生效; ⚠️ 原稿写「fallback(只出现一次」与「可替换兜底」自相矛盾,已按实现修正;Extras.router_owned的文档注释必须含「不许自带 fallback」。- 反自证 14/14:临时往
routes.rs追加第二处.layer(catch_all())⇒ 闸门必须红,随即恢复文件。 - 「平台包内不出现业务字面量」由 AR18 负责,AR19 不重复该规则。
7.4 仓外 git-tag 探针(P0 那次的 ⚠️ 这次照做)
/tmp 新建最小 crate,只写 sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.3.0" }(决策 D 已变更:tag 已 push 到 origin ⇒ 直接用业务仓真实会写的 URL),
cargo check + 单测:
use sspf::{Assembled, Finish, Platform, VERSION};
fn probe(p: Platform) -> Result<Assembled, String> { /* 只验编译 */ }
cargo tree 解析来源必须是 (git?tag=v0.3.0#<sha>)、sspf v0.3.0、0 个 sspf-pack-*。
推送前另用 file:///Users/xs/Desktop/workspace/ssw-platform 跑过一轮(同一判据),两轮结果见 §11.4 / §11.6。
7.5 发布
git commit + annotated tag v0.3.0 → git push origin main + git push origin v0.3.0 →
git ls-remote --tags origin 可见 refs/tags/v0.3.0 与 ^{}(annotated tag 解引用)。
决策 D 变更:原为「只打本地 tag、不 push」,交付后提出方要求直接推送 ⇒ 已执行。
CHANGELOG.md 补 5–8 行(P0 那次只落在文档 §10.4 / HANDOFF §0,这次一并补上独立文件)。
8. tdc-rs 侧 P2 对照改造(信息性,不要求本仓配合)
v0.3.0 到位后,业务仓按 §4.2 的写法切 src/main.rs,改动面:
Cargo.toml:sspf的tag→v0.3.0。src/main.rs:删掉自开PGlite/ensure_schema/AppState::new/auth_state那段, 改成assemble → 用 db.pg() 造 tdc AppState → build_router → finish/serve。main.rs里的.route("/api", any(api_not_found))/.route("/api/{*rest}", any(api_not_found))/.route("/migrate.sql", any(api_not_found))三条要搬进业务 Router(with_state之前), 不要散落在main.rs;Finish.fallback接管 SPA 后,它们仍是「/api/**404 裸三键」的显式保险。../tdc-rs/src/tdc/controller/mod.rs:27:build_router返回类型Router<TdcState>→Router<()>(内部已有.with_state(state),只改返回类型标注;132 个 handler 一行不动)。- 三道门从
main.rs的全局.layer()改成业务 Router 的.route_layer()(只作用于业务子树,面 B 不受影响)。🔴 不要塞进Finish.layers—— 那是全局层, 会让面 B 登录过业务鉴权(决策 A);Finish.layers只留 CORS 这类无差别件。 src/platform/的db.rs/session.rs/state.rs退场或降为薄适配层(保留query_json的f_↔ camelCase 归一,这是契约的一部分)。
出口:cargo test ≥ 280、五把尺子全绿(smoke.sh 80/80、check-contract.sh 132 条端点一致)、
401/403 裸三键、SPA 深链、/api/** 404 裸三键、面 B 登录同端口 200。
9. 明确不做(P1 边界)
- ❌ 不要求 tdc 改成声明式
EntitySpec/ RESTful 三件套(会改掉 132 条端点契约,属 P3)。 - ❌ 不把 132 个 handler 改成
State<sspf::AppState>+Extension<TdcState>(重写级,不可接受)。 - ❌ 不让业务仓自己抄
fallback + layer + with_state(P0 §2 那条原则继续有效)。 - ❌ 不改
Platform::router()的签名,不删build_app()/serve()(v0.2.0兼容)。 - ❌ 不裁面 B、不动
base_*表、不改 cipher / 602 码 / 信封形状。 - ❌ 不统一两套会话层 / 两套
query_json归一(P3 再谈;本轮只求「同一个库、同一个端口」)。 - ❌ 不改
panic策略:业务仓已在8a351b7删掉panic = "abort",平台侧继续依赖 unwind。
10. 风险与已知坑(都是踩过或本轮核准出来的)
OnceLockfirst-call-wins:bootstrap::packs()一旦被默认空注册表占住,注入静默失效。 P0 的解法(门面全程显式PackRegistry)在assemble()里必须继续遵守。- feature unification:平台仓内测试构建可能把
example-packs渗进门面。 ⇒ 新增探针要在仓外用 git tag 再跑一遍(§7.4),别只信仓内测试。 - 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。 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.*死锁)。- rustc 1.95.0:本仓
rust-toolchain.toml锁 1.95.0(L3 dylib ABI 前提); 门面rust-version = "1.85"只是 MSRV。业务仓已按 1.95.0 补了同名文件,别照 1.85 改。 - 发布前先 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_it1 passed / 0 failed(2.41s):同句柄建表可见、自带状态、 双契约单端口、业务层只作用业务子树、两种兜底、业务 panic ⇒ 200 +code=400、 405 信封、默认路径/api/health逐字等价、零示例包。check-arch.sh30/30、--self-test14/14(新增 AR19 反自证)。cargo test --offline --workspace711 passed / 0 failed / 7 ignored(基线 710 + 新探针 1)。pack-sync.py --check4 处派生一致;cargo tree -p sspf0 个sspf-pack-*。verify.sh --fast8 步全绿(70.6s);verify.sh --smoke14 步全绿(189.3s), 其中perm-smoke(43 条断言尺子自证)、perm-smoke-jnpf面 B 23/23、lowcode-smoke/baseline-smoke/mcp-smoke全绿。check-citationsCIT1–CIT3 全绿(1374 条引文):需求稿的 21 条跨仓引文已统一成../tdc-rs/.../ 本仓相对路径写法,尺子才认得(这是本次新增文档踩的坑)。- 仓外
file://+ tagv0.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会拒绝 checkoutfile://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 |