Files
ssw-platform/docs/known-limitations.md
T
admin 6d6e0ee329 feat(platform): 标准平台包 v0.3.0 —— 业务自带状态的可组合装配
- Db 暴露同一个 Arc<PGlite>(Db::pg());Platform 两阶段装配 Assembled/Finish
- Extras 加自带状态路由 / 可替换兜底 / 全局层,with_state 前移;默认路径行为不变
- 新增探针 business_composition_it 与闸门 AR19(反自证 14/14)
- 文档:CHANGELOG / known-limitations / 需求稿实施记录与勘误
2026-11-04 18:20:03 +08:00

179 lines
32 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 不做递归是**有意**的(避免一次请求删掉整棵子树) |
| (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 '%,<uid>,%'` 等 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 导出库。返假链接(前端会直接 `<img src>`)只会 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: "<geojson 字符串>", 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<PGlite>` 后绕过 `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` 上抢先处理 |