Files
ssw-jnpf-lite-rust/docs/known-limitations.md
T
adminandClaude Code 5350fc6400 feat(spec): 官方 JNPF 对齐三件套 + 第二把尺子(面 B 规格落地前的地基)
- docs/JNPF_SOURCE_AUDIT.md:官方 Java/Vue 源码逐行核对(标 文件:行号),
  差异清单 D1–D8(端点风格 / 列表响应 / CurrentUser 形状 / 码表 / 菜单接口 /
  鉴权模型 / 请求头 / 口令存储)。
- docs/JNPF_COMPAT_SURFACE.md:面 B 规格 —— 官方形状的端点 / 响应 / 码表 /
  分流规则 / 落地顺序 S1–S6。
- docs/MIGRATION.md:本仓 ↔ 官方逐项映射 + 数据 ETL + 口令 secretkey 换算
  (一次性换算即可,不需要明文)。
- scripts/perm-smoke-jnpf.sh:第二把尺子,18 条官方形状断言;未落地记 SKIP
  且不计入 PASS(当前 PASS=5 FAIL=0 SKIP=13 ⇒ 覆盖 5/18)。

fix(spec): 面 A/面 B 判别头纠错 —— 改用 `Vue-Version: 3`

规格初稿断言「本仓前端一个官方头都不带」并用 `Jnpf-Origin: pc` 判面,
但本仓前端 request.ts:35-36 **也发** App-Code 与 Jnpf-Origin(与官方同款)
⇒ 按字面实现会把每个面 A 请求都误判成面 B。三个官方头里只有 Vue-Version
是本仓前端唯一不发的 ⇒ 判别只能用它。已在规格(§2.2 / D7 / A13 / §3.7)
统一改正,并在 check-module.sh 的「全局红线」段静态钉住两侧:
本仓前端禁发该头 + 面 B 尺子必带该头。

docs: 导航文档补链 + 已知限制新增 §H

CLAUDE.md 红线加第 9 条(判别头)、README.md 目录与「第二把尺子」、
HANDOFF.md §0/§6/§9(已知限制 + 下一步 S1–S6)、known-limitations.md §H
(面 B 只有规格没有实现 / 缺 secretkey 一步 / 判据是菜单路径不是点权限 /
码表缺 602)。

验证:cargo test 179 passed / 0 failed;check-module.sh PASS=57 FAIL=0;
perm-smoke.sh(面 A)PASS=32 FAIL=0;perm-smoke-jnpf.sh PASS=5 SKIP=13。

Co-Authored-By: Claude Code <[email protected]>
2026-10-26 10:37:20 +08:00

15 KiB
Raw Blame History

分支级已知限制清单(tds-lite-rs · 交付态)

本清单是逐任务评审过程中被明确「接受/挂起」的条目汇总 —— 不是新发现,是已裁决的。 每条都带裁决来源(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 · 面 B 规格 JNPF_COMPAT_SURFACE.md · 迁移指南 MIGRATION.md。

# 限制 出处 为什么接受 / 代价
(ac) 面 B 只有规格、没有实现 —— 官方形状的端点 / 响应 / 码表全部只写在 docs/JNPF_COMPAT_SURFACE.md,代码一行没写 面 B 规格 §7(落地顺序 S1–S6) 规格先行是本轮的刻意安排:先逐行核对官方源码把差异钉死(D1–D8),再按 S1–S6 落地,避免"边写边猜契约"。代价:官方 JNPF 前端目前还跑不进本仓(CurrentUser 形状、列表分页、602 码都还没做)⇒ scripts/perm-smoke-jnpf.sh 当前报 覆盖 5/18(其余 SKIP,不计入 PASS)
(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) 权限判据是菜单路径,不是官方的点权限 —— 本仓守卫 = spec.module_key == base_module.f_url_address;官方取 base_module.f_en_code(@SaCheckPermission("permission.user")) JNPF_SOURCE_AUDIT.md D6 · PERMISSION.md §二 本仓种子菜单没有 f_en_code(官方才有)。为何接受:面 A 的判权已被 32 条断言钉死(含"菜单收窄 + 403 拦截")。代价:迁官方前必须给菜单补 f_en_code(MIGRATION.md §2.4);面 B 落地时要两套判据并存(路径判权给面 A、f_en_code 判权给面 B)
(af) 官方码表有 4 个本仓没有的 code:401 VALIDATEERROR / 500 EXCEPTION / 601 SESSIONOFFLINE / 602 SESSIONERROR JNPF_SOURCE_AUDIT.md §4 · JNPF_COMPAT_SURFACE.md §4 本仓只有 200/400/403/600。为何接受:面 A 契约逐字定死(docs/contract.md),加 code 会改面 A 行为。代价:🔴 官方前端 request.ts:78-80 只在 601/602 时清 token ⇒ 只返 600 会让页面卡住不跳登录 ⇒ 面 B 的无 token 必须返 602,面 A 继续返 600(两套并存,靠判别头分流)

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 尺子必带该头。