From e13768edd50eb38c4dd27bba48f26c4f33a2a398 Mon Sep 17 00:00:00 2001 From: admin Date: Wed, 4 Nov 2026 23:08:08 +0800 Subject: [PATCH] =?UTF-8?q?feat(p5):=20=E4=B8=9A=E5=8A=A1=E5=BA=93?= =?UTF-8?q?=E6=93=8D=E4=BD=9C=E6=94=B9=E8=B5=B0=20sspf=20Db=EF=BC=8C?= =?UTF-8?q?=E4=B8=8E=E5=B9=B3=E5=8F=B0=E5=85=B1=E7=94=A8=E5=90=8C=E4=B8=80?= =?UTF-8?q?=E6=8A=8A=E9=94=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Cargo.toml 升到 sspf v0.5.0;platform/db.rs 注入进程级 Arc - query_json_params→query_json_raw(不归一)/ exec_params / query_scalar_text+column_types→query_rows - 函数签名仍 db: &PGlite,service/* 与 controller/* 零改动;ensure_schema 启动期豁免 - main.rs 在任何业务 DB 操作前注入,失败即退出(不接受静默双锁) - 新增 tests/sspf_db_lock.rs:真库验不归一 + 平台持锁时业务写排队 - 双契约尺子 17→18 断言(启动日志自证锁已接入) - sspf_platform_package 的版本断言改为从 Cargo.toml 读 tag 对账,升级不再手改 - cargo test 296 passed / 0 failed / 1 ignored;七把尺子全绿 --- .workbuddy/memory/2026-11-04.md | 49 ++++++++++++++ CLAUDE.md | 40 ++++++----- Cargo.lock | 38 +++++------ Cargo.toml | 4 +- scripts/check-dual-contract.sh | 15 +++++ src/main.rs | 18 +++++ src/platform/db.rs | 69 ++++++++++++++++++- src/platform/state.rs | 7 +- tests/sspf_db_lock.rs | 115 ++++++++++++++++++++++++++++++++ tests/sspf_platform_package.rs | 24 ++++++- 10 files changed, 340 insertions(+), 39 deletions(-) create mode 100644 tests/sspf_db_lock.rs diff --git a/.workbuddy/memory/2026-11-04.md b/.workbuddy/memory/2026-11-04.md index fab46b1..57c159d 100644 --- a/.workbuddy/memory/2026-11-04.md +++ b/.workbuddy/memory/2026-11-04.md @@ -238,3 +238,52 @@ check-contract **132 条端点一致**、其余三把静态)全绿;`check-du `Cargo.toml` tag 升级、`AppState` 注入 `Arc`、`platform/db.rs` 6 个函数改走 Raw API(保留 tdc `db_lock` 管「一次业务操作跨多条 SQL」的原子性), 再跑一遍 132 端点 / 五把尺子 / 双契约 17/17 的形状零漂移对账。 + +--- + +## P5:业务库操作与平台共用同一把 `Db.lock`(sspf `v0.5.0` 已到位) + +### 平台侧交付核对(`509c6b1`,annotated tag `v0.5.0` 已推 origin) + +`Db` 新增三个入口,与需求 R1–R7 逐条对齐:`query_json_raw`(持锁 + `row_to_json` 包裹 + +**不归一**)、`query_rows`(持锁返回原始 `pglite::Row`)、`lock_owned()`(`OwnedMutexGuard`)。 +`exec_params` / `exec` 本来持锁,写路径无需新增代码。门面 `VERSION` 断言同步 `0.5.0`。 + +### 业务侧切换(`Cargo.toml` tag `v0.3.0` → `v0.5.0`) + +- `platform/db.rs` 新增进程级 `OnceLock>` + `install_sspf_db()` / `sspf_db()`: + 与 `process_db_lock()` 同款形状,**函数签名 `db: &PGlite` 不变** ⇒ `service/*`、 + `controller/*`、`mapper` 全部零改动。 +- 4 个查询/写函数切到持锁入口;`query_json_params` 调 `query_json_raw`(**不是** + `query_json*`,否则多一层 `f_`→camelCase 归一,132 条端点形状全漂)。 +- `ensure_schema` 豁免(启动期单线程建表,多语句只能走 simple protocol 的 `exec`)。 +- 未注入时(单测 / 集成测试自建 `AppState`)回落裸句柄旧路径,行为与 v0.4.0 一致。 +- `main.rs` 在**任何业务 DB 操作之前**注入;失败即 `exit(1)`(双锁是静默劣化,不接受)。 + +### 两条新增判据(不靠文档承诺) + +1. `tests/sspf_db_lock.rs`(真库 2 条): + - `query_json_params` 出来的键仍是 `f_id` / `f_name`(**raw 不归一**,断言里显式写 + `rows[0].get("id").is_none()`); + - 平台 `lock_owned()` 持锁时,业务 `exec_params` 在 300ms 内**写不进去**(超时即排队 + 正确);解锁后立刻可写且只落 1 行(被取消的那次没生效)。 +2. `check-dual-contract.sh` 第 18 条:真进程启动日志必须出现「库操作出口已持平台锁」。 + 该行只在 `install_sspf_db` 返回 `true` 时打印 ⇒ 装配链是否真的接上,端到端可验。 + +### 顺手修的一个过期断言 + +`tests/sspf_platform_package.rs` 原来硬编码 `assert_eq!(sspf::VERSION, "0.3.0")`,升 tag 必红。 +改成从本仓 `Cargo.toml` 读 `sspf` 的 `tag =` 值,与 `sspf::VERSION` 对账 +⇒ tag ↔ 门面版本只有一处真相,以后升级不用手改两处。 + +### 验收(全绿) + +`cargo test` **296 passed / 0 failed / 1 ignored**(P3 294 + 新增 2 条单锁探针); +七把尺子全绿:smoke **80/80**、check-contract **132 条端点一致**、双契约 **18/18**、 +`check-db-access` **0 处越界**、其余三把静态通过。 + +### 仍未做(不在本轮范围) + +18 实体声明式 `EntitySpec` 化(`packs/tdc`):`EntitySpec` 只声明列清单 + 生成 6 条 CRUD 路由, +承载不了 tdc 的分档判定 / 状态机 / 聚合详情 ⇒ 属独立重写级改造。 +`state.db_lock` 在生产路径已无消费者,但仍是测试的串行化手段,暂留。 diff --git a/CLAUDE.md b/CLAUDE.md index f907508..5ae392c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ This file provides guidance to AI coding agents (CodeBuddy / Claude Code / Curso | 层 | 技术栈 | 职责 | |---|---|---| -| 平台底座 | **`sspf` v0.3.0**(`ssw-platform` 发布的标准平台包,git tag 锁版本) | **单进程 / 单库 / 单端口**:开唯一的 PGlite 实例、建平台 `base_*` 表、提供面 B(JNPF 兼容)全套端点。`Cargo.toml` 里只认这一个依赖 | +| 平台底座 | **`sspf` v0.5.0**(`ssw-platform` 发布的标准平台包,git tag 锁版本) | **单进程 / 单库 / 单端口 / 单锁**:开唯一的 PGlite 实例、建平台 `base_*` 表、提供面 B(JNPF 兼容)全套端点。`Cargo.toml` 里只认这一个依赖 | | 后端 | Rust 2021 + axum 0.8 + tokio(**业务层**) | 鉴权 / 会话 / 18 实体 CRUD / 聚合详情 / 账号层 / 静态托管;由 `sspf::Platform` **两阶段装配**(`assemble()` → 引导业务状态 → `finish()`) | | 数据库 | `pglite-rs` 0.2(进程内原生 PostgreSQL,**平台与业务共用同一个实例**) | 平台 `base_*` 表(百余张)+ `tdc_*` 业务表(**30 张**);`migrate.sql` 声明的 3 张账号层表由平台代建,数据落盘 `data/tdc.pg/` | | 前端 | **上游(Java/Vue)完整前端的构建产物**,托管在 `static/` | **零自研前端、零构建步骤**(`scripts/build-frontend.sh` 可重放) | @@ -34,15 +34,19 @@ 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 个函数**,业务层零改动。 +> **P5 单锁(`sspf v0.5.0`,已完成)**:此前平台侧 SQL 持 `sspf::Db.lock`、业务侧 SQL 持 +> tdc 自己的 `db_lock`,**两把锁互不覆盖** ⇒ 共库并发写可能交错。 +> `v0.5.0` 交付三个「持 `Db.lock`」的入口(`query_json_raw` 不归一 / `query_rows` 原始行 / +> `exec_params`),业务侧把 `src/platform/db.rs` 的 6 个函数切过去,平台句柄经 +> `platform::db::install_sspf_db(boot.state.db.clone())` 注入进程级 `OnceLock` +> ⇒ **业务与平台共用同一把锁**,函数签名仍是 `db: &PGlite`,`service/*` 与 `controller/*` 零改动。 +> 🔴 **绝不能改调 `Db::query_json*`(非 raw)**:那会多做一层 `f_`→camelCase 归一 + 别名还原, +> 而业务仓的归一在上层 `mapper` ⇒ 会改掉 132 条端点的响应形状。归一只能有一处。 +> 🔴 `ensure_schema` 与 `tdc/schema.rs::ensure_schema_coexist` **豁免**(启动期单线程建表, +> 不参与请求期并发)。`state.db_lock` 在**生产路径已无消费者**(测试仍用它串行化裸句柄), +> 留着是因为它同时是「进程级单锁」的语义占位。 +> 验收:`tests/sspf_db_lock.rs` 真库验「不归一 + 平台持锁时业务写排队」,`check-dual-contract.sh` +> 第 18 条断言靠启动日志自证 `install_sspf_db` 真的成功。 > **pglite-rs ≠ 浏览器 PGlite**。crate 名 `pglite-rs`、import 名 `pglite`;它把 postgres-pglite 编译成原生静态库链接进二进制, > 是**真实 PostgreSQL 语义**(类型 / MVCC / 事务 / 扩展 / 线协议),进程内单 backend,**无服务器、无 Docker、无 WASM**。 @@ -61,7 +65,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 / exec_params / query_scalar_text / column_types / ensure_schema) +│ │ ├── db.rs # PGlite 封装 + **库操作唯一出口**(query_json / query_json_params / exec_params / query_scalar_text / column_types / ensure_schema);P5 起 6 个函数全部切到 `sspf::Db` 的持锁入口 │ │ ├── session.rs # 会话存储(两种 kind:Identity / Account;Account 行携带镜像的平台 token) │ │ ├── envelope.rs # 业务信封 ActionResult(HTTP 200 + {code,msg,data}) │ │ ├── auth.rs # 入向鉴权中间件 + 三道门 + 主体(Principal) @@ -94,13 +98,13 @@ tdc-rs/ │ # + **五把尺子**:smoke.sh(HTTP 契约)/ check-boundary.sh(边界静态) │ # / check-entity.sh(实体静态)/ check-contract.sh(契约对账) │ # / check-upstream-tests.sh(**上游测试用例移植台账**对账) -│ # + check-dual-contract.sh(**P2 附加尺子**:双契约 + P3 会话桥,真进程,17 断言) +│ # + check-dual-contract.sh(**P2 附加尺子**:双契约 + P3 会话桥 + P5 单锁,真进程,18 断言) │ # + 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(台账真源) │ # + boundary-ledger.txt / upstream-json-ignore.tsv -├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_model / spa_fallback / bootstrap_fail / tds_biz) +├── tests/ # 集成测试(account_api / api_smoke / auth_flow / crud_engine / permission_model / spa_fallback / bootstrap_fail / tds_biz / sspf_platform_package / **sspf_db_lock**) │ # + upstream_guard_parity.rs / upstream_tds_timeout_parity.rs(**上游用例移植** · 29 条) ├── docs/ # **契约四件套**(B5):contract.md(唯一真源)/ decisions.md / known-limitations.md / runbook.md │ # + ACCOUNT-LAYER.md(账号层契约) @@ -205,7 +209,7 @@ python3 scripts/check-citations.py # 附:文档引用自检(`文件:行号` **P2 附加尺子**(不改「五把尺子」编号体系,因为它验的是**平台包装配链**,必须起真二进制): ```bash -bash scripts/check-dual-contract.sh # PASS=17 FAIL=0 +bash scripts/check-dual-contract.sh # PASS=18 FAIL=0 bash scripts/check-db-access.sh # 库操作单一出口:7 处命中全在白名单,0 处越界 ``` @@ -213,7 +217,8 @@ bash scripts/check-db-access.sh # 库操作单一出口:7 处命中全 面 B 独有 `/api/oauth/getLoginConfig` 与 `/api/app/Menu` 返回平台信封、6 条撞车路径里 `/api/oauth/Login` 由业务侧胜出、SPA 深链回退 200;**P3 会话桥**另验登录 token 仍是 32 位 hex、 面 A / 面 B `CurrentUser` 认同一个 token(200 + `userAccount` / `isAdministrator`)、 -无 token 仍返 602、业务受保护端点仍返 200。 +无 token 仍返 602、业务受保护端点仍返 200;**P5 单锁**验启动日志自报 +「库操作出口已持平台锁」(只有 `install_sspf_db` 返回 true 才打印)。 🔴 `baseTables` 口径是「`migrate.sql` 声明的 3 张表」,不是全库 `base_*` 计数 —— 共库后平台自带 120+ 张,按全库数会让契约从 3 漂到 123。 @@ -332,7 +337,10 @@ bash scripts/check-db-access.sh # 库操作单一出口:7 处命中全 1. **查询结果序列化**:任意 SELECT 用 `SELECT row_to_json(q)::text AS _row FROM () q` 包成单列文本, 后端 `rows[i].get::>(0)` 取文本后 `serde_json::from_str` 得标准 JSON。 **这是规避逐列类型映射的关键手法**,新增查询一律沿用 `query_json()`,不要另起逐类型分支。 -2. **单 backend 串行化**:pglite 是单 in-process backend,所有 DB 访问必须持 `state.db_lock`(`tokio::Mutex`)。 +2. **单 backend 串行化**:pglite 是单 in-process backend,一次业务操作要跨多条 SQL 时必须与平台互斥。 + 🔴 **P5 起的正确做法**:业务 SQL 一律经 `src/platform/db.rs`(内部调 `sspf::Db` 的持锁入口); + `state.db_lock`(`tokio::Mutex`)只在测试里用来串行化裸句柄,生产路径已无消费者。 + 直接拿 `state.db.pg()` 跑请求期 SQL = 绕过 `Db.lock` ⇒ 会被 `check-db-access.sh` 抓红。 3. **表名白名单**:`valid_table()` 只允许 `[A-Za-z][A-Za-z0-9_]*`,任何拼接表名的地方都要走它; `entity::validate()` 在**启动时**自检全部拼进 SQL 的标识符(不过白名单 ⇒ 秒退)。 4. **路径与 cwd 解耦**:`resolve_project_dir()` 从可执行文件向上找含 `static/index.html` 的目录, diff --git a/Cargo.lock b/Cargo.lock index 0b7956e..6720c56 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1426,8 +1426,8 @@ dependencies = [ [[package]] name = "sspf" -version = "0.3.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +version = "0.5.0" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "libc", @@ -1444,7 +1444,7 @@ dependencies = [ [[package]] name = "sspf-compat-core" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "serde", @@ -1456,7 +1456,7 @@ dependencies = [ [[package]] name = "sspf-compat-ext" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "chrono", @@ -1472,7 +1472,7 @@ dependencies = [ [[package]] name = "sspf-compat-msg" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "chrono", @@ -1486,7 +1486,7 @@ dependencies = [ [[package]] name = "sspf-compat-onlinedev" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "serde", @@ -1499,7 +1499,7 @@ dependencies = [ [[package]] name = "sspf-compat-permission" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "chrono", @@ -1515,7 +1515,7 @@ dependencies = [ [[package]] name = "sspf-compat-system" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "chrono", @@ -1530,7 +1530,7 @@ dependencies = [ [[package]] name = "sspf-compat-workflow" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "aes", "axum", @@ -1547,7 +1547,7 @@ dependencies = [ [[package]] name = "sspf-contract" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "http", "serde", @@ -1558,7 +1558,7 @@ dependencies = [ [[package]] name = "sspf-core" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "aes", "axum", @@ -1579,7 +1579,7 @@ dependencies = [ [[package]] name = "sspf-lowcode" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "serde", "serde_json", @@ -1589,7 +1589,7 @@ dependencies = [ [[package]] name = "sspf-lowcode-exec" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "chrono", "pglite-rs", @@ -1603,7 +1603,7 @@ dependencies = [ [[package]] name = "sspf-mcp" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "serde", "serde_json", @@ -1614,7 +1614,7 @@ dependencies = [ [[package]] name = "sspf-mcp-adapter" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "axum", "pglite-rs", @@ -1633,7 +1633,7 @@ dependencies = [ [[package]] name = "sspf-plugin" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "serde", "serde_json", @@ -1644,7 +1644,7 @@ dependencies = [ [[package]] name = "sspf-sdk" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "sspf-contract", ] @@ -1652,7 +1652,7 @@ dependencies = [ [[package]] name = "sspf-store" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "chrono", "pglite-rs", @@ -1664,7 +1664,7 @@ dependencies = [ [[package]] name = "ssw-platform" version = "0.1.0" -source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.3.0#ca8abf9cc9c47fe8d329626f6fa4b406a1cd4b21" +source = "git+http://127.0.0.1:13300/ssw/ssw-platform.git?tag=v0.5.0#509c6b1d1fe76809c805c7e5c46a7d29a58420a6" dependencies = [ "aes", "axum", diff --git a/Cargo.toml b/Cargo.toml index a1d73f1..329a665 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,7 +11,9 @@ path = "src/main.rs" [dependencies] # 🔴 sspf 标准平台包(JNPF 兼容底座)—— 业务仓唯一的平台依赖,按 tag 锁版本。 # 开发期调试可临时换 path = "../ssw-platform/crates/sspf";交付一律用 git tag。 -sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.3.0" } +# 🔴 v0.5.0 起业务库操作与平台共用同一把 `Db.lock`(`query_json_raw` / `query_rows` / +# `exec_params`),见 `src/platform/db.rs`。 +sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" } # Web 框架 / 运行时 axum = "0.8" diff --git a/scripts/check-dual-contract.sh b/scripts/check-dual-contract.sh index bd3aa54..6872cab 100755 --- a/scripts/check-dual-contract.sh +++ b/scripts/check-dual-contract.sh @@ -152,6 +152,21 @@ BIZ_CODE="$(curl -s --noproxy '*' --max-time 10 -o /dev/null -w '%{http_code}' \ -H "Authorization: bearer ${TOKEN}" "${B}/api/ssw/tdc/Identity")" check "业务受保护端点仍认 tdc token ⇒ HTTP 200" "200" "${BIZ_CODE}" +echo "── P5 单锁:业务库操作持的是平台那把锁 ────────────" +# 🔴 真进程自证:`main.rs` 只有在 `install_sspf_db()` 返回 true 时才打印这行。 +# 日志在 ⇒ 业务 SQL 与平台共用同一把 `sspf::Db.lock`(不再是 tdc 自己的 `db_lock`)。 +if [ -n "${PID}" ]; then + if grep -q '库操作出口已持平台锁' "${TMP}/server.log"; then + echo " ✅ 启动日志自报「库操作出口已持平台锁」⇒ 单进程单锁" + PASS=$((PASS + 1)) + else + echo " ❌ 启动日志里没有「库操作出口已持平台锁」⇒ main 未成功注入平台 Db" + FAIL=$((FAIL + 1)) + fi +else + echo " … 外部实例(B 外部指定)⇒ 跳过启动日志断言" +fi + echo "── 兜底 ──────────────────────────────────────────" SPA="$(curl -s --noproxy '*' --max-time 10 -o /dev/null -w '%{http_code}' "${B}/tdc/Product")" check "SPA 深链回退 ⇒ 200" "200" "${SPA}" diff --git a/src/main.rs b/src/main.rs index ba5af6f..3d6c58b 100644 --- a/src/main.rs +++ b/src/main.rs @@ -14,6 +14,10 @@ //! `lite-*` 会话;平台 Router 上的翻译层把 `Authorization` 换成平台 token ⇒ //! JNPF 官方前端拿同一个 token 能访问面 B 的 `CurrentUser`。映射挂在 tdc 会话行上, //! 业务登出 / 30 分钟过期后面 B 同步失效(`src/tdc/session_bridge.rs`)。 +//! - **P5 单锁**:`install_sspf_db(boot.state.db.clone())` 把平台 `Db` 句柄注入 +//! `platform::db` 的进程级 `OnceLock` ⇒ 业务 SQL 与平台 SQL 共用**同一把** +//! `sspf::Db.lock`(此前是「平台 `Db.lock` + 业务 `db_lock`」两把锁互不覆盖)。 +//! 注入失败即退出:退化成双锁属于静默劣化,不允许。 //! //! 对应 ssw-mvp 中 `boot/ssw-tdc` 子系统,但去除了 JNPF/Spring 重底座与隐私计算作业 //! (Nax/Tee/Sandbox 等依赖 Nax 引擎与 scard TEE,本地不可行,列为 MVP 外)。 @@ -141,6 +145,20 @@ async fn main() { // 不能另开 `PGlite::open()` / `Db::open_temp()`。 // ⚠️ 全进程只造**一个** tdc 状态(两个状态意味着两把 db_lock ⇒ 序列化前提被破坏)。 let pg = boot.state.db.pg(); + // 🔴 **P5:把平台 `Db` 句柄注入业务库操作出口**(`src/platform/db.rs`)。 + // 注入后业务 SQL 与平台共用**同一把 `sspf::Db.lock`** ⇒ 真正的单进程单锁; + // 未注入时退化成「业务持 `db_lock`、平台持 `Db.lock`」的双锁(v0.4.0 行为)。 + // 必须在下面任何业务 DB 操作(引导身份 / 账号层)之前完成。 + if !tdc_connector::platform::db::install_sspf_db(boot.state.db.clone()) { + eprintln!("[tdc-connector] 平台 Db 句柄注入失败:本进程已注入过另一个句柄"); + std::process::exit(1); + } + // 🔴 这行是 `check-dual-contract.sh` 的端到端判据:只有 `install_sspf_db` 真的 + // 返回 true 才会打印 ⇒ 「业务库操作已持平台锁」不靠文档承诺,靠启动日志自证。 + println!( + "[tdc-connector] 库操作出口已持平台锁(sspf::Db v{},与平台共用 Db.lock)", + sspf::VERSION + ); // 🔴 **P3 会话桥**:拿平台那张会话表的**同一个 Arc**(绝不是新建一张)。 // 平台自己的 `/api/oauth/Login` 被业务侧接管 ⇒ 只有业务登录才会往里签会话。 let platform_sessions = boot.state.sessions.clone(); diff --git a/src/platform/db.rs b/src/platform/db.rs index c323bd2..3b1c89e 100644 --- a/src/platform/db.rs +++ b/src/platform/db.rs @@ -5,12 +5,53 @@ //! 再反序列化为标准 JSON —— 规避逐列类型映射。 //! - 表名一律走 `valid_table()` 白名单。 //! - 绑定参数一律按 text 传;类型转换由 SQL 里的 `CAST` 负责(见设计文档「关键事实 E」)。 +//! +//! ## 🔴 P5:本文件是业务仓「库操作」的**唯一出口**,且与平台共用**同一把锁** +//! +//! tdc 原来自己持 `state.db_lock`(`src/platform/state.rs::process_db_lock`), +//! 而平台侧持 `sspf::Db.lock` —— **两把锁互不覆盖**,同一进程里并发写同一个库 +//! 仍可能交错(`sspf docs/known-limitations.md` 的「双锁」条)。 +//! +//! sspf `v0.5.0` 交付了三个「持 `Db.lock`」的入口,本文件把 6 个函数切过去: +//! +//! | 本文件函数 | 切换后调 | +//! |---|---| +//! | `query_json` / `query_json_params` | [`sspf::Db::query_json_raw`](**不归一**,归一仍由业务 `mapper` 做) | +//! | `exec_params` | [`sspf::Db::exec_params`] | +//! | `query_scalar_text` / `column_types` | [`sspf::Db::query_rows`](原始行) | +//! | `ensure_schema` | **豁免**:启动期单线程建表,继续用裸句柄 | +//! +//! 🔴 **绝不能改调 `Db::query_json*`(非 raw)**:那会多做一层 `f_* → camelCase` +//! 归一,而业务侧 `mapper` 已经做了一次 ⇒ 键会二次转换,132 条端点的响应形状全漂。 +//! +//! 🔴 函数签名保持 `db: &PGlite` 不变 ⇒ 所有调用点(`service/*`、`controller/*`、 +//! `mapper`)**零改动**;平台句柄经 [`install_sspf_db`] 注入到进程级 `OnceLock`。 +//! 未注入时(单测 / 集成测试自建 `AppState`)回落到裸句柄旧路径,行为与 v0.4.0 一致。 use std::collections::HashMap; +use std::sync::{Arc, OnceLock}; use pglite::{Error as PgError, PGlite, ToSql}; use serde_json::Value; +/// 进程级唯一的平台 `Db` 句柄(与 `process_db_lock` 同款 `OnceLock` 形状)。 +/// +/// 🔴 只允许注入一次(`pglite-rs` 每进程只允许一个 `PGlite` ⇒ 也就只有一个 `Db`)。 +static SSPF_DB: OnceLock> = OnceLock::new(); + +/// 注入平台 `Db` 句柄(`main.rs` 在装配完平台后调用,**必须先于任何业务 DB 操作**)。 +/// +/// 返回 `true` 表示本次注入生效;`false` 表示此前已注入过(重复调用是幂等的, +/// 进程里只可能有一个 `PGlite`,第二次的句柄必然不是「另一个库」)。 +pub fn install_sspf_db(db: Arc) -> bool { + SSPF_DB.set(db).is_ok() +} + +/// 已注入的平台句柄;未注入 ⇒ `None`(单测 / 集成测试走裸句柄回落)。 +pub fn sspf_db() -> Option<&'static Arc> { + SSPF_DB.get() +} + /// 首次初始化执行的 schema(上游 82 个迁移的生成产物:30 张 tdc_* 表) /// /// 🔴 文件在 `schema/`,**不在 `static/`(web root)** —— 编译期 `include_str!` 内嵌进二进制, @@ -317,6 +358,10 @@ pub fn json_key_to_column(key: &str) -> String { /// 旧口径是「**某张业务表**在 ⇒ 跳过」;新口径是「**public 下有表** ⇒ 跳过」。 /// 两者在「本仓自己建的库」上等价;差别只在**半初始化**的库上 /// (旧口径会去跑 `migrate.sql` 然后撞「表已存在」;新口径直接跳过)。 +/// +/// 🔴 **P5 豁免**:本函数只在启动期单线程跑(`on_ready` 之前 / 集成测试建库), +/// 不存在请求期并发 ⇒ 建表循环继续用裸句柄(多语句只能走 simple protocol 的 `exec`)。 +/// 若将来把它挪到请求期,必须改走 [`sspf::Db::exec`]。 pub async fn ensure_schema(db: &PGlite) -> Result<(), PgError> { let table_count = query_scalar_text( db, @@ -345,6 +390,12 @@ pub async fn query_json_params( sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result, PgError> { + // 🔴 P5:已注入平台句柄 ⇒ 走 `Db::query_json_raw`(持 `Db.lock` + `row_to_json` + // 包裹 + **不归一**)。包裹与反序列化由平台侧做,语义与下面这段回落实现逐字一致 + // (同一个 `SELECT row_to_json(q)::text AS _row FROM (...) AS q` 外壳)。 + if let Some(pdb) = sspf_db() { + return pdb.query_json_raw(sql, params).await; + } let trimmed = sql.trim_end_matches(';').trim(); let wrapped = format!( "SELECT row_to_json(q)::text AS _row FROM ({}) AS q", @@ -379,6 +430,10 @@ pub async fn exec_params( sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result<(), PgError> { + // 🔴 P5:写路径同样持平台锁 ⇒ 「一次业务操作跨多条 SQL」的串行化由 `Db.lock` 统一保证。 + if let Some(pdb) = sspf_db() { + return pdb.exec_params(sql, params).await; + } db.query(sql, params).await.map(|_| ()) } @@ -388,6 +443,14 @@ pub async fn query_scalar_text( sql: &str, params: &[&(dyn ToSql + Sync)], ) -> Result, PgError> { + // 🔴 P5:`Db::query_rows` 持锁返回原始行;取列的方式与下面回落实现一致。 + if let Some(pdb) = sspf_db() { + let rows = pdb.query_rows(sql, params).await?; + let Some(row) = rows.first() else { + return Ok(None); + }; + return row.get::>(0); + } let rows = db.query(sql, params).await?; if rows.is_empty() { return Ok(None); @@ -412,7 +475,11 @@ pub async fn column_types(db: &PGlite, table: &str) -> Result 0 AND NOT a.attisdropped", tbl ); - let rows = db.query(&sql, &[]).await?; + // 🔴 P5:元数据查询走 `Db::query_rows`(持锁 + 原始行,不做 `row_to_json`)。 + let rows = match sspf_db() { + Some(pdb) => pdb.query_rows(&sql, &[]).await?, + None => db.query(&sql, &[]).await?, + }; let mut out = HashMap::new(); for row in &rows { let name: Option = row.get(0)?; diff --git a/src/platform/state.rs b/src/platform/state.rs index aadf36b..32d6ae1 100644 --- a/src/platform/state.rs +++ b/src/platform/state.rs @@ -32,10 +32,15 @@ pub fn process_db_lock() -> Arc> { pub struct AppState { pub config: Arc, pub db: Arc, - /// PGlite 是单 in-process backend,所有 DB 访问必须持这把锁。 + /// PGlite 是单 in-process backend,所有 DB 访问必须串行化。 /// /// 🔴 这是**进程级唯一**的那把(见 [`process_db_lock`])⇒ 同一进程里的所有 /// `AppState`(哪怕指向同一个 `PGlite`)都共享它。 + /// + /// 🔴 **P5 起生产路径已无消费者**:业务 SQL 全部经 `crate::platform::db` 走 + /// `sspf::Db` 的持锁入口(与平台共用 `Db.lock`)⇒ 真正的串行域是那一把。 + /// 本字段现在只服务于**测试**(集成测试各自持它来串行化裸句柄的建库 / 造数), + /// 保留是因为它同时表达「一个进程只有一把库锁」这条语义。 pub db_lock: Arc>, pub sessions: Arc, } diff --git a/tests/sspf_db_lock.rs b/tests/sspf_db_lock.rs new file mode 100644 index 0000000..114f1fd --- /dev/null +++ b/tests/sspf_db_lock.rs @@ -0,0 +1,115 @@ +//! P5 探针:业务库操作**真的**持平台的 `Db.lock`(而不是 tdc 自己那把 `db_lock`)。 +//! +//! 判据(对应 `ssw-platform/docs/SSPF-BUSINESS-DB-ACCESS.md` §4 的业务侧验收): +//! 1. `platform::db::*` 切换后仍**不归一** —— `f_*` 键原样出来(归一由业务 `mapper` 做); +//! 2. 平台持 `Db.lock` 期间,业务写**排队**而不是插队 ⇒ 单进程单锁成立。 +//! +//! 🔴 这两条必须真进程验:静态护栏只能说「调用点收在一处」,说不了「锁是不是同一把」。 +//! 🔴 `pglite-rs` 每进程只允许一个实例 ⇒ 本文件用 `OnceCell` 共享**一个** `Db` +//! (两个测试并行跑也只有一个库)。 + +use std::sync::Arc; +use std::time::Duration; + +use sspf::Db; +use tdc_connector::platform::db; + +/// 进程级唯一的平台库(`OnceCell` 保证并发测试只开一次)。 +static DB: tokio::sync::OnceCell> = tokio::sync::OnceCell::const_new(); + +async fn shared_db() -> Arc { + DB.get_or_init(|| async { + let db = Arc::new(Db::open_temp().await.expect("打开临时库失败")); + assert!( + db::install_sspf_db(db.clone()), + "进程级注入只允许一次(pglite 每进程只有一个实例)" + ); + db + }) + .await + .clone() +} + +/// ① 四个查询入口全部经平台 `Db`,且 **JSON 键不归一**。 +#[tokio::test] +async fn business_sql_holds_the_platform_lock_and_leaves_keys_raw() { + let db = shared_db().await; + let pg = db.pg(); + + db.exec("DROP TABLE IF EXISTS p5_probe").await.unwrap(); + db.exec("CREATE TABLE p5_probe (f_id text, f_name text)") + .await + .unwrap(); + + // 写路径:`platform::db::exec_params` → `Db::exec_params` + db::exec_params( + &pg, + "INSERT INTO p5_probe VALUES ($1, $2)", + &[&"a1", &"n1"], + ) + .await + .expect("业务写失败"); + + // 读路径:`platform::db::query_json_params` → `Db::query_json_raw` + let rows = db::query_json_params(&pg, "SELECT f_id, f_name FROM p5_probe", &[]) + .await + .expect("业务读失败"); + assert_eq!(rows.len(), 1); + // 🔴 契约核心:键必须是 `f_*` 原样。若这里变成 `id` / `name`,说明走了平台的 + // `query_json*`(归一)而不是 `query_json_raw` ⇒ 132 条端点响应形状全漂。 + assert_eq!(rows[0]["f_id"], "a1", "raw 不得归一:{rows:?}"); + assert_eq!(rows[0]["f_name"], "n1", "raw 不得归一:{rows:?}"); + assert!( + rows[0].get("id").is_none(), + "raw 不得把 `f_id` 折叠成 `id`:{rows:?}" + ); + + // 取首行首列:`query_rows` + let count = db::query_scalar_text(&pg, "SELECT count(*)::text FROM p5_probe", &[]) + .await + .expect("取标量失败"); + assert_eq!(count.as_deref(), Some("1")); + + // 元数据:`query_rows`(`pg_catalog`) + let types = db::column_types(&pg, "p5_probe").await.expect("取列类型失败"); + assert_eq!(types.get("f_id").map(String::as_str), Some("text")); + assert_eq!(types.get("f_name").map(String::as_str), Some("text")); +} + +/// ② 平台持锁时业务写必须排队 —— 证明两侧用的是**同一把**锁。 +#[tokio::test] +async fn business_write_queues_behind_the_platform_lock() { + let db = shared_db().await; + let pg = db.pg(); + + db.exec("DROP TABLE IF EXISTS p5_lock").await.unwrap(); + db.exec("CREATE TABLE p5_lock (f_id text)").await.unwrap(); + + // 平台侧持锁(模拟平台正在跑一段业务 / 一次事务) + let guard = db.lock_owned().await; + + let blocked = tokio::time::timeout( + Duration::from_millis(300), + db::exec_params(&pg, "INSERT INTO p5_lock VALUES ($1)", &[&"blocked"]), + ) + .await; + assert!( + blocked.is_err(), + "平台持有 Db.lock 期间,业务写必须排队 —— 300ms 内就写成功说明用的是两把锁" + ); + + drop(guard); + + // 解锁后立刻可写 ⇒ 不是「永久卡死」,是「排队」 + db::exec_params(&pg, "INSERT INTO p5_lock VALUES ($1)", &[&"after"]) + .await + .expect("解锁后业务写失败"); + let count = db::query_scalar_text(&pg, "SELECT count(*)::text FROM p5_lock", &[]) + .await + .expect("取标量失败"); + assert_eq!( + count.as_deref(), + Some("1"), + "被超时取消的那次写不应落库 ⇒ 只应有解锁后那 1 行" + ); +} diff --git a/tests/sspf_platform_package.rs b/tests/sspf_platform_package.rs index c935016..a2769b8 100644 --- a/tests/sspf_platform_package.rs +++ b/tests/sspf_platform_package.rs @@ -92,10 +92,32 @@ async fn table_exists(db: &Db, table: &str) -> bool { } } +/// 从本仓 `Cargo.toml` 读出给 `sspf` 锁的 git tag(`vX.Y.Z`)。 +/// +/// 🔴 为什么不用硬编码字符串:升级平台包要同时改 `Cargo.toml` 的 tag 与本断言, +/// 两处一旦忘一处,测试才会红 —— 但那已经是「改完才发现」。直接读清单后, +/// **tag ↔ 门面 `VERSION` 只有一处真相**,升级时漏改任何一边都当场红。 +fn locked_sspf_tag() -> Option { + let manifest = std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/Cargo.toml")) + .expect("读不到本仓 Cargo.toml"); + // 只找以 `sspf =` 开头的那条依赖行(注释行以 `#` 开头,天然排除)。 + let line = manifest + .lines() + .find(|l| l.trim_start().starts_with("sspf ="))?; + let rest = line.split("tag = ").nth(1)?; + let tag = rest.trim_start().strip_prefix('"')?; + Some(tag.split('"').next()?.to_string()) +} + #[tokio::test] async fn platform_package_boots_one_port_with_one_db() { // 门面版本必须与业务仓 Cargo.toml 锁的 tag 对得上。 - assert_eq!(sspf::VERSION, "0.3.0", "业务仓锁的是 sspf v0.3.0"); + let tag = locked_sspf_tag().expect("Cargo.toml 里应有 `sspf = { git = ..., tag = ... }`"); + assert_eq!( + tag, + format!("v{}", sspf::VERSION), + "业务仓锁的 tag 必须与门面 VERSION 一致(改 Cargo.toml 忘改 tag 会在这里红)" + ); // ---- 配置:临时库(进程级单例 ⇒ 全文件只有这一个测试)---- let mut config = Config::from_env(PathBuf::from("/tmp/tdc-p1-platform-probe"));