# SSPF 平台包需求(三):让业务仓的库操作走同一个 `Db` > 目标 tag:**`v0.5.0`**(`v0.4.0` 已用于「平台包零业务清理」,不能复用) > 提出方:`tdc-rs`(厚业务仓,自带状态类型 / 自带 JSON 归一语义) > 状态:**已实施并发布 → annotated tag `v0.5.0` 已推 `origin`**(实施记录见 §10)。 > **业务侧已按 §5 完成切换**(`tdc-rs` 提交 `e13768e`,见 §11);两条附加判据全部落地。 > 前两份需求:`SSPF-PLATFORM-PACKAGE.md`(v0.2.0)、`SSPF-BUSINESS-COMPOSITION.md`(v0.3.0)。 --- ## 0. 一句话 `Db::pg()` 把同一个 `Arc` 交给了业务仓,但没有把 **`Db.lock`** 一起交出去。 ⇒ 平台侧所有 SQL 持 `Db.lock`,业务侧所有 SQL 持业务仓自己的 `db_lock`, **两把锁互不覆盖**,两边并发写同一个 PGlite 后端时可能交错。 本需求要平台包补一个「**持同一把锁、但不碰业务仓的 JSON 键归一**」的入口, 让业务仓把库操作统一收进 `Db` 的串行域,且**对外契约一字不变**。 --- ## 1. 背景:三版之后剩下的唯一硬缺口 | 版本 | 解决了什么 | 留下什么 | |---|---|---| | v0.2.0 | 门面 `crates/sspf/`、零业务、git tag 依赖 | 业务仓只能整包注入 | | v0.3.0 | `Db.pg: Arc` + `pg()`、两阶段装配、`Extras` 三注入点 | `Db::pg()` **绕过** `Db.lock`(`db.rs` 的 `pg()` 文档自己写明了) | | v0.4.0 | 平台包零业务清理、示例搬技能仓 | 与本题无关 | | **v0.5.0(本需求)** | 业务仓库操作与平台共用同一把 `Db.lock` | — | `tdc-rs` 在 P2 完成了单进程 / 单库 / 单端口装配,P3 打通了两套会话; `CHANGELOG.md` 的 v0.3.0 条目也已如实登记「`Db::pg()` 绕过 `Db.lock` 时, 平台与业务各自的多语句事务可能交错」。本需求就是来销这一条的。 --- ## 2. 硬约束(已核实,不是推测) ### 2.1 单实例 / 单后端 `pglite-rs 0.2` 进程级只允许一个 `PGlite` 实例;平台与业务共用同一个 `Arc`(`Db::pg()`)。因此本题**不是**「再开一个连接」,而是 「同一个连接上,两边的临界区必须互斥」。 ### 2.2 平台侧的锁是私有的 `crates/sspf-store/src/db.rs`: - `Db { pg: Arc, lock: Arc> }` —— `lock` 字段 `private`; - `Db::query_json` / `query_json_params` / `exec` / `exec_params` / `scalar_text` / `ensure_schema` 全部先 `let _guard = self.lock.lock().await`; - `Db::begin()` 返回 `DbTransaction`,`_guard` 在整个事务期间持有同一把锁; - `Db::pg()` 的文档明写:「**这个句柄绕过本层的 `Db.lock`**……一次业务操作跨多条 SQL 的串行化要业务仓自己保证」。 ⇒ 业务仓今天**拿不到** `Db.lock`,只能自己造一把 → 两把锁。 ### 2.3 🔴 JSON 键归一是两套,直接换 `Db::query_json` 会破契约 这是本需求**最容易踩的坑**,务必先读: | | `sspf::Db::query_json*` | `tdc-rs::platform::db::query_json*` | |---|---|---| | SQL 包裹 | `SELECT row_to_json(q)::text AS _row FROM (…) AS q` | 同款 | | 键归一 | `normalize_json_keys`:`f_` 前缀 → camelCase、还原被 PG 折叠的未加引号别名、双引号别名视为权威 | **完全不归一**,原样返回 PG 折叠后的列名 | | 谁再归一 | 平台 handler 直接用 | `tdc::mapper` 用 `column_to_json_key` 在 Rust 侧做 `f_*` → camelCase | `db.rs` 的 `normalize_json_keys` 注释也承认「与 `tdc-rs` 的做法一致」, 但那是**最终结果**一致,**中间层**不一致:业务仓的 SQL 投影是 `f_` 列名, mapper 已经做了一次转换。若业务侧直接改调 `Db::query_json_params`, 键会被归一两次 / 在加引号别名上漂移 ⇒ **`tdc-rs` 的 132 条端点响应形状会变**。 > 🔴 **因此:禁止用「把业务 SQL 改调现有 `Db::query_json*`」来实现本题。** > 现有 `query_json*` 的归一行为一个字都不许改(面 A / 面 B 契约依赖它)。 ### 2.4 业务仓的库操作已经收在一个文件里(本轮先做了收拢) 🔴 **调研时发现的坑**:原先 `tdc-rs/src/tdc/service/{crud,account,identity}.rs` 有 **12 处** 直接 `state.db.query(&sql, &refs)`(写路径),绕过了 `platform/db.rs`。 本轮已把它们全部收进新增的 `platform::db::exec_params`,并用 `scripts/check-db-access.sh` 护栏钉死「业务层不许再直接碰裸 PGlite」。 ⇒ 现在 `tdc-rs/src/platform/db.rs` 是唯一出口,6 个 `pub` 函数: | 函数 | 用途 | 平台侧对应能力 | |---|---|---| | `query_json(db, sql)` | 无参 SELECT | `query_json_params(db, sql, &[])` | | `query_json_params(db, sql, params)` | 带参 SELECT(`row_to_json` 包裹,**不归一**) | 需要新增 `Db::query_json_raw` | | `exec_params(db, sql, params)` | 带参写(INSERT / UPDATE / DELETE,丢弃结果集) | **现有 `Db::exec_params` 即可** | | `query_scalar_text(db, sql, params)` | 取第一行第一列文本(带参) | 需要新增 `Db::query_rows` | | `column_types(db, table)` | 查 `pg_catalog` 拿列类型(原始行) | 需要新增 `Db::query_rows` | | `ensure_schema(db)` | 启动期建表(多语句 `exec`) | 现有 `Db::exec` 即可 | 另有 2 处**豁免**(护栏白名单,不参与请求期并发): - `src/tdc/schema.rs::ensure_schema_coexist` —— 启动期 `on_ready` 单线程建表; - `src/main.rs` 的 `on_ready` —— 调的是 **`sspf::Db::exec`**(本身已持平台锁,不是裸句柄)。 ⇒ 业务侧切换只需改 `platform/db.rs` 的 6 个函数 + 状态里注入 `Arc`; `mapper.rs` / `service/*` / `controller/*` **零改动**(它们已经全部走封装)。 --- ## 3. 需求(R1–R7) ### R1(必选)新增 `Db::query_json_raw` —— 持锁 + 不归一 ```rust impl Db { /// 持 `Db.lock`,把 `sql` 用 `row_to_json` 包成单行文本并反序列化, /// **不做任何 JSON 键归一**(返回 PostgreSQL 原样的列名 / 别名折叠结果)。 /// /// 给自带归一语义的厚业务仓用:它们自己在上层把 `f_*` 转 camelCase, /// 平台不能替它做第二次。 /// /// 🔴 与 `Db::query_json` 的唯一差别就是「不归一」;SQL 包裹、参数绑定、 /// 错误类型、锁,全部与 `query_json_params` 逐字一致。 pub async fn query_json_raw( &self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result, pglite::Error>; } ``` 实现建议:把 `query_json_inner` 拆成 `query_json_inner_raw`(只持锁 + 包裹 + 反序列化)与 `query_json_inner`(在其结果上再跑 `normalize_json_keys`), 两者共用同一个 `let _guard = self.lock.lock().await`。 **不要复制粘贴一整份 SQL 包裹逻辑** —— 复制必然漂移。 对应的无参便捷方法 `query_json_raw(sql)` 可选(业务仓只有一个 `query_json` 无参入口, 内部转调带参版即可)。 ### R2(必选)新增 `Db::query_rows` —— 持锁 + 原始行 ```rust impl Db { /// 持 `Db.lock`,执行带参查询并返回原始 `pglite::Row`。 /// 用于元数据查询(`pg_catalog`)、取第一行第一列等**不需要 row_to_json** 的场景。 pub async fn query_rows( &self, sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result, pglite::Error>; } ``` `Row` 类型通过 `crates/sspf-store/src/db.rs` 已有的 `pub use pglite` 对外可见; 门面 `crates/sspf/src/lib.rs` 已 `pub use sspf_store::db::pglite` ⇒ 业务仓无需 重复声明 `pglite` 依赖。 ### R3(必选,零新增代码)写路径复用现有 `Db::exec` / `exec_params` 平台已有且**都持锁**: - `exec(sql)`:simple protocol,可多语句、整批一个隐式事务(建表 / 批量 DDL 用); - `exec_params(sql, params)`:extended protocol,单语句(带参 INSERT/UPDATE/DELETE 用)。 需求里明确写一句「业务仓写路径一律改调这两个,不许再直接 `pg.exec(...)`」即可, 平台侧不需要新增方法。 ### R4(推荐,作为 R1/R2 的保守替代)`Db::lock_owned()` 若平台侧不愿在公开签名里出现 `pglite::Row`,可改成暴露一个**所有权 guard**: ```rust impl Db { /// 取得进程级业务锁(与所有 `Db::*` / `DbTransaction` 共用同一把)。 /// 业务仓可在 guard 存活期间用 `Db::pg()` 的裸句柄执行自有 SQL, /// 保持自己的归一语义;guard drop 即释放。 pub async fn lock_owned(&self) -> tokio::sync::OwnedMutexGuard<()> { Arc::clone(&self.lock).lock_owned().await } } ``` - 比 `pub fn lock(&self) -> &Mutex<()>` 安全:不暴露内部可变性,guard 有明确生命周期; - 业务仓写 `let _g = db.lock_owned().await;` 后**函数体一字不改** ⇒ 切换成本最低; - 🔴 文档必须写明纪律:**持 guard 期间不得再调任何 `Db::*` 方法**(tokio Mutex 不可重入 ⇒ 死锁),也不得再 `begin()`。 > 平台侧可 R1+R2 与 R4 **二选一**:给了 R4,业务仓就能用「只加锁」路径完成本题; > 给了 R1+R2,业务仓改用 `Db` 而不是 `PGlite`,封装更好。两者都给也欢迎, > 但**至少要有一个**。 ### R5(必选)`Db::pg()` 注释补一句指路 现有 `pg()` 文档已经写了「绕过 `Db.lock`」,但没写「该怎么办」。补: ``` /// 若业务仓需要与平台共用串行域,请改用 `query_json_raw` / `query_rows` / /// `exec*` / `lock_owned()`;本句柄只适合启动期单线程建表与只读元数据探测。 ``` ### R6(必选)门面导出核对 `crates/sspf/src/lib.rs` 已 `pub use sspf_store::db::Db` 与 `pub use sspf_store::db::pglite`。 新增方法自动可见,**不需要**新增 re-export;但要在门面文档的版本表与 `version_matches_the_manifest` 单测里把 cargo 版本同步为 `0.5.0`。 ### R7(必选)静态闸门 + 集成探针 - 新增静态闸门 **AR20**(编号按实现时的最大编号顺延):钉住 「`query_json_raw` 的实现里**不出现** `normalize_json_keys`」以及 「`query_json` / `query_json_raw` 共用同一个 `lock`」—— 反自证: 把 `normalize_json_keys` 塞进 raw 路径 ⇒ 当场红。 - 新增集成探针 `db_raw_it.rs`(或并入 `db_it.rs`): 1. `query_json_raw("SELECT f_id, f_real_name FROM …")` ⇒ 键仍是 `f_id` / `f_real_name` (**没有**被转成 `id` / `realName`); 2. 同一个 SQL 走 `query_json` ⇒ 键是 `id` / `realName`;两条路径结果**同时成立**; 3. 持 `lock_owned()`(若实现)期间并发跑 `Db::exec` ⇒ 后者被阻塞到 guard 释放 (用 `tokio::time::timeout` 断言,别用 sleep 猜); 4. `query_rows` 能读 `pg_catalog` 原始行。 ### 明确不做 - ❌ 不改 `Db::query_json` / `query_json_params` / `normalize_json_keys` 的任何行为; - ❌ 不把业务仓的 18 实体 `EntitySpec` 化(那是另一条独立改造,见 §8); - ❌ 不引入第二把锁、不在业务仓复制一份归一逻辑; - ❌ 不改面 A / 面 B 任何端点形状、码表、表结构; - ❌ 不给 `Db::pg()` 加隐式锁(会破坏启动期建表与现有探针)。 --- ## 4. 验收判据(平台侧) | # | 判据 | |---|---| | A1 | `cargo test --workspace` 全绿,测试数**不低于**当前基线(v0.4.0 清理后基线见 `HANDOFF.md`,别硬写旧数字 710) | | A2 | `scripts/check-arch.sh` 全绿 + `--self-test` 全绿(含新增 AR20) | | A3 | `scripts/verify.sh --fast` 全绿 | | A4 | 新探针 `db_raw_it` 4 条断言全过(尤其「raw 不归一」与「同一把锁互斥」) | | A5 | `cargo tree -p sspf` 依赖树仍 **0 个 `sspf-pack-*`**(AR17 不回归) | | A6 | `Finish::default()` 路径与 v0.4.0 逐字等价;`Platform::assemble()` / `serve()` 签名未改 | | A7 | 门面 `sspf::VERSION == "0.5.0"`,`crates/sspf/Cargo.toml` 显式 `version = "0.5.0"` | | A8 | `CHANGELOG.md` 追加 5–8 行,只写「改了什么 / 什么影响」,并销掉 v0.3.0 那条「双锁」已知局限 | | A9 | `docs/known-limitations.md` 的「双锁」条改成「已由 v0.5.0 的 raw 入口解决」 | | A10 | `git tag -a v0.5.0` **annotated** 并推远程(`git ls-remote --tags origin` 可见 tag 与 `^{}`) | | A11 | 仓外 git 依赖实测一次:只写 `sspf = { git = "…", tag = "v0.5.0" }` 的空 crate `cargo check` 通过,且能调用 `Db::query_json_raw` / `lock_owned()` | --- ## 5. 业务仓侧切换清单(`tdc-rs`,**等 v0.5.0 到位后由本仓执行**) > 这一节是给平台侧看的「下游会怎么用」,也是业务仓自己的施工单。 1. `Cargo.toml`:`tag = "v0.4.0"` → `tag = "v0.5.0"`(当前业务仓仍锁 `v0.3.0`, 中间跨一个版本,需复核 v0.4.0 的零业务清理对业务仓零影响 —— 已确认: 业务仓从没用过示例包,`cargo tree` 里 0 个 `sspf-pack-*`)。 2. `tests/sspf_platform_package.rs`:版本断言同步。 3. `src/platform/state.rs`:`AppState` 增加 `sspf_db: Option>` (或进程级 `OnceLock>`,与现有 `process_db_lock()` 同款), `AppState::new` 保持签名不变、默认 `None`,加一个 `with_sspf_db()` builder。 4. `src/main.rs`:`boot.state.db.clone()` 注入(`boot.state.db` 是 `Arc`)。 5. `src/platform/db.rs` **6 个函数**内部改为持平台锁 / 调 Raw API,**函数签名保持 `db: &PGlite` 不变** ⇒ 所有调用点零改动: - `query_json_params` → `Db::query_json_raw`(或 `lock_owned()` + 原样 `db.query`); - `exec_params` → **现有 `Db::exec_params`**(或 guard + 原样 `db.query`); - `query_scalar_text` / `column_types` → `Db::query_rows`(或 guard + 原样 `db.query`); - `query_json` → 转调 `query_json_params`; - `ensure_schema` 保持启动期裸句柄(**豁免**,见下)。 6. **保留** tdc 的 `db_lock`:它负责「一次业务操作跨多条 SQL」的原子性 (如 `service/identity.rs` 的「查不到 ⇒ 插入」),与跨平台互斥是两件事。 切换后 `Db.lock` 成为全局串行点,tdc 锁只是业务内部额外一层,无害。 7. **豁免** `src/tdc/schema.rs::ensure_schema_coexist`:只在 `on_ready` 启动期、 平台路由还没开始服务时单线程跑,不存在并发写;继续保持裸 `pg.exec`。 若将来它移到请求期,必须一并改走 `Db::exec`。 8. 静态护栏 `scripts/check-db-access.sh`(**本轮已落地并跑绿**): 把「业务代码不得直接碰裸 `PGlite`」钉死;允许清单 3 个文件 (`platform/db.rs` 封装本身 / `tdc/schema.rs` 启动建表 / `main.rs` 的 `sspf::Db::exec`),当前命中 7 处全在白名单、0 处越界。 ⇒ v0.5.0 到位时切换面确定、可验证,不会有人从别处漏一条 SQL 出去。 ### 业务侧验收(v0.5.0 到位后) - `cargo test` ≥ 294 passed / 0 failed / 1 ignored(当前基线 294); - 五把尺子全绿:smoke **80/80**、`check-contract.sh` **132 条端点一致**、其余三把静态全绿; - `check-dual-contract.sh` **17/17**(含 P3 会话桥断言); - 🔴 **响应形状零漂移**:切前后的 `/api/ssw/tdc/*` 列表 / 详情 / 分页 JSON 键集合 逐字相同(可直接用 smoke 的 `hidden_fields` / numeric 列断言覆盖); - 并发探针:业务侧与面 B 同时写同一库不出现 `database is locked` / 交错读。 --- ## 6. 风险表 | 风险 | 后果 | 缓解 | |---|---|---| | 把 `normalize_json_keys` 塞进 raw 路径 | 业务仓 132 端点响应键漂移 | AR20 反自证 + `db_raw_it` 断言 1&2 | | `lock_owned()` guard 期间再调 `Db::*` | tokio Mutex 不可重入 ⇒ 死锁 | 文档纪律 + 探针用 `timeout` 而非 sleep | | `query_rows` 暴露 `pglite::Row` | 业务仓被迫声明 pglite 依赖 | 门面已 `pub use pglite`,用 `sspf::pglite::Row` 命名 | | 复制一份 SQL 包裹逻辑 | 两份实现漂移 | R1 明确要求拆 `*_inner_raw` 共用 | | 业务仓忘了改某条 SQL | 仍绕过锁 | 业务侧静态护栏(§5.8)+ 五把尺子 | | 版本号与 tag 不一致 | 业务仓 `git + tag` 解析到旧代码 | A7 / A10 / A11 三道核对 | --- ## 7. 发布节奏 1. 平台侧实现 R1–R7,跑完 A1–A9; 2. 打 annotated tag `v0.5.0` 并推远程(A10),跑仓外 git 探针(A11); 3. 通知业务仓;业务仓按 §5 切换,跑完业务侧验收; 4. 两仓各自写工作日志 / `CHANGELOG`,`docs/known-limitations.md` 销条。 > 🔴 `v0.4.0` 已是「零业务清理」版且已推远程(tag 现指向 `ff34ca5`, > 其后含「门面 cargo 版本对齐 0.4.0」与「本需求入库」两个提交),**不要挪动它**; > 实现本需求请直接在这条基线上开 `v0.5.0`,别改 `v0.4.0` 的 tag 或版本号。 --- ## 8. 与「18 实体 EntitySpec 化」的关系 `tdc-rs` 的 18 个实体至今走自研 CRUD 引擎(分档判定 / 状态机 / 聚合详情 / 编码生成 / 隐藏字段),`EntitySpec` 只声明列清单并生成 6 条 CRUD 路由。 **EntitySpec 化是另一条独立改造**,不是本题的前置条件,也不该搭车做: 本题只统一「库操作的锁与入口」,不改任何业务规则、不动 132 条端点。 等本题落地、`Db.lock` 成为唯一串行点之后,再逐实体评估是否迁移更稳妥。 --- ## 9. 事实出处(实现前请自己复核一遍) | 结论 | 出处 | |---|---| | `Db.lock` 私有、所有 `Db::*` 持锁 | `crates/sspf-store/src/db.rs` 的 `pub struct Db` / `query_json_inner` / `exec` / `exec_params` | | `Db::pg()` 明确说「绕过 `Db.lock`」 | 同文件 `Db::pg()` 文档注释 | | `DbTransaction` 也持同一把锁 | 同文件 `pub struct DbTransaction` 的 `_guard` 字段与三条使用纪律 | | 平台归一 `normalize_json_keys` | 同文件 `normalize_json_keys` / `collect_alias_info` / `column_to_json_key` | | 业务仓不归一、mapper 才归一 | `tdc-rs/src/platform/db.rs` 的 `query_json_params`;`tdc-rs/src/tdc/mapper.rs` | | 双锁已知局限 | `CHANGELOG.md` v0.3.0 末条、`docs/known-limitations.md` | | 业务仓库操作单一出口 | `tdc-rs/src/platform/db.rs` 的 5 个 `pub` 函数;启动建表在 `tdc-rs/src/tdc/schema.rs` | | P2 装配 / P3 会话桥 | `tdc-rs/src/main.rs`、`tdc-rs/src/tdc/session_bridge.rs` | --- ## 10. 实施记录(2026-11-04,tag `v0.5.0`) | 需求 | 落地 | 位置 | |---|---|---| | R1 `Db::query_json_raw` | ✅ 持锁 + 包裹 + **不归一**;与 `query_json_params` 共用 `query_json_inner_raw`(SQL 包裹只有一份) | `crates/sspf-store/src/db.rs` | | R2 `Db::query_rows` | ✅ 持锁返回 `Vec`;`pglite::Row` 经 `sspf::pglite` 可见 | 同上 | | R3 写路径复用 | ✅ 文档口径写清(`exec` 多语句 / `exec_params` 单语句,两者都持锁);**零新增代码** | 同上 | | R4 `Db::lock_owned()` | ✅ 返回 `OwnedMutexGuard<()>`,基于 `Arc::clone(&self.lock).lock_owned()`;注释写明「持 guard 期间不许再调 `Db::*`」 | 同上 | | R5 `Db::pg()` 指路 | ✅ 注释补入口对照表(raw / 归一 / 原始行 / 写 / 持锁裸句柄) | 同上 | | R6 门面导出 | ✅ 无需新增 re-export;`crates/sspf/Cargo.toml` 与 `VERSION` 断言同步为 `0.5.0` | `crates/sspf/` | | R7 闸门 + 探针 | ✅ **AR20**(raw 不归一 / 共用段 / 8 个公开入口全持同一把锁)+ 反自证 **15/15**;探针 `db_raw_it.rs` **4/4** | `scripts/check-arch.sh` / `crates/tests/tests/db_raw_it.rs` | **验收对照(§4)**:A1 **653 passed / 0 failed / 8 ignored**(基线 649 + 新增 4 条)· A2 `check-arch` **25/25**、自证 **15/15** · A3 `verify.sh --smoke` **14/14** · A4 `db_raw_it` **4/4** · A5 `cargo tree -p sspf` **0 个 `sspf-pack-*`** · A6 `Finish::default()` 路径未改 · A7 `sspf::VERSION == "0.5.0"` · A8 CHANGELOG 已加并销双锁条 · A9 已知限制 (bq) 已改 · A10 tag 已推 · A11 仓外探针见下。 **A11 仓外探针**:空 crate 只写 `sspf = { git = "...", tag = "v0.5.0" }`, `cargo check` 通过并调用 `Db::query_json_raw` / `Db::lock_owned()`(探针代码见 `HANDOFF.md` §0 的 v0.5.0 段)。 **两条实现纪律(别再踩)** 1. 归一逻辑**只准有一处**(`query_json_inner`),raw 侧共用 `query_json_inner_raw`; 复制 SQL 包裹会让两条路慢慢漂,而漂的方向永远是「raw 也开始归一」。 2. `lock_owned` 的 guard 期间**再调 `Db::*` 必死锁**(tokio Mutex 不可重入)—— 探针用 `timeout` 断言,不用 sleep 猜。 --- ## 11. 业务侧切换记录(`tdc-rs` 提交 `e13768e`,2026-11-04) | 项 | 落地 | |---|---| | 依赖 | `Cargo.toml` 的 `sspf` tag `v0.3.0` → **`v0.5.0`** | | 注入 | `src/platform/db.rs` 新增进程级 `OnceLock>` + `install_sspf_db()`;`main.rs` 在**任何业务 DB 操作之前**注入,失败即 `exit(1)` | | R1 | `query_json_params` → `Db::query_json_raw`(**不归一**;归一仍由 `mapper` 做) | | R2 | `query_scalar_text` / `column_types` → `Db::query_rows` | | R3 | `exec_params` → `Db::exec_params` | | 签名 | 6 个函数仍是 `db: &PGlite` ⇒ `service/*`、`controller/*`、`mapper` **零改动** | | 豁免 | `platform::db::ensure_schema` 与 `tdc/schema.rs::ensure_schema_coexist`(启动期单线程建表) | | 回落 | 未注入(单测 / 集成测试自建 `AppState`)走裸句柄旧路径,行为与 v0.4.0 一致 | **两条新判据(替代「文档承诺」)** 1. `tdc-rs/tests/sspf_db_lock.rs`(真库 2 条):`query_json_params` 出来的键仍是 `f_id` / `f_name`(并显式断言 `get("id").is_none()`);平台 `lock_owned()` 持锁时业务 `exec_params` 在 300ms 内写不进去,解锁后立刻可写且只落 1 行。 2. `tdc-rs/scripts/check-dual-contract.sh` 第 **18** 条:真进程启动日志必须出现 「库操作出口已持平台锁」—— 该行只在 `install_sspf_db` 返回 `true` 时打印。 **业务侧验收**:`cargo test` **296 passed / 0 failed / 1 ignored**;七把尺子全绿 (smoke 80/80、check-contract **132 条端点一致**、双契约 **18/18**、check-db-access 0 处越界、 其余三把静态);`check-citations.py` 仍是既有的 32 条失效(全指向上游 Java/TS 文件),无新增。 > 🔴 切换踩到的唯一坑:**不能图省事改调 `Db::query_json*`(非 raw)** —— 会多一层 > `f_* → camelCase` 归一 + 别名还原,业务侧 `mapper` 再做一次 ⇒ 键二次转换。 > 现由 `tests/sspf_db_lock.rs` 的裸键断言钉住,改错当场红。