diff --git a/docs/SSPF-BUSINESS-DB-ACCESS.md b/docs/SSPF-BUSINESS-DB-ACCESS.md index 7a18d10..72b60a5 100644 --- a/docs/SSPF-BUSINESS-DB-ACCESS.md +++ b/docs/SSPF-BUSINESS-DB-ACCESS.md @@ -3,7 +3,7 @@ > 目标 tag:**`v0.5.0`**(`v0.4.0` 已用于「平台包零业务清理」,不能复用) > 提出方:`tdc-rs`(厚业务仓,自带状态类型 / 自带 JSON 归一语义) > 状态:**已实施并发布 → annotated tag `v0.5.0` 已推 `origin`**(实施记录见 §10)。 -> 业务仓本轮只做切换面收拢,不改 `Cargo.toml` 的 tag;切换单见 §5。 +> **业务侧已按 §5 完成切换**(`tdc-rs` 提交 `e13768e`,见 §11);两条附加判据全部落地。 > 前两份需求:`SSPF-PLATFORM-PACKAGE.md`(v0.2.0)、`SSPF-BUSINESS-COMPOSITION.md`(v0.3.0)。 --- @@ -357,3 +357,34 @@ A7 `sspf::VERSION == "0.5.0"` · A8 CHANGELOG 已加并销双锁条 · A9 已知 复制 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` 的裸键断言钉住,改错当场红。