diff --git a/.workbuddy/memory/2026-11-04.md b/.workbuddy/memory/2026-11-04.md index 4f89fa3..fab46b1 100644 --- a/.workbuddy/memory/2026-11-04.md +++ b/.workbuddy/memory/2026-11-04.md @@ -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> }`:**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`、`platform/db.rs` 6 个函数改走 +Raw API(保留 tdc `db_lock` 管「一次业务操作跨多条 SQL」的原子性), +再跑一遍 132 端点 / 五把尺子 / 双契约 17/17 的形状零漂移对账。 diff --git a/CLAUDE.md b/CLAUDE.md index c70b8a1..f907508 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` 交给业务仓,但没把 `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`)、 diff --git a/scripts/check-db-access.sh b/scripts/check-db-access.sh new file mode 100644 index 0000000..edcc29f --- /dev/null +++ b/scripts/check-db-access.sh @@ -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 diff --git a/src/platform/db.rs b/src/platform/db.rs index ad61f5f..c323bd2 100644 --- a/src/platform/db.rs +++ b/src/platform/db.rs @@ -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, diff --git a/src/tdc/service/account.rs b/src/tdc/service/account.rs index 0b1c593..09fc652 100644 --- a/src/tdc/service/account.rs +++ b/src/tdc/service/account.rs @@ -452,10 +452,7 @@ pub async fn create( let refs = bind_refs(¶ms); { 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(¶ms); { 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 = vec![operator.to_string(), id.to_string()]; let refs = bind_refs(¶ms); 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(¶ms); { 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(¶ms); { 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 = vec![id.clone(), account.clone(), password_hash, secretkey]; let refs = bind_refs(¶ms); - 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=`)⇒ 管理员具备 `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)))?; } diff --git a/src/tdc/service/crud.rs b/src/tdc/service/crud.rs index 50cd595..0909b77 100644 --- a/src/tdc/service/crud.rs +++ b/src/tdc/service/crud.rs @@ -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(), diff --git a/src/tdc/service/identity.rs b/src/tdc/service/identity.rs index b1850b8..5ac196c 100644 --- a/src/tdc/service/identity.rs +++ b/src/tdc/service/identity.rs @@ -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); // 🔴 插入失败 ⇒ **库里没有身份行** ⇒ 不得回传密钥(否则会打印一个永不生效的凭证),