Files
ssw-platform/docs/known-limitations.md
T
admin afc4fc1f5f 面 B:跑通 JNPF 前端用户管理页 + 补齐机构 CRUD
- 前端真跑起来:登录→/home→/permission/user 正常渲染,零非 200
- 新增端点 31 条(Group 一族/SetPosition/getDevUser/workHandover/Organize CRUD+Selector/
  页面级 404 五条)
- 新表 base_group(官方 DDL 逐字),tables 12→13
- 修:preferenceJson 必须为字符串;菜单 urlAddress 走 permission/user;
      Users 列表 keyword 未进 SQL;空关键词多传参数导致 PG bind 报错
- 契约三处 + JNPF_REGISTERED 同步;六闸全绿,cargo test 221 全过
2026-10-31 03:13:13 +08:00

108 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 分支级已知限制清单(ssw-jnpf-lite-rust · 交付态)
> 本清单是**逐任务评审过程中被明确「接受/挂起」**的条目汇总 —— 不是新发现,是**已裁决**的。
> 每条都带裁决来源(ledger 的 `Ruling P##` / `Ruling F##` / 任务号)与「代价」。
> 最终整体评审**不必重新裁决**这些,但可以指出「某条其实该修」。
🔴 **本文件是 SDD 工作区(`.superpowers/sdd/<plan>/`)里那份清单的**受版本控制的正本**——
工作区是 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<String>` 遇**畸形百分号编码** ⇒ 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<AppState>`(内部 `.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 尺子**必带**该头。