# 分支级已知限制清单(ssw-jnpf-lite-rust · 交付态) > 本清单是**逐任务评审过程中被明确「接受/挂起」**的条目汇总 —— 不是新发现,是**已裁决**的。 > 每条都带裁决来源(ledger 的 `Ruling P##` / `Ruling F##` / 任务号)与「代价」。 > 最终整体评审**不必重新裁决**这些,但可以指出「某条其实该修」。 🔴 **本文件是 SDD 工作区(`.superpowers/sdd//`)里那份清单的**受版本控制的正本**—— 工作区是 git-ignored 的过程草稿,会在交付时清掉;本文件才是跟着仓库走的。 --- ## A. 后端实现层 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (a) | `restore_base_module` 用**子串匹配**恢复模块 ⇒ 会误伤 `base_module_ext`、会丢二级索引 | Task 6 遗留 | 契约未要求二级索引;代价:菜单恢复不是精确恢复 | | (b) | `Db` **没有跨调用持锁的公开接口** ⇒ 业务上的多步写**不是**单一事务 | P59 / P71 | 契约 §6 只要求「单次调用原子」;代价:跨表多写可能部分失败(具体实例见 **(z)**) | | (c) | Task 7 的「DB 报错」测试会**重复插入** admin 的 `base_role_relation` 行 | Task 7 | 测试夹具问题;不影响生产路径 | | (d) | `sys.rs` **1290 行单文件** | P68 | 5 组 `base_*` 显式 handler 的必然体量;代价:可读性/可拆分度 | | (e) | `user_role_map` **整表加载**到内存 | P69 | 数据量小;代价:多用户场景内存随行数线性增长。**M-12 补充的具体例子**(最终整体评审修复轮 R=3):每次列用户都会把**整张** `base_role_relation`(全量用户↔角色关系)+ **整张** `base_role` 拉进内存 ⇒ 用户/角色规模上去后,单次请求的内存占用随行数线性增长 | | (f) | `or_zero` 对**非字符串**值的处理未逐类型覆盖 | P67 | 契约只对 string 有要求。**M-11 补充的具体例子**(最终整体评审修复轮 R=3):`or_zero` 把「数字 / 布尔 / 对象 / 数组」一律当 `"0"` ⇒ 例如 body 传 `"organizeId": 123`(**数字**而非字符串)会落库成 `"0"` 而不是 `"123"` | | (g) | `write_cast` 用**硬编码 cast 表**,未直接用 `col.numeric` | P73 | 两条路径已由测试钉住一致;代价:schema 变更时需同步两处 | | (h) | **6 条既有 clippy 告警**:`sys.rs`×3 / `permission.rs`×2 / `tests/seed_it.rs`×1 | P75 | 全部先于本分支存在;**零新增**;代价:CI 需容忍这 6 条 | | (i) | `insert_new` 与 `update_existing` 各自构造 `$n::text{cast}` 占位符,**逻辑重复** | Task 8 Minor 2 | 合并属「顺手重构」;代价:一处改了另一处可能漏 | ## B. 装配与路由层 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (j) | **后端不托管前端静态产物**(无 static 文件服务) | P79 | 契约 §6.8/§10 把静态托管写成**可选**;前端由 vite dev server(`:5173`) 托管、`/api` 代理到 `:30010`;**四条验收门没有一条**要求后端托管前端。**红线「DDL 绝不可从 HTTP 下载」由「后端根本不读文件系统响应请求」天然满足**,并另有守卫测试(`GET /db/schema.sql` ⇒ 404 + 信封)。代价:后端**不能**单独跑全栈 | | (k) | release 二进制**没有 catch-all 的自动化覆盖** | Task 10 Minor 4 | panic 端点是 `#[cfg(test)]` 专属(守住「非测试代码零 `panic!()`」红线);catch-all 中间件代码在测试构建与 release 构建**逐字相同**,且 release profile **无** `panic = "abort"` ⇒ 行为等价 | | (l) | ~~`Path` 遇**畸形百分号编码** ⇒ axum 默认返**非信封的 400 响应**~~(该断言**已被推翻**,见右栏) | Task 10 Minor 7 | 🔴 **已推翻**(最终整体评审修复轮 R=3,控制器逐条独立复现):axum 0.8.9 **接受**该转义 —— 实测 `PUT /api/permission/Authority/Data/%zz` 返回 **HTTP 200 + `{"code":600,"msg":"未登录","data":null}`**(信封,正常)⇒ **不存在**「返非信封 400」这种破口。原裁决的前提(axum 会吐非信封的 400)**不成立** ⇒ **不改代码** | | (m) | 标识符白名单自检是**兜底 tripwire、不是完备证明** | P77 | 自检只查 spec 的表/列 + 10 张表字面量清单;**明确不查** `sys.rs` 的 4 组投影列常量(源码字面量常量,写错编译期就炸)。代价:编译期 SQL 拼写错误不在自检覆盖面内 | ## C. 冒烟脚本层(`scripts/perm-smoke.sh`) | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (n) | 每次跑**留一行** `shop_product` + 一行 `book_shop_book` + 一行 `smoke_user` | Task 11 fix R=1 | react 版同款行为;契约 §13 **未要求**清理 ⇒ 不改。代价:重复跑会让这两张表**无界增长**(第 30 条断言的计数因此递增)。🔴 **仅在复用外部后端时**:尺子**默认自起隔离实例**(临时数据目录)⇒ 跑完即删、不留脏数据 | | (o) | 「重复账号 curl 超时」场景下 stderr 会多一行 `cat: … No such file` | Task 11 fix R=1 | 纯观感;断言 7/8/9 仍正确判失败 | | (p) | 「空 body 前置失败」时 jq/python 两条路径的**前置提示文案不同**(`code=无` vs `code=ERR`) | Task 11 fix R=1 | 退出码**都是 2**;纯文案不一致 | ## D. 前端层 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (q) | `src/api/request.ts:5` 的注释仍写「转发到 **30000**」 | Task 12 brief S13① | **刻意留下**:「逐字复制、只改代理目标」是硬约束 ⇒ `diff -r` 的判据是「全部差异只出现在 `vite.config.ts`」。改它会让 diff 门失败。代价:一行**陈旧但无害**的注释 | | (r) | 前端 `api/*.ts` 的导出名是**自然英语复数**(`listBooks` / `listProducts`) | Task 12 brief S13② | 逐字复制的必然结果;`scripts/check-module.sh` 照抄 react 的 `plural()` 逻辑适配 | | (ac) | Dashboard 的「功能菜单」**只渲染二级节点**(`node.children.map`)⇒ 顶层菜单(`Demo 示例` / `产品管理` / `图书超市`,种子 `parent_id='0'`)**只出标题、没有按钮**,这三个业务页只能按 URL 直达 | 逐字复制 react 版 `src/frontend/src/views/Dashboard.tsx:46-56` | **刻意留下**:前端是 react 技能的逐字复制(唯一允许的改动 = vite 代理端口)⇒ 改 Dashboard 会让「前端差异只出现在 `vite.config.ts`」的核对门失败。契约 §8.4 只规定菜单树结构、**没规定 Dashboard 按钮粒度** ⇒ 契约未覆盖。代价:三个业务页在 UI 上无侧栏入口(需记 URL / 收藏);门④ 的浏览器自验同样按 URL 直达验的 | ## E. 已明确「不改」的契约级偏差(**已由测试钉住**) | # | 事项 | 出处 | 说明 | |---|---|---|---| | (s) | `crud.rs` 的 UPDATE 占位符改成 `$n::text{cast}` | P78(Task 8 R=1) | 改前:写 timestamp/numeric/int **100% 失败**(`code=400`);改后:参数恒为 text、转换在服务端做。**契约可观测行为方向是「违约 → 守约」**;返回值形状/错误文案/列集/路径分流/handler 签名全未变 | | (t) | 契约 §9 写 `build_router(state) -> Router`,而 `Router<()>` 与「main 再调 `with_state`」**类型上不能同时字面成立** | P76 | 裁决:`build_router(state: AppState) -> Router`(内部 `.with_state(state)` 是**类型层面 no-op**,只为让契约的 `state` 参数有去处),**链尾唯一一次** `with_state(state)` 把类型落成 `Router<()>` | ## F. 运行脚本层(`run.sh`) | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (u) | ~~`pkill -f "vite"` 是死代码~~ | 控制器 2026-10-26 | 🔴 **已推翻**(控制器早先据一次失效探针得出的「macOS `pkill -f` 只匹配 argv[0]」是**错的**):重做实测证明 `pkill -f` 匹配**完整命令行** ⇒ `pkill -f "vite"` **打得中**,但**匹配面过宽**(别的项目的 vite 也中)。⇒ 该条已**从限制清单移出**,改为 Task 12 修复轮 R=1 的**必改项**(收窄模式 / 删掉 vite pkill,交给 `kill_ports`) | | (v) | `run.sh dev` **就绪失败**时只收**前端**(按 PID 文件),**不收后端** | Task 12 修复轮 R=2 | 已实测的失败场景(后端打不开数据库目录)里**后端自己会退出**(pglite 报错 ⇒ 进程 exit 1)⇒ 只需要收前端。**残留场景**:后端进程活着但 `/api/health` 一直不通(HTTP 层坏了)⇒ 后端会留在后台占着 30010。**为何不改**:① 该场景要求 HTTP 层已经坏了(`kill_ports` 在启动前已清过端口 ⇒ 端口被占不会触发它);② **自愈** —— 下一次 `dev` / `stop` 的 `kill_ports 30010` 会把它收掉;③ 贸然收后端会有「后端只是慢、其实好的」被误杀的副作用。**代价**:极端场景下 `dev` 失败后机器上留一个后端进程 | | (w) | `run.sh stop` / `run.sh logs` 仍无条件 `mkdir -p "$LOGS" "$RUN"` ⇒ `logs`(**只读** tail)也会造出空的 `.run/` + `.logs/` | Task 12 修复轮 R=2(scoped re-review 新增 Minor) | R=1 必改 5b 的 brief **点名**了 `dev`/`stop`/`logs` 三个分支 ⇒ 实现者照办。**代价**:纯观感(两个空目录,`.gitignore` 已覆盖);`--help` 与无参**不造**目录(原缺陷已消除) | ## G. 最终整体评审新增(修复轮 R=3,2026-10-26) | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (x) | **token 的真实寿命 = 后端进程寿命**(`session.rs` 是内存 token 表、**没有 TTL**);登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量(`docs/contract.md:448`)、**不会被强制执行** | M-6(最终整体评审) | `expiresIn: 7200` 继承自 JNPF/Sa-Token 的语义;**契约逐字定死**该字面量 ⇒ 改代码即破契约 ⇒ 只如实写清文档。代价:进程不重启时 token 永不过期(与内存 token 表「进程重启即失效」是同一条事实的另一面) | | (y) | **口令比对不是常量时间**(`auth.rs` 里 `stored.to_lowercase() != plain_md5.to_lowercase()`) | M-7(最终整体评审) | **为何接受**:HTTP 上对 md5-hex 比对的计时攻击收益可忽略;且改动落在**最敏感的登录路径**、收益 < 风险 ⇒ 挂起。代价:留下一个理论上的计时侧信道(**实际不可利用**) | | (z) | `sys.rs` 的 `user_save` 的「插用户行」与「写角色关系」是**两条独立语句** ⇒ 步骤 2 失败时**用户行已提交、角色关系没写** ⇒ 响应 `code=400` 而库里已有该用户 | M-10(最终整体评审);是 (b)(P59 / P71 裁决)的**具体实例** | 契约**未**要求跨调用原子性(`docs/contract.md` 全文无「原子 / 事务 / atomic」字样)⇒ 不改。代价:极端场景下前端提示「保存失败」但用户其实已建好 | | (aa) | **停机后第二个 SIGTERM / SIGINT 不再强制终止进程**(首个信号后 tokio 的信号 handler 仍在位) | R=3 scoped re-review Minor 4 | 首个信号后进入优雅停机,收尾**有界**(`postmaster.pid` 轮询上限 3 秒)⇒ 不会挂死。**为何不改**:加「二次信号 ⇒ force-exit」要动刚写好的信号路径,收益仅是省 ≤3 秒等待,风险 > 收益。代价:急停需另发 `SIGKILL` | | (ab) | 停机路径用 `std::process::exit(0)` 收尾 ⇒ `run()` 的 `Ok` 路径不可达;且 `axum::serve` 以 `Err` 结束时 `?` **提前返回** ⇒ PG **不走**优雅关闭(仍被 SIGKILL 掉) | R=3 scoped re-review Minor 6 | **刻意设计**:pglite 的收尾线程可能卡死 ⇒ 不能让它吊住整个进程。`serve` 异常退出与改动前行为一致(**非回归**)。代价:`serve` 异常退出时 PG 仍要走 crash recovery | ## H. 官方 JNPF 对齐(面 B)—— 2026-10-26 > 本节是**「把官方 JNPF 前端跑进本仓」**这条线的已知限制。三份配套文档: > 官方源码核对 [`JNPF_SOURCE_AUDIT.md`](../JNPF_SOURCE_AUDIT.md) · 面 B 规格 > [`JNPF_COMPAT_SURFACE.md`](../JNPF_COMPAT_SURFACE.md) · 迁移指南 [`MIGRATION.md`](../MIGRATION.md)。 | # | 限制 | 出处 | 为什么接受 / 代价 | |---|---|---|---| | (ac) | ~~**面 B 只有规格、没有实现**~~ —— ✅ **2026-10-26 已落地**(S1–S6 一次性做完):`src/backend/src/platform/jnpf.rs` + `routes.rs` 5 条新路由 + `seed.rs` 的 `f_en_code` + `permission.rs` 的第二套判据 | 面 B 规格 §7 | **规格先行**的收益兑现:官方形状的 18 条断言**全部落地** ⇒ `scripts/perm-smoke-jnpf.sh` 从 **`覆盖 5/18`** 走到 **`PASS=18 FAIL=0 SKIP=0`(18/18)**;面 A `perm-smoke.sh` 仍 **`PASS=32 FAIL=0`**(面 A 的 27 条路由**一字未动**) | | (ad) | **口令存储缺官方 `secretkey` 一步** —— 本仓 `base_user.f_password` 存 `md5(明文)` 的小写 hex;官方存 `md5(lower(md5(明文)) + lower(secretkey))` | `JNPF_SOURCE_AUDIT.md` §2.6 · `MIGRATION.md` §7 | **迁官方时可一次性换算,且不需要明文**(`secretkey` 是每行自带的 ⇒ 库里算得出)。**为何本仓不改**:官方 `secretkey` 的**生成规则**未在本仓建模(每用户一个随机 secret),改了会让本仓与 react 版**不再同形**、破坏"两版可开同一个库"的前提。代价:**现在不能直接把本仓的库丢给官方后端登录**(须先跑一次换算) | | (ae) | **面 A 的权限判据仍是菜单路径** —— 面 A 守卫 = `spec.module_key == base_module.f_url_address`;**面 B** 另有一套 = `base_module.f_en_code`(`@SaCheckPermission("permission.user")`) | `JNPF_SOURCE_AUDIT.md` D6 · `PERMISSION.md` §二 · 面 B 规格 §3 | ✅ **两套判据已并存**(`has_module` 给面 A / `has_en_code_permission` 给面 B),**互不影响**、各自短路与放行规则同构。**代价**:面 B 的 `f_en_code` 判据**依赖菜单行存在** ⇒ 未映射 ⇒ 放行(与面 A 同一条红线)⇒ 官方点权限**不映射就没有**;且本仓**只做菜单级**(`item_type='module'`),按钮级不做(见 (ag)) | | (af) | ~~**官方码表有 4 个本仓没有的 code**~~ —— ✅ **2026-10-26 已补齐**(`envelope.rs` 的 `code::*`:含 `401`/`500`/`601`/**`602`**) | `JNPF_SOURCE_AUDIT.md` §4 · 面 B 规格 §4 | 面 A 的码**一个都没改**(`600` 未登录 / `403` 无权限 / `400` 业务失败),**面 B 走 `602`** ⇒ 官方前端 `request.ts:78-80` 只在 `601`/`602` 清 token ⇒ 不会卡住不跳登录 | | (ag) | **按钮 / 列 / 表单 / 数据级权限不做** —— `permissionList` 的 `button`/`column`/`resource`/`form` **恒空数组** | 面 B 规格 §8 B4 | 官方 DDL 里 `base_module_button` / `_column` / `_form` / `_data` 都有,但 v1 范围只做 `item_type='module'`。**代价**:官方前端**动态模型页的按钮恒显**(不隐藏);官方前端对 `permissionList` 缺项是**容错**的(`list && list.button ? list.button : []`)⇒ 不报错 | | (ah) | **三个业务菜单的 `f_en_code` 是本仓自定占位** —— `permission.demo` / `permission.shop.product` / `permission.books.book` | 面 B 规格 §8 B8 | 官方没有 demo/shop/books 三个模块。**代价**:迁官方时要改成官方编码;当前占位**不与官方 `permission.*` 冲突**(官方只用到 `permission.user`/`role`/`organize`/`menu` 等) | | (ai) | **`AuthorizeDataReturnVO.list`(权限树模型)返空数组** —— 只保证 `ids`/`all` 语义正确 | 面 B 规格 §8 B1 | 官方那套树模型(`modelId` + `button`/`column`/`resource`/`form` 子树)本仓不做。**代价**:官方授权弹窗需二次适配(`ids` 可直接用) | | (aj) | **组织 `AsyncList/{id}` 不分页** —— 按父 id 逐层取,`pageSize` = 本层条数 | 面 B 规格 §8 B10 | 官方前端就是靠这个接口**逐层展开**机构树。**代价**:机构极多时无分页保护(本仓机构表本身很小) | | (ak) | **`DELETE /api/permission/Organize/{id}` 不级联** —— 只软删本行 | 面 B 实现 2026-10-31 | 官方删父机构会连带子机构。**代价**:删父后子机构**悬挂**(`f_parent_id` 指向已软删的行),列表里**不会再出现**(`f_delete_mark=0` 过滤)⇒ 表现为「孤儿节点静默消失」。v1 不做递归是**有意**的(避免一次请求删掉整棵子树) | | (al) | ~~**`GET /api/permission/Users` 的 `keyword` 不生效**~~ —— ✅ **2026-10-31 已补齐**:`f_account` / `f_real_name` / `f_mobile_phone` 三列 ILIKE,空关键词**一个参数都不传** | 面 B 实现 2026-10-31 | 🔴 坑:空关键词时若仍把 `like` 塞进参数数组 ⇒ SQL 里没有 `$1`,PG 报「bind message supplies 1 parameters, but prepared statement requires 0」⇒ **必须** `if keyword.is_empty() { Vec::new() }` | ### H.1 🔴 一条**判别规则**(不是限制,是红线) 面 A(本仓 ssw/react 形状)与面 B(官方 JNPF 形状)**共用同一套 `base_*` 表与 cipher**,靠**请求头**分流: | 请求头 | 判定 | |---|---| | 含 **`Vue-Version: 3`** | ⇒ **面 B**(官方形状) | | 不含 | ⇒ **面 A**(ssw 形状) | 🔴 **判别头只能是 `Vue-Version`**:官方前端发 `App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3` 三个头, 而本仓前端 `src/frontend/src/api/request.ts` **也发**前两个(与官方同款)⇒ **只有 `Vue-Version` 是本仓前端唯一不发的**。 🔴 **本仓前端禁止发 `Vue-Version`**(发了 ⇒ 面 A 请求被误判成面 B ⇒ 契约整体错位)。 🔴 `scripts/check-module.sh` 的「全局红线」段**静态钉住两侧**:前端**禁发**该头 + 面 B 尺子**必带**该头。