Files
ssw-platform/docs/decisions.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

976 lines
86 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 决策记录(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>`」。**
— 理由:核对 `src/backend/src/platform/config.rs:41` = `#[derive(Clone, Debug)]`。
契约的 `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` 列与引文闸门**耦合** ⇒ 官方源码换了文件/行号 ⇒
引文闸门会红(这是**故意的**:出处漂移了就该报)。