diff --git a/docs/SSPF-BUSINESS-DB-ACCESS.md b/docs/SSPF-BUSINESS-DB-ACCESS.md index 3dc5832..4520f8f 100644 --- a/docs/SSPF-BUSINESS-DB-ACCESS.md +++ b/docs/SSPF-BUSINESS-DB-ACCESS.md @@ -71,25 +71,29 @@ mapper 已经做了一次转换。若业务侧直接改调 `Db::query_json_param > 🔴 **因此:禁止用「把业务 SQL 改调现有 `Db::query_json*`」来实现本题。** > 现有 `query_json*` 的归一行为一个字都不许改(面 A / 面 B 契约依赖它)。 -### 2.4 业务仓的库操作已经收在一个文件里 +### 2.4 业务仓的库操作已经收在一个文件里(本轮先做了收拢) -`tdc-rs/src/platform/db.rs` 是唯一出口,5 个 `pub` 函数: +🔴 **调研时发现的坑**:原先 `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` 即可 | -`src/tdc/schema.rs::ensure_schema_coexist` 是另一处直接用裸句柄的地方, -但**只在启动时 `on_ready` 单线程跑**,不参与请求期并发 ⇒ 可以保持现状, -文档 §5 会把它列为豁免。 +另有 2 处**豁免**(护栏白名单,不参与请求期并发): +- `src/tdc/schema.rs::ensure_schema_coexist` —— 启动期 `on_ready` 单线程建表; +- `src/main.rs` 的 `on_ready` —— 调的是 **`sspf::Db::exec`**(本身已持平台锁,不是裸句柄)。 -⇒ 业务侧切换只需改 `platform/db.rs` 的 5 个函数 + 状态里注入 `Arc`; -`mapper.rs` / `service/crud.rs` / `service/account.rs` / `service/identity.rs` / -`controller/health.rs` / `controller/tds_biz.rs` **零改动**。 +⇒ 业务侧切换只需改 `platform/db.rs` 的 6 个函数 + 状态里注入 `Arc`; +`mapper.rs` / `service/*` / `controller/*` **零改动**(它们已经全部走封装)。 --- @@ -245,9 +249,10 @@ impl Db { (或进程级 `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` 5 个函数内部改为持平台锁 / 调 Raw API,**函数签名保持 +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` 保持启动期裸句柄(**豁免**,见下)。 @@ -257,8 +262,10 @@ impl Db { 7. **豁免** `src/tdc/schema.rs::ensure_schema_coexist`:只在 `on_ready` 启动期、 平台路由还没开始服务时单线程跑,不存在并发写;继续保持裸 `pg.exec`。 若将来它移到请求期,必须一并改走 `Db::exec`。 -8. 新增静态护栏(本轮已先行落地):把「业务代码不得直接碰裸 `PGlite`」钉死, - 允许清单只有 `src/platform/db.rs`(封装本身)与 `src/tdc/schema.rs`(启动建表)。 +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 到位后) @@ -292,10 +299,9 @@ impl Db { 3. 通知业务仓;业务仓按 §5 切换,跑完业务侧验收; 4. 两仓各自写工作日志 / `CHANGELOG`,`docs/known-limitations.md` 销条。 -> 🔴 `v0.4.0` 已是「零业务清理」版且已推远程,**不要挪动它**; -> 平台仓工作区当前还有「门面版本 0.3.0 → 0.4.0」的两处未提交改动 -> (`crates/sspf/Cargo.toml` 与 `crates/sspf/src/lib.rs`), -> 实现本需求时请先把它收干净,别和 v0.5.0 的版本号改动混在一起。 +> 🔴 `v0.4.0` 已是「零业务清理」版且已推远程(tag 现指向 `ff34ca5`, +> 其后含「门面 cargo 版本对齐 0.4.0」与「本需求入库」两个提交),**不要挪动它**; +> 实现本需求请直接在这条基线上开 `v0.5.0`,别改 `v0.4.0` 的 tag 或版本号。 ---