Files
ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md
admin 60af816ded docs(req): 记业务侧 v0.5.0 切换完成(tdc-rs e13768e)
- §11 补切换表、两条新判据、业务侧验收数字
- 状态行改为「业务侧已完成切换」
2026-11-04 23:08:23 +08:00

391 lines
22 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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<PGlite>` 交给了业务仓,但没有把 **`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<PGlite>` + `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<PGlite>`(`Db::pg()`)。因此本题**不是**「再开一个连接」,而是
「同一个连接上,两边的临界区必须互斥」。
### 2.2 平台侧的锁是私有的
`crates/sspf-store/src/db.rs`:
- `Db { pg: Arc<PGlite>, lock: Arc<Mutex<()>> }` —— `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<Db>`;
`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<Vec<Value>, 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<Vec<pglite::Row>, 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<Arc<sspf::Db>>`
(或进程级 `OnceLock<Arc<Db>>`,与现有 `process_db_lock()` 同款),
`AppState::new` 保持签名不变、默认 `None`,加一个 `with_sspf_db()` builder。
4. `src/main.rs`:`boot.state.db.clone()` 注入(`boot.state.db` 是 `Arc<Db>`)。
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>`;`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<Arc<sspf::Db>>` + `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` 的裸键断言钉住,改错当场红。