- 新增 sspf-contract(契约类型,不含 axum)、sspf-store(db/config,不认识 HTTP)、
sspf-sdk(业务包唯一依赖)与 packs/asset 样板包(可独立编译)
- 内核 platform/{envelope,entity,menu,ids,db,config}.rs 改为 re-export,引用路径零变化
- jnpf.rs → face_b.rs,9 处标识符改名;契约字面量(jnpf-origin / jnpfKey)刻意保留
- 新增 check-arch / check-naming / mem-budget 三道闸门;rust-toolchain 锁 1.95.0
- 影响:行为零变化(240 测试 / 九闸全绿 / 空载 7 MB),Profile 从 guard 迁到 config 断开假依赖
977 lines
86 KiB
Markdown
977 lines
86 KiB
Markdown
# 决策记录(ssw-jnpf-lite-rust · 分支级)
|
||
|
||
> 本文件是 **`ssw-jnpf-lite-rust` 从零实现全过程中控制器(controller)逐条作出的裁决**,
|
||
> 格式统一为「**裁决了什么 — 为什么 — 判错了的代价**」。
|
||
> 它是**代码之外的「为什么」**:`docs/contract.md` 说什么必须成立,本文件说**为什么这样实现**、
|
||
> **哪些分歧被有意留下**、**哪些判断是带风险的**。
|
||
|
||
🔴 **来源**:SDD 过程 ledger(`.superpowers/sdd/ssw-jnpf-lite-rust-v1/progress.md`)—— 那份 ledger 是
|
||
**git-ignored 的过程草稿**,交付时已清理;本文件是它的**受版本控制的正本**(只保留裁决正文,
|
||
不含逐条验证输出与任务流水)。
|
||
|
||
**编号**:
|
||
- `P##` = 逐任务实施期的裁决(Plan 阶段起的第 P 批);
|
||
- `F##` = **最终整体评审**(Final review)的裁决 —— 那一轮把 15 条评审发现压成 11 条裁决 +
|
||
后续修复轮追加的 F11/F12。
|
||
|
||
**配套阅读**:
|
||
- 契约(权威)→ [`docs/contract.md`](contract.md)
|
||
- 交接文档(设计 / 四门 / 风险)→ [`../HANDOFF.md`](../HANDOFF.md)
|
||
- 分支级已知限制(被「接受/挂起」的东西)→ [`known-limitations.md`](known-limitations.md)
|
||
|
||
---
|
||
|
||
**Ruling F1(I-2 的机制陈述被推翻,但加固照做)** ——
|
||
评审的因果链(npm 只向直接子进程发信号 ⇒ SIGTERM 到不了 vite)**实测不成立**:
|
||
`kill -TERM <npm pid>` ⇒ npm 与 vite 双双死、5173 被释放。
|
||
但 runbook 承诺的「不会在 5173 上留残进程」应当**无条件**为真 ⇒ 失败分支补 `kill_ports 5173`。
|
||
**代价**:一行;`kill -9` 只作用于**本仓自己的 5173**(`kill_ports` 的端口清单硬约定)。
|
||
|
||
**Ruling F2(M-10 不是契约缺陷)** ——
|
||
契约全文对「原子/事务/atomic」**零提及** ⇒ 契约只要求「单次调用原子」。
|
||
M-10 是 known-limitation (b)(「`Db` 没有跨调用持锁的公开接口 ⇒ 多步写不是单一事务」,
|
||
P59/P71 已裁决)的**具体实例**,不是新缺陷 ⇒ 不改代码,把具体场景写进 (b) 的代价栏。
|
||
**代价**:`user_save` 步骤 2 失败 ⇒ 用户行已提交、角色关系没写 ⇒ 响应 `code=400` 而库里已有该用户。
|
||
|
||
**Ruling F3(M-6 只能改文档)** ——
|
||
契约 §6.1(line 448)**逐字定死** `{token, expiresIn: 7200, tokenTypeName:'bearer'}` ⇒ 代码不许改。
|
||
`session.rs` 无 TTL ⇒ token 实际寿命 = **进程寿命**;`expiresIn: 7200` 是**继承自 JNPF/Sa-Token 的语义**、非强制值。
|
||
⇒ 改文档 + known-limitations 新增一行。**代价**:文档要如实说明「7200 不会真的到期」。
|
||
|
||
**Ruling F4(M-1 的三处文档断言是假的)** ——
|
||
`%zz` 实测 ⇒ HTTP 200 + 正常信封 ⇒ known-limitations (l) 的「纯文本 400」**不存在**。
|
||
⇒ **就地改写**该行(先例:(u) 就是这么处理的:标「已推翻」+ 给实测),并同步 `README.md` / `HANDOFF.md`。
|
||
**代价**:无(去掉一条不存在的限制)。
|
||
|
||
**Ruling F5(I-3:默认绑 `127.0.0.1`,`BIND_ADDR` 可覆盖)** ——
|
||
全部文档写的都是 `http://127.0.0.1:30010`,代码却绑 `0.0.0.0` ⇒ **文档与代码不符**;
|
||
且「admin/123456 + 口令永不过期 + 全网卡监听」= 局域网可直连的弱口令服务 ⇒ 默认改回 `127.0.0.1`,
|
||
新增 env `BIND_ADDR`(非法值回落 `127.0.0.1`,**朝安全方向**回落)。
|
||
**代价**:容器/反代场景要显式 `BIND_ADDR=0.0.0.0`(写进 `.env.example`)。
|
||
|
||
**Ruling F6(M-8:413 归一为信封,传输状态码保留)** ——
|
||
契约 §2「没有第三种形状」管的是**信封**;§6.5 对 404/405 采取「**传输状态码保留 + body 归一为信封**」,
|
||
且**未覆盖 413** ⇒ 照 405 的先例:**HTTP 413 + `{code:413,msg:'请求体过大',data:null}`**。
|
||
🔴 `msg` 是**本仓自定**(契约未规定 413 的文案)⇒ 记在此处,契约不因此改动。
|
||
|
||
**Ruling F7(M-9:优雅停机)** ——
|
||
`run.sh stop` 发 SIGTERM → 1s → SIGKILL;后端**忽略 SIGTERM** ⇒ **每一次 stop 都是 SIGKILL 掉嵌入式 PG**
|
||
(下次启动要 crash recovery,数据目录还留 `postmaster.pid`)。
|
||
⇒ 装 SIGTERM/SIGINT 处理 → `axum::serve(...).with_graceful_shutdown(...)` → 退出前调 pglite 的
|
||
`PGlite::shutdown(&self)`(pglite-rs 0.2.7 `src/db.rs:444` 确有此方法)。
|
||
**代价**:`main.rs`/`db.rs` 多 ~20 行;tokio 的 `signal` feature 已在 `features=["full"]` 里 ⇒ **不新增依赖**。
|
||
|
||
**Ruling F8(M-7 挂起)** ——
|
||
口令比对非常量时间**不是契约缺陷**、也**不是文档与代码不符**;HTTP 上对 md5-hex 比对的计时攻击收益可忽略;
|
||
而这轮要在**最后一道门**上动**最敏感的文件**(`auth.rs` 的登录路径)⇒ 风险 > 收益。
|
||
⇒ 挂起,记为 known-limitations 新行(写清代价与将来要改的形状)。
|
||
**代价**:留下一个理论上的计时侧信道(实际不可利用)。
|
||
|
||
**Ruling F9(M-11 / M-12 已覆盖)** —— 分别落在 (f) / (e) 内 ⇒ 不新增行,只把具体例子补进去。
|
||
|
||
**Ruling F10(契约在分支内被改过 13 次这件事本身要记档)** ——
|
||
评审说「契约从未被修改」**不准确**:`git log --oneline -- docs/contract.md | wc -l` = **14**
|
||
(初次提交 `0aed12a` 之后 13 次修订:`6b8c30e 4a7805a c927632 1db2f0a 0de161d f44b300 28de290
|
||
349aeef 0fef2fb aa45da8 a77d8c1 15469ea c055e1b`)。
|
||
评审自己核过其中一次(`c055e1b` 把 DB 报错的措辞**朝 react 参照物**修正)⇒ 修订都是**收紧**而非放松。
|
||
⇒ 合规判据是**最终的 §编号正文**;这一点记在此处,让轨迹可见。**代价**:无。
|
||
|
||
**Ruling P1 — 官方 DDL 可逐字使用。** 官方 JNPF dump 里 7 张 `base_*` 表除 `f_id`/`f_tenant_id` 外**没有其它 NOT NULL 列**,
|
||
整份 dump **零 UNIQUE 约束** ⇒ 直接逐字入库,不改列名/类型/约束。
|
||
代价:若实现时发现某列有隐式 NOT NULL,插入会报 23502 —— 表现为运行期错误,不是契约错误。
|
||
|
||
**Ruling P2 — 禁止 `SELECT *`,全部显式列投影。** 官方 DDL 有 30~60 列,react 版库(TypeORM `synchronize`)只有 entity 的列。
|
||
显式投影让本仓后端**能开 react 建出来的库**("两版后端可开同一个库"要成立就必须这样),
|
||
且响应 JSON 与 react 逐字相同。代价:每个查询要多写列名;新增列要同步改 spec。
|
||
|
||
**Ruling P3 — `PGLITE_DIR=memory://` ⇒ `PGlite::open_temp()`。** pglite-rs 0.2.7 **没有**内存模式,
|
||
`PGlite::open()` 只接受路径。项目 `CLAUDE.md` 里"纯内存"那句与现实不符 ⇒ 实现按 `open_temp()` 落地,
|
||
并**在 `CLAUDE.md` 里更正那句话**(Task 12 一并改)。代价:`open_temp()` 是临时目录,不是纯内存,进程退出即丢。
|
||
|
||
**Ruling P4 — 拆 `src/lib.rs` + `src/main.rs`。** lib 供集成测试 `use ssw_jnpf_lite_rust::…`;
|
||
bin 是薄壳(`fn main() { ssw_jnpf_lite_rust::run() }`)。计划文字只提了 `main.rs` ⇒ 按此裁决加 `lib.rs`。
|
||
代价:多一个文件。不影响 HTTP 契约。
|
||
|
||
**Ruling P5 — `resolve_project_dir()` 锚点改为 `src/backend/db/schema.sql` + 根 `Cargo.toml`。**
|
||
计划文字提到 `static/` 锚点,但本仓**没有** `static/`(前端跑 Vite `:5173`)⇒ 锚点无效。
|
||
代价:无。锚点文件换成了真实存在的两个。
|
||
|
||
**Ruling P6 — 时间列:存 UTC 朴素、读出投影 ISO `...Z`。** 官方 DDL 是 `TIMESTAMP(0) WITHOUT TIME ZONE`(秒精度),
|
||
react entity 声明的是 `timestamptz`。用 `TIMESTAMP(0)` 口径 + `to_char(...)||'Z'` 投影,
|
||
与 react 的 ISO 串(`2026-01-01T00:00:00.000Z`)**不完全相同**(无毫秒)。
|
||
冒烟断言不依赖时间格式 ⇒ 可接受。代价:与 react 的时间串差一个毫秒位。
|
||
|
||
**Ruling P7 — 业务表不加 `f_tenant_id`。** react 版 3 张业务表 entity 没有该列 ⇒ 加了会让
|
||
"两版后端开同一个库"的 INSERT 报列不存在。`base_*` 全部保留 `f_tenant_id`(官方 DDL 有)。
|
||
代价:业务表与 `base_*` 口径不一致 —— 这是刻意的(对齐 react)。
|
||
|
||
**Ruling P8 — `base_authorize` / `base_role_relation` / `base_user_relation` 允许插入时
|
||
`f_creator_time` 等官方列留空。** 官方 DDL 这些列可空 ⇒ 不必全填。省事且不违反契约。
|
||
|
||
**Ruling P9 — User Save 的响应剥掉 `password`(唯一一处与 react 刻意偏离)。**
|
||
react 的 `saveUser` 直接返回 TypeORM 的 saved entity,**带着 `password` 列的 md5 摘要**。
|
||
该摘要可被前端 `cipher.ts` 重新加密成**合法登录密文** ⇒ 响应里出现它等于泄露凭据。
|
||
R1.6(口令不得外泄)**优先于**与 react 的逐字一致 ⇒ 本仓 List 与 Save **都**剥。
|
||
代价:与 react 的 Save 响应少一个字段;前端 `UserManage` 从不读 `password` ⇒ 无功能影响。
|
||
(已写进 `docs/contract.md` §7.7 偏离表。)
|
||
|
||
**Ruling P10 — 授权端点**忽略 body 里的 `objectType`,一律写 `f_object_type='role'`。
|
||
react 的 `AuthorizeController.save` **只读 `body.module`**,从不读 `body.objectType`;
|
||
落库的 `objectType` 是 `saveRoleModules` 里**硬编码**的 `'role'`。
|
||
原计划文字说"objectType 必须小写,否则写不进去" —— 对 react **不成立**(它根本不看这个字段)。
|
||
本仓按 react 实际行为实现:忽略该字段、不校验大小写。
|
||
代价:与 JNPF 官方语义(官方会静默忽略大写)**恰好一致**,无需额外校验。
|
||
|
||
**Ruling P11 — §7 整节按 react 源码逐字重写(2026-10-25)。**
|
||
读完 `sys.service.ts` / `auth.service.ts` / `authorize.controller.ts` / 三个业务 service 后,
|
||
发现原 §7 有 9 处与源码不符,全部修正(记录在 `docs/contract.md` §7 的各条括号里):
|
||
User 更新也查重 / User 更新**总是**覆盖 `isAdministrator` 与 `organizeId` /
|
||
Role 更新**不**查重**不**碰 `sortCode`·`enabledMark` / Role 删除**不**带 `f_item_type` 过滤 /
|
||
Module 删除**不**带 `f_object_type` 过滤 / Organize·Module **不写** `f_creator_user_id` /
|
||
业务模块保存有**三条**路径(无 id / 有 id 但行不存在 / 有 id 且存在)/
|
||
`roleNames` 查不到就**跳过**(数组可能比 `roleIds` 短)。
|
||
|
||
**Ruling P12 — 业务表只有 `f_delete_mark` 带 DB 默认值 `DEFAULT 0`。**
|
||
react entity 上 `deleteMark` 有 `default: 0`;§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)
|
||
靠这个默认值补出 `0`,其余列"body 没给 ⇒ NULL" ⇒ **其它业务列一律不得有默认值**。
|
||
🔴 **本条已被 P18 部分推翻**:`book_shop_book.f_stock` 在 react 的 entity 上**也有** `default: 0`,
|
||
⇒ 它也带 DB 默认值。P12 当时只看了 `deleteMark` 就推广到全部列,属推理漏洞(已由 P18 修正)。
|
||
|
||
**Ruling P13 — 未捕获异常(panic / DB 报错)也走业务信封:HTTP 200 + `code=400` + `msg='系统异常,请联系管理员'`。**
|
||
react 的全局 `ActionResultFilter` 兜底分支就是这个形状(真实堆栈只进服务端日志,不外泄)。
|
||
Rust 侧若放任 axum 默认的 **HTTP 500 空 body**,前端 `request.ts` 的错误分支只会拿到
|
||
"Request failed with status code 500",**丢掉了 `msg`** ⇒ 与 react 行为不一致。
|
||
⇒ 必须在链尾装 catch-all 中间件(§6.5 / §10 第 6 步)。
|
||
同时把 **405 的 HTTP 状态定死为 405**(保留 `Allow` 头)——
|
||
react 侧 Express 路由对错误方法返 404,但前端从不发错方法 ⇒ 不在契约面上;
|
||
定成 405 是「传输层状态码保留」,比掉进 R1.2 的 HTTP 200 规则更清楚。
|
||
代价:多一个中间件;契约面(前端实际会发的请求)零影响。
|
||
|
||
**Ruling P14 — `src/backend/src/lib.rs` 的唯一 owner 是 Task 4。**
|
||
Task 0 评审发现「`lib.rs` 声明完毕不再改」与「§9 要求 `AppState` 落在 `lib.rs`(或新 `state.rs`)」有潜在冲突:
|
||
两条路都会逼后续任务改 `lib.rs`,两个任务并行改就撞 CLAUDE.md 红线 8(同文件并行 Edit = last-writer-wins)。
|
||
裁决:`AppState` 放**独立 `src/backend/src/state.rs`**;`lib.rs` 只加**一行** `pub mod state;`,
|
||
由 **Task 4(ids + session)** 一次性落地 —— 它是 `AppState` 三个依赖(`Config`/`Db` 来自 Task 3、
|
||
`SessionStore` 来自 Task 4)里最后就位的。Task 1/2/3 **一律不许碰 `lib.rs`**;Task 5+ 只读不写。
|
||
代价:多一个文件(`state.rs`);换来 `lib.rs` 全程只有一个写入者。
|
||
|
||
**Ruling P15 — `decrypt_to_md5` 返回 `None` ⇒ 登录端点回 `400 '账号或密码错误'`(与 react 同形)。**
|
||
react 的 `decryptToMd5` 遇非法 hex / 非法填充返回**空串** ⇒ 与库里 md5 比对不等 ⇒ 抛 `账号或密码错误`。
|
||
⇒ 本仓的 `None` 必须映射到**同一条消息**,不另造「密文格式错误」。
|
||
同时**不加**「解密结果长度必须 == 32」的额外校验(react 没有,加了只会与 react 不一致)。
|
||
Task 1 实现者的 concern①/② 就按这条关掉。
|
||
|
||
**Ruling P16 — 种子失败 ⇒ 打印人话错误 + `exit 1`(启动期 fail-fast),不学 react 的「warn 后继续跑」。**
|
||
react 的 `SeedService.onModuleInit` 是 try/catch + `logger.warn`(因为它是 NestJS 容器里已挂载的应用,退不出去)。
|
||
本仓是**单二进制**:种子失败 ⇒ 没有 admin 用户 ⇒ 整个应用 100% 不可用 ⇒ 半死不活地跑着只会让人对着 403 猜。
|
||
与 §10 第 3 步「白名单自检不过 ⇒ 秒退」同一处置。
|
||
这条**不在 HTTP 契约面上**(服务要么正常起来,要么根本不起来)⇒ 不影响与 react 的契约对齐。
|
||
|
||
**Ruling P17 — `ensure_base()` 的三处「不过滤软删」必须逐字照抄 react。**
|
||
读 `seed.service.ts` 源码后发现 react 的三处查询**都不带 `deleteMark` 条件**:
|
||
① 判「内置角色已存在」查 `base_role` 全部行(软删的 `admin` 角色也算存在 ⇒ 不补);
|
||
② 判「内置菜单已存在」查 `base_module` 全部行(软删的也不复活);
|
||
③ 判「admin 角色已授权」查 `base_authorize` 全部行(软删的授权行也算已授权 ⇒ 不补)。
|
||
另:`f_object_id='admin'`(**账号名,不是 UUID**)也照抄。
|
||
⇒ 规格 §8.6 已按源码逐字重写。
|
||
|
||
**Ruling P18 — 业务表 DDL 逐字对齐 react 的 TypeORM entity(2026-10-25,Task 3 派发前发现)。**
|
||
读 react 的三个 business entity 源码,发现计划的业务表 DDL 有 3 处与 react 不一致:
|
||
① `demo_item.f_status` react 是 **varchar(32)**,计划写 50;
|
||
② `book_shop_book.f_isbn` react 是 **varchar(32)**,计划写 50;
|
||
③ `book_shop_book.f_stock` react 的 entity 上有 **`default: 0`**(⇒ TypeORM 建的库带 `DEFAULT 0`),
|
||
计划却写「业务表只有 `f_delete_mark` 有 DB 默认值」⇒ 计划自己的 P12 推理漏了 stock。
|
||
③ 是**真契约分歧**:§7.6 路径 2(带 id 但行不存在 ⇒ 用该 id 新建)在 react 里 `f_stock` 得 **0**,
|
||
按计划实现会得 **NULL** ⇒ 响应不同。
|
||
裁决:业务表 DDL **逐字照抄 react entity**(列宽 + 默认值都照抄)——
|
||
理由是「两版后端可开同一个库」要求两张表是**同一张表**,否则 react 的 `synchronize` 会 `ALTER` 掉我们建的列。
|
||
⇒ 规格 §5.1 已补业务表逐字 DDL 表;§7.6 路径 2 已把 `f_stock` 改成「没给 ⇒ 0」。
|
||
代价:`f_status` / `f_isbn` 收窄到 32 —— react 的库本来就是 32,收窄零风险。
|
||
|
||
**Ruling P19 — 去掉 release 的 `panic = "abort"`,改 `unwind`;catch-all 中间件自己手写,不引新依赖。**
|
||
发现 P13(panic ⇒ HTTP 200 + `code=400`)与 Task 0 在根 `Cargo.toml` 里定的
|
||
`[profile.release] panic = "abort"` **直接冲突**:
|
||
`panic = "abort"` 下 `std::panic::catch_unwind` **抓不到 panic**(进程直接 abort),
|
||
⇒ panic 时客户端拿到的是**连接重置**(连 HTTP 500 都没有),比 axum 默认还差。
|
||
而 react 侧 Node 抛异常**不会**终止进程(NestJS 全局 filter 接住)⇒ 与 react 对齐必须是「接住」不是「崩掉」。
|
||
裁决:
|
||
① 根 `Cargo.toml` 去掉 `panic = "abort"`(回到默认 `unwind`);
|
||
② catch-all 中间件**手写**(约 25 行,`Pin<Box<F>>` + `std::panic::catch_unwind`,**无需 `unsafe`**)
|
||
⇒ **不引 `tower` / `tower-http` / `futures`**(CLAUDE.md 的依赖集由 Task 0 锁死,加依赖要动根 Cargo.toml 重跑全量编译);
|
||
③ 「DB 报错」那条路**不走 panic 捕获** —— handler 返回 `Result`,`Err` 在**类型层**映射成
|
||
`fail(400, "系统异常,请联系管理员")`(普通 `match`,零依赖)。
|
||
代价:release 二进制略大(unwind 表 + 栈回溯信息);换来 panic 不再杀进程。
|
||
落地:Task 10 brief 已写明中间件骨架。
|
||
|
||
**Ruling S11 — 集成测试**全文件共用一个 `Db` 实例**(pglite 进程级单实例约束)。**
|
||
pglite-rs 0.2.7 的 `OPEN` / `BOOTED` 是**进程级全局标志**:第二次 `open()` ⇒ `Error::AlreadyOpen`,
|
||
关掉再开 ⇒ `Error::ReopenUnsupported`。
|
||
Rust test harness 把**同一个 `tests/*.rs` 里的所有 `#[tokio::test]` 放进同一个进程**
|
||
⇒ 原 brief 里「每个测试各开一个临时库 / 用不同子目录隔离」的做法**必然在第二个测试炸**。
|
||
裁决:
|
||
① 每个 `tests/*.rs` 用一个 `tokio::sync::OnceCell<Db>` 起一次 `Db::open_temp()`,全文件共享;
|
||
② `cargo test` 每个 `tests/*.rs` 是**独立二进制 = 独立进程** ⇒ `seed_it.rs` / `sys_it.rs` / `crud_it.rs`
|
||
各自一个库,**互不干扰** ✅(这正好把三组集成测试的库隔离开);
|
||
③ 测试间数据隔离靠**专属账号/编码/名称** + 需要干净前置条件时**自己先 `DELETE`**,
|
||
**不依赖测试执行顺序**。
|
||
落地:Task 5 / 8 / 9 brief 已追加 S11 段。
|
||
|
||
**Ruling P20 — 承认两处「畸形密文」角落与 react 不同,不追平(2026-10-25,核对 react `cipher.ts` 时发现)。**
|
||
react 的 `decryptToMd5` 有两处**宽容**行为,本仓是**严格**的:
|
||
① `CryptoJS.enc.Hex.parse` 会**静默剔除**非 hex 字符 ⇒ `zz<合法密文>` 仍能解出;
|
||
Rust `hex::decode` 直接失败。
|
||
② `CryptoJS.pad.Pkcs7.unpad` **不校验** padding(只看末字节数值就裁掉),
|
||
且 `enc.Utf8.stringify` 遇非法 UTF-8 会 **throw `Malformed UTF-8 data`**
|
||
⇒ react 控制器 catch 后回 `fail(400, "Malformed UTF-8 data")`。
|
||
本仓:`hex::decode` 失败 / PKCS7 严格解包失败 / 非 UTF-8 ⇒ `decrypt_to_md5` 返回 `None`
|
||
⇒ 按 P15 回 `fail(400, "账号或密码错误")`。
|
||
**观测差异只在畸形密文上**:`code` 都是 400、HTTP 都是 200,**只有 msg 不同**。
|
||
正常路径(合法密文 / 错口令)**完全一致** ✅ —— 冒烟 32 条断言不涉及此路径。
|
||
裁决:**不追平**。理由:react 的宽容是「意外」,不是契约;严格更安全。
|
||
代价:若将来有客户端发畸形密文,msg 会与 react 不同(前端不依赖该 msg,只看 code)。
|
||
|
||
**Ruling P21** — 修复轮 R1 只动 `src/backend/src/cipher.rs`(加测试 + debug_assert)与报告措辞,**不改算法**。
|
||
理由:评审明确「代码是对的,理由是伪造的」;改算法会危及「上游向量逐字节相等」这条硬约束。
|
||
**代价**:P20 的两处畸形密文文案分歧**继续存在**(react 抛 "Malformed UTF-8 data"、
|
||
本仓返 `None` ⇒ 登录端点文案 "账号或密码错误")—— 已由 P20 记录为有意分歧,
|
||
HTTP 状态与 `code` 相同、仅 `msg` 不同、无测试覆盖。
|
||
|
||
**Ruling P22** — 修复轮的提交**只 `git add` 显式路径**(`src/backend/src/cipher.rs`),
|
||
不碰 Task 3 实现者正在写的 `config.rs` / `db.rs` / `schema.sql` / `tests/`。
|
||
理由:避免与并发实现者抢 git index(`index.lock` 冲突 ⇒ 对方提交失败)。
|
||
**代价**:无(Task 3 的四个文件在 `d73b161` 后仍是未提交状态,已复核 `git status`)。
|
||
|
||
**Task 1: complete — `a7308af`(+ 修复轮 R1 `d73b161` / `08c2665`)** — cipher 三函数 + 11 条单测
|
||
(含「PKCS7 填充不合法 ⇒ `None`」严格性钉住、上游向量双向断言);评审修复轮复审结论
|
||
**All findings addressed, no new Critical/Important breakage**。
|
||
|
||
**Ruling P23** — 规格投影别名改为**带双引号**:`f_xxx AS "<JSON键>"`。
|
||
修订 `docs/contract.md` §R1.4 / §4 / §5.2 / §5.3(提交 `0fef2fb`,独立提交,规格不漂移)。
|
||
理由:加引号是**原生 PG 行为**(不依赖任何文本解析);未加引号依赖「谁来还原大小写」。
|
||
**代价**:下游 5 个任务的 SQL 别名要加引号(多两个字符);已写进 Task 6–10 brief 的 **S12** 段。
|
||
|
||
**Ruling P24** — 保留 `db.rs` 的**键归一安全网**(别名还原 + `f_*`→camelCase),
|
||
但规格写明它是**安全网**、不是规范路径;规范写法(加引号)本身不依赖它。
|
||
理由:防漏 —— 万一某处漏了引号,**不会静默产出小写键**;`db_it.rs:213-222` 已钉住两种写法都出 `realName`。
|
||
**代价**:多一层 SQL 文本解析(`collect_alias_map`)在热路径上;已由实现者的单测覆盖
|
||
(字符串/注释/dollar-quote 跳过、只收含大写的别名、已加引号的别名不收)。
|
||
|
||
**Ruling P25** — Task 3 的 concern②(业务表时间列 `TIMESTAMP(0)` vs react 的 TypeORM 默认精度 6)
|
||
按**已知无害偏离**处理,不改 DDL:契约 §5.1 已写死 `TIMESTAMP(0)`;列名/类型族不变,
|
||
两版后端开同一个库无碍;前端不用 `creatorTime`。concern③(`pub use pglite;`)是集成测试写带参
|
||
SQL 的必要出口,**保留**。concern④(`split_sql_statements` 丢弃注释内容)规格未要求保留注释,
|
||
**接受**。concern⑤(未起 HTTP 服务)—— 装配链属 Task 10 的验收范围。
|
||
|
||
**Ruling P26** — 键归一安全网改为**作用域受限**扫描(原 `collect_alias_map` → `collect_alias_info`)。
|
||
理由:评审实测两条**静默错值** —— `WITH c AS (SELECT 1 AS Title) SELECT f_title AS "title" FROM demo_item`
|
||
把契约键 `title` 静默改成 `Title`;`SELECT CAST(1 AS NUMERIC) AS "numeric"` 把 `numeric` 改成 `NUMERIC`。
|
||
根因是「扫整条 SQL 的别名」与「拿结果对象的键查全局表」跨作用域混用 —— 安全网反而制造了
|
||
§R1.4 要消灭的静默失败。改法:**只扫外层 SELECT 的投影列表**(第一个深度 0 的 `SELECT` → 第一个深度 0 的 `FROM`)、
|
||
**只认相对深度 0 的 `AS`**(⇒ `CAST(x AS TYPE)`、CTE、子查询里的 `AS` 都不登记)、
|
||
双引号别名进 `quoted` 集且**归一时优先于一切还原**、同名不同写法**放弃还原**。
|
||
**代价**:多一层括号深度跟踪;`AS realName`(未加引号)这条兼容路径仍在(P24 的安全网保留),
|
||
但它现在**只对外层投影列表生效** —— 内层/子查询里的未加引号别名不再被还原(契约不依赖它)。
|
||
|
||
**Ruling P27** — `scalar_text` 按**列类型 OID 分派**;非文本/整数/布尔类型**返回 `Err`**(不猜)。
|
||
理由:评审实测 `scalar_text("SELECT count(*) FROM base_user")` 返回 8 个 NUL(`String::from_sql`
|
||
不校验列类型、pglite 走 extended protocol 拿的是二进制格式)⇒ 下游 count/exists 判断会**静默判错**。
|
||
分派:TEXT/VARCHAR/BPCHAR/NAME/UNKNOWN ⇒ 原样;INT2/INT4/INT8 ⇒ 十进制字符串;BOOL ⇒ `true`/`false`;
|
||
其余(numeric/timestamp/json…)⇒ `Err`,错误信息提示写 `::text`。
|
||
**公开签名不变** ⇒ 下游 Task 6/8/9 不用改代码。**代价**:调用方写 `SELECT count(*)` 不加 `::text`
|
||
拿到的是**响亮的错误**而不是错的字符串 —— 这是有意的(宁可报错也不要静默判错)。
|
||
|
||
**Ruling P28** — `split_sql_statements` 遇到注释时往结果里推**一个空格**(原来什么都不推)。
|
||
理由:评审实测 `SELECT 1/*x*/FROM t` 被切成 `SELECT 1FROM t`(token 粘连、语义变了)。
|
||
当前 `schema.sql` 的注释都是整行 ⇒ 现在无害,但这是 `pub fn` ⇒ 下游可能踩。
|
||
**代价**:无(切出的语句多一个空格,SQL 语义不变)。
|
||
|
||
**Ruling P29** — `exec`(simple protocol,可多语句、整批隐式事务)与
|
||
`exec_params`(extended protocol,**只能单语句**)的能力不对等 ⇒ **只补 doc 注释,不改实现**。
|
||
理由:brief 的 S1 明文要求 `exec_params` 建在 `query(sql, params)` 之上;改实现就得放弃参数。
|
||
**代价**:调用方需自己知道 `exec_params` 不接受多语句(已写进 doc)。
|
||
|
||
**Ruling P30** — `Db::open` 与 `config::pg_is_temp()` 各判一次 `memory://` ⇒ **不改**。
|
||
理由:评审自己确认「不是 bug」,两处都判是双重保险;改它要动 `config.rs`,
|
||
而本轮修复范围只给 `db.rs` + `db_it.rs`。**代价**:无。
|
||
|
||
**Task 3: 修复轮 R1 已派给实现者 `a5cdd71d7d46fd631`**(规格:
|
||
`.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-3-fix-r1.md`)。
|
||
BASE = `0fef2fb`。本轮**只许**改 `src/backend/src/db.rs` + `src/backend/tests/db_it.rs`
|
||
(`lib.rs` 是 Task 4 的专属写入文件,Task 4 马上派工 ⇒ 本轮不许碰,否则撞车)。
|
||
|
||
**Ruling P31 — 观察 O1/O2 均为「按规格实现的预期取舍」,不改代码。**
|
||
— 理由:契约 §5.3 的规范写法是带双引号的 camelCase 键,安全网只是防漏;
|
||
两种契约写法(双引号别名 / 直接投影 `f_*`)复审实测均正确 ⇒ 契约未破。
|
||
— 若错了的代价:将来若出现「子查询定义别名 + 外层裸选」的 SQL,返回的键会全小写、
|
||
前端读不到字段且不报错(静默失败);届时改 `collect_alias_info` 的扫描范围即可,
|
||
成本 = 一次局部修改 + 一条回归测试。
|
||
|
||
**Ruling P32 — 观察 O3(`AliasInfo` 可见性)不处理。**
|
||
— 理由:它不是缺陷,也不影响任何调用方(`collect_alias_info` 与字段都是 crate 内部使用);
|
||
现在动它属于纯噪音改动,会污染后续任务的 diff。— 若错了的代价:几乎为零。
|
||
|
||
**Ruling P33 — 键归一安全网的作用域(供 Task 5~10 引用):**
|
||
安全网**只认外层 SELECT 投影列表里相对深度 0 的 `AS`**;
|
||
CTE / 子查询 / `CAST(x AS TYPE)` 里的 `AS` 不登记。
|
||
⇒ 本仓 SQL 一律按契约写法 `f_xxx AS "<JSON键>"`(双引号);安全网不是规范路径。
|
||
(已写进 task-6..10 brief 的 S13。)
|
||
|
||
**Ruling P36 — brief S11 关于 `Config` 不可克隆的说法是笔误,已更正为「`Config` 是 `Clone`,
|
||
但契约 §9 仍写死 `Arc<Config>` ⇒ 照契约用 `Arc<Config>`」。**
|
||
— 理由:核对 `crates/sspf-store/src/config.rs:66` = `#[derive(Clone, Debug)]`(P0 拆 crate 后
|
||
`Config` 的定义搬到了存储层;内核侧 `platform/config.rs` 只做转发)。
|
||
契约的 `Arc<Config>` 仍然成立(`AppState` 要 `Clone`,`Arc` 是最省 clone 的写法)。
|
||
— 若错了的代价:几乎为零(`Arc<Config>` 与 `Config` 在行为上等价,只是 clone 成本不同)。
|
||
|
||
**Ruling P37 — brief 里 UUID 下标断言自相矛盾,按**真实 v4 布局**钉住。**
|
||
brief 原写「第 15 个字符是 `'-'`」「第 14 个字符是 `'4'`」——两句都反了:
|
||
真实 `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx` 的 1-based 连字符在 9/14/19/24,
|
||
版本号 `4` 在第 15 位,变体位在第 20 位(8/9/a/b)。
|
||
实现者按真实布局写测试并在测试的 doc 注释里记下 brief 的错 ⇒ **行为正确**。
|
||
(已把 brief 改对,避免以后再被同一句话误导。)
|
||
— 若错了的代价:几乎为零(若按 brief 原样写测试,则该测试必失败 ⇒ 反而更早暴露)。
|
||
|
||
**Ruling P38 — 观察「variant nibble 未断言」不改。**
|
||
— 理由:`new_uuid()` = `Uuid::new_v4().to_string()`,**variant 位由 `uuid` crate 按 RFC-4122 保证**
|
||
(8/9/a/b)⇒ 断言的是构造器的契约,不是本仓实现的契约;评审的 2000 样本探针实测全部正确。
|
||
— 条件:若将来 `new_uuid` 改为手搓 UUID ⇒ **必须**补 variant 位断言。
|
||
— 若错了的代价:几乎为零(uuid crate 不可能产出非 v4 的 v4 UUID)。
|
||
|
||
**Ruling P39 — 观察「`issue` 在写锁中毒时仍返回 token」不改。**
|
||
— 理由:触发前提是 `HashMap::insert` 期间 panic(OOM 之类)⇒ 进程本就不健康;
|
||
且 `resolve` 用 `.ok()?` ⇒ 中毒只导致 `resolve` 返回 `None`,**不会 panic 传播、不杀请求**。
|
||
契约面(登录成功/未登录)无差别。
|
||
— 若错了的代价:几乎为零。
|
||
|
||
**Ruling P40 — 观察「session 表无 TTL / 无容量上限」v1 不实现 TTL。**
|
||
— 理由:契约 §6.1 逐字写死「token 形态 = `lite-`+32 hex;**进程重启即失效(内存表)**」,
|
||
`expiresIn: 7200` 是**响应字面量**;项目 CLAUDE.md 也明确认可「内存 token 表」形态
|
||
(与 JNPF 的 Sa-Token 内存模式同代)。
|
||
实现 TTL 会引入「token 提前失效 ⇒ 冒烟脚本随机失败」的新失败模式,
|
||
换来的收益是防一个 v1 规模下**不可观测**的内存增长。
|
||
— 条件:v2 面向真实用户时补「TTL + 容量上限」。
|
||
— 若错了的代价:低(长跑进程里 token 表单调增长;每条 ~50 字节,登录量级下无感)。
|
||
|
||
**Ruling P41 — 观察「`trim()` 放宽了接受范围」不改。**
|
||
— 理由:只**放宽**不收紧(`' bearer <tok> '` 现在能解析),token 本身仍要精确匹配 ⇒ 无安全副作用。
|
||
— 若错了的代价:几乎为零。
|
||
|
||
**Ruling P42 — 契约 §7.2/§7.3/§7.4 的「覆盖」语义 = 「只 SET body 里出现的键」(react 的 `undefined` 语义)。**
|
||
— 理由:契约 §7.1 明确写了全局规则「**只覆盖 body 里出现的键,`undefined` ⇒ 不动原值**」,
|
||
§7.2/§7.3/§7.4 只是**没重复**这句全局规则,不是要改成「总是覆盖」。
|
||
react 的行为真源(`sys.service.ts`)也一致:`Object.assign(ex, {urlAddress: dto.urlAddress})`
|
||
⇒ `undefined` ⇒ TypeORM `save` 跳过该列 ⇒ 原值不动。
|
||
— 承重之处:菜单的 `f_url_address` 是**权限守卫的比对键**(§8.2)。
|
||
若一次 Module 更新把它清成 NULL ⇒ 该菜单变成「**未映射**」⇒ 守卫走「未映射放行」
|
||
⇒ **任何登录用户都能访问该模块**(静默越权)。
|
||
「只 SET body 里出现的键」这条通用规则正是防这个的。
|
||
— 已写进 task-8-brief 的 **S16**(含逐字段兜底表:`f_type`/`f_category` 用 `?? 原值`,
|
||
`f_sort_code` 用 `?? 0`,`f_parent_id` 用 `|| '0'`,`f_is_administrator` 用「真值?1:0」,
|
||
`f_organize_id` 用 `|| '0'`,`f_password` 非空才覆盖;`f_url_address`/`f_icon`/`f_en_code`/`f_description` 缺省不动)。
|
||
— 待办:**把这条全局规则回写进 `docs/contract.md` §7.2/§7.3/§7.4**(Task 5 提交落地后、派 Task 6 之前做,
|
||
免得在实现者运行时动工作区)。
|
||
— 若错了的代价:菜单 `f_url_address` 被清空 ⇒ 越权窗口(中高)。
|
||
|
||
**Ruling P43 — 冒烟断言按契约 §13 的 32 条实现(react 脚本实际只有 31 个 `check`)。**
|
||
— 理由:逐个数过 react 的 `scripts/perm-smoke.sh`:它的「smoke_user 登录」那一步**只提取 token、没有 `check`**,
|
||
实际 `check` 调用数 = 31;而契约 §13 的表把「`smoke_user` 登录 ⇒ `code=200`」**列为第 12 条** ⇒ 表里 32 行。
|
||
契约(binding authority)与 react(行为真源)在此**不是冲突而是粒度差** ⇒ 取更严的契约口径。
|
||
— 好处:登录失败会**立刻**定位,而不是让后面 8 条连环假失败(噪音大、难定位)。
|
||
— 已写进 task-11-brief 的 S13(含 react JS 表达式 → jq 表达式的**逐条翻译表**、
|
||
`$ROOT` 定位 `--enc` 二进制、`mktemp` 临时目录、第 9 条 msg 的**全角冒号**、第 5/13 条的 `|` 用单引号)。
|
||
— 若错了的代价:几乎为零(多断言一条登录成功;真失败时反而更好定位)。
|
||
|
||
**Ruling P44 — `permission.rs` 里的 DB 报错必须「拒」,不得当成「未映射放行」。**
|
||
— 理由:契约 §9 把 `resolve_user_module_ids` / `has_module` / `build_menu_list` 的签名定成
|
||
**不带 `Result`**(`HashSet<String>` / `bool` / `Vec<MenuNode>`)⇒ DB 报错**没法往外传**,
|
||
只能在模块内部消解。而 `has_module` 第 2 步的语义是「查 `base_module` 查不到 ⇒ **未映射放行** ⇒ true」,
|
||
「**查不到**」与「**查询失败**」极易被写成同一分支(`if !found { return true }`)。
|
||
写成同一分支 ⇒ DB 一挂,全站模块守卫**全部放行** ⇒ **静默全站越权**。
|
||
— 裁定:DB 报错 ⇒ `has_module` 返回 `false`(拒)、`resolve_user_module_ids` 返回空集、
|
||
`build_menu_list` 返回空 `Vec`,并在 `eprintln!` 里记一行(不打印口令/token/密文)。
|
||
「查不到」与「查询失败」**必须分成两条路径**。
|
||
— 已写进 task-6-brief 的 **S15**。
|
||
— 若错了的代价:DB 故障时全站越权(高)。
|
||
|
||
**Ruling P45 — 🔴 修:固定字面量 id 的 INSERT 必须与「存在性判定」对齐,否则改一次名就永久起不来。**
|
||
— 缺陷(Important,reviewer 指 `seed.rs:212-252` / `seed.rs:264-309`):
|
||
存在性按 `f_en_code` / `f_url_address` 判,但 INSERT 用**固定字面量 id**(`role_admin` / `m_user` …)。
|
||
`base_module` / `base_role` 的 PK 是 `(f_id, f_tenant_id)` ⇒ 只要用户通过 UI 改过内置菜单的
|
||
`urlAddress`(契约 §7.4 允许)或内置角色的 `enCode`(§7.2 允许),
|
||
下次启动就会「查不到 ⇒ INSERT 固定 id」⇒ **主键冲突** ⇒ 种子失败 ⇒ 进程 `exit 1` ⇒
|
||
**此后每次启动都失败,且因为服务起不来,用户无法通过 UI 改回去** ⇒ 只能手工改库。
|
||
react 不会这样:它的 `save({id:'m_user', …})` 是**按主键 upsert**。
|
||
— 裁定:存在性判定改成 **「`f_en_code`/`f_url_address` 命中清单 **或** `f_id` = 固定字面量」** ⇒
|
||
已有行一律不碰(保住「只补缺项、绝不覆盖已改值」),且**永不再 INSERT 撞主键**。
|
||
(备选 `ON CONFLICT (f_id, f_tenant_id) DO NOTHING` 也可,但「OR f_id」语义更准:
|
||
撞主键的那一行本来就**不该被覆盖**。)
|
||
— 这条同时暴露了**契约本身的一处缺口**:§8.6 同时规定了「固定 id」与「按 en_code/url 判存在」,
|
||
两者在「人工改名」之后就会打架。⇒ 本仓以「两条都算存在」消解。
|
||
— 若错了的代价:改一次名 ⇒ 后端**永久起不来**(高)。
|
||
|
||
**Ruling P46 — 不修(Minor 2 的 `base_role_relation` 多填两列):按契约 §8.6 逐字删掉。**
|
||
— 契约 §8.6 对 `base_role_relation` 那行**逐字列了 7 个业务字段**(`f_object_type`/`f_object_id`/
|
||
`f_role_id`/`f_sort_code`/`f_delete_mark`/`f_tenant_id`/`f_id`),**没有** `f_creator_user_id`/
|
||
`f_creator_time`;react 的 `roleRelRepo.save` 也不写。Ruling P34 的「统一约定」明确只覆盖
|
||
**角色行 / 菜单行**,没覆盖这条关联行。⇒ **删掉这两个字段**(本仓 DDL 允许 NULL,不影响任何逻辑)。
|
||
— 若错了的代价:两列审计字段为 NULL(极低)。
|
||
|
||
**Ruling P47 — 评审的 ⚠️#2(react 的 `base_*` entity 是官方 DDL 的**子集** ⇒ 本仓种子往
|
||
`base_module`/`base_authorize` 写 `f_creator_user_id` 在 react 建的库上会「列不存在」)**不属于本任务缺陷**。**
|
||
— 理由:契约 §5.1 把「两版后端可开同一个库」这句话**挂在三张业务表上**
|
||
(原文:「**业务表**的列宽与默认值必须逐字对齐 react 的 TypeORM entity —— 这是『两版后端可开同一个库』
|
||
能成立的**前提**」)。`base_*` 7 张是**官方 DDL 逐字**(本仓的「契约」),
|
||
react 的 entity 只是它的**子集**(react 的 `base_module` 无 `f_creator_user_id`、
|
||
`base_authorize` 无 `f_creator_time`/`f_creator_user_id`)⇒ **react 后端本来就打不开本仓的库**
|
||
(它的 `synchronize: true` 会 `ALTER` 掉官方 DDL 的多余列)。
|
||
契约 §5.3 已经把这件事处理过了(「⚠️ react 的 `base_authorize` entity 没有 `f_creator_time`/
|
||
`f_creator_user_id` ⇒ **投影里不要它们**」)—— 那是**读**的方向;**写**的方向以官方 DDL 为准。
|
||
⇒ 本仓真正的复用对象是 react 的**前端**,不是 react 的**后端**。
|
||
— 处置:记为**项目级边界**(写进 `docs/contract.md` §5.1 的注解 + `CLAUDE.md` 的措辞),
|
||
不算 Task 5 的缺陷、不改代码。
|
||
— 若错了的代价:拿 react 后端指过来会 `ALTER` 官方 DDL(但那是 react 侧的行为,本仓管不了)。
|
||
|
||
**Ruling P48 — 「改掉内置角色 `f_en_code` ⇒ 不再补 admin 授权行」是契约行为,不是缺陷。**
|
||
— `ensure_admin_authorizations` 仍按 `f_en_code='admin'` 找 admin 角色(契约 §8.6 逐字)。
|
||
用户把内置 admin 角色的 `f_en_code` 改掉后,`ensure_base` 不会补授权行
|
||
—— 但**不报错、不撞主键**(R1 的核心诉求已满足),且 admin 本人是 `f_is_administrator=1`
|
||
⇒ 走管理员短路,菜单不受影响。
|
||
— 为什么不加「或 `f_id='role_admin'`」:那会在「用户另建一个 `en_code='admin'` 的角色」时
|
||
出现**两个候选**,可能把授权挂到 `role_admin` 上 ⇒ 与 §8.6 的语义冲突
|
||
(契约说 admin 角色 = `f_en_code='admin'` 的那一行,且 `f_en_code` 无 UNIQUE ⇒ 取 `ORDER BY f_id LIMIT 1`)。
|
||
— `first_seed` 的 `f_role_id='role_admin'` 仍是字面量(§8.6 明文);该 id 恒存在
|
||
(`ensure_base` 先行补齐;用户改名时行还在、硬删时会被重建)⇒ **不会悬空**。
|
||
— 若错了的代价:改过内置 admin 角色编码后,该角色的非管理员成员失去菜单授权(低)。
|
||
|
||
**Ruling P49 — `MAX_TREE_DEPTH = 32` 保留(不改代码),只补一行注释说明它是「防御性上限」。**
|
||
— 契约 §8.3 对层数**无**规定,react 的 `toTree` 也没有层数概念 ⇒ 不是「偏离契约」,是防御性上限。
|
||
— 控制器已逐行核对 `build_tree` / `build_node`:**环**(A.parent=B、B.parent=A)靠
|
||
`by_parent.remove()` 的**消费式取值**本来就终止(环成员互为子、无根 ⇒ 输出空;
|
||
挂在根下的环走一圈后 `remove()` 取空)⇒ 封顶**不是**防环的唯一手段。
|
||
— 但**极深的链**(>1000 层)会让递归爆栈 ⇒ SIGSEGV ⇒ 整个进程死掉。
|
||
而 react 在环场景下更糟:它造出**循环引用**的对象图 ⇒ JSON 序列化抛
|
||
「Converting circular structure to JSON」⇒ 500。⇒ **截断严格优于 react 的行为**。
|
||
— 截断只在「菜单嵌套 > 32 层」时生效(UI 逐级建菜单,现实中不可达)。
|
||
— 若错了的代价:>32 层的菜单子树被静默丢弃(极低)。
|
||
|
||
**Ruling P50 — `has_module` 里 `LIMIT 1` 不加 `ORDER BY`,保持与 react 一致。**
|
||
— 契约写的是「取第一条」;react 的 `findOne` 同样不确定 ⇒ 加 `ORDER BY` 反而是**偏离**。
|
||
`f_url_address` 无 UNIQUE 是**官方 DDL 的既定事实**,重复 url 属应用层该防的事,不在本任务范围。
|
||
|
||
**Ruling P51 — `grant_type` 空串:按 react 的 falsy 语义放行,并**修订契约措辞**(实现不动)。**
|
||
— 契约 §6.1 原文「`grant_type` **存在且** ≠ `password` ⇒ 400」,字面读会把空串判成 400。
|
||
— 行为真源(react `auth.controller.ts`)是 `if (grantType && grantType !== 'password')`
|
||
⇒ JS 空串 **falsy** ⇒ 空串放行;全局约束第 1 条要求逐字对齐 react。
|
||
— 且前端恒发 `grant_type=password`(`auth.ts:11`)⇒ 退化输入,影响面为零。
|
||
— ⇒ 裁决:`auth.rs` 的判定逻辑**保持**(`!grant_type.is_empty() && grant_type != "password"`),
|
||
**修订 `docs/contract.md:439`** 为「**非空**且 ≠ `password`」,并同步 `auth.rs` 的 doc 注释。
|
||
— 若错了的代价:一个退化输入的 400/放行差异;无现实影响。
|
||
|
||
**Ruling P52 — 登录的 DB 报错 ⇒ `系统异常,请联系管理员`(**推翻**实现者报告 §5.3 与评审的意见)。**
|
||
— 契约 §R1.2(`docs/contract.md:28`)与 §6.5(`:493`)**逐字规定**:
|
||
「未捕获异常(panic / **DB 报错**)⇒ HTTP 200 + `{code:400,msg:'系统异常,请联系管理员',data:null}`」。
|
||
— 实现者与评审都判成「规格没规定 ⇒ 取不泄露信息的安全文案」⇒ **规格其实规定了**,两人都漏读 §R1.2。
|
||
— react 那边把 `e.message` 回给客户端(泄露 PG 原文);本仓刻意不抄,但契约给的通用文案同样不泄露。
|
||
— ⇒ 裁决:改成 `fail(400, "系统异常,请联系管理员")`(HTTP 200 不变),保留 `eprintln!`;
|
||
补一条 DROP `base_user` 的测试钉住它。
|
||
— 若错了的代价:DB 故障时客户端看到「系统异常」而非「账号或密码错误」——这正是契约要的可区分性;
|
||
用户不会误以为口令错而反复重试。
|
||
|
||
**Ruling P53 — `LoginForm` 去掉 `Debug` / `Default` / `Clone`(只留 `serde::Deserialize`)。**
|
||
— `Debug` 派生的结构体里装着**口令密文** ⇒ 一次 `{:?}` 就是一次泄漏(评审 Minor)。
|
||
— `Default` / `Clone` 全仓零使用点(`auth_it.rs` 用结构体字面量)。
|
||
— 若错了的代价:将来真要用时编译期会报(加回即可)。
|
||
|
||
**Ruling P54 — 口令哈希的 JSON 键改名:`f_password AS "password"` ⇒ `AS "storedPassword"`。**
|
||
— 那个 `Value` 里有一个**键名叫 `password`** 的字段 ⇒ 一次误打日志就是哈希泄漏(评审 Minor)。
|
||
— 只改这一列的别名与对应的一处读取点;`id` / `account` / `isAdministrator` 三个别名一字不动。
|
||
— 若错了的代价:无(该键不进响应体)。
|
||
|
||
**Ruling P55 — `cipher.rs::encrypt_password` 的两处 `.expect()` 必须去掉(**控制器自查发现,评审未报**)。**
|
||
— 项目红线「非测试代码零 `unwrap`/`expect`/`panic!`」;`cipher.rs:60/63` 是**全仓仅剩**的两处
|
||
(`cipher.rs:158/181`、`envelope.rs:118+`、`session.rs:124+` 全在 `#[cfg(test)] mod tests` 里)。
|
||
— key 构造换成 `KeyInit::new(&GenericArray)`(不可失败;`new_from_slice` 内部就是
|
||
`Self::new(Key::from_slice(key))` ⇒ **完全等价**);填充的 `Err` 用 `match` fail-closed
|
||
(**绝不回显明文**);上游检验向量必须一字不变(测试钉住)。
|
||
— 若错了的代价:零。
|
||
|
||
**Ruling P56 — 补两条测试钉子(解析失败分支 / 校验顺序优先级)。**
|
||
— 这两条分支此前**没有测试钉住**:把 `login_from_bytes` 的 `Err(_)` 分支删掉、
|
||
或把校验顺序 1 与 2 调换,现有 16 条测试**照样全绿** ⇒ 契约被静默改掉也没人发现。
|
||
— ⇒ 用**重复键**(`account=a&account=b`)触发 serde 的 duplicate field 错误;
|
||
用「缺 password + `grant_type=foo`」钉住顺序(必须得到 `缺少 account / password`)。
|
||
|
||
**Ruling P57 — 契约文本的修改必须回到 `docs/contract.md`,不能只写进任务报告。**
|
||
— 评审明确指出:`grant_type=""` 的分歧「应在 `docs/contract.md` 里对账,而不只是写进任务报告 ——
|
||
否则契约仍是权威,却读起来像 `""` ⇒ 400」。
|
||
— 契约是**约束真源**,任务报告只是记录 ⇒ 分歧必须在契约里消除。
|
||
|
||
**Ruling P58 — 保留 `cipher.rs::encrypt_password` 里既有的 `debug_assert_eq!(src.len(), 32, ...)`(不删)。**
|
||
— 实现者提出的**非阻塞**关切:该断言在 debug 构建下会 panic。
|
||
— 控制器判定**保留**:① MD5 摘要恒为 16 字节 ⇒ hex 恒 32 个 ASCII 字符 ⇒ 这是**编译期常量级**的不变式;
|
||
② `debug_assert!` 正是陈述这类不变式的惯用法(release 下被编译掉,debug 下会响亮地炸);
|
||
③ 红线「非测试代码零 `unwrap`/`expect`/`panic!`」针对的是**运行时可能失败**的路径,
|
||
而这条断言恒真;④ 它既不是 `unwrap` 也不是 `expect` 也不是 `panic!`。
|
||
— 若错了的代价:几乎为零(最坏是 debug 构建多一次恒真断言开销)。
|
||
|
||
**Ruling P59 — 多步写操作的原子性口径。**
|
||
— `Db` 的每个公开方法**各自**持进程级 `Mutex`(`db.rs` 内部实现);**没有**跨多次调用
|
||
公开持锁的接口 ⇒ `db.rs` 自己的 S3 注释(「一次业务操作跨多条 query 必须由本层进程级
|
||
Mutex 兜住」)目前**无接口可实现** ⇒ **已知缺口**,交给最终整体评审。
|
||
— 本任务口径:能写成**一条**语句的多步写(授权写入的「软删旧行+插新行」;User Save 的
|
||
「删旧 role_relation+插新行」)⇒ 用 **data-modifying CTE** 合成一条 SQL
|
||
(PG 的数据修改型 CTE 无论是否被引用都执行且只执行一次 ⇒ 一条语句 = 一个隐式事务 = 原子),
|
||
值全部走绑定参数;确实需要多步的 ⇒ 顺序多次参数化调用(与 `permission.rs` 既有模式一致)。
|
||
— **不要**改 `db.rs`(Task 8 改动面只有 `sys.rs` + `tests/sys_it.rs`)。
|
||
— 若错了的代价:并发下可能读到「软删已完成、插入未完成」的中间态(方向是**少权限**,非越权)。
|
||
|
||
**Ruling P60 — Task 8 的 handler 签名(Task 10 装配要用,现在定死)。**
|
||
— 统一形状:`State<AppState>` + `HeaderMap` +(Save/Authority 用 `Bytes` 原始 body;
|
||
Delete/Modules 用 `RawQuery`)+ 返回 `Json<ActionResult>`。
|
||
— 🔴 **body 用 `Bytes` 自己解析**(`serde_json::from_slice`):axum 的 `Json<T>` 解析失败会返回
|
||
**422 + 非信封 body** ⇒ 契约破(与 Task 7 `login_handler` 同一个坑)。
|
||
— 🔴 **query 用 `RawQuery` 自己解析**(`serde_urlencoded::from_str`):axum 的 `Query<T>` 解析失败
|
||
会返回 **400 + 非信封 body** ⇒ 契约破。解析失败 ⇒ 视作「参数缺失」⇒ 走既有业务文案。
|
||
— 若错了的代价:Task 10 装配时签名对不上,要返工改 `sys.rs` + `routes.rs`(小)。
|
||
|
||
**Ruling P61 — 非法 JSON body 的文案(契约未覆盖,控制器裁决)。**
|
||
— body 解析失败 ⇒ `fail(400, "请求参数格式错误")`(**HTTP 200** + 信封)。
|
||
— 理由:契约 §R1.2 要求业务失败一律走 `{code,msg,data}`;axum 默认的 422 文本**不是**信封 ⇒ 破。
|
||
— 若错了的代价:文案不在契约清单里(契约未列此场景)⇒ 极小;改起来是一行。
|
||
|
||
**Ruling P62 — Delete 端点在「`id` 参数缺失 / id 不存在」时返回成功(实现者 concern 1)。**
|
||
— 契约 §7.1 明确:User Delete「软删 `base_user`(按 id,**不按 `f_delete_mark` 过滤** ⇒ 幂等)」
|
||
+「**不检查用户是否存在** ⇒ 不存在也返回成功」;Role Delete / Module Delete 未要求存在性检查;
|
||
Organize Delete 先查子机构(无子机构即软删,不存在也是软删 0 行)。
|
||
— ⇒ 「id 不存在」在契约下就是**成功**;「`id` 参数**缺失**」契约未单列,取**同一读法**(幂等成功)
|
||
是与契约最一致的选择。
|
||
— 🔴 **安全前置条件**:`id` 缺失时**绝不能**退化成「无 WHERE 条件的全表更新」⇒
|
||
实现必须是 `WHERE f_id = $1::text`(绑定空串 ⇒ 匹配 0 行)。已核对 `sys.rs` 的 4 个 delete
|
||
handler 均为 `WHERE f_id = $1::text` 绑定参数 ⇒ 无误伤风险。**维持现状,不改。**
|
||
— 理由:改成 `400 '用户不存在'` 反而**违反**契约 §7.1 的显式条款。
|
||
— 若错了的代价:契约 §7.1 若被改写,4 个 delete handler 各一行(极小)。
|
||
|
||
**Ruling P63 — `roleIds` 的非字符串元素 / `f_type`·`f_sortCode` 的不可解析值(实现者 concern 2)。**
|
||
— `roleIds` 非字符串元素:契约 §7.1 第 5 条说「每个 roleId 插一行」,未规定非字符串元素的行为;
|
||
react 原样落库 ⇒ 会在 `f_role_id`(varchar)里写入非 id 串 ⇒ 污染授权数据。
|
||
控制器判定:**丢弃非字符串元素**是更安全的一侧(不污染),且契约未禁止 ⇒ **维持现状**。
|
||
— `f_type` / `f_sortCode` 不可解析值回落「原值 / 0」:契约 §7.2/§7.4 说 `f_type` = body.type ?? **原值**、
|
||
`f_sort_code` = body.sortCode ?? 0 ⇒ 「值不可解析」时回落默认与契约的「缺省」语义一致;
|
||
另一条路是让 DB 报类型错 ⇒ 变成「系统异常」⇒ **违反** §R1.2 的语义分层。⇒ **维持现状。**
|
||
— 若错了的代价:极小(契约未覆盖非字符串 roleId 的精确行为)。
|
||
|
||
**Ruling P64 — `write_user_roles` 不得吞掉 DB 错误(唯一阻塞项)。**
|
||
— 契约 §7.1 第 5 条把「先硬删旧行再插新行」列为 User Save 的**必经步骤**;
|
||
原实现 `sys.rs:547-549` 只 `eprintln!` 后返回 `()`,调用点忽略返回值
|
||
⇒ 角色写失败仍回 `{code:200,msg:'成功'}` ⇒ **契约要求的写入没生效却报成功**。
|
||
— 修法:`write_user_roles` 返回 `Result<(), pglite::Error>`;两个调用点映射
|
||
`db_error(e, "用户角色关联写入")` ⇒ HTTP 200 + `fail(400, "系统异常,请联系管理员")`。
|
||
— 若错了的代价:与契约 §R1.2 的「DB 报错 ⇒ 400」不一致(吞错)。
|
||
|
||
**Ruling P65 — body 里 `id` 存在但非字符串 ⇒ 走更新分支(不是新建)。**
|
||
— 契约 §7.1 第 4 条写的是「**有 `id`** ⇒ 更新」;react 的 `if (dto.id)` 对数字 `123` 是 truthy
|
||
⇒ 行为真源也走更新分支。原实现 `as_str()` 得 `None` ⇒ 被当成「无 id」⇒ **静默多插一行**。
|
||
— 修法:新增 `body_id(&obj)`(`None`/`Null`/空串 ⇒ 无 id;其余 ⇒ 按 JSON 文本当 id)。
|
||
— 若错了的代价:域外输入下多插一行(静默数据污染)。
|
||
|
||
**Ruling P66 — `roleIds` 原始数组非空但全非法 ⇒ 不动已有关系行。**
|
||
— P63 只裁定「丢弃非字符串元素」,**没考虑先删后插的放大效应**:
|
||
`roleIds:[123]` ⇒ 旧行已硬删 + 过滤后为空 ⇒ 用户的**全部**角色授权被清空。
|
||
— 修法:原始数组**非空**且过滤后为空 ⇒ 早退,**不动**关系行;
|
||
原始数组本身就是 `[]` ⇒ 仍按契约 §7.1 第 5 条「空数组 ⇒ 只删不插」。
|
||
— 若错了的代价:一次畸形输入清空用户的角色授权。
|
||
|
||
**不要求改的 Minor(已裁决,记此备最终整体评审复查)**:
|
||
|
||
- **P67 — `or_zero` 把非字符串 `organizeId`/`parentId` 写成 `'0'`** ⇒ **不改**。
|
||
契约只规定默认值 `'0'`、未规定入参类型;本仓 id 全是 UUID 字符串 ⇒ 数字型是**域外输入**;
|
||
前端恒传字符串。记为已知偏离。
|
||
|
||
- **P68 — `sys.rs` 单文件 1273 行承载 5 组** ⇒ **不改**。
|
||
计划与 brief 的目录结构明确要求「`sys.rs` = 5 组 `base_*` 显式 handler」,拆文件会与计划冲突。
|
||
⇒ 留给**最终整体评审**裁决。
|
||
|
||
- **P69 — `user_role_map` 每次加载整张 `base_role_relation` + `base_role`** ⇒ **不改**。
|
||
v1 规模(几十行)完全够用,优化留到稳定期。
|
||
|
||
**R=1 范围复审(sonnet `a51282a746faf814a`)结论:PASS。**
|
||
必改 1–5 全部 ADDRESSED;New Breakage: None;未要求改的 4 个 Minor 一律未动。
|
||
|
||
**Ruling P70 — `body_id` 对 `0` / `false` 这类 JS falsy 的非字符串 id 判为「有 id」⇒ 不改。**
|
||
— 契约对 `id` 的取值域就是 36 位 UUID 字符串 ⇒ 数字/布尔是**域外输入**;
|
||
与 P67(`or_zero` 域外输入不处理)同一口径 ⇒ 记录备查,不阻塞。
|
||
|
||
**Ruling P71 — 新建路径角色写入失败可能残留「有用户、无角色关系」的半成品 ⇒ 不改。**
|
||
— 这是 Ruling P59 的**已知缺口**(`Db` 没有跨调用持锁的公开接口)的具体表现
|
||
⇒ 统一交给**最终整体评审**裁决;本任务**不改 `db.rs`**。
|
||
|
||
**修复轮 R=2(唯一补洞项)**:补 2 条测试,钉住 R=1 必改 3 引入的**早退分支**
|
||
(原始 `roleIds` 非空但全非法 ⇒ 关系行**不动**)与其**相邻**的契约分支
|
||
(原始 `roleIds` 就是 `[]` ⇒ 只删不插 ⇒ **清空**授权)—— 两条长得极像、结果相反、**都没有测试**。
|
||
清单见 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-8-fix2.md`。
|
||
|
||
**Ruling P72 — react 前端的 `30000` 实际有 3 处(不是 2 处);`request.ts:5` 的端口注释保持逐字节不变。**
|
||
— 控制器 2026-10-26 实测全目录 grep(排除 `node_modules`/`package-lock.json`):
|
||
`vite.config.ts:11`(注释)/ `vite.config.ts:12`(代理目标)/ `request.ts:5`(文档注释,**也是端口**)/
|
||
`request.ts:31`(axios **超时毫秒**)。原 Task 12 brief 的 S13① 只列了 2 处 ⇒ 表述不准确。
|
||
— 为什么:plan 明文「逐字复制、唯一允许的改动 = `vite.config.ts` 的代理目标」,
|
||
且 Task 12 的 diff 门判据是「`diff -r` 的**全部**差异只允许出现在 `vite.config.ts`」
|
||
⇒ 改 `request.ts:5` 会让 diff 门失败。
|
||
— 代价:`request.ts:5` 在改完后**描述的是旧端口 30000**(纯注释、无功能影响)⇒ 记为**已知陈旧注释**,
|
||
最终整体评审按 Minor 处理;🔴 **禁止**在 Task 12 顺手"修好"它。
|
||
— 已同步修正 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-12-brief.md` 的 S13①(三处清单 + 处理列 + 理由)。
|
||
|
||
**Task 9 评审(opus)结论:✅ Spec compliant / Approved(Critical 0 / Important 0 / Minor 6)。**
|
||
逐条核对契约 §7.6 三条路径 + §5.3 三套列集 + `??`/`||` 语义 + `module_key` 守卫 + 9 个 handler 签名
|
||
⇒ **全部逐字落地且有测试钉住**;三份文件严格在 allowlist 内;零 `unwrap/expect/panic!`;SQL 全参数化。
|
||
|
||
**5 条 concern 的裁定(评审者比对 `docs/contract.md` + react 真源后确认实现正确)**:
|
||
- Concern 1(`??` vs `||`):**合规**。契约 §7.6 明文写出两套表达式;§7.1–§7.4 的
|
||
「null ⇒ 写 NULL」规则**自带作用域标注**「(§7.1–§7.4 通用)」⇒ **不治理 §7.6**。
|
||
- Concern 2(路径 2/3 存在性判定不过滤 `f_delete_mark`):**合规**。契约分流条件是
|
||
「库里查不到该行」;react `findOne({where:{id}})` 同样不过滤 ⇒ 一致。
|
||
- Concern 3(路径 3 允许写 `f_creator_time`):**合规**(在 §5.3 列集内 ⇒ 可写),
|
||
但**该分支无测试** ⇒ 列为必改 2。
|
||
- Concern 4(`save` 非单事务):按 S16 口径**不是本任务缺陷** ⇒ 归 P59 已知缺口。
|
||
- Concern 5(clippy):「`permission.rs` 已有同类告警」**属实**,但计数需修正 ——
|
||
实跑 `cargo clippy --all-targets`:`doc_lazy_continuation` **共 6 条**
|
||
(**本任务新引入 4 条**:`crud.rs:5-6` / `entity.rs:5-6`;既有 2 条:`permission.rs:18-19`)。
|
||
⇒ 另发现**既有**告警:`sys.rs` 3 条(`question_mark` / `unnecessary_first_then_check` /
|
||
`vec_init_then_push`)+ `tests/seed_it.rs` 1 条(`type_complexity`)⇒ 共 6 条待清。
|
||
🔴 **根因已定位**:`crud.rs:4` / `entity.rs:4` 的**行首是 `+`** ⇒ markdown 当成无序列表标记
|
||
⇒ 后两行变成该列表项的惰性续行 ⇒ clippy 告警(`permission.rs` 同机制:`:17` 行首是 `-`)。
|
||
|
||
**Ruling P73 — `write_cast` 的硬编码 cast 表与 spec 的 `numeric` 脱钩 ⇒ 本轮只补一致性测试,不重构。**
|
||
— 风险真实存在:将来新增一个 numeric 列时,投影会正确加 `::text`、写入却不会加 `::numeric`
|
||
⇒ PG 报类型错 ⇒ 只在运行时变成「系统异常」信封,编译期/启动期无提示。
|
||
— 但重构 `write_cast` 为「由 `col.numeric` 推导」会改**写入口的类型转换**(生产逻辑)⇒
|
||
超出「告警 + 测试 + 注释」这一轮的范围,且 v1 只有三张固定 spec ⇒ 本轮**只补一条一致性测试**
|
||
(遍历三张 spec,断言每个 `numeric: true` 的列都落在 `::numeric` 分支)把这条不变量**钉住**。
|
||
— 代价:若将来新增 numeric 列而**忘了同步 cast 表**,新测试会失败(这是我们要的),
|
||
但重构本身被推迟 ⇒ 留给**最终整体评审**。
|
||
|
||
**Ruling P74 — 0 字节 body ⇒ `fail(400,"请求参数格式错误")`,**不**跟随 react 的 `{}` ⇒ 有意偏离。**
|
||
— react 侧 express body-parser 对空 body 给 `{}` ⇒ 建行;本仓 JSON 解析失败 ⇒ 400。
|
||
— 契约未覆盖 0 字节 body,但通用规则「非法 JSON ⇒ 请求参数格式错误」优先 ⇒ 0 字节 body 不是合法 JSON。
|
||
— 处置:**写进 `crud.rs` 模块文档**说明这是有意偏离(不静默埋着),不改逻辑。
|
||
|
||
**Ruling P75 — 本轮消掉本任务新引入的 4 条 clippy 告警;其余 6 条留给最终整体评审的修复轮。**
|
||
— `permission.rs` ×2、`sys.rs` ×3、`tests/seed_it.rs` ×1 全是**既有/其它任务遗留**,
|
||
改它们会越出本任务的文件白名单(`crud.rs` / `entities.rs` / `crud_it.rs`)。
|
||
— 🔴 记为**最终整体评审的必清项**(全是机械改动:`?` 运算符 / `!rows.is_empty()` / `vec![]` /
|
||
列表续行缩进 / type alias)。
|
||
|
||
**修复轮 R=1(in flight)**:清单见 `.superpowers/sdd/ssw-jnpf-lite-rust-v1/task-9-fix1.md`
|
||
—— 必改 1 消 4 条 clippy;必改 2 补「路径 3 写 `f_creator_time`」测试;
|
||
必改 3 补「numeric 列 ↔ `write_cast` 一致性」测试(须自证 load-bearing);
|
||
必改 4 两条文档说明(P74 / `numeric_columns` 权威来源)。
|
||
明确不改:Minor 6(性能)、Concern 4(P59 已知缺口)、`permission.rs`/`sys.rs`/`seed_it.rs` 的既有告警。
|
||
|
||
**Task 10 预备裁决(在派单前补齐 brief 的两处缺口)**
|
||
|
||
**Ruling P76 — `build_router` 的签名 + 三层兜底的挂法(契约 §9 与 §10 有表面冲突)。**
|
||
— 冲突:§9 写 `pub fn build_router(state: AppState) -> Router;` 且括注「`with_state` 由 `main.rs` 在链尾调用」;
|
||
§10 第 6 步又写「`build_router(state)` + … + `with_state(state)`(链尾)」。
|
||
`-> Router`(=`Router<()>`)与「main 再调 `with_state`」**在类型上不能同时字面成立**。
|
||
— 裁决:`routes::build_router(state: AppState) -> axum::Router<AppState>`,
|
||
内部以 `.with_state(state)`(`S2` 显式落在 `AppState`)**让契约的 `state` 参数有去处**、
|
||
同时**不**终结状态;`main.rs` 链尾**唯一一次** `.with_state(state)` 把类型落成 `Router<()>`。
|
||
— 🔴 兜底挂法:`.fallback(not_found_handler())` **必须写在两个 `.layer(...)` 之前** ——
|
||
`Router::layer` 只包住**调用它时已存在**的 fallback ⇒ 先 layer 后 fallback ⇒ 404 兜底
|
||
既不过 405 改写、panic 也不被 catch_all 接住。
|
||
正确链:`build_router → .fallback(404) → .layer(405) → .layer(catch_all) → .with_state(state)`。
|
||
— 代价:`build_router` 里那一句 `.with_state(state)` 语义上是 no-op(链尾会覆盖),
|
||
纯粹是为了让契约 §9 的 `state` 参数不产生 `unused_variables` warning ⇒ **已在 brief 里注明**,
|
||
避免最终评审误判为多余代码。
|
||
|
||
**Ruling P77 — 标识符白名单自检的口径(契约 §10 第 3 步只说"自检",没说自检什么)。**
|
||
— 自检函数放 `main.rs`(私有),在 `Db::open` **之前**;不过 ⇒ 打印人话 + `exit 1`。
|
||
— 检查对象只有**两类**:① `entities::all_specs()` 里每张 spec 的 `table`(过 `db::valid_table`)
|
||
与每个 `col.column`(过 `db::valid_column`);② **10 张表的字面量清单**(7 张 `base_*` + 3 张业务表)
|
||
逐个过 `db::valid_table`,且**每张 spec 的 `table` 必须在这张清单里**(抓"拼错但仍是合法标识符")。
|
||
— 🔴 **明确不查**:`sys.rs` 的 4 组投影列常量(`USER_COLUMNS` 等)——它们是**源码里的字面量常量**、
|
||
不是运行时输入,真写错编译期就炸 ⇒ 启动自检对它们无防错价值 ⇒ **本任务不需要改 `sys.rs`**。
|
||
— 代价:自检是**兜底 tripwire**、不是完备证明 ⇒ 记为已知简化,最终整体评审可见。
|
||
|
||
**Ruling P78 — 接受 R=1 实现者主动报告的「越界改动」(`crud.rs` 的 UPDATE 占位符加 `::text`)。**
|
||
— 越界点:`update_existing` 的占位符从 `$n{cast}` 改成 `$n::text{cast}`;
|
||
实现者称不改的话,裁决书「必改 2」(路径 3 写 `f_creator_time` 且 `code==200`)**不可达**
|
||
(PG 对 `SET f_creator_time = $1::timestamp` 把 `$1` **推断成 timestamp**,
|
||
而 pglite 一律按 text 编码 `Option<String>` ⇒ 协议层类型错 ⇒ 400 系统异常)。
|
||
— 复审(独立在 `/tmp` 副本复现)确认:
|
||
① **必要**:改回原形 ⇒ 路径 3 写 timestamp / numeric / int **全部** `code=400`;
|
||
② **安全**:改后参数恒为 text、转换在服务端做;与 `insert_new` 的 `$i::text{cast}` **逐字同构**;
|
||
timestamp → `"2026-01-01T00:00:00Z"` ✅、numeric `"9.90"` → `"9.90"` ✅、int `42` → `42` ✅、
|
||
JSON 数字 `9.9` → `"9.90"`(numeric(12,2) scale)✅、**NULL → NULL** ✅、
|
||
非法值 `"abc"` → 仍是 `code=400 系统异常,请联系管理员`(与路径 1 同口径同文案)✅;
|
||
③ **契约可观测行为有变化,但方向是「违约 → 守约」**:改前路径 3 写 numeric/int/timestamp
|
||
**100% 失败**(不存在可回归的旧行为);返回值形状 / 错误文案 / 列集 / 路径分流 / handler 签名全未变;
|
||
④ **最小**:一个 format 串 + 一个 token + 5 行注释;把 `::text` 塞进 `write_cast` 需连带改 `insert_new`
|
||
(改动更大);合并两个函数属「顺手重构」⇒ 否决。
|
||
— 裁决:**接受,不判违规**;但这条改动**改了对外可观测行为** ⇒ 必须有回归测试钉住
|
||
⇒ 开了 R=2 补「路径 3 写 numeric / int 列」的测试(复审 M1)。
|
||
— 代价:改动的"正当性"依赖上面那份复现实验;⇒ 复审 M2(INSERT/UPDATE 两处各自手写占位符、
|
||
建议抽共享 helper)**留给最终整体评审的修复轮**(本轮禁重构)。
|
||
|
||
**Ruling P79 — Task 10 **不**实现静态托管(后端不读文件系统来响应请求)。**
|
||
— 计划 §610 与契约 §68 都把静态托管写成**可选**(「后端**若**托管静态产物,只能托管前端 `dist/`」)。
|
||
— 事实:前端由 **vite dev server(:5173)** 托管、`/api` 代理到 `:30010`(Task 12 的 `run.sh`);
|
||
契约的 4 条验收门**没有任何一条**要求后端托管前端产物(门④就是 `http://127.0.0.1:5173` 手验)。
|
||
— 裁决:Task 10 **不**加静态文件服务;`config.static_dir`(`<root>/src/frontend/dist`)**故意不使用**。
|
||
「DDL 绝不可从 HTTP 下载」这条红线由「后端根本不读文件系统来响应请求」**天然**满足,
|
||
并**另加一条守卫测试**:`GET /db/schema.sql` / `GET /src/backend/db/schema.sql` ⇒ HTTP 404 + 信封。
|
||
— 理由:静态服务会引入路径穿越 / content-type 猜测 / SPA fallback 三类**新风险**,
|
||
而**没有任何验收门依赖它** ⇒ 不在 v1 引入。
|
||
— 代价:后端**不能**单独托管已构建的前端("单二进制跑全栈"不成立)⇒ 若最终整体评审认为这是硬伤,
|
||
再开一轮加静态服务(届时须自带路径穿越守卫)。
|
||
|
||
**Ruling P80 — Task 10 的 brief 内部有三处自相矛盾,控制器统一收敛(控制器已改 brief)。**
|
||
— 矛盾①:「catch-all 中间件」段写「handler 一律返回 `Result<Json<ActionResult>, pglite::Error>`」,
|
||
与 S14③(`pglite::Error` **没有** `IntoResponse` ⇒ 编译不过)及**实际的 27 个 handler 签名**
|
||
(全部返回 `Json<ActionResult>`)冲突。
|
||
⇒ 收敛为:**catch-all 只管 panic**;DB 报错**已**在 handler 内部由 `db_error(e, ctx)`
|
||
(`sys.rs:79` / `crud.rs:63`)映射成 `fail(400, "系统异常,请联系管理员")`(HTTP 200 + code=400),
|
||
**不改任何 handler 的返回类型**。
|
||
— 矛盾②:「catch-all 的位置」段与 S16 里的顺序写 `→ .layer(404兜底)`,
|
||
与 S25 的 `.fallback(404)` 冲突。
|
||
⇒ 收敛为 S25 的链:`build_router → .fallback(404) → .layer(405) → .layer(catch_all) → .with_state(state)`。
|
||
**控制器已核 axum 0.8.9 源码**(`axum-0.8.9/src/routing/mod.rs`):
|
||
`Router::fallback(h)` 同时写 `catch_all_fallback` 与 `fallback_router`;`Router::layer(l)` 把 `l`
|
||
**同时**包到 `path_router` / `fallback_router` / `catch_all_fallback` 三处;官方文档原话
|
||
「the middleware is only applied to existing routes. So you have to first add your routes
|
||
(and / or fallback) and then call `layer` afterwards.」⇒ `.fallback()` 必须在两个 `.layer()` **之前**。
|
||
`Router::layer` 的实现是逐条 `route.layer(l)` ⇒ **后挂的在外层**(后进先出)。
|
||
— 矛盾③:S15 写「查询参数用 `axum::extract::Query<T>` 取」,
|
||
与 S17(`Query<T>` 解析失败 ⇒ **400 + 非信封 body** ⇒ 契约破;handler 签名里已经是 `RawQuery`)冲突。
|
||
⇒ 收敛为:**路由注册时完全不用管 query**(handler 收 `RawQuery` 并在内部自己解析)。
|
||
— 代价:brief 变长、且「以 S25 / S17 为准」这类**交叉引用**读起来略绕 ⇒ 若实现者漏读,
|
||
会在复审时被退回;这正是**任务级评审**要抓的东西,故保留。
|
||
|
||
## 2026-10-26 追加:后端分层(平台层 / 业务层)
|
||
|
||
**Ruling P81 — 后端平铺改两层目录:`src/platform/`(契约实现)+ `src/modules/`(业务模块)。**
|
||
— 动机:react 版后端本来就是两段(`common`+`auth`+`sys` / `demo`+`shop`+`books`),
|
||
官方 JNPF 同样是两段(`jnpf-common`+`jnpf-system` / `jnpf-admin`);
|
||
本仓当时是平铺(`src/{config,db,cipher,…,entities}.rs`)⇒ 加业务模块要动平台文件,
|
||
形态与参照物不一致。
|
||
— 裁决:按用户口径**只分目录层**(不动 `db/schema.sql` 的业务表 DDL、不动前端、不动契约)。
|
||
平台层 = `config · db · cipher · envelope · ids · session · state · auth · permission · seed ·
|
||
sys · jnpf · entity · crud`;业务层 = `mod.rs` + `demo.rs` / `shop.rs` / `books.rs`,
|
||
每个业务模块自带 **spec 表 + 3 条路由 + 自己的 `router()`**。
|
||
— 连带两条**独立**裁决(否则「加模块不动平台」只是口号):
|
||
① **业务路由清单搬到业务层**(`modules/<app>.rs::ROUTES` ⇒ `modules::ALL_ROUTES`),
|
||
平台层的钉子测试遍历它 ⇒ 原来「每加一模块要改 `routes.rs` 路由表」的口子被堵死。
|
||
② **平台层最后一个业务知识泄漏清掉**:S22 的 `f_creator_user_id` 规则原先在引擎里写死
|
||
`app_code == "demo"` ⇒ 改成**业务 spec 自己声明**(`EntitySpec.creator_fixed`),引擎只读声明。
|
||
— 理由:平台层必须**可插拔**——契约(信封 / 权限 / 密文 / 两面分流)跨项目不变,
|
||
业务层随项目变。分层边界画在「业务表名 / app_code 出现在哪个层」这条线上,是可静态检查的
|
||
(`check-module.sh` 的反向断言),比靠注释约定可靠。
|
||
— 代价:① 平台层与业务层的**边界靠约定**(`entity.rs` 的 `EntitySpec` 是唯一跨界的数据结构),
|
||
将来若要加第二种业务形态(如带树形的实体),得先扩 `EntitySpec`;② `check-module.sh` 从
|
||
「9 接触点」升到 **69 条断言**(新增反向断言 + 业务层登记断言),维护成本上升。
|
||
— 历史裁决(P14 / P21 / P22 等)**保留原路径写法**——它们记的是「为什么这么实现」,
|
||
不是「文件在哪」;文件路径以本文与 `HOWTO_MODULE.md` 的现状描述为准。
|
||
|
||
## 2026-10-27 追加:分层边界可执行化 + 生产档守卫 + macOS 资源回收
|
||
|
||
> 背景:把兄弟项目 `tdc-rs` 的**机制**(尺子 / 台账 / 守卫 / 引文校验)逐条搬过来,
|
||
> 但**只搬机制、不搬内容** —— `tdc-rs` 的实体名 / `tdc_` 表前缀 / `/api/ssw/tdc/` 路由前缀 /
|
||
> 数值-JSON 规则 / 内部 token 分级**一律不引入**,因为那些是**那一个业务应用**的知识,
|
||
> 搬过来就污染本仓的通用骨架。每一条新机制都在**本仓自己的契约/行为真源**上重新推导。
|
||
|
||
**Ruling P82 — 业务菜单由业务层声明,平台层只留「类型」,中间加一个装配根 `src/bootstrap.rs`。**
|
||
— 动机:P81 之后平台层已经不含业务表名,但**业务菜单**仍住在 `platform/seed.rs`
|
||
⇒ 加一个业务模块必须改平台层 ⇒ 「加模块只碰业务层」这条红线**没兑现**。
|
||
难点在于:平台层要种菜单(那是契约行为),又不能知道菜单是哪个业务的 ⇒ 单靠分层拆不开。
|
||
— 裁决:拆成三块。① `platform/menu.rs` 只定义 **`MenuSpec` 这个类型**(字段全是平台语义
|
||
的通用属性:`id` / `full_name` / `en_code` / `url_address` / `parent_id` / `menu_type` /
|
||
`icon` / `sort_code`),**不含任何具体菜单**;② 每个业务模块在 `modules/<app>.rs` 声明
|
||
`pub const <APP>_MENU: MenuSpec = …`,登记进 `modules::ALL_MENUS`;
|
||
③ 新增 `src/bootstrap.rs` 作**装配根**(composition root)——
|
||
`bootstrap::ensure_base(db) = platform::seed::ensure_base(db, modules::all_menus())`。
|
||
`platform::seed` 从「自带 8 个菜单常量」改成「自带 5 个系统菜单 + 接收外部菜单参数」。
|
||
— 理由:**装配根是唯一允许同时认识两层的文件**,这是经典的 composition root 模式
|
||
(依赖倒置的落点)。平台层依旧可插拔,业务层不反向依赖平台层的 seed 细节。
|
||
— 代价:多一个文件(`bootstrap.rs`)和一层间接;`seed::ensure_base` 的签名从
|
||
`(db)` 变成 `(db, extra_menus)` ⇒ **平台层测试要传 `&[]`**,未来若再加第二种菜单来源
|
||
(如从配置文件读),`ensure_base` 的参数会变复杂。
|
||
|
||
**Ruling P83 — 分层红线从「注释约定」升级成「可执行闸门」,且禁用词表由业务层自己反推。**
|
||
— 动机:P81 的分层边界「是可静态检查的(`check-module.sh` 的反向断言)」——
|
||
但那只检查**已知的三个业务模块**;换一个 app_code 就漏检。且检查写在**脚本里**,
|
||
脚本里的期望值也可能与代码漂移。
|
||
— 裁决:新增 `scripts/check-boundary.sh`(CP1–CP6)+ `scripts/check-boundary-scan.py`。
|
||
扫描器的**禁用词表不是手写的**,而是从 `modules/*.rs`(跳�� `mod.rs`)里
|
||
**反推**出:表名、实体名、`/api/ssw/<app_code>/` 路由前缀、菜单 id、`en_code`、`url_address`
|
||
⇒ **加一个业务模块,禁用词表自动变严**(不写新规则也能拦住新泄漏)。
|
||
扫描器只认**字符串字面量**,注释里的提及**不算**(否则文档化讨论会误报)。
|
||
CP1 还额外扫 `routes.rs` / `main.rs` / `bootstrap.rs`(它们也是平台侧文件)。
|
||
— 附带一条**防自证**约定:扫描器带 `--self-test` 模式 —— 造一棵假的
|
||
`modules/` + `platform/` 树,断言**恰好**抓到 1 处泄漏(字面量里的泄漏被抓到,
|
||
注释里的提及不误报)⇒ 扫描器不会悄悄退化成「永远通过」的空壳。
|
||
— 代价:① 禁用词表由业务层反推 ⇒ **业务层改名会同步改禁用词表**,
|
||
旧名字不再被禁(这是**特性**:模块改完名,旧名泄漏反而抓不到——但旧名已无人使用,
|
||
危害有限);② 平台层里哪怕是**测试夹具**里的业务字面量也会被报出来
|
||
⇒ 本仓把 `platform/db.rs` 的测试夹具表名从 `demo_item` 改成中性的 `t_item`
|
||
(🔴 注意:**只改测试夹具**,不动任何真实业务表名)。
|
||
|
||
**Ruling P84 — `main.rs` 的 `EXPECTED_TABLES` 硬编码 10 张表 ⇒ 改为「DDL 对账」。**
|
||
— 动机:P83 之后,「加业务模块要改 `main.rs`」这个口子**又活过来了**
|
||
(白名单自检要核对表名)。入口文件是**平台侧**文件,它一旦知道业务表名,分层就漏了。
|
||
— 裁决:把硬编码的 10 张表拆成 `BASE_TABLES`(7 张 `base_*`,平台侧)+ **对账**:
|
||
① `db::ddl_tables()` 解析 `schema.sql` 里所有 `CREATE TABLE <name>`;
|
||
② DDL 里的每张表**必须**要么在 `BASE_TABLES` 里、要么有对应的业务 spec
|
||
⇒ 否则**孤儿 DDL**(建了表但没 spec)报错;
|
||
③ 每张 spec 表**必须**在 DDL 里有 `CREATE TABLE` ⇒ 否则**漏建表**报错。
|
||
— 理由:这比原来的硬编码**更强**(多抓两类错)而不是更弱,且入口文件**再也不需要**
|
||
为业务模块而改 ⇒ 红线 12 完整兑现。
|
||
— 代价:多一个 `db::ddl_tables()`(用 `include_str!` 读 DDL 文本 + 正则解析);
|
||
DDL 写法的自由度高了一点(解析器认的是「行首 `CREATE TABLE <name>`」这一种写法)。
|
||
|
||
**Ruling P85 — 弱口令不靠「文档里写一句」⇒ 加**部署档位**守卫(`SSW_PROFILE=prod`)。**
|
||
— 动机:本仓的种子口令是 `admin/123456`(契约 §8.6 逐字要求)、token 永不过期、
|
||
默认只监听 `127.0.0.1` ⇒ 本地开发形态是安全的,但**部署到生产**时同一份配置就是弱口令暴露。
|
||
契约不能改(`123456` 是契约的一部分),所以只能在**部署档位**上分叉。
|
||
— 裁决:新增 `platform/guard.rs`(纯函数、无 IO ⇒ 好测)与两个环境变量:
|
||
`SSW_PROFILE`(`dev` 缺省 / `prod`;**非法值回落 dev**,朝不误伤本地开发的方向)、
|
||
`SEED_ADMIN_PASSWORD`(缺省 `123456`,**只在空库首启时生效**)。
|
||
`prod` 档下六条判据逐条生效:① 键不在本部署清单里 ⇒ 跳过
|
||
② 值为空/空白 ③ 精确等于已知弱值 ④ 含已知弱值(反绕过)⑤ 命中弱标记词(整体词)
|
||
⑥ 长度 < 12 ⇒ 任一违规**拒绝启动**(人话报错 + exit 1)。
|
||
🔴 **额外做一次 DB 级回读**:种子口令只对空库生效 ⇒ 库里那个 admin 可能是当初种下的
|
||
`123456`,而运维后来才设了 `SEED_ADMIN_PASSWORD` ⇒ **只查配置 = 守卫形同虚设** ⇒ 必须回读库。
|
||
— 🔴 **刻意排除 `CIPHER_KEY`**:cipher 的 key 是 `md5_hex("EY8WePvjM5GGwQzn")`,
|
||
**协议共享**(前端 `cipher.ts` 与后端逐字节等价)⇒ 它不是「可轮换的弱密钥」,
|
||
当成弱密钥去判 ⇒ 整个系统开不了机。**协议常量 ≠ 部署密钥**,这条判据必须写死。
|
||
— 代价:多两个环境变量 + 一条启动前置检查;`prod` 档下第一次起必须先设一个强口令
|
||
(否则报错退出,这是**故意的**)。
|
||
|
||
**Ruling P86 — macOS 的 SysV 信号量泄漏自建回收器(`scripts/ipc-reap.c` + `reap-ipc-leaks.sh`)。**
|
||
— 动机:macOS(XNU) 的 SysV 信号量集**在创建进程退出后不回收**(与 Linux 不同),
|
||
且 macOS **不带 `ipcrm` / `ipcs`**。本仓每个测试文件一个 `Db::open_temp()`
|
||
⇒ 7 个测试文件 ⇒ 每轮 `cargo test` 漏 7 个 `nsems=20` 的 set ⇒ 累积到
|
||
`kern.sysv.semmns`(87381)上限后,**任何新的 PostgreSQL 实例都起不来**
|
||
(`semget: No space left on device`)。
|
||
— 裁决:自写 C 回收器。回收口径**刻意保守**(宁可漏回收也不误伤活进程):
|
||
① 只回收 `nsems == 20`(= PGlite/postgres-pglite 的指纹);
|
||
② 只回收创建者 uid == 当前用户的 set(不碰 root / 其他用户);
|
||
③ 只回收「最近一次操作时间」距今超过 `--min-idle` 秒的 set
|
||
(活着的 PostgreSQL 会持续 `semop` ⇒ otime 是新的 ⇒ 不会误删)。
|
||
默认 `--min-idle 3600`(1 小时),`--dry-run` 只报不删。
|
||
— 代价:多一个 C 源文件(需 `cc`,即 Xcode Command Line Tools);
|
||
判据③的「1 小时」是经验值(宁可漏,不误伤);`free_capacity()` 靠二分探测,
|
||
每次运行会新建并立刻释放一个 set ⇒ 净中性。
|
||
|
||
**Ruling P87 — 契约端点表下沉成「机器可读」段落(附录 A `[ENDPOINT]` / `[FACE]`)。**
|
||
— 动机:契约的「端点全表」一直是给人看的人话表格,而尺子的期望值另写在脚本里
|
||
⇒ **同一件事两处**,改端点只改脚本不改契约 ⇒ 契约慢慢退化成"过期文档"。
|
||
本仓的其它期望值(菜单 / 业务模块)早已下沉到附录 A(`[MENU]` / `[MODULE]`),
|
||
端点表是**最后一块没下沉的**。
|
||
— 裁决:把 §6 端点全表在附录 A 落成 `[ENDPOINT]` 段(列:face / method / path / guard / owner),
|
||
另加 `[FACE]` 段记三面条数(A 25 / B 5 / AB 2)。
|
||
`scripts/contract_expect.py` 新增 `endpoint` / `endpoints` / `face` 三个子命令读它。
|
||
— 🔴 **face 是必要的新维度**:面 A 专属 25 + 面 B 专属 5 + 两面共用 2 = 32,
|
||
而"面 A 27 条"= 25 + 2(共用算进面 A)⇒ **不记面就必然有人对不上数**。
|
||
`[FACE]` 段自带的 `条数` 列就是让这个口径**写在契约里**而不是各自记。
|
||
— 代价:契约文档里同一批端点出现两次(人话表 + 机器表)⇒ **改端点必须两处同改**
|
||
(`HOWTO_MODULE.md` §2.4 已写死这条),换来"尺子期望值只有一处"这个更值钱的性质。
|
||
|
||
**Ruling P88 — 加第三道静态闸门 `check-contract.sh`:契约端点表 ↔ 代码真实路由「双向」对账。**
|
||
— 动机:已有的闸门都查不出"**契约里写了一条、代码里没实现**"或"**代码多了一条、契约没登记**"——
|
||
前者要人读文档、后者要人读源码,两者都不在任何尺子的射程内;
|
||
而"文档与实现漂移"恰恰是本仓这种"契约优先"项目最容易出的错。
|
||
— 裁决:新增 `scripts/check-contract.sh` + `scripts/check-contract-scan.py`
|
||
(纯静态,不起后端、不连库)。扫描器用**掩码解析**读 Rust 源码:
|
||
先把注释/字符串字面量挖空但**保留字节偏移**,在掩码文本上找结构、
|
||
在原文同偏移处取字面量 ⇒ 注释里写的 `.route(` 不会被误当成真路由。
|
||
检查项 CC2–CC9:端点总数 / 契约→代码(存在 + 方法一致)/ 代码→契约(无未登记)/
|
||
归属层(platform vs 业务层)/ 守卫 / 钉子测试覆盖 / 业务路由三处一致 / 面计数自洽。
|
||
— 代价:多一个 Python 扫描器要跟着路由写法演进;**只认 axum 的 `.route(` 写法**
|
||
(本仓唯一写法),换写法必须改扫描器——这是"静态对账"换来的确定性的代价。
|
||
|
||
**Ruling P89 — 静态闸门必须自带「反自证」(`--self-test`),且"推不出"判 WARN 不判失败。**
|
||
— 动机:一条只会在"代码碰巧对"时才绿的闸门等于没有闸门——
|
||
**尺子本身要能证明自己抓得住错**。另外静态推导有天然盲区:守卫写法一变就推不出来,
|
||
若把它判成失败 ⇒ 闸门天天误报 ⇒ 团队习惯性忽略 ⇒ 闸门名存实亡。
|
||
— 裁决:① `--self-test` 模式**注入六种已知漂移**(契约多一条 / 少一条 / 方法写错 /
|
||
守卫写错 / 归属层写错 / 面计数写错)到契约副本,断言每种都被抓到;
|
||
**同时先断言真契约零漂移**——两向都过才算自证成立。
|
||
② 推不出守卫 ⇒ 报 `WARN`(**不计失败**)⇒ 闸门只在"确知不一致"时红。
|
||
— 🔴 **自证本身不计入 PASS/FAIL**:CC1' 只表现为 ✅/❌,不参与 9 条断言的计数
|
||
⇒ 尺子不能用"自己多认一条"来给自己加分。
|
||
— 代价:自证要维护一份"漂移注入"样板(每种漂移一段),新增检查类型时须同步补注入用例。
|
||
|
||
**Ruling P90 — 文档里的「路径:行号」会**静默漂移** ⇒ 加第四道静态闸门 `check-citations.sh`。**
|
||
— 动机:本仓的文档(`SKILL` / `README` / `MIGRATION` / `JNPF_SOURCE_AUDIT` / `PERMISSION` …)
|
||
大量引用源码位置(**百余条**全限定引文 + **84 处**续行行号;**条数随文档改动而变** ⇒
|
||
以 `check-citations.sh` 的输出为准,这里不钉死数字)。行号是**会漂移**的:
|
||
源码改一行 ⇒ 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**——
|
||
**不报错**,只是悄悄说错话(这比"链接 404"更坏:404 会被人看见)。
|
||
P0-1 的契约↔代码对账管的是**端点**,管不到**行号**。
|
||
— 裁决:新增 `scripts/check-citations.sh` + `scripts/check-citations-scan.py`(纯静态)。
|
||
三条判据:CIT1 引文**可解析** / CIT2 引文**行号有效** / CIT3 **DDL 行号表**对账
|
||
(`CLAUDE.md` 写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE`)。
|
||
引文行号支持四种写法:`N` / `N-M` / `N/M`(多个散行)/ `N+`(及以后)。
|
||
解析三级:精确 ⇒ 相对路径**后缀** ⇒ **基名**(官方源码文档里 `ActionResult.java:27` 这种)。
|
||
参照根四处:本仓 / 官方 JNPF 源码 / react 姊妹技能 / **cargo registry**
|
||
(引文指到依赖源码时,如 `pglite-rs 0.2.7` 的 `src/db.rs:444`)。
|
||
— 🔴 **三条「不判失败」的口径是刻意的**(不然闸门天天误报 ⇒ 被人忽略 ⇒ 闸门名存实亡):
|
||
① **外部参照根缺失 ⇒ 判「跳过」**(官方源码 / react 技能 / cargo registry 不在本机时,
|
||
只校验本仓内的引文);② **无路径的续行行号**(`:NNN`)**只报不判失败**——
|
||
那是本仓表格的约定,且**相邻两行可能指不同文件** ⇒ 机械继承必然误报 ⇒
|
||
改用「上文 40 行内点名的文件里**任意一个**行数够」的**弱判据**;③ 行号越界才是硬失败。
|
||
— 代价:多一个 Python 扫描器;**文档改行号后必须同步改**(这是本闸门的全部意义);
|
||
弱判据意味着**个别**续行行号漂移抓不到(能抓到"没有任何点名的文件够长"这一档)。
|
||
|
||
**Ruling P91 — 契约尺子**默认自起隔离后端**;显式给了 `B` 才不自起。**
|
||
— 动机:两把契约尺子原先都要求「后端已经在 `:30010` 起着」⇒ 三个具体问题:
|
||
① **两把尺子互相踩** —— 面 A 尺子改了库里的角色/菜单授权 ⇒ 面 B 尺子的前置状态被污染
|
||
⇒ 面 B 的结论**依赖面 A 跑没跑、跑的顺序** ⇒ 尺子不可独立复现;
|
||
② **跑完留脏数据** —— 每次跑都往 `src/backend/data/lite.pg` 里多一行 `smoke_user` /
|
||
`shop_product` / `book_shop_book`(`known-limitations` (n))⇒ 重复跑让这两张表无界增长;
|
||
③ **CI 里没法跑** —— 没人替你起后端 ⇒ 闸门形同虚设。
|
||
— 裁决:把「起后端」收进尺子自己(新文件 `scripts/smoke_backend.sh`,被两把尺子 `source`,
|
||
**不独立可执行**),口径三条:
|
||
① **没给 `B`** ⇒ 先探 `:30010`:**通** ⇒ 就用它(保留「跑开发中的后端」这个习惯,不逼用户改习惯);
|
||
**不通** ⇒ **自起隔离实例** —— 空闲端口(`python3` 真 bind 一下拿端口,退化时扫 `30110-30199`)
|
||
+ `mktemp -d` 临时 `PGLITE_DIR`(**绝对路径**,契约要求);
|
||
② **显式给了 `B`** ⇒ **不自起**(尊重外部后端)⇒ 不可达即**退出码 2**;
|
||
③ 退出时尺子 `trap` 先 `TERM` 后端(等 6s 再兜底 `KILL`)再删临时目录 ⇒ 库里的痕迹**随临时目录一起消失**。
|
||
⇒ 断言可重复、两把尺子互不污染、CI 可跑。
|
||
— 🔴 **刻意不做的事**:**不**在尺子里把外部后端「顶掉」(不许抢 30010、不许 kill 用户的进程)——
|
||
显式 `B` 不可达就**报错退出**,而不是自作主张换端口打空气;
|
||
**不**把「自起」做成默认的**唯一**路径(那会逼用户放弃「打开发中后端」的习惯)。
|
||
— 代价:① 多了 `scripts/smoke_backend.sh` 一个文件(尺子不再自包含 ⇒ 拷贝尺子时**必须一起带走**);
|
||
② 自起路径要等后端就绪(最多 40s,冷启动含建 10 张表)⇒ 尺子比原来慢一点;
|
||
③ **端口是动态的** ⇒ 依赖固定端口 30010 的外部脚本会拿不到(显式 `B` 可绕)。
|
||
|
||
**Ruling P92 — 官方端点覆盖要有一本**机器可读的账**(`[OFFICIAL]` 台账 + CC10 双向对账)。**
|
||
— 动机:面 B 的「做了多少」原先只有**尺子的断言数**(`面 B 覆盖 18/18`)这一个信号,
|
||
而**官方端点全表**(`JNPF_SOURCE_AUDIT.md` §4)是**散文表格** ⇒
|
||
「官方端点做了没、做到什么程度」**只能靠人读散文** ⇒ 既不可机器核对,也没法当进度条。
|
||
另一个隐患:**散文表格与代码各说各话** —— 台账说做了、代码里没注册(或反过来)没人发现。
|
||
— 裁决:在 `docs/contract.md` 附录 A 新增 **`[OFFICIAL]`** 区段(机器可读,53 行),
|
||
每行 = `method` / `path` / `status` / `src`(官方出处 `文件:行号`)/ `note`(偏差说明)。
|
||
状态词表**穷举四态**:
|
||
`implemented`(已落地且形状对齐)/ `partial`(已落地但**形状有偏差**,偏差逐条指向
|
||
`JNPF_COMPAT_SURFACE.md` §8 的 B1–B10)/ `absent`(未实现,可后置)/
|
||
`oos`(v1 明确不做:导入导出族、数据权限链接 —— **不进覆盖分母**)。
|
||
`scripts/check-contract-scan.py` 加 **CC10**,与**代码真实路由双向**对账:
|
||
① 说 `implemented/partial` 的必须**真的注册了**;说 `absent/oos` 的必须**没有**注册;
|
||
② 反向:**面 B / 共用**的每条路由都必须在台账上**有账**(防"实现了但没记账");
|
||
③ 打印**「官方端点覆盖 N/M」**(N = implemented+partial,M = 再加 absent)——
|
||
与面 B 尺子的「覆盖 N/18」同一路数:**诚实量进度**。
|
||
台账的 `src` 列是官方出处 `文件:行号` ⇒ 由**引文闸门(P90)逐条核对**
|
||
⇒ 台账里的官方出处**不是抄来的,是验过的**(现 198 条引文全中)。
|
||
— 🔴 **刻意做的三件事**:
|
||
① **台账与散文表格并存**(§4 仍是人读的)⇒ 代价是**同一批官方端点写两处**,
|
||
两处都用 `🔴` 互相指路(§4 指 `[OFFICIAL]`;`[OFFICIAL]` 的 `src` 指 §4 的行号);
|
||
② **CC10 挂在 `check-contract.sh` 而不是新开第七道闸门** —— 它的性质与 CC2–CC9 完全同源
|
||
(都是「台账 ↔ 代码」),合在一起只多一条断言(9 → 10),闸门总数仍是**六道**;
|
||
③ **`partial` 单列成一态** —— 硬塞进 `implemented` 会让覆盖数虚高,
|
||
硬塞进 `absent` 又会让人以为"没做" ⇒ 官方形状的**偏差**必须**看得见**。
|
||
— 代价:① 官方端点表写两处(改端点 ⇒ 两处都改,CC10 会红);
|
||
② **覆盖 N/M 是个会动的数**(官方端点表一变,分母就变)⇒ 文档里**不钉死具体数字**的地方
|
||
只能写"以尺子输出为准";③ 台账的 `src` 列与引文闸门**耦合** ⇒ 官方源码换了文件/行号 ⇒
|
||
引文闸门会红(这是**故意的**:出处漂移了就该报)。
|