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

86 KiB
Raw Blame History

决策记录(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。

配套阅读:


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 列与引文闸门耦合 ⇒ 官方源码换了文件/行号 ⇒ 引文闸门会红(这是故意的:出处漂移了就该报)。