chore(p4): 收拢库操作到唯一出口,为统一 sspf Db.lock 做准备

- 新增 platform::db::exec_params,收拢业务层 12 处裸 state.db.query
- 新增 check-db-access.sh 护栏:白名单 3 文件,7 处命中 0 越界
- 平台侧需求写入 ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md(目标 v0.5.0)
- Cargo.toml 仍锁 v0.3.0,132 端点契约与响应形状未变
This commit is contained in:
admin committed 2026-11-04 22:20:55 +08:00
1 parent 6a66698607
commit 43dcd3f9eb
7 files changed
+245 -51

No files matched your search

+53
View File
@@ -185,3 +185,56 @@ ssw-platform 侧提交 `9083394`(门面)+ `3d3fd69`(文档/记忆),工
(`menuList` / `userInfo` / `sysConfigInfo` 等),管理员标记按真实 `base_user` 行传。
- 剩余 P3(未做):① 业务 `Db::pg()` 绕过 sspf `Db.lock`,与 tdc `db_lock` 互不覆盖,
并发写同库可能交错;② 18 实体声明式 `EntitySpec` 化(`packs/tdc`)。
## P4 库操作统一到 sspf Db(用户「库操作应该走sspf 实体按你的建议」)
先澄清范围(改动量差一个数量级):用户选了「统一到 sspf `Db`」这一档,**不做 18 实体
`EntitySpec` 化**。三档选项分别是「统一 Db / EntitySpec 化 / 两档都做」。
### 调研核准的硬约束(写进需求前逐条核过)
- `sspf-store/src/db.rs` 的 `Db { pg, lock: Arc<Mutex<()>> }`:**lock 私有**;
`query_json` / `exec` / `exec_params` / `scalar_text` / `ensure_schema` 全部先持 `lock`;
`begin()` 的 `DbTransaction._guard` 也持同一把。`Db::pg()` 文档**明写**「绕过本层 `Db.lock`」。
- 🔴 **两边 JSON 归一是两套**:sspf `Db::query_json` 有 `normalize_json_keys`
(`f_`→camelCase + 还原被 PG 折叠的未加引号别名 + 双引号别名权威);
tdc `platform/db.rs::query_json_params` **完全不归一**,归一在上层 `tdc::mapper`。
⇒ **直接把业务 SQL 换成 `Db::query_json` 会改掉 132 条端点响应形状**,禁止这么干。
- `Db::begin()` + `DbTransaction::query` 确实能拿到「持平台锁 + 原始 Row」,
但会把每个查询包进真实事务(多两次 round-trip、commit 纪律、语义变化)⇒ 只作备选,不采用。
- **`v0.4.0` 已被「平台包零业务清理」占用且已推远程**(`225b838`),db.rs 只改了注释;
平台仓工作区还有「门面版本 0.3.0 → 0.4.0」两处未提交改动 ⇒ 新需求目标改 **`v0.5.0`**。
### 交付一:第三份平台需求(ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md)
R1 `Db::query_json_raw`(持锁 + row_to_json 包裹 + **不归一**)、R2 `Db::query_rows`
(持锁 + 原始 Row,覆盖 `query_scalar_text` / `column_types`)、R3 写路径复用现有
`Db::exec_params`、R4 保守替代 `Db::lock_owned()`(业务仓 `let _g = …await` 后函数体一字不改)、
R5 `pg()` 注释指路、R6 门面版本 0.5.0、R7 新增 AR20 反自证 + `db_raw_it` 探针。
验收 A1–A11(含仓外 git-tag 探针),明确不改现有 `query_json` 归一、不搭车 EntitySpec 化。
### 交付二:tdc-rs 侧同步准备(本轮已落地,可编译可测)
🔴 **调研时推翻了自己的假设**:原以为库操作全收在 `platform/db.rs`,实扫发现
`tdc/service/{crud,account,identity}.rs` 还有 **12 处**直接 `state.db.query(&sql, &refs)`。
- 新增 `platform::db::exec_params(db, sql, params)`(纯转发 `db.query(...).map(|_| ())`),
把 12 处全部收拢;`crud.rs` 3 处单行 + `account.rs` 8 处链式(脚本正则批量替换,
带 `assert 计数` 防误改)+ `identity.rs` 1 处手工改。**函数签名不变、SQL 不变、契约零变化**。
- 新增 `scripts/check-db-access.sh` 附加静态尺子:只扫非测试代码、剥注释,
白名单 3 文件(`platform/db.rs` 封装 / `tdc/schema.rs` 启动建表 / `main.rs` 的
`sspf::Db::exec` 已持锁)。当前 **7 处命中全在白名单、0 处越界**。
⇒ v0.5.0 到位后**只改 `platform/db.rs` 的 6 个函数**,业务层零改动。
- `CLAUDE.md` 同步 P4 待办、目录树、附加尺子;`Cargo.toml` 的 tag **仍锁 `v0.3.0` 未动**。
### 验收(全绿)
`cargo test` **294 passed / 0 failed / 1 ignored**;五把尺子(smoke **80/80**、
check-contract **132 条端点一致**、其余三把静态)全绿;`check-dual-contract.sh` **17/17**;
`check-db-access.sh` **0 处越界**;`cargo check` exit 0。
### 下一步(等平台侧)
平台实现 R1–R7 → 打 annotated tag `v0.5.0` 并推远程 → 业务仓按需求 §5 切换:
`Cargo.toml` tag 升级、`AppState` 注入 `Arc<sspf::Db>`、`platform/db.rs` 6 个函数改走
Raw API(保留 tdc `db_lock` 管「一次业务操作跨多条 SQL」的原子性),
再跑一遍 132 端点 / 五把尺子 / 双契约 17/17 的形状零漂移对账。
+13 -1
View File
@@ -34,6 +34,16 @@ This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Curso
> 换成平台 token。🔴 翻译层**只挂平台 Router**,`Finish.layers` 是全局层会把业务侧的头也改掉 ⇒ 401。
> 映射随 tdc 会话过期 / 吊销一起消失 ⇒ 面 B 不会比业务侧晚失效;对外 `data.token` 仍是 32 位 hex。
> **P4 待办:库操作统一走 sspf 的 `Db`(等平台 `v0.5.0`)**:`Db::pg()` 把同一个
> `Arc<PGlite>` 交给业务仓,但没把 `Db.lock` 交出来 ⇒ 平台侧 SQL 持 `Db.lock`、
> 业务侧 SQL 持 tdc 自己的 `db_lock`,两把锁互不覆盖,并发写同库可能交错。
> 🔴 **不能直接换 `sspf::Db::query_json`**:它会多做一层 `f_`→camelCase 归一和别名还原,
> 而业务仓的归一在上层 mapper ⇒ 换过去会改掉 132 条端点的响应形状。
> 平台需求见 `ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md`(要「持同一把锁、不碰归一」
> 的 Raw API)。本轮已把散在 `service/{crud,account,identity}.rs` 的 **12 处**裸
> `state.db.query(...)` 收进 `platform::db::exec_params`,并用 `check-db-access.sh` 钉死
> ⇒ tag 到位后**只改 `platform/db.rs` 的 6 个函数**,业务层零改动。
> **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制,
> 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。
> 浏览器端 WASM 版(`@electric-sql/pglite` + IndexedDB)曾是本项目的错误实现,已废弃删除,勿再引入。
@@ -51,7 +61,7 @@ tdc-rs/
│ ├── platform/ # 【平台层】与业务**零**知识(边界由 check-boundary.sh 静态钉住)
│ │ ├── state.rs # AppState(config + db + db_lock + sessions)—— **零业务字段**(业务态在 `tdc/state.rs`)
│ │ ├── config.rs # **平台**环境变量配置(端口/数据目录/令牌/出向地址)+ 密钥守卫(**零业务字段**)
│ │ ├── db.rs # PGlite 封装(query_json / ensure_schema / f_↔camelCase 映射)
│ │ ├── db.rs # PGlite 封装(**库操作唯一出口**:query_json / exec_params / query_scalar_text / column_types / ensure_schema)
│ │ ├── session.rs # 会话存储(两种 kind:Identity / Account;Account 行携带镜像的平台 token)
│ │ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data})
│ │ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal)
@@ -85,6 +95,7 @@ tdc-rs/
│ # / check-entity.sh(实体静态)/ check-contract.sh(契约对账)
│ # / check-upstream-tests.sh(**上游测试用例移植台账**对账)
│ # + check-dual-contract.sh(**P2 附加尺子**:双契约 + P3 会话桥,真进程,17 断言)
│ # + check-db-access.sh(**P4 附加静态尺子**:库操作单一出口,0 处越界)
│ # + contract_probe.py(check-contract 的探针)/ check-citations.py(文档引用自检)
│ # + upstream-action-census.py(上游动作端点普查 · 只读上游克隆)
│ # + upstream-test-census.py(**上游测试类普查**)/ upstream-test-ledger.tsv(台账真源)
@@ -195,6 +206,7 @@ python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号`
```bash
bash scripts/check-dual-contract.sh # PASS=17 FAIL=0
bash scripts/check-db-access.sh # 库操作单一出口:7 处命中全在白名单,0 处越界
```
一个进程、一个端口、一个库同时验:业务侧 `/api/health` 裸对象(`tables=30` / `baseTables=3`)、
+135
View File
@@ -0,0 +1,135 @@
#!/usr/bin/env bash
# 库操作**单一出口**静态护栏(附加尺子,不改「五把尺子」编号体系)
#
# 判据:业务代码不许直接碰裸 `PGlite` 句柄(`.query(` / `.exec(` / `.exec_params(`)。
# 所有 SQL 必须经 `src/platform/db.rs` 的封装函数 ⇒ 等 sspf v0.5.0 把
# 「持 Db.lock 的 Raw API」交付后,切换面只有那一个文件,不会漏改。
#
# 允许清单(每一条都写明理由,只许变短不许变长):
# src/platform/db.rs —— 唯一封装出口(query_json / query_json_params /
# exec_params / query_scalar_text / column_types / ensure_schema)
# src/tdc/schema.rs —— 启动期 on_ready 单线程建表,不参与请求期并发
# src/main.rs —— on_ready 里的 sspf::Db::exec(本身已持平台锁)
#
# 扫描口径:只扫非测试代码(第一处 `#[cfg(test)]` 之前)、剥掉注释(文档注释里的
# 「错误示例」不算数)。与 check-boundary.sh 同一套口径。
#
# 用法:bash scripts/check-db-access.sh [--report]
# 退出码:0 绿 / 1 有越界 / 2 前置错误
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
REPORT_ONLY=0
[ "${1:-}" = "--report" ] && REPORT_ONLY=1
[ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ] && { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0; }
PY_BIN="${PY_BIN:-$(command -v python3 2>/dev/null || true)}"
[ -n "${PY_BIN}" ] || { echo "❌ 前置错误:找不到 python3。"; exit 2; }
[ -d "${ROOT}/src" ] || { echo "❌ 前置错误:${ROOT}/src 不存在。"; exit 2; }
"${PY_BIN}" - "${ROOT}" "${REPORT_ONLY}" <<'PYEOF'
import os, re, sys
ROOT = sys.argv[1]
REPORT_ONLY = sys.argv[2] == "1"
ALLOW = {
"src/platform/db.rs": "唯一封装出口(SQL 全在这里)",
"src/tdc/schema.rs": "启动期 on_ready 单线程建表",
"src/main.rs": "on_ready 里的 sspf::Db::exec(已持平台锁)",
}
CALL = re.compile(r"\.(?:query|exec|exec_params)\s*\(")
def strip_comments(src: str) -> str:
"""剥 // 行注释与 /* */ 块注释,保留换行与字符串内容(行号不能漂)。"""
out = []
i, n = 0, len(src)
in_str = in_char = in_line = in_block = False
while i < n:
c = src[i]
nxt = src[i + 1] if i + 1 < n else ""
if in_line:
if c == "\n":
in_line = False
out.append(c)
i += 1
continue
if in_block:
if c == "*" and nxt == "/":
in_block = False
i += 2
continue
out.append(c if c == "\n" else " ")
i += 1
continue
if in_str:
out.append(c)
if c == "\\":
if i + 1 < n:
out.append(src[i + 1]); i += 2; continue
elif c == '"':
in_str = False
i += 1
continue
if in_char:
out.append(c)
if c == "\\":
if i + 1 < n:
out.append(src[i + 1]); i += 2; continue
elif c == "'":
in_char = False
i += 1
continue
if c == "/" and nxt == "/":
in_line = True; i += 2; continue
if c == "/" and nxt == "*":
in_block = True; i += 2; continue
if c == '"':
in_str = True; out.append(c); i += 1; continue
if c == "'":
# 生命周期标记('a)不是字符字面量:只在后面紧跟单个字符 + ' 时才算
if i + 2 < n and (src[i + 2] == "'" or (nxt == "\\" and i + 3 < n)):
in_char = True
out.append(c); i += 1; continue
out.append(c)
i += 1
return "".join(out)
hits, violations = [], []
for dirpath, _dirs, files in os.walk(os.path.join(ROOT, "src")):
for f in sorted(files):
if not f.endswith(".rs"):
continue
path = os.path.join(dirpath, f)
rel = os.path.relpath(path, ROOT).replace(os.sep, "/")
with open(path, encoding="utf-8") as fh:
code = strip_comments(fh.read())
# 只扫生产代码:第一处 #[cfg(test)] 之后不计入
cut = code.find("#[cfg(test)]")
if cut != -1:
code = code[:cut]
for lineno, line in enumerate(code.splitlines(), 1):
if CALL.search(line):
rec = (rel, lineno, line.strip())
hits.append(rec)
if rel not in ALLOW:
violations.append(rec)
print("库操作单一出口自检")
print(" 允许清单(%d):" % len(ALLOW))
for k, why in ALLOW.items():
cnt = sum(1 for r in hits if r[0] == k)
print(" ✅ %-28s %s(命中 %d 处)" % (k, why, cnt))
print(" 裸句柄调用命中:%d 处" % len(hits))
for rel, lineno, text in hits:
flag = "白名单" if rel in ALLOW else "越界"
print(" [%s] %s:%d %s" % (flag, rel, lineno, text[:110]))
if violations:
print("❌ 有 %d 处业务代码直接碰裸 PGlite ⇒ 请改走 platform::db::* 的封装" % len(violations))
sys.exit(0 if REPORT_ONLY else 1)
print("库操作单一出口自检通过 ✅(0 处越界)")
PYEOF
+17
View File
@@ -365,6 +365,23 @@ pub async fn query_json_params(
Ok(out)
}
/// 执行带参数的**写**语句(INSERT / UPDATE / DELETE),丢弃结果集。
///
/// 🔴 **业务层写路径的唯一出口**:此前 `tdc/service/{crud,account,identity}.rs` 有 12 处
/// 直接 `state.db.query(...)`,绕过了本文件 ⇒ 将来把库操作统一切到 sspf 的
/// `Db::exec_params` 时要改 12 处,还容易漏。全部收拢到这里后,
/// **切换面只剩 `platform/db.rs`**(见平台仓 `docs/SSPF-BUSINESS-DB-ACCESS.md`)。
///
/// ⚠️ `pglite::query` 走 extended protocol ⇒ **只能单语句**;多语句请用 `db.exec`
/// (simple protocol,整批一个隐式事务)。
pub async fn exec_params(
db: &PGlite,
sql: &str,
params: &[&(dyn ToSql + Sync)],
) -> Result<(), PgError> {
db.query(sql, params).await.map(|_| ())
}
/// 取第一行第一列的文本值(无行 ⇒ `None`)。
pub async fn query_scalar_text(
db: &PGlite,
+8 -32
View File
@@ -452,10 +452,7 @@ pub async fn create(
let refs = bind_refs(&params);
{
let _g = state.db_lock.lock().await;
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("新建账号失败: {}", e)))?;
}
find(state, &id)
@@ -497,10 +494,7 @@ pub async fn update(
let refs = bind_refs(&params);
{
let _g = state.db_lock.lock().await;
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("更新账号失败: {}", e)))?;
}
let _ = current;
@@ -525,10 +519,7 @@ pub async fn remove(state: &AppState, operator: &str, id: &str) -> Result<(), Ac
let params: Vec<String> = vec![operator.to_string(), id.to_string()];
let refs = bind_refs(&params);
let _g = state.db_lock.lock().await;
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map(|_| ())
.map_err(|e| AccountError::Server(format!("删除账号失败: {}", e)))
}
@@ -558,10 +549,7 @@ pub async fn set_enabled(
let refs = bind_refs(&params);
{
let _g = state.db_lock.lock().await;
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("设置账号状态失败: {}", e)))?;
}
let _ = current;
@@ -598,10 +586,7 @@ pub async fn reset_password(
let refs = bind_refs(&params);
{
let _g = state.db_lock.lock().await;
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("重设口令失败: {}", e)))?;
}
find(state, id)
@@ -658,10 +643,7 @@ pub async fn bootstrap_account_layer(
.iter()
.map(|s| s as &(dyn pglite::ToSql + Sync))
.collect();
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("种角色 {} 失败: {}", en_code, e)))?;
}
@@ -699,10 +681,7 @@ pub async fn bootstrap_account_layer(
);
let params: Vec<String> = vec![id.clone(), account.clone(), password_hash, secretkey];
let refs = bind_refs(&params);
state
.db
.query(&sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
.map_err(|e| AccountError::Server(format!("引导管理员账号失败: {}", e)))?;
// ④ 绑定角色(`f_object_type='user'` + `f_object_id=<admin f_id>`)⇒ 管理员具备 `user` 角色码。
@@ -731,10 +710,7 @@ pub async fn bootstrap_account_layer(
.iter()
.map(|s| s as &(dyn pglite::ToSql + Sync))
.collect();
state
.db
.query(&rel_sql, &refs)
.await
crate::platform::db::exec_params(&state.db, &rel_sql, &refs).await
.map_err(|e| AccountError::Server(format!("绑定管理员角色失败: {}", e)))?;
}
+3 -3
View File
@@ -650,7 +650,7 @@ pub async fn create(
let refs = bind_refs(&binds);
let res = {
let _g = state.db_lock.lock().await;
state.db.query(&sql, &refs).await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
};
match res {
Ok(_) => ActionResult::ok_msg("新增成功", id).into_response(),
@@ -751,7 +751,7 @@ pub async fn update(
let refs = bind_refs(&binds);
let res = {
let _g = state.db_lock.lock().await;
state.db.query(&sql, &refs).await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
};
match res {
Ok(_) => ActionResult::ok_msg("修改成功", id.to_string()).into_response(),
@@ -807,7 +807,7 @@ pub async fn delete(
let refs = bind_refs(&binds);
let res = {
let _g = state.db_lock.lock().await;
state.db.query(&sql, &refs).await
crate::platform::db::exec_params(&state.db, &sql, &refs).await
};
match res {
Ok(_) => ActionResult::ok_msg("删除成功", id.to_string()).into_response(),
+16 -15
View File
@@ -144,21 +144,22 @@ pub async fn bootstrap_identity(state: &AppState, tdc_config: &TdcConfig) -> Boo
CAST('REGISTERED' AS character varying), 1, now(), CAST($6 AS character varying), \
now(), CAST($7 AS character varying))";
let creator = "SYSTEM".to_string();
if let Err(e) = state
.db
.query(
insert,
&[
&identity_id,
&identity_code,
&identity_name,
&identity_name,
&secret,
&creator,
&creator,
],
)
.await
// 🔴 写路径统一走 `platform::db::exec_params`(与其它 11 处同一出口),
// 将来切到 sspf `Db::exec_params` 时只改那一个函数。
if let Err(e) = crate::platform::db::exec_params(
&state.db,
insert,
&[
&identity_id,
&identity_code,
&identity_name,
&identity_name,
&secret,
&creator,
&creator,
],
)
.await
{
eprintln!("[tdc-connector] 引导本地身份失败: {}", e);
// 🔴 插入失败 ⇒ **库里没有身份行** ⇒ 不得回传密钥(否则会打印一个永不生效的凭证),