Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
509c6b1d1f | ||
|
|
18a6586c1d | ||
|
|
db3f891f7a | ||
|
|
060e6eb755 |
No files matched your search
@@ -247,3 +247,32 @@ CannotCache(incremental): ["--crate-name", "probe", ..., "-C", "incremental=..."
|
||||
|
||||
**待办**:第二批改技能仓(依赖 sspf 发布 tag 的薄脚手架 + 示例 + 前端);
|
||||
版本号「打 v0.4.0 还是只提交」需用户拍板,未擅自打。
|
||||
|
||||
## v0.4.0 口径修正 + 第二批「改技能」完成(22:00–22:40)
|
||||
|
||||
**口径修正(平台仓)**:清理提交漏了门面自身版本 —— `crates/sspf/Cargo.toml` 仍 `0.3.0`,
|
||||
业务仓锁 `tag = "v0.4.0"` 会解析成 `sspf v0.3.0 (?tag=v0.4.0)`。已改 Cargo.toml + lib.rs
|
||||
版本表/断言 + Cargo.lock + CHANGELOG,`v0.4.0` 移到对齐后的提交(`ff34ca5`,当时零消费者),
|
||||
`main` 与 tag 同提交已推 `origin`。仓外探针确认:`sspf v0.4.0 (...?tag=v0.4.0#ff34ca50)`、0 个 `sspf-pack-*`。
|
||||
顺手收入第三份需求 `docs/SSPF-BUSINESS-DB-ACCESS.md`(目标 v0.5.0,未实现)。
|
||||
|
||||
**第二批(技能仓 `~/.agents/skills/ssw-jnpf-lite-rust`,提交 `fe9f84b`)**:
|
||||
- 删自研平台:`src/backend/src/platform/`(17 文件)、`routes.rs`、`bootstrap.rs`、`db/schema.sql`、7 个旧集成测试。
|
||||
- 平台改为 `sspf = { git = ".../ssw-platform.git", tag = "v0.4.0" }`(workspace 唯一入口);应用瘦成 ~500 行薄壳。
|
||||
- 迁入 4 个示例包 `packs/{demo,shop,books,asset}`,依赖 `sspf-sdk` → 门面 `sspf`。
|
||||
- 脚本:新增 `check-scaffold.py`(SC1–SC6 + 反自证 6/6)、重写 `pack-sync.py`(4 处派生位置)、
|
||||
新增 `new-pack.{sh,py}` 与 `verify.sh`;**删除** check-module/boundary/contract/citations(无测量对象)。
|
||||
- 契约补 asset:`[MENU_TREE]` 9 菜单、`[ENDPOINT]` +3、`[FACE]` A=28;前端 `dist/` 入库(免 npm build)。
|
||||
|
||||
**硬结论(技能仓侧)**
|
||||
- `pack-sync.py` 的 ROOT 不能用脚本自身路径,否则反自证在临时树里跑时检查的是真实仓库 ⇒ SC6 **假绿**;已加 `PACK_SYNC_ROOT`。
|
||||
- 生成段必须由生成器输出**完整声明块**(只输出数组元素会把 `pub const … = &[` 与 `];` 一起盖掉 ⇒ 语法错)。
|
||||
- 业务菜单**不要**传给 `.menus()`:`.packs(reg)` 已带 `PackRegistry.menus`,给两次种子 INSERT 撞主键。
|
||||
- 平台默认 `resolve_project_dir` 锚点是 `src/backend/db/schema.sql`(本仓已删)⇒ 应用侧自己按
|
||||
`SSW_PROJECT_DIR` → `Cargo.toml` + `packs/` 向上找 → cwd。
|
||||
- 加 asset 包后菜单树 8 → 9,`[MENU_TREE]` 不改则面 A 尺子当场红(尺子是对的)。
|
||||
|
||||
**验收**:`check-scaffold` 6/6 + 自证 6/6;`perm-smoke` 32/32;`perm-smoke-jnpf` 18/18;
|
||||
`verify.sh` **7/7 全绿**(84s);`new-pack.sh probe Widget` 端到端:表数 182(177+5)、面 A 600 / 面 B 602。
|
||||
|
||||
**未做**:技能仓未推 `origin`(等用户确认);历史报告类文档(MIGRATION/JNPF_*)仍引旧路径,未逐条改。
|
||||
@@ -1,5 +1,15 @@
|
||||
# CHANGELOG
|
||||
|
||||
## v0.5.0(2026-11-04,业务库操作收进同一个 `Db`)
|
||||
|
||||
- 新增 `Db::query_json_raw(sql, params)`:持 `Db.lock`、`row_to_json` 包裹、**不做 JSON 键归一**(`f_id` 原样返回),给自带归一语义的厚业务仓用。
|
||||
- 新增 `Db::query_rows(sql, params)`:持锁返回原始 `pglite::Row`(`pg_catalog` 元数据 / 取首行首列),业务仓经 `sspf::pglite` 引用类型、不必自己声明依赖。
|
||||
- 新增 `Db::lock_owned() -> OwnedMutexGuard<()>`:与所有 `Db::*` / `DbTransaction` 共用同一把锁;持 guard 期间可在裸句柄上跑自有 SQL。
|
||||
- `query_json_inner` 拆成共用的 `query_json_inner_raw`(包裹 + 反序列化)+ 归一那一层 ⇒ SQL 包裹只有一份;`query_json*` 行为**一字未改**。
|
||||
- 新增闸门 AR20(raw 不归一 / 共用包裹段 / 公开入口全持同一把锁)+ 反自证 15/15;新增探针 `db_raw_it.rs`(4 条:raw 键不归一、归一路径同时成立、guard 期间 `Db::exec` 被阻塞、`query_rows` 读 `pg_catalog`)。
|
||||
- `Db::pg()` 文档补「要与平台共用串行域该走哪个入口」的指路表;销掉 v0.3.0 的「双锁」已知局限(`docs/known-limitations.md` 的 (bq))。
|
||||
- 影响:面 A / 面 B 端点形状、码表、表结构零变化;`Platform` 的公开签名未改(`Finish::default()` 路径逐字等价)。`sspf` 版本 0.5.0。
|
||||
|
||||
## v0.4.0(2026-11-04,平台包零业务清理)
|
||||
|
||||
- 4 个示例业务包与 `modules/` 的 4 个面 A 适配器整体移出本仓;`packs/` 与 `sspf-pack-*` 依赖、 `example-packs` feature、门面 `example_packs()` 全部移除。
|
||||
|
||||
Generated
+1
-1
@@ -1069,7 +1069,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "sspf"
|
||||
version = "0.4.0"
|
||||
version = "0.5.0"
|
||||
dependencies = [
|
||||
"axum",
|
||||
"libc",
|
||||
|
||||
+52
-3
@@ -9,6 +9,54 @@
|
||||
|
||||
---
|
||||
|
||||
## 0. 2026-11-04 深夜:`v0.5.0` —— 业务库操作收进同一个 `Db`(**最新**)
|
||||
|
||||
需求:`docs/SSPF-BUSINESS-DB-ACCESS.md`(第三份,`tdc-rs` 提)。要销的是 v0.3.0 留下的
|
||||
那条已知局限:**`Db::pg()` 绕过 `Db.lock`** ⇒ 平台与业务各一把锁,跨平台的多语句事务不保证串行。
|
||||
|
||||
**做了什么**
|
||||
|
||||
1. **新增三个库入口**(`crates/sspf-store/src/db.rs`):
|
||||
- `Db::query_json_raw(sql, params)` —— 持 `Db.lock`、`row_to_json` 包裹、**不做 JSON 键归一**
|
||||
(`f_id` 原样回来),给自带归一语义的厚业务仓;
|
||||
- `Db::query_rows(sql, params)` —— 持锁返回原始 `pglite::Row`(`pg_catalog` 元数据 / 取首行首列);
|
||||
- `Db::lock_owned() -> OwnedMutexGuard<()>` —— 与所有 `Db::*` / `DbTransaction` 共用**同一把**锁,
|
||||
持 guard 期间可在裸句柄上跑自有 SQL。
|
||||
2. **拆共用段**:`query_json_inner` → `query_json_inner_raw`(包裹 + 反序列化)+ 归一那一层。
|
||||
SQL 包裹逻辑只有一份 ⇒ 两条路不会漂。`query_json*` 的对外行为**一字未改**。
|
||||
3. **文档指路**:`Db::pg()` 的注释补了一张「要与平台共用串行域该走哪个入口」的表,
|
||||
并写明持 `lock_owned()` 期间**不许**再调 `Db::*`(tokio Mutex 不可重入)。
|
||||
4. **闸门 AR20**(`scripts/check-arch.sh`):扫 `db.rs` 的函数体,钉住
|
||||
① `query_json_raw` 里不出现 `normalize_json_keys`;② 它必须走共用的 `query_json_inner_raw`
|
||||
且不调会归一的 `query_json_inner`;③ 共用段自身不归一;④ 8 个公开库入口都持 `self.lock`;
|
||||
⑤ `lock_owned` 基于 `self.lock`(不是第二把锁)。反自证从 14 项加到 **15 项**。
|
||||
5. **探针 `db_raw_it.rs`**(4 条):raw 键不归一 / 同一条 SQL 走 `query_json` 仍归一(两条路同时成立)/
|
||||
持 `lock_owned()` 期间 `Db::exec` 被阻塞(用 `timeout` 断言「没完成」,不用 sleep 猜)/
|
||||
`query_rows` 读 `pg_catalog` 原始行。
|
||||
6. **销条**:`docs/known-limitations.md` 的 (bq)「双锁」改为「已由 v0.5.0 解决」;
|
||||
`CHANGELOG.md` 加 v0.5.0 条目;`README.md` 版本表 + 依赖示例升到 `v0.5.0`。
|
||||
|
||||
**验收**
|
||||
|
||||
| 判据 | 结果 |
|
||||
|---|---|
|
||||
| `cargo test --workspace --no-fail-fast` | **653 passed / 0 failed / 8 ignored**(v0.4.0 基线 649 + 4 条 `db_raw_it`) |
|
||||
| `verify.sh --smoke` | **14/14 步全绿**(122.7s) |
|
||||
| `check-arch.sh` / `--self-test` | **25/25 / 0 跳过**,反自证 **15/15** |
|
||||
| `cargo tree -p sspf` | 仍 **0 个 `sspf-pack-*`**(AR17 不回归) |
|
||||
| 面 A / 面 B | 端点形状 / 码表 / 表结构零变化;`Platform` 公开签名未改 |
|
||||
|
||||
**踩过 / 别踩**
|
||||
|
||||
- 🔴 AR20 的函数体提取**必须允许不带 `pub`**:`query_json_inner_raw` 是私有共用段,
|
||||
只认 `pub async fn` 会把它判成「不存在」⇒ 尺子自己先红(本轮踩过)。
|
||||
- 🔴 自证注入点要落在**函数体内部**(`{` 之后插一行),落在文件末尾不构成「raw 路径归了」。
|
||||
|
||||
**下游**:`tdc-rs` 按需求 §5 切换(`tag → v0.5.0` + `platform/db.rs` 六个函数改走 `Db`),
|
||||
业务侧验收清单在需求文档 §5 末尾。
|
||||
|
||||
---
|
||||
|
||||
## 0. 2026-11-04 晚:平台包零业务清理 → `v0.4.0`(第一批,**已推 `origin`:`main` + tag**)
|
||||
|
||||
需求:`@docs/SSPF-BUSINESS-COMPOSITION.md` 之后的追加要求 —— 「示例部分拿到外面去做,
|
||||
@@ -62,10 +110,11 @@
|
||||
`verify.sh --smoke` **14/14 步全绿**(6 道静态闸门 + 全量测试 + 5 把运行时尺子);
|
||||
`check-arch.sh` 24/24 / 0 跳过,`--self-test` 14/14;`cargo tree -p sspf | grep sspf-pack` 无输出。
|
||||
|
||||
**已发布**:annotated tag `v0.4.0` 与 `main` **同一提交**(含门面 cargo 版本对齐 `0.4.0`),
|
||||
均已推 `origin`(`git ls-remote --tags origin` 可见 `v0.4.0` 与 `^{}`)。业务仓 / 技能仓按
|
||||
**已发布**:annotated tag `v0.4.0` → `ff34ca5`(含门面 cargo 版本对齐 `0.4.0`),已推 `origin`
|
||||
(`git ls-remote --tags origin` 可见 `v0.4.0` 与 `^{}`,解引用即 `ff34ca5`)。
|
||||
`main` 在其后可能还有**纯文档提交**(需求稿 / 日志),不影响 tag 的内容。业务仓 / 技能仓按
|
||||
`http://127.0.0.1:13300/ssw/ssw-platform.git` + `tag = "v0.4.0"` 锁依赖,
|
||||
`cargo tree` 应解析为 `sspf v0.4.0 (...?tag=v0.4.0#<sha>)`。
|
||||
`cargo tree` 应解析为 `sspf v0.4.0 (...?tag=v0.4.0#ff34ca50)`。
|
||||
|
||||
**待办(第二批)**:技能仓 `~/.agents/skills/ssw-jnpf-lite-rust` 接收示例,改成
|
||||
依赖 `sspf v0.4.0` 的薄脚手架,删掉旧的 `src/backend` 自研实现,重写
|
||||
|
||||
@@ -24,7 +24,7 @@
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.4.0" }
|
||||
sspf = { git = "http://127.0.0.1:13300/ssw/ssw-platform.git", tag = "v0.5.0" }
|
||||
```
|
||||
|
||||
```rust
|
||||
@@ -109,7 +109,8 @@ cargo tree -p sspf | grep sspf-pack # 必须无输出(平台包零业务
|
||||
|---|---|
|
||||
| `v0.2.0` | 标准平台包 P0:门面 `sspf`、示例包选装、AR17/AR18 |
|
||||
| `v0.3.0` | P1:`Db::pg()` 同句柄、`assemble()/Finish` 两阶段装配、AR19 |
|
||||
| `v0.4.0` | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流(**已推 `origin`**) |
|
||||
| `v0.4.0` | 平台包零业务清理:示例包 / 面 A 适配器 / `example-packs` 全部退役,闸门改防回流 |
|
||||
| `v0.5.0` | 业务库操作收进同一个 `Db`:`query_json_raw`(持锁不归一)/ `query_rows` / `lock_owned()`,闸门 AR20(**已推 `origin`**) |
|
||||
|
||||
发布说明见 `CHANGELOG.md`,逐版实施记录见 `HANDOFF.md` 与 `docs/SSPF-*.md`。
|
||||
已发布的 tag **一字不动**;破坏性变更走新 tag。
|
||||
|
||||
+105
-8
@@ -27,7 +27,7 @@ use std::sync::OnceLock;
|
||||
|
||||
use pglite::{PGlite, ToSql};
|
||||
use serde_json::Value;
|
||||
use tokio::sync::Mutex;
|
||||
use tokio::sync::{Mutex, OwnedMutexGuard};
|
||||
|
||||
/// 重新导出 pglite crate。
|
||||
///
|
||||
@@ -233,13 +233,47 @@ impl Db {
|
||||
///
|
||||
/// 🔴 返回的是 `Arc::clone`,不是 `PGlite::clone()`:`Arc` 的共享可用
|
||||
/// `Arc::ptr_eq` 钉住,`PGlite` 自己的 `Clone` 语义不对外承诺。
|
||||
/// 🔴 这个句柄**绕过本层的 `Db.lock`**:单次 SQL 有 pglite 的 `serial_guard`
|
||||
/// 兜着,但「一次业务操作跨多条 SQL」的串行化要业务仓自己保证
|
||||
/// (见 `docs/known-limitations.md` 的「双锁」条)。
|
||||
/// 🔴 **这个句柄绕过本层的 `Db.lock`**:单次 SQL 有 pglite 的 `serial_guard`
|
||||
/// 兜着,但「一次业务操作跨多条 SQL」的串行化**不由本层保证**。
|
||||
///
|
||||
/// ## 要与平台共用串行域 ⇒ 用这四个入口,别用裸句柄
|
||||
///
|
||||
/// | 想要什么 | 用什么 |
|
||||
/// |---|---|
|
||||
/// | SELECT,且**自己**做 `f_* → camelCase` 归一 | [`Db::query_json_raw`](持锁、**不归一**) |
|
||||
/// | SELECT,想要平台风格的 JSON 键 | [`Db::query_json`] / [`Db::query_json_params`] |
|
||||
/// | 要原始 `pglite::Row`(`pg_catalog` 元数据、取首行首列) | [`Db::query_rows`] |
|
||||
/// | 写(INSERT / UPDATE / DELETE / DDL) | [`Db::exec`] / [`Db::exec_params`] |
|
||||
/// | 要自己在裸句柄上跑一批 SQL,但**必须与平台互斥** | [`Db::lock_owned`](持 guard 期间用 `pg()`) |
|
||||
///
|
||||
/// 🔴 `pg()` 本句柄只适合**启动期单线程建表**与**只读元数据探测**;
|
||||
/// 请求期用它会与平台侧各自开锁(见 `docs/known-limitations.md` 的「双锁」条,
|
||||
/// v0.5.0 起已有正式的替代入口)。
|
||||
pub fn pg(&self) -> Arc<PGlite> {
|
||||
Arc::clone(&self.pg)
|
||||
}
|
||||
|
||||
/// 取得**进程级业务锁**(与所有 `Db::*` / [`DbTransaction`] 共用同一把)。
|
||||
///
|
||||
/// 给「必须自己写 SQL、又要与平台互斥」的业务仓用:guard 存活期间,
|
||||
/// 平台侧任何 `Db::*` 调用都会排队;`drop` 即释放。
|
||||
///
|
||||
/// ```ignore
|
||||
/// let _g = db.lock_owned().await;
|
||||
/// let rows = db.pg().query(&sql, ¶ms).await?; // 裸句柄,但在锁内
|
||||
/// ```
|
||||
///
|
||||
/// ## 🔴 两条纪律(违反必死锁 / 必错乱)
|
||||
///
|
||||
/// 1. **持 guard 期间不得再调任何 `Db::*` 方法**(`begin()` 也算)——
|
||||
/// tokio 的 `Mutex` **不可重入** ⇒ 自己等自己。
|
||||
/// 2. **不得把 guard 传出去跨请求持有** —— 那是全局串行点,持有越久吞吐越低。
|
||||
///
|
||||
/// 比 `pub fn lock(&self) -> &Mutex<()>` 安全:不暴露内部可变性,guard 有明确生命周期。
|
||||
pub async fn lock_owned(&self) -> OwnedMutexGuard<()> {
|
||||
Arc::clone(&self.lock).lock_owned().await
|
||||
}
|
||||
|
||||
/// schema 初始化(**只在 `base_user` 不存在时**整体执行一次)。
|
||||
///
|
||||
/// - 探测用 `to_regclass('public.base_user')`(一次 round-trip,S5)。
|
||||
@@ -316,6 +350,52 @@ impl Db {
|
||||
self.query_json_inner(sql, params).await
|
||||
}
|
||||
|
||||
/// 同 [`Db::query_json_params`],但**不做任何 JSON 键归一**(v0.5.0)。
|
||||
///
|
||||
/// 持 `Db.lock`、`row_to_json` 包裹、参数绑定、错误类型与
|
||||
/// [`Db::query_json_params`] **逐字一致**;唯一差别是返回 PostgreSQL
|
||||
/// **原样**的列名 / 别名折叠结果(`f_id` 还是 `f_id`,不会变 `id`)。
|
||||
///
|
||||
/// ## 🔴 给谁用
|
||||
///
|
||||
/// 自带归一语义的厚业务仓(例如 `tdc-rs`:它在上层用 `column_to_json_key`
|
||||
/// 把 `f_*` 转 camelCase)。对它们来说,平台再归一一次就是**第二次转换**
|
||||
/// ⇒ 键会漂移(尤其加引号别名)。
|
||||
///
|
||||
/// 无参形态直接传 `&[]`。
|
||||
///
|
||||
/// ```ignore
|
||||
/// let rows = db.query_json_raw("SELECT f_id, f_real_name FROM base_user", &[]).await?;
|
||||
/// // ⇒ [{"f_id": "...", "f_real_name": "..."}]
|
||||
/// ```
|
||||
pub async fn query_json_raw(
|
||||
&self,
|
||||
sql: &str,
|
||||
params: &[&(dyn ToSql + Sync)],
|
||||
) -> Result<Vec<Value>, pglite::Error> {
|
||||
let _guard = self.lock.lock().await;
|
||||
let (_alias_info, rows) = self.query_json_inner_raw(sql, params).await?;
|
||||
Ok(rows)
|
||||
}
|
||||
|
||||
/// 持 `Db.lock` 执行带参查询,返回**原始** `pglite::Row`(v0.5.0)。
|
||||
///
|
||||
/// 给元数据类查询用(`pg_catalog`、`to_regclass`、取首行首列)——
|
||||
/// 那些场景不需要 `row_to_json`,也不需要 JSON 键归一。
|
||||
///
|
||||
/// `pglite::Row` 类型经 `sspf::pglite` 可见,业务仓不必自己声明 `pglite` 依赖。
|
||||
///
|
||||
/// 🔴 **列类型按 OID 自己判**:`row.get::<Option<String>>(0)` 对非 text 列
|
||||
/// 是拿二进制字节做 `from_utf8`(不校验类型,静默判错)。
|
||||
pub async fn query_rows(
|
||||
&self,
|
||||
sql: &str,
|
||||
params: &[&(dyn ToSql + Sync)],
|
||||
) -> Result<Vec<pglite::Row>, pglite::Error> {
|
||||
let _guard = self.lock.lock().await;
|
||||
self.pg.query(sql, params).await
|
||||
}
|
||||
|
||||
/// 执行(无返回值)语句。
|
||||
///
|
||||
/// 🔴 走 **simple protocol** ⇒ **可以一次执行多条语句**,且整批是一个**隐式事务**
|
||||
@@ -391,11 +471,16 @@ impl Db {
|
||||
|
||||
// ---- 以下为**持锁调用**的内部实现(调用方已持有 `self.lock`)----
|
||||
|
||||
async fn query_json_inner(
|
||||
/// `row_to_json` 包裹 + 参数绑定 + 反序列化,**不归一**(v0.5.0 拆出来)。
|
||||
///
|
||||
/// 🔴 [`Db::query_json_raw`] 与 [`Db::query_json_inner`] **共用这一段**:
|
||||
/// SQL 包裹逻辑只许有一份(复制必漂移)。
|
||||
/// 返回值里的 [`AliasInfo`] 只有归一那一侧用得上,raw 侧丢弃。
|
||||
async fn query_json_inner_raw(
|
||||
&self,
|
||||
sql: &str,
|
||||
params: &[&(dyn ToSql + Sync)],
|
||||
) -> Result<Vec<Value>, pglite::Error> {
|
||||
) -> Result<(AliasInfo, Vec<Value>), pglite::Error> {
|
||||
let inner = trim_sql(sql);
|
||||
// 预先扫出**外层投影列表**的 `AS <别名>` ⇒ 查询后能把 PG 折叠掉的大写还原回去。
|
||||
let alias_info = collect_alias_info(inner);
|
||||
@@ -410,9 +495,21 @@ impl Db {
|
||||
let value = serde_json::from_str::<Value>(&text).map_err(|e| {
|
||||
pglite::Error::Protocol(format!("row_to_json 结果反序列化失败: {e}"))
|
||||
})?;
|
||||
out.push(normalize_json_keys(value, &alias_info));
|
||||
out.push(value);
|
||||
}
|
||||
Ok(out)
|
||||
Ok((alias_info, out))
|
||||
}
|
||||
|
||||
async fn query_json_inner(
|
||||
&self,
|
||||
sql: &str,
|
||||
params: &[&(dyn ToSql + Sync)],
|
||||
) -> Result<Vec<Value>, pglite::Error> {
|
||||
let (alias_info, rows) = self.query_json_inner_raw(sql, params).await?;
|
||||
Ok(rows
|
||||
.into_iter()
|
||||
.map(|v| normalize_json_keys(v, &alias_info))
|
||||
.collect())
|
||||
}
|
||||
|
||||
/// 取第一行的第一列 ⇒ 文本。
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
[package]
|
||||
name = "sspf"
|
||||
version = "0.4.0"
|
||||
version = "0.5.0"
|
||||
edition = "2021"
|
||||
rust-version = "1.85"
|
||||
description = "SSPF 标准平台包 —— 业务仓唯一依赖的门面(平台能力 + 装配注入)"
|
||||
|
||||
# 🔴 **为什么显式写 version,不用 `version.workspace = true`**:
|
||||
# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.4"` / tag `v0.4.0`),
|
||||
# 业务仓(tdc-rs)锁的是**这个 crate 的语义版本**(`sspf = "0.5"` / tag `v0.5.0`),
|
||||
# 而本仓 workspace 版本(0.1.0)跟的是内核实现节奏。两者独立演进 —— 混用会让
|
||||
# 「业务仓能不能升级」变成「内核发了几个 commit」。
|
||||
#
|
||||
|
||||
@@ -41,7 +41,7 @@
|
||||
//!
|
||||
//! | 版本 | 值 | 谁看 |
|
||||
//! |---|---|---|
|
||||
//! | 本 crate(cargo) | `0.4.0` | 业务仓锁依赖 / git tag |
|
||||
//! | 本 crate(cargo) | `0.5.0` | 业务仓锁依赖 / git tag |
|
||||
//! | 契约版本 | `0.4.0` | 业务包 `pack.toml` 的 `kernel_req` |
|
||||
//! | workspace(cargo) | `0.1.0` | 内核实现节奏 |
|
||||
//!
|
||||
@@ -109,7 +109,7 @@ mod tests {
|
||||
/// **改版本时这里必须同步改**,否则测试当场红 —— 这是有意的护栏。
|
||||
#[test]
|
||||
fn version_matches_the_manifest() {
|
||||
assert_eq!(super::VERSION, "0.4.0");
|
||||
assert_eq!(super::VERSION, "0.5.0");
|
||||
}
|
||||
|
||||
/// 🔴 **平台包恒零业务**(2026-11-04 清理)—— 与 AR17 的静态判据互补:
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
//! db_raw —— v0.5.0 新入口的集成探针(`query_json_raw` / `query_rows` / `lock_owned`)。
|
||||
//!
|
||||
//! ## 这四条断言在钉什么
|
||||
//!
|
||||
//! 1. **raw 不归一**:`f_id` / `f_real_name` 原样返回(厚业务仓自己转 camelCase);
|
||||
//! 2. **归一那侧没被改坏**:同一条 SQL 走 `query_json` 仍是 `id` / `realName`
|
||||
//! —— 两条路径**同时**成立,说明 R1 只是「多开一条不归一的出口」,
|
||||
//! 不是「把归一逻辑挪走」;
|
||||
//! 3. **同一把锁**:持 `lock_owned()` 期间 `Db::exec` 必须**排队**(用 `timeout`
|
||||
//! 断言「没完成」,而不是 `sleep` 后猜「应该没完成」);
|
||||
//! 4. **`query_rows` 能读 `pg_catalog` 原始行**(元数据查询不需要 `row_to_json`)。
|
||||
//!
|
||||
//! 🔴 断言 3 是本题的**核心**:这两把锁如果不统一,业务仓与平台并发写同一个
|
||||
//! PGlite 后端时会交错 —— 而这在任何单线程测试里都看不出来。
|
||||
|
||||
use std::time::Duration;
|
||||
|
||||
use sspf_core::db::Db;
|
||||
use tokio::sync::OnceCell;
|
||||
|
||||
/// 全文件共享的临时库(pglite 进程级单实例,见 `db_it.rs` 的说明)。
|
||||
static DB: OnceCell<Db> = OnceCell::const_new();
|
||||
|
||||
async fn db() -> &'static Db {
|
||||
DB.get_or_init(|| async { Db::open_temp().await.expect("打开 pglite 临时库失败") })
|
||||
.await
|
||||
}
|
||||
|
||||
/// 一条**不需要建表**的投影:直接把字面量起成 `f_*` 列名。
|
||||
///
|
||||
/// 🔴 刻意不用 `base_user`:`query_json` 的键归一与「表里有没有数据」无关,
|
||||
/// 用字面量投影才能让这条断言**不依赖种子 / DDL**(失败时原因唯一)。
|
||||
const SQL_LITERAL_ROW: &str = "SELECT 'u-1'::text AS f_id, '张三'::text AS f_real_name";
|
||||
|
||||
#[tokio::test]
|
||||
async fn raw_does_not_normalize_keys() {
|
||||
let db = db().await;
|
||||
|
||||
let rows = db
|
||||
.query_json_raw(SQL_LITERAL_ROW, &[])
|
||||
.await
|
||||
.expect("query_json_raw 失败");
|
||||
|
||||
assert_eq!(rows.len(), 1, "字面量投影必须恰好一行");
|
||||
let obj = rows[0].as_object().expect("行必须是 JSON 对象");
|
||||
|
||||
assert_eq!(
|
||||
obj.get("f_id").and_then(|v| v.as_str()),
|
||||
Some("u-1"),
|
||||
"raw 路径必须保留 f_id 原样(归一了就说明走错入口)"
|
||||
);
|
||||
assert_eq!(
|
||||
obj.get("f_real_name").and_then(|v| v.as_str()),
|
||||
Some("张三"),
|
||||
"raw 路径必须保留 f_real_name 原样"
|
||||
);
|
||||
assert!(
|
||||
obj.get("id").is_none() && obj.get("realName").is_none(),
|
||||
"raw 路径**不许**出现归一后的键:{obj:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn normalize_path_still_works_on_the_same_sql() {
|
||||
let db = db().await;
|
||||
|
||||
// 🔴 同一条 SQL,两个入口 ⇒ 两种键集合,同时成立。
|
||||
// 这条断言防的是「为了做 raw 把 normalize_json_keys 挪走 / 改掉」。
|
||||
let rows = db
|
||||
.query_json(SQL_LITERAL_ROW)
|
||||
.await
|
||||
.expect("query_json 失败");
|
||||
|
||||
assert_eq!(rows.len(), 1, "字面量投影必须恰好一行");
|
||||
let obj = rows[0].as_object().expect("行必须是 JSON 对象");
|
||||
|
||||
assert_eq!(
|
||||
obj.get("id").and_then(|v| v.as_str()),
|
||||
Some("u-1"),
|
||||
"query_json 必须把 f_id 归一成 id"
|
||||
);
|
||||
assert_eq!(
|
||||
obj.get("realName").and_then(|v| v.as_str()),
|
||||
Some("张三"),
|
||||
"query_json 必须把 f_real_name 归一成 realName"
|
||||
);
|
||||
assert!(
|
||||
obj.get("f_id").is_none() && obj.get("f_real_name").is_none(),
|
||||
"query_json 不许残留 f_* 键:{obj:?}"
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn lock_owned_blocks_db_calls_until_dropped() {
|
||||
let db = db().await;
|
||||
|
||||
let guard = db.lock_owned().await;
|
||||
|
||||
// 持 guard 期间另起一个 `Db::exec`:它必须**卡在锁上**。
|
||||
let db2 = db.clone();
|
||||
let mut task = tokio::spawn(async move { db2.exec("SELECT 1").await });
|
||||
|
||||
let early = tokio::time::timeout(Duration::from_millis(200), &mut task).await;
|
||||
assert!(
|
||||
early.is_err(),
|
||||
"持 lock_owned() 期间 Db::exec 不该完成 —— 两把锁没统一?"
|
||||
);
|
||||
|
||||
// 放锁之后必须很快完成(5s 上限只是防挂死)。
|
||||
drop(guard);
|
||||
let done = tokio::time::timeout(Duration::from_secs(5), task)
|
||||
.await
|
||||
.expect("释放 guard 后 Db::exec 仍没完成 —— 锁没被释放?");
|
||||
done.expect("Db::exec 任务 panic").expect("Db::exec 失败");
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn query_rows_reads_pg_catalog() {
|
||||
let db = db().await;
|
||||
|
||||
// 先建一张**探针表**(不依赖平台 schema,失败原因唯一)。
|
||||
// 顺带证明写路径走的 `Db::exec`(持锁)与读路径共用同一个库。
|
||||
db.exec("CREATE TABLE IF NOT EXISTS raw_probe_tbl (f_id text)")
|
||||
.await
|
||||
.expect("建探针表失败");
|
||||
|
||||
// 原始行:不包 `row_to_json`,直接拿 `pglite::Row`。
|
||||
let rows = db
|
||||
.query_rows(
|
||||
"SELECT tablename FROM pg_catalog.pg_tables \
|
||||
WHERE schemaname = 'public' AND tablename = 'raw_probe_tbl'",
|
||||
&[],
|
||||
)
|
||||
.await
|
||||
.expect("query_rows 失败");
|
||||
|
||||
assert_eq!(rows.len(), 1, "pg_catalog 里必须能查到刚建的表");
|
||||
|
||||
// 第一列是 name 类型 ⇒ 按 String 取(pglite 的 Row::get 会做类型转换)。
|
||||
let name: String = rows[0].get::<String>(0).expect("取 tablename 失败");
|
||||
assert_eq!(name, "raw_probe_tbl", "取出来的列值不对");
|
||||
}
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
> 目标 tag:**`v0.5.0`**(`v0.4.0` 已用于「平台包零业务清理」,不能复用)
|
||||
> 提出方:`tdc-rs`(厚业务仓,自带状态类型 / 自带 JSON 归一语义)
|
||||
> 状态:**待平台侧实现**。业务仓本轮只做切换面收拢,不改 `Cargo.toml` 的 tag。
|
||||
> 状态:**已实施并发布 → annotated tag `v0.5.0` 已推 `origin`**(实施记录见 §10)。
|
||||
> 业务仓本轮只做切换面收拢,不改 `Cargo.toml` 的 tag;切换单见 §5。
|
||||
> 前两份需求:`SSPF-PLATFORM-PACKAGE.md`(v0.2.0)、`SSPF-BUSINESS-COMPOSITION.md`(v0.3.0)。
|
||||
|
||||
---
|
||||
@@ -71,25 +72,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<Db>`;
|
||||
`mapper.rs` / `service/crud.rs` / `service/account.rs` / `service/identity.rs` /
|
||||
`controller/health.rs` / `controller/tds_biz.rs` **零改动**。
|
||||
⇒ 业务侧切换只需改 `platform/db.rs` 的 6 个函数 + 状态里注入 `Arc<Db>`;
|
||||
`mapper.rs` / `service/*` / `controller/*` **零改动**(它们已经全部走封装)。
|
||||
|
||||
---
|
||||
|
||||
@@ -245,9 +250,10 @@ impl Db {
|
||||
(或进程级 `OnceLock<Arc<Db>>`,与现有 `process_db_lock()` 同款),
|
||||
`AppState::new` 保持签名不变、默认 `None`,加一个 `with_sspf_db()` builder。
|
||||
4. `src/main.rs`:`boot.state.db.clone()` 注入(`boot.state.db` 是 `Arc<Db>`)。
|
||||
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 +263,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 +300,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 或版本号。
|
||||
|
||||
---
|
||||
|
||||
@@ -321,3 +328,32 @@ impl Db {
|
||||
| 双锁已知局限 | `CHANGELOG.md` v0.3.0 末条、`docs/known-limitations.md` |
|
||||
| 业务仓库操作单一出口 | `tdc-rs/src/platform/db.rs` 的 5 个 `pub` 函数;启动建表在 `tdc-rs/src/tdc/schema.rs` |
|
||||
| P2 装配 / P3 会话桥 | `tdc-rs/src/main.rs`、`tdc-rs/src/tdc/session_bridge.rs` |
|
||||
|
||||
---
|
||||
|
||||
## 10. 实施记录(2026-11-04,tag `v0.5.0`)
|
||||
|
||||
| 需求 | 落地 | 位置 |
|
||||
|---|---|---|
|
||||
| R1 `Db::query_json_raw` | ✅ 持锁 + 包裹 + **不归一**;与 `query_json_params` 共用 `query_json_inner_raw`(SQL 包裹只有一份) | `crates/sspf-store/src/db.rs` |
|
||||
| R2 `Db::query_rows` | ✅ 持锁返回 `Vec<pglite::Row>`;`pglite::Row` 经 `sspf::pglite` 可见 | 同上 |
|
||||
| R3 写路径复用 | ✅ 文档口径写清(`exec` 多语句 / `exec_params` 单语句,两者都持锁);**零新增代码** | 同上 |
|
||||
| R4 `Db::lock_owned()` | ✅ 返回 `OwnedMutexGuard<()>`,基于 `Arc::clone(&self.lock).lock_owned()`;注释写明「持 guard 期间不许再调 `Db::*`」 | 同上 |
|
||||
| R5 `Db::pg()` 指路 | ✅ 注释补入口对照表(raw / 归一 / 原始行 / 写 / 持锁裸句柄) | 同上 |
|
||||
| R6 门面导出 | ✅ 无需新增 re-export;`crates/sspf/Cargo.toml` 与 `VERSION` 断言同步为 `0.5.0` | `crates/sspf/` |
|
||||
| R7 闸门 + 探针 | ✅ **AR20**(raw 不归一 / 共用段 / 8 个公开入口全持同一把锁)+ 反自证 **15/15**;探针 `db_raw_it.rs` **4/4** | `scripts/check-arch.sh` / `crates/tests/tests/db_raw_it.rs` |
|
||||
|
||||
**验收对照(§4)**:A1 **653 passed / 0 failed / 8 ignored**(基线 649 + 新增 4 条)· A2 `check-arch` **25/25**、自证 **15/15** · A3 `verify.sh --smoke` **14/14** ·
|
||||
A4 `db_raw_it` **4/4** · A5 `cargo tree -p sspf` **0 个 `sspf-pack-*`** · A6 `Finish::default()` 路径未改 ·
|
||||
A7 `sspf::VERSION == "0.5.0"` · A8 CHANGELOG 已加并销双锁条 · A9 已知限制 (bq) 已改 · A10 tag 已推 · A11 仓外探针见下。
|
||||
|
||||
**A11 仓外探针**:空 crate 只写 `sspf = { git = "...", tag = "v0.5.0" }`,
|
||||
`cargo check` 通过并调用 `Db::query_json_raw` / `Db::lock_owned()`(探针代码见
|
||||
`HANDOFF.md` §0 的 v0.5.0 段)。
|
||||
|
||||
**两条实现纪律(别再踩)**
|
||||
|
||||
1. 归一逻辑**只准有一处**(`query_json_inner`),raw 侧共用 `query_json_inner_raw`;
|
||||
复制 SQL 包裹会让两条路慢慢漂,而漂的方向永远是「raw 也开始归一」。
|
||||
2. `lock_owned` 的 guard 期间**再调 `Db::*` 必死锁**(tokio Mutex 不可重入)——
|
||||
探针用 `timeout` 断言,不用 sleep 猜。
|
||||
@@ -167,12 +167,12 @@
|
||||
|
||||
|
||||
|
||||
## L. 单进程双 DB 锁与 413 改写(v0.3.0,2026-11-04)
|
||||
## L. 单进程双 DB 锁(**v0.5.0 已销**)与 413 改写(v0.3.0,2026-11-04)
|
||||
|
||||
> 需求与决策见 `docs/SSPF-BUSINESS-COMPOSITION.md` §10.3 / §10.4 / §11.1。
|
||||
> 这两条都是「平台包承载自带状态的厚业务仓」时**主动接受**的边界,不是缺陷回归。
|
||||
|
||||
| # | 限制 | 为什么接受 / 代价 |
|
||||
|---|---|---|
|
||||
| (bq) | **平台与业务各有一把 DB 锁**:业务仓经 `Db::pg()` 拿 `Arc<PGlite>` 后绕过 `sspf_store::Db::lock`,自己的 `process_db_lock()` 与平台那把互不覆盖 ⇒ 并发下「一次业务操作跨多条 SQL」可能与平台 SQL 交错 | 单次 SQL 有 pglite 的 `serial_guard()` 串行化,不会破坏单条查询;本轮只求「同一个库、同一个端口」,统一到 `Db::begin()` 或暴露共享锁出口属 P3。代价:跨平台 / 业务的**多语句事务**不保证整体串行,业务仓需自行持锁;暂不暴露 `Db::lock()` 也避免了「业务持锁误调 `db.*` 死锁」 |
|
||||
| (bq) | ~~**平台与业务各有一把 DB 锁**~~ —— **已由 v0.5.0 解决**:`Db::query_json_raw` / `Db::query_rows` / `Db::lock_owned()` 三个入口都持**同一把** `Db.lock`,业务仓把库操作收进 `Db` 后不再需要自造锁 | v0.3.0 时只暴露了 `Db::pg()`(裸句柄),业务仓只能自己开一把锁 ⇒ 跨平台的多语句事务不保证串行。v0.5.0 补齐入口后,纪律变成「业务 SQL 要么走 `Db::*`,要么在 `lock_owned()` 的 guard 内用裸句柄」;沿用旧的 `pg()` 仍**不**持锁(那是有意的:启动期建表要能跑)。判据 `check-arch.sh` 的 AR20 + 探针 `db_raw_it.rs` 钉住「raw 不归一 / 同一把锁」 |
|
||||
| (br) | **业务侧的 413 / 非空体 405 会被平台改写成信封**:`m_status_rewrite()` 挂在总 Router 上,对任何 405 / 413 无条件改写;tdc 原来的 413 是 axum 默认 `text/plain` | 保持 S25「fallback 在两个平台 layer 之前、catch-all 覆盖面 B 与业务路由」这条硬约束,不给 `Extras` 加「跳过平台层」开关。405 两边形状逐字相同(`code/msg/data`),改写幂等;**413 与带 body 的 405 形状会变**。代价:业务契约里若钉死 413 的裸响应,需在业务 Router 自己的 `route_layer` 上抢先处理 |
|
||||
+157
-15
@@ -66,6 +66,7 @@
|
||||
# 404 兜底会静默错位且测试全绿(S25)。
|
||||
# 🔴 AR17/AR18 是「sspf 标准平台包」(2026-11-04 P0)的边界:平台包里零业务。
|
||||
# 🔴 AR19 是「业务自带状态的可组合装配」(2026-11-04 P1)的边界:装配链仍然只有一份。
|
||||
# 🔴 AR20 是「业务仓库操作共用同一把锁」(2026-11-04 v0.5.0)的边界:raw 入口不归一、不造第二把锁。
|
||||
|
||||
set -u
|
||||
|
||||
@@ -101,7 +102,7 @@ skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; }
|
||||
|
||||
usage() {
|
||||
echo "用法: bash scripts/check-arch.sh [--self-test]"
|
||||
echo " 静态检查 crate 依赖纪律(AR1–AR19)与内存红线(MEM1–MEM2)"
|
||||
echo " 静态检查 crate 依赖纪律(AR1–AR20)与内存红线(MEM1–MEM2)"
|
||||
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错"
|
||||
}
|
||||
|
||||
@@ -935,12 +936,116 @@ PY
|
||||
fi
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- AR20
|
||||
# **库入口的锁与归一纪律**(2026-11-04 v0.5.0:`query_json_raw` / `query_rows` / `lock_owned`)。
|
||||
#
|
||||
# 🔴 **为什么需要**:新增的 raw 入口是为了让厚业务仓(`tdc-rs`)把库操作收进
|
||||
# **同一把 `Db.lock`**。它一旦被「顺手加上归一」或「自己造第二把锁」,
|
||||
# 后果都不是报错,而是**静默变形状 / 静默并发交错**:
|
||||
# - raw 路径混进 `normalize_json_keys` ⇒ 业务仓 132 条端点的 JSON 键漂移;
|
||||
# - 新入口不持 `self.lock` ⇒ 平台与业务各开一把锁,并发写同一个 PGlite 交错。
|
||||
#
|
||||
# 判据(扫 `crates/sspf-store/src/db.rs` 的函数体):
|
||||
# 1. `query_json_raw` 里**不许**出现 `normalize_json_keys`;
|
||||
# 2. `query_json_raw` **必须**走共用的 `query_json_inner_raw`(不许复制一份 SQL 包裹),
|
||||
# 且**不许**调会归一的 `query_json_inner`;
|
||||
# 3. 共用段 `query_json_inner_raw` 自身也不许归一(否则两条路都归一了);
|
||||
# 4. 所有公开库入口都持 `self.lock`;`lock_owned` 必须基于 `self.lock`(不是第二把锁)。
|
||||
check_ar20() {
|
||||
local file="$ROOT/crates/sspf-store/src/db.rs"
|
||||
[ -f "$file" ] || { skip "AR20 db.rs 不存在"; return; }
|
||||
local hits
|
||||
hits="$(python3 - "$file" <<'PY'
|
||||
import re
|
||||
import sys
|
||||
|
||||
src = open(sys.argv[1], encoding="utf-8").read()
|
||||
|
||||
|
||||
def body(name):
|
||||
"""取 `<[pub] async fn> <name>` 的函数体(花括号配平)。
|
||||
|
||||
🔴 **允许不带 `pub`**:`query_json_inner_raw` 是私有的共用段,
|
||||
只认 `pub async fn` 会把它判成「不存在」⇒ 尺子自己先红。
|
||||
"""
|
||||
m = re.search(r"(?:\bpub )?\basync fn " + name + r"\b", src)
|
||||
if not m:
|
||||
return None
|
||||
i = src.find("{", m.end())
|
||||
if i < 0:
|
||||
return None
|
||||
depth, j = 0, i
|
||||
while j < len(src):
|
||||
c = src[j]
|
||||
if c == "{":
|
||||
depth += 1
|
||||
elif c == "}":
|
||||
depth -= 1
|
||||
if depth == 0:
|
||||
return src[i : j + 1]
|
||||
j += 1
|
||||
return None
|
||||
|
||||
|
||||
bad = []
|
||||
|
||||
raw = body("query_json_raw")
|
||||
if raw is None:
|
||||
bad.append("raw-missing: 找不到 async fn query_json_raw")
|
||||
else:
|
||||
if "normalize_json_keys" in raw:
|
||||
bad.append("raw-normalizes: query_json_raw 里出现 normalize_json_keys(raw 必须不归一)")
|
||||
if "query_json_inner_raw" not in raw:
|
||||
bad.append("raw-not-shared: query_json_raw 没走共用的 query_json_inner_raw(SQL 包裹会漂成两份)")
|
||||
if re.search(r"query_json_inner\s*\(", raw):
|
||||
bad.append("raw-goes-through-normalizing-path: query_json_raw 调了 query_json_inner(那条会归一)")
|
||||
|
||||
shared = body("query_json_inner_raw")
|
||||
if shared is None:
|
||||
bad.append("shared-missing: 找不到 query_json_inner_raw(raw 与归一必须共用同一段)")
|
||||
elif "normalize_json_keys" in shared:
|
||||
bad.append("shared-normalizes: query_json_inner_raw 里出现 normalize_json_keys")
|
||||
|
||||
for fn in (
|
||||
"query_json",
|
||||
"query_json_params",
|
||||
"query_json_raw",
|
||||
"query_rows",
|
||||
"exec",
|
||||
"exec_params",
|
||||
"scalar_text",
|
||||
"begin",
|
||||
):
|
||||
b = body(fn)
|
||||
if b is None:
|
||||
bad.append(f"lock-fn-missing: 找不到 {fn}")
|
||||
elif "self.lock" not in b:
|
||||
bad.append(f"lock-missing: {fn} 没有持 self.lock(并发会绕过平台串行域)")
|
||||
|
||||
lo = body("lock_owned")
|
||||
if lo is None:
|
||||
bad.append("lock-owned-missing: 找不到 async fn lock_owned")
|
||||
elif "self.lock" not in lo:
|
||||
bad.append("lock-owned-different: lock_owned 没基于 self.lock(等于造了第二把锁)")
|
||||
|
||||
for b in bad:
|
||||
print(b)
|
||||
PY
|
||||
)"
|
||||
if [ -z "$hits" ]; then
|
||||
ok "AR20 库入口纪律(raw 不归一 / 共用包裹段 / 全部持同一把 lock)"
|
||||
else
|
||||
bad "AR20 库入口纪律被破坏(归一漂移或第二把锁):"
|
||||
printf '%s\n' "$hits" | sed 's/^/ /'
|
||||
fi
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------- 反自证
|
||||
# 🔴 永远返回「干净」的尺子 = 没有尺子。造明知违规的输入,必须被抓到。
|
||||
self_test() {
|
||||
local rc=0
|
||||
|
||||
echo "── 反自证 1/14:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
|
||||
echo "── 反自证 1/15:造一个依赖越界的假 pack,AR2 必须报 ❌ ──"
|
||||
local tmp="$ROOT/packs/__arch_selftest__"
|
||||
mkdir -p "$tmp"
|
||||
cat > "$tmp/Cargo.toml" <<'TOML'
|
||||
@@ -970,7 +1075,7 @@ TOML
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 2/14:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
|
||||
echo "── 反自证 2/15:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **为什么必须自证 AR9**:它的判据是 `grep 目录`。
|
||||
# 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。
|
||||
@@ -1009,7 +1114,7 @@ TOML
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 3/14:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
|
||||
echo "── 反自证 3/15:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_`
|
||||
# 和 `= EntitySpec {`,PACK1 就必须红。
|
||||
@@ -1035,7 +1140,7 @@ RS
|
||||
echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)"
|
||||
fi
|
||||
|
||||
echo "── 反自证 4/14:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
|
||||
echo "── 反自证 4/15:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──"
|
||||
local pfile="$CRATES/sspf-plugin/Cargo.toml"
|
||||
if [ -f "$pfile" ]; then
|
||||
cp "$pfile" "$pfile.bak"
|
||||
@@ -1056,7 +1161,7 @@ RS
|
||||
echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)"
|
||||
fi
|
||||
|
||||
echo "── 反自证 5/14:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
|
||||
echo "── 反自证 5/15:往平台层塞 crate::platform::compat,AR10 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **必须自证 AR10**:它的判据是「扫平台层目录找契约面引用」。
|
||||
# 目录名写错 / 路径拼错 ⇒ 扫描永远返回空 ⇒ **永远"通过"** ⇒ 虚假安全感。
|
||||
@@ -1092,7 +1197,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 6/14:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
|
||||
echo "── 反自证 6/15:往契约面底座塞 use super::system,AR11 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴🔴 **M7 起底座只有一处**:真源 `crates/sspf-compat-core/src/helper.rs`
|
||||
# (转发壳 `src/backend/src/platform/compat/helper.rs` 已随 M7 删除)。
|
||||
@@ -1115,7 +1220,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 7/14:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
|
||||
echo "── 反自证 7/15:往壳里写 crate::platform::,AR15 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **必须自证 AR15**:删掉 `platform/` 转发壳之后,旧路径就**没有编译器**兜底了
|
||||
# —— 只要有人重建壳目录并把 import 改回去,**一切照常编译、测试照常全绿**,
|
||||
@@ -1157,7 +1262,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 8/14:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
|
||||
echo "── 反自证 8/15:给域包塞一条未授权的跨包依赖,AR12 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **为什么必须自证 AR12**:它的判据是「读 Cargo.toml 找 sspf-compat-* 依赖」。
|
||||
# 若 grep 模式写错(包名含连字符/下划线混用)⇒ 永远扫不到依赖 ⇒
|
||||
@@ -1184,7 +1289,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 9/14:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
|
||||
echo "── 反自证 9/15:给执行层塞一个越界依赖 + 一条业务包引用,AR13 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **必须自证 AR13**:它的判据是「读 Cargo.toml + grep 源码」。
|
||||
# 两种失效模式都得堵:
|
||||
@@ -1217,7 +1322,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 10/14:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
|
||||
echo "── 反自证 10/15:给适配层塞一个越界依赖 + 一条业务包引用,AR14 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **必须自证 AR14**:它是 M6 新增的判据,守护的是「全仓唯一知道全部包的
|
||||
# 汇聚点」的依赖面。两种失效模式都得堵:
|
||||
@@ -1250,7 +1355,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 11/14:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
|
||||
echo "── 反自证 11/15:内核加回 [[bin]] + 塞回 tests/*.rs,AR16 必须两处都报 ❌ ──"
|
||||
#
|
||||
# 🔴 **必须自证 AR16**:它的三条判据全是「文件/目录在不在」——
|
||||
# 路径写错(比如把 $KERNEL 拼成别的名字)⇒ 永远判「没问题」⇒
|
||||
@@ -1284,7 +1389,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 12/14:往内核塞回一条 sspf-pack 依赖,AR17 必须报 ❌ ──"
|
||||
echo "── 反自证 12/15:往内核塞回一条 sspf-pack 依赖,AR17 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **2026-11-04 清理**:依赖清单里已经没有 pack 行可改 ⇒ 旧探针(去掉
|
||||
# `optional = true`)找不到锚点,自证会**假红**。改成「注入一整条硬依赖」,
|
||||
@@ -1309,7 +1414,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 13/14:往门面里塞一句业务字面量,AR18 必须报 ❌ ──"
|
||||
echo "── 反自证 13/15:往门面里塞一句业务字面量,AR18 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **为什么自证 AR18**:它扫的是「门面源码里的业务名」。目录写错 / 正则写错
|
||||
# ⇒ 永远空 ⇒ 永远"通过"。这条自证保证「平台包里零业务」不是一句口号。
|
||||
@@ -1332,7 +1437,7 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 14/14:往 routes.rs 塞第二处 .layer(catch_all()),AR19 必须报 ❌ ──"
|
||||
echo "── 反自证 14/15:往 routes.rs 塞第二处 .layer(catch_all()),AR19 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **为什么自证 AR19**:它数的是「非注释代码里 catch_all 层的条数」。
|
||||
# 正则写错 / 扫描面写错 ⇒ 永远数到 1 ⇒ 永远"通过"。
|
||||
@@ -1356,6 +1461,42 @@ RS
|
||||
rc=1
|
||||
fi
|
||||
|
||||
echo "── 反自证 15/15:往 query_json_raw 里塞 normalize_json_keys,AR20 必须报 ❌ ──"
|
||||
#
|
||||
# 🔴 **为什么自证 AR20**:它读的是「函数体里有没有某个标识符」。
|
||||
# 正则写错 / 取错函数体 ⇒ 永远判干净 ⇒ raw 某天被顺手加上归一,
|
||||
# 业务仓 132 条端点的键就静默漂移,而且**测试可能全绿**(只要没人比键名)。
|
||||
local a20file="$ROOT/crates/sspf-store/src/db.rs"
|
||||
local a20ok=0
|
||||
if [ -f "$a20file" ]; then
|
||||
cp "$a20file" "$a20file.ar20bak"
|
||||
python3 - "$a20file" <<'PY'
|
||||
import re
|
||||
import sys
|
||||
|
||||
path = sys.argv[1]
|
||||
src = open(path, encoding="utf-8").read()
|
||||
m = re.search(r"pub async fn query_json_raw\b", src)
|
||||
i = src.find("{", m.end())
|
||||
# 在函数体开头注入一行「归一」—— 这正是本题最怕的退化。
|
||||
src = src[: i + 1] + "\n let _ar20_probe = normalize_json_keys;" + src[i + 1 :]
|
||||
open(path, "w", encoding="utf-8").write(src)
|
||||
PY
|
||||
local a20before=$FAIL
|
||||
check_ar20 >/dev/null 2>&1
|
||||
local a20caught=0
|
||||
[ "$FAIL" -gt "$a20before" ] && a20caught=1
|
||||
mv "$a20file.ar20bak" "$a20file"
|
||||
FAIL=$a20before
|
||||
[ "$a20caught" -eq 1 ] && a20ok=1
|
||||
fi
|
||||
if [ "$a20ok" -eq 1 ]; then
|
||||
echo "✅ 反自证通过:AR20 抓到了 raw 路径里的归一"
|
||||
else
|
||||
echo "❌ 反自证失败:AR20 没抓到 raw 路径里的 normalize_json_keys ⇒ 尺子是假的"
|
||||
rc=1
|
||||
fi
|
||||
|
||||
return $rc
|
||||
}
|
||||
|
||||
@@ -1382,6 +1523,7 @@ check_ar16
|
||||
check_ar17
|
||||
check_ar18
|
||||
check_ar19
|
||||
check_ar20
|
||||
check_pack1
|
||||
check_mem1
|
||||
check_mem2
|
||||
|
||||
Reference in new issue
Block a user