后端从平铺(src/{config,db,cipher,…,entities}.rs)改两层,对齐 react 版的
common+auth+sys / demo+shop+books 与官方 JNPF 的 jnpf-common+jnpf-system / jnpf-admin。
- 平台层 src/platform/:契约实现(config·db·cipher·envelope·ids·session·state·
auth·permission·seed·sys·jnpf·entity·crud)—— 加业务模块不动
- 业务层 src/modules/:mod.rs + demo/shop/books,各自带 spec + 3 条路由 + 自己的 router()
- routes.rs 变成「平台路由 + 一次 merge(modules::router())」,业务路由不再登记在平台层
- 业务路由清单也搬到业务层(modules::ALL_ROUTES),平台层钉子测试遍历它
⇒ 原来「每加一模块要改 routes.rs 路由表」的口子被堵死
- 清掉平台层最后一个业务知识泄漏:S22 的 f_creator_user_id 规则原在引擎里写死
app_code == "demo",改为业务 spec 自己声明(EntitySpec.creator_fixed)
- check-module.sh 新增反向断言(平台层不得注册业务路由)+ 正向断言(业务层须登记)
⇒ 断言 57 → 69
- 文档同步(SKILL/CLAUDE/README/HANDOFF/PERMISSION/MIGRATION/HOWTO_MODULE/contract),
新增红线「平台层不许出现业务表名 / app_code」;decisions.md 补 P81
验证:cargo build --release 0 error 0 warning · cargo test 197 passed / 0 failed ·
check-module.sh PASS=69 FAIL=0 · 面 A PASS=32 FAIL=0 · 面 B PASS=18 FAIL=0 SKIP=0
Co-Authored-By: Claude Code <[email protected]>
773 lines
67 KiB
Markdown
773 lines
67 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>`」。**
|
||
— 理由:核对 `src/backend/src/config.rs:25` = `#[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` / `entities.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` / `entities.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` 的现状描述为准。
|