# 分支级已知限制清单(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 不做递归是**有意**的(避免一次请求删掉整棵子树) | | (am) | **消息中心 7 条「真连服务商」端点恒明确失败** —— 本仓**没有 HTTP 客户端** ⇒ `Account/testSendMail` / `Account/{id}`(前端动态路径别名) / `Send/testSendConfig` / `Template/testSendMail` / `Monitor/{id}/Retry` / `Supplier/SyncTemplate` / `Supplier/TestConnect` 一律 `code=400` + `data:null` + 人话 | 面 B 实现 2026-11-02(批次 20) | **不返假发送结果、不返假模板、不返假连通性**。代价:官方前端「发送测试 / 测试连接 / 同步模板 / 重发」按钮点下去只会看到失败提示(本仓确实发不出去) | | (an) | **消息账号 / 供应商的密钥字段照官方返明文**(`smtpPassword` / `secretKey`) | 面 B 实现 2026-11-02(批次 20) | 官方 DDL 就是**明文**存(`base_msg_account.f_smtp_password` / `base_intg_supplier.f_secret_key`)且官方前端**要拿回来编辑** ⇒ 本仓**照官方**。🔴 与「用户登录口令不得外泄」是**两条不同的红线**(那条只管 `base_user.f_password`)。代价:**第三方服务商密钥会出现在响应体与前端内存里** | | (ao) | **供应商的新增 / 更新跳过「测试连接」** | 面 B 实现 2026-11-02(批次 20) | 官方落库前会**真连服务商**做「测试连接」⇒ 本仓**写库照做**(名称 / 编码 / 密钥重复校验全做),只跳过连通性。代价:**可能落库一个连不通的供应商**(官方会当场拦下) | | (ap) | **官方 Java 多暴露 12 条、官方前端从不调的 msgCenter 端点,本批不做** | 面 B 实现 2026-11-02(批次 20) | Account 的 `detail/{id}` / `unable/{id}` / `Action/Export` / `Action/Import`、Template 的同 4 条、Send 的 `/Selector` / `getInfoByEnCode/{enCode}` / `detail/{id}`、Monitor 的 `POST /Monitor`。代价:**按官方 Java 直接调的第三方客户端**会拿到 404(官方前端一条都不调) | | (aq) | **消息中心不做应用隔离** | 面 B 实现 2026-11-02(批次 20) | `base_msg_*` / `base_intg_supplier*` **没有 `f_system_id` 列**(官方 DDL 如此)⇒ `App-Code` 头**不影响**这一族。代价:**同一租户下多个应用的配置项互相可见**(与「多应用 = 同一租户下的多个子系统」口径一致,不是隔离漏洞) | | (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 尺子**必带**该头。 ## I. AI 中心 / extend 示例 / teamwork(批次 21–23,2026-11-03) > 这三族把官方前端 `src/api/**` 的**最后 179 条**端点补齐(`fe-gap` 从 717/900 → **900/900**)。 > 口径与批次 20 一致:**能本地自洽的真落库,需要外部能力的如实失败**。 | # | 限制 | 为什么接受 / 代价 | |---|---|---| | (ar) | **AI 中心没有 LLM 推理能力**:`Chat/Send` / `Translate` / `Optimize` / `AiSupplier/checkAi` / `Mcp/Sync` 一律 `code=400` + 人话 | 本仓 `src/backend/Cargo.toml` **没有 HTTP 客户端**(无 reqwest / hyper client)。假装流式返回一段文本 = 骗前端。代价:AI 中心页面只能做**元数据管理**,对话/翻译/连通性检查用不了 | | (as) | **知识库召回是关键词匹配,不是向量检索**:`Document/{id}/study` 本地按行切片(≤800 字)并落 `f_state=1`;`Knowledge/{id}/Test` 用 ILIKE 命中的词数占比当 `score` | 本仓没有向量库 / embedding 服务。**真做了切片与召回**(不是空壳),但语义召回质量不如向量检索。代价:同义词、跨语言召回会漏 | | (at) | **AI 中心的守卫只到「登录」**:官方是 `@SaCheckPermission("aiCenter.*")`,本仓没有 AI 菜单/权限点种子 | 如实降级(`require_login_face_b`)。代价:**任何登录用户都能改 AI 配置**(dev 环境可接受;集成期补菜单种子后改回 `guard(...)` 即可) | | (au) | **供应商密钥不下发**:列表/详情的 `credential` 恒空串,只给 `credentialConfigured` 布尔 | 官方会把密钥原样返给前端编辑;但本仓守卫只到登录 ⇒ 不能把密钥发给任何登录用户。代价:编辑供应商时**必须重新输入密钥**(留空=不改,更新逻辑已处理) | | (av) | **extend 的邮件 / 导入导出 / 预览不可用**:`POST Email`(发信)、`Email/Receive`、`Email/Config/Actions/CheckMail`、`Employee/{ExportData,ImportData,ImportPreview,TemplateDownload}`、`DocumentPreview/{id}/Preview` 一律 400 | 没有 SMTP/IMAP 客户端、没有 Excel 库、没有文件服务。草稿(`SaveDraft`)与邮箱配置**真落库**。代价:这些示例页的「发送/导出」按钮只会提示失败 | | (aw) | **extend 的金额 / 业务日期列是 TEXT** | 本仓的 SQL 绑定参数是 `$N::text`(进 NUMERIC/TIMESTAMP 列需逐列 cast)⇒ 示例页只做展示,用 TEXT 换实现简单。代价:**不能直接用 SQL 做金额汇总/日期比较**(报表要用需先 cast) | | (ax) | **`TableExample/CityList/{id}` 依赖 `base_province`**,本仓**没有行政区划种子** ⇒ 恒空列表 | 不编造城市数据。代价:控件示例的「城市」下拉为空(`IndustryList` 是官方同款静态选项,有值) | | (ay) | **teamwork 只存文件元数据,不存字节**:`UploadBlob` / `PackDownload` / `merge` 一律 400;文件夹 / 改名 / 移动 / 复制 / 分享 / 回收站 / 最近 / 标签 / 空间**真落库** | 本仓没有对象存储 / onlyoffice / 分片合并。代价:页面上传文件会失败,但目录与分享体系可用 | | (az) | **日程只落库,不推送提醒**:`base_schedule` 的 `reminderTime` / `sendConfigId` 原样存,**没有调度器真发提醒** | 本仓的 `scheduletask` 只登记任务、不执行;IM/邮件通道也没有。代价:日程到点不会通知 | ## J. 官方移动端(批次 24,2026-11-03) > 官方移动端(`jnpf/7.0-jnpf-app-vue3`)的 `api/**` 有一批**只在移动端出现**的端点 > —— 官方 Web 前端 `src/api/**` 里没有 ⇒ 做「Web 前端 900/900」时天然覆盖不到。 > 本批次新增 `platform/compat/mobile.rs`(39 条路由)+ `ext_work_log` 表。 > 🔴 **判别头不变**:移动端 `utils/request.js` 同样带 `Vue-Version: 3` ⇒ 仍走**面 B**。 | # | 限制 | 为什么接受 / 代价 | |---|---|---| | (ba) | **扫码登录确认失败**:`GET /api/oauth/confirmLogin/{ticket}` 一律 `code=400` | 本仓**没有扫码票据表**(官方用 Redis 存票据 + 状态机)。返「已确认」这种**假状态**会让桌面端误判成登录成功 ⇒ 如实失败。代价:扫码登录整条链路不可用 | | (bb) | **第三方登录全族失败**:`/api/oauth/socials/render/{source}`、`/api/oauth/socials/app/callback/{source}`、`POST /api/oauth/logoutCurrentUser` 一律 `code=400`;`GET /api/permission/socials/login` 返**空数组** | 本仓没有 OAuth provider 注册表,也**没有账号注销业务规则**。返假授权 URL 只会跳到 404 ⇒ 如实失败。空数组 = 「一个第三方都没配」的真实语义(不是假成功) | | (bc) | **地图服务失败**:`GET /api/system/Location/regeo` 一律 `code=400` | 本仓没有高德 key、也没有 HTTP 客户端。返假坐标会让移动端把设备定位到错误地点 ⇒ 如实失败 | | (bd) | **SaaS 邀请链接失败**:`GET /api/system/tenant/saas/inviteurl` 一律 `code=400` | 本仓是单租户,没有「邀请他人加入租户」的业务场景。代价:多租户邀请流程不可用 | | (be) | **工作日志「我收到的」靠 `f_to_user_id` 逗号串匹配**,没有官方的 `ext_work_log_share` 分享表 | 官方 `WorkLogServiceImpl.create` 会把收件人拆开逐个写进 `ext_work_log_share`(`share_user_id`),Receive 从那张表查。本仓只存了 `ext_work_log.f_to_user_id` 逗号串 ⇒ 用**精确匹配**(`LIKE '%,,%'` 等 4 段)代替,避免官方裸 `%uid%` 的「`abc` 误命中 `abcd`」问题。代价:无法回答「这条日志分享给了谁」的明细 | | (bf) | **App 菜单只按 `category='App'` 过滤**,不做「当前用户所属系统」的二次过滤 | 官方 `AppMenuController` 还要按 `appSystemId` 过滤。本仓**单系统** ⇒ 过滤恒等。代价:多系统部署时需要补这层 | | (bg) | **常用菜单(`MenuData/getAppDataList` / `getDataList`)返回**扁平列表**,不是官方那种嵌套树 | 官方 `getAppDataList` 把 `base_module_data`(`f_module_type='App'`)与 `base_module` 求交集后转成树(`TreeDotUtils.convertListToTreeDot`)。本仓已按官方真源(`base_module_data`,**不是** `base_app_data`)取数并带 `parentId`,但**没有在服务端组树** ⇒ 移动端需自己按 `parentId` 拼。代价:前端多一步 | | (bh) | **`WorkLog/Send` / `Receive` 存的是 user id**(官方 `WorkLogServiceImpl` 用 `UserProvider.getUser().getUserId()`),本仓**同样用 user id**;但本仓没有 `ext_work_log_share` 表 | 一开始误用 `user.account` 会导致「我发出的」永远为空 —— 已由 `mobile_it.rs` 的 `creatorUserId` 断言钉死。代价:跨系统搬运时要注意 id 语义一致 | | (bi) | **审批驳回落库口径**:任务 `f_status=3`(`TaskStatusEnum.REJECTED`)、处理人 `f_handle_status=0`(`FlowNature.REJECT_COMPLETION`)、留痕 `f_node_status=3`(`NodeStateEnum.REJECT`) | 官方 `FlowNature` 的 `handleStatus` 语义是 **NULL=待办 / 0=拒绝 / 1=通过** ⇒ 待办查询必须判 `f_handle_status IS NULL`(用 `COALESCE(...,0)=0` 会把「已拒绝」也算进待办)。已由 `mobile_it.rs` 的 `flow_before_cancel_writes_official_status_codes` 钉死 | ## K. 官方大屏(批次 25,2026-11-03) > 官方大屏设计器(`jnpf-visualdata`)**8 个 Controller / 53 条端点**,本批次新增 **52 条** > (此前只有 1 条「恒失败」占位)。三源对照:官方后端源码 + 官方 PostgreSQL DDL(9 张 > `blade_visual*` 表)+ 官方前端 api(`jnpf-web-datascreen-vue3/src/api/**`)。 > 🔴 **列族是 Blade 系**(`id` / `is_deleted` / `create_time`),与本仓其它契约面的 > `f_` 列族**故意不同名** ⇒ 未复用 `compat::res` 引擎,另建 `BRes` 专用层。 | # | 限制 | 为什么接受 / 代价 | |---|---|---| | (bj) | **大屏「数据源连库测试」与「动态 SQL」失败**:`POST /api/blade-visual/db/db-test`、`POST /api/blade-visual/db/dynamic-query` 一律 `code=400` | 本仓没有**外部数据库连接器**(只有内嵌 pglite,且不允许任意 SQL 出口)。返「连接成功」是**假连接** ⇒ 如实失败。代价:大屏的「数据集预览」链路不可用(配置能存,不能试连) | | (bk) | **大屏「代理 / API 转发」失败**:`POST /api/blade-visual/visual/proxy`、`POST /api/blade-visual/visual/GetApiData` 一律 `code=400` | 官方是**任意 URL 转发**(前端 `src/axios.js:68` 把带 `headers.proxy` 的请求统一改写到 `visual/proxy`)⇒ 本仓**不做 SSRF 面**。代价:大屏的「外部数据源取数」不可用(只能力取本仓内库数据) | | (bl) | **大屏文件服务全族失败**:`POST /visual/put-file/{type}`、`GET /visual/{type}`、`POST /visual/{id}/Actions/ExportData`、`POST /visual/Model/Actions/ImportData` 一律 `code=400` | 本仓**没有对象存储 / 文件服务**,也没有 Excel / zip 导出库。返假链接(前端会直接 ``)只会 404 ⇒ 如实失败。代价:大屏的「背景图上传 / 模板导入导出」不可用 | | (bm) | **大屏地图数据无来源时失败**:`GET /api/blade-visual/map/data` 在 `blade_visual_map.data` 为空时 `code=400` | 本仓没有高德 / 天地图 key,也没有地图服务。返假 geojson 会让 echarts `registerMap` 画出**编造的行政区边界** ⇒ 如实失败。代价:地图组件在没有真实 geojson 数据源时不可用(地图**元数据** CRUD 正常) | | (bn) | **`GET /map/data` 的响应**在本仓是**信封**(`{code, data: "", msg}`),官方是**裸字符串** body | 官方 Java 返回类型是 `String`(`VisualMapController.java:139`),前端 `src/echart/packages/map/index.vue:145` 取 `res.data` 直接 `registerMap` ⇒ **官方形状要求裸 body**。本仓统一走信封(其余 52 条端点也是)⇒ 官方大屏前端直接接本仓时,`map/data` 需多取一层 `data`。已由 `visualdata_it.rs` 钉死「失败时 `data` 必须是 `null` 且不含 `FeatureCollection`」 | | (bo) | **大屏「地图懒加载」不按 `parentId` 过滤时返全量** | 官方 `VisualMapServiceImpl.getListWithColnums` 用 `parentId` 过滤 + `hasChild` 标记。本仓照抄了 `hasChildren` / `parentName`,但**根节点**(无 `parentId`)与「全部」两种语义靠前端区分。代价:一次懒加载可能拿到多于一层的节点 | | (bp) | **大屏权限码只到 `onlineDev.dataScreen`**:官方**没挂** `@SaCheckPermission` 的端点(`assets/list`、`component/list`、`map/lazy-list`、`map/detail`)本仓也**只要求登录** | 照抄官方注解的**有无**(不是照抄语义)。代价:这些端点任何登录用户可读(大屏配置本身不是敏感数据) | ## L. 单进程双 DB 锁与 413 改写(v0.3.0,2026-11-04) > 需求与决策见 `docs/SSPF-BUSINESS-COMPOSITION.md` §10.3 / §10.4 / §11.1。 > 这两条都是「平台包承载自带状态的厚业务仓」时**主动接受**的边界,不是缺陷回归。 | # | 限制 | 为什么接受 / 代价 | |---|---|---| | (bq) | **平台与业务各有一把 DB 锁**:业务仓经 `Db::pg()` 拿 `Arc` 后绕过 `sspf_store::Db::lock`,自己的 `process_db_lock()` 与平台那把互不覆盖 ⇒ 并发下「一次业务操作跨多条 SQL」可能与平台 SQL 交错 | 单次 SQL 有 pglite 的 `serial_guard()` 串行化,不会破坏单条查询;本轮只求「同一个库、同一个端口」,统一到 `Db::begin()` 或暴露共享锁出口属 P3。代价:跨平台 / 业务的**多语句事务**不保证整体串行,业务仓需自行持锁;暂不暴露 `Db::lock()` 也避免了「业务持锁误调 `db.*` 死锁」 | | (br) | **业务侧的 413 / 非空体 405 会被平台改写成信封**:`m_status_rewrite()` 挂在总 Router 上,对任何 405 / 413 无条件改写;tdc 原来的 413 是 axum 默认 `text/plain` | 保持 S25「fallback 在两个平台 layer 之前、catch-all 覆盖面 B 与业务路由」这条硬约束,不给 `Extras` 加「跳过平台层」开关。405 两边形状逐字相同(`code/msg/data`),改写幂等;**413 与带 body 的 405 形状会变**。代价:业务契约里若钉死 413 的裸响应,需在业务 Router 自己的 `route_layer` 上抢先处理 |