From 5350fc64001bd85c2338ca05bf65dc36c351ecd0 Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 26 Oct 2026 10:37:20 +0800 Subject: [PATCH] =?UTF-8?q?feat(spec):=20=E5=AE=98=E6=96=B9=20JNPF=20?= =?UTF-8?q?=E5=AF=B9=E9=BD=90=E4=B8=89=E4=BB=B6=E5=A5=97=20+=20=E7=AC=AC?= =?UTF-8?q?=E4=BA=8C=E6=8A=8A=E5=B0=BA=E5=AD=90=EF=BC=88=E9=9D=A2=20B=20?= =?UTF-8?q?=E8=A7=84=E6=A0=BC=E8=90=BD=E5=9C=B0=E5=89=8D=E7=9A=84=E5=9C=B0?= =?UTF-8?q?=E5=9F=BA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .workbuddy/memory/2026-10-26.md | 40 ++ CLAUDE.md | 15 +- HANDOFF.md | 51 ++- README.md | 27 +- docs/JNPF_COMPAT_SURFACE.md | 408 ++++++++++++++++++++ docs/JNPF_SOURCE_AUDIT.md | 637 ++++++++++++++++++++++++++++++++ docs/MIGRATION.md | 303 +++++++++++++++ docs/known-limitations.md | 27 ++ scripts/check-module.sh | 21 ++ scripts/perm-smoke-jnpf.sh | 573 ++++++++++++++++++++++++++++ 10 files changed, 2093 insertions(+), 9 deletions(-) create mode 100644 .workbuddy/memory/2026-10-26.md create mode 100644 docs/JNPF_COMPAT_SURFACE.md create mode 100644 docs/JNPF_SOURCE_AUDIT.md create mode 100644 docs/MIGRATION.md create mode 100644 scripts/perm-smoke-jnpf.sh diff --git a/.workbuddy/memory/2026-10-26.md b/.workbuddy/memory/2026-10-26.md new file mode 100644 index 0000000..3d273fb --- /dev/null +++ b/.workbuddy/memory/2026-10-26.md @@ -0,0 +1,40 @@ +# 2026-10-26 工作日志 + +## 本轮做了什么 + +- **官方 JNPF 对齐三件套**(新增):`docs/JNPF_SOURCE_AUDIT.md`(官方源码逐行核对,标 `文件:行号`)· + `docs/JNPF_COMPAT_SURFACE.md`(**面 B 规格**:官方形状的端点/响应/码表 + 落地顺序 S1–S6)· + `docs/MIGRATION.md`(本仓 ↔ 官方逐项映射 + 口令 `secretkey` 换算)。 +- **第二把尺子**(新增):`scripts/perm-smoke-jnpf.sh`(18 条官方形状断言,打判别头;未落地记 **SKIP**,**不计入 PASS**)。 + 当前实测 `PASS=5 FAIL=0 SKIP=13`(覆盖 5/18)⇒ 官方 JNPF 前端**还跑不进本仓**。 +- **技能 `ssw-jnpf-lite-rust`**(新增):落 `~/.agents/skills/ssw-jnpf-lite-rust/`(**唯一真相源**); + `~/.claude/skills` / `~/.workbuddy/skills` / `~/.qwenworkcn/skills` 三处**相对**软链已验证能读到 `SKILL.md`。 + 资产 = 脚手架(`src/` + `scripts/` + `run.sh`)+ `SKILL.md` / `README.md` / `HOWTO_MODULE.md` / `PERMISSION.md` + 三份对齐文档。 +- **导航文档补链**:`CLAUDE.md`(红线加第 9 条)/ `README.md`(目录 + 第二把尺子 + 已知限制)/ + `HANDOFF.md`(§0 状态 / §6 参考文件 / §9 已知限制 + 下一步 S1–S6)/`docs/known-limitations.md`(新增 §H)。 + +## 🔴 本轮最重要的一条决定(判别头) + +**面 A(本仓 ssw/react 形状)与面 B(官方 JNPF 形状)靠请求头 `Vue-Version: 3` 分流。** + +- 官方前端发 `App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3` 三个头; + 本仓前端 `src/frontend/src/api/request.ts:35-36` **也发前两个**(与官方同款)⇒ **只有 `Vue-Version` 是本仓前端唯一不发的**。 +- 规格初稿曾断言「本仓前端一个头都不带」并用 `Jnpf-Origin` 判面 ⇒ **按字面实现会把每个面 A 请求都误判成面 B**。 + 已改正(`JNPF_COMPAT_SURFACE.md` §2.2 / `JNPF_SOURCE_AUDIT.md` D7+A13+§3.7 三处)。 +- **红线**:本仓前端**禁发** `Vue-Version`;面 B 尺子**必带**它。 + `scripts/check-module.sh` 的「全局红线」段**静态钉住两侧** ⇒ 规则不会静默腐坏。 + +## 验证(全绿) + +- `cargo test` = **179 passed / 0 failed**(8 个测试目标) +- `scripts/check-module.sh` = **PASS=57 FAIL=0**(仓库与技能目录**各自独立**跑,均 57/0) +- `scripts/perm-smoke.sh`(面 A)= **PASS=32 FAIL=0** +- `scripts/perm-smoke-jnpf.sh`(面 B)= **PASS=5 FAIL=0 SKIP=13** +- `bash -n` 全过;`\$VAR` 紧跟中文扫描 clean;仓库与技能**全部 md 相对链接无死链**; + 技能 `src/` 与参照仓 `src/` 逐字节一致(只差 `data/` 与 `dist/`)。 + +## 下一步(需人拍板才动代码) + +**落地面 B**(`docs/JNPF_COMPAT_SURFACE.md` §7 的 S1–S6):判别头分流 + `f_en_code` 第二套守卫 → `PcUserVO` → +分页信封 → 码表补 `602`(官方前端只在 `601`/`602` 清 token)→ 官方 RESTful 路径 → `f_en_code` 种子 + `secretkey` 换算。 +**面 A 必须零改动**(`perm-smoke.sh` 保持 `PASS=32`)。 diff --git a/CLAUDE.md b/CLAUDE.md index 4f7ddd4..f5e21f5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,6 +59,9 @@ tds-lite-rs/ │ ├── runbook.md # 怎么起 / 怎么冒烟 / 常见故障 │ ├── decisions.md # 实施期逐条裁决(88 条「什么—为什么—代价」) │ ├── known-limitations.md # 分支级已知限制(被接受/挂起的东西) +│ ├── JNPF_SOURCE_AUDIT.md # 官方源码逐行核对报告(每条带 文件:行号) +│ ├── JNPF_COMPAT_SURFACE.md # 面 B(官方 JNPF 契约面)规格书 + 落地顺序 S1–S6 +│ ├── MIGRATION.md # 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java)+ 数据 ETL + 口令换算 │ └── ddl/ # 官方 DDL 摘录 ├── src/ │ ├── backend/ # Rust 后端(workspace 唯一成员,crate 名 tds-lite-rs) @@ -82,7 +85,8 @@ tds-lite-rs/ │ │ └── data/ # 运行期数据(gitignore) │ └── frontend/ # react 技能前端逐字复制(**只改** vite.config.ts 的代理端口 30000→30010) ├── scripts/ -│ ├── perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖) +│ ├── perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖)—— 面 A 尺子 +│ ├── perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言)—— 面 B 尺子(未落地记 SKIP) │ └── check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端) └── .gitignore ``` @@ -109,6 +113,12 @@ tds-lite-rs/ 且要有兜底守卫(`/api/**` 之外的静态托管只放前端产物)。 8. 🔴 **同一文件的多个 Edit 必须串行**(并行 Edit = last-writer-wins 静默覆盖)。 改完**必须 grep 复核**全部改动点。 +9. 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**,不是 `Jnpf-Origin: pc`。 + 官方前端必带 `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 尺子必须带该头。 ### 官方 DDL 的两个"故意不修正"的陷阱 @@ -242,8 +252,9 @@ npm --prefix src/frontend run build # 产出 src/frontend/dist npm --prefix src/frontend run dev # http://127.0.0.1:5173(vite 代理 /api → 30010) # 冒烟 / 自检 -bash scripts/perm-smoke.sh # 默认打 127.0.0.1:30010(32 条断言) +bash scripts/perm-smoke.sh # 面 A:默认打 127.0.0.1:30010(32 条断言) B=http://127.0.0.1:30010 bash scripts/perm-smoke.sh +bash scripts/perm-smoke-jnpf.sh # 面 B:官方 JNPF 形状(18 条断言;未落地记 SKIP) bash scripts/check-module.sh # 9 接触点静态自检(纯静态,不起后端) ./target/release/tds-lite-rs --enc 123456 # cipher 自证(免 node 依赖) ``` diff --git a/HANDOFF.md b/HANDOFF.md index bfd56e8..432159a 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -16,9 +16,11 @@ | `HANDOFF.md`(本文件) | ✅ 已写并已同步(§0 状态表 / §9 交接话术,Task 12) | | 代码 | ✅ 后端已实现(`src/backend/`,Rust 2021 + axum 0.8 + pglite-rs 0.2,**10 张表**、**27 条路由**) | | 前端 | ✅ 已逐字复制(`src/frontend/`;**唯一改动 = vite 代理端口改成 `30010`**,其余文件逐字节相同) | -| 脚本 | ✅ `scripts/perm-smoke.sh`(**32 条断言**)+ `scripts/check-module.sh`(9 接触点静态自检,**55 条 ✅**) | +| 脚本 | ✅ `scripts/perm-smoke.sh`(**32 条断言**)+ `scripts/check-module.sh`(9 接触点静态自检,**55 条 ✅**)+ `scripts/perm-smoke-jnpf.sh`(**面 B 尺子,18 条断言;代码未落地 ⇒ 当前 PASS=5 / SKIP=13**) | | 工程脚本 | ✅ `run.sh`(`install`/`build`/`dev`/`backend`/`frontend`/`stop`/`logs`,退出码 0/1/2) | | 文档 | ✅ `README.md` / `docs/runbook.md` / `.env.example` | +| 官方对齐文档 | ✅ `docs/JNPF_SOURCE_AUDIT.md`(官方源码逐行核对)· `docs/JNPF_COMPAT_SURFACE.md`(**面 B 规格**)· `docs/MIGRATION.md`(迁移指南) | +| 技能资产 | ✅ `ssw-jnpf-lite-rust` 已落 `~/.agents/skills/ssw-jnpf-lite-rust/`(真相源;`~/.claude/skills` / `~/.workbuddy/skills` / `~/.qwenworkcn/skills` 三处相对软链已验证可读 `SKILL.md`) | | 验收四门 | ✅ 全绿(编译 **0 error 0 warning** · 单测 **179 passed / 0 failed** · 冒烟 **PASS=32 FAIL=0** · 前端**浏览器**手验全过) | **读法**:`CLAUDE.md`(红线与坑位,日常改代码必读)→ §9(怎么起 / 怎么复现验收)。 @@ -323,6 +325,18 @@ tds-lite-rs/ ← 独立 git 仓(已 init,未 commit) 同目录还有 jnpf_db_init.sql(base_user 的 INSERT 可二次确证列名)等 9 个 init 文件 ``` +### 本仓的官方对齐文档(面 B / 迁移期必读) + +| 文件 | 何时读 | 内容 | +|---|---|---| +| `docs/JNPF_SOURCE_AUDIT.md` | 迁移期 / 存疑时 | 官方源码(Java + Vue)逐行核对报告,全部结论标 `文件:行号`;含本仓与官方的**差异清单 D1–D8** | +| `docs/JNPF_COMPAT_SURFACE.md` | 落地面 B 前 | **面 B 规格**:官方形状的端点 / 响应形状 / 码表 / 判别头 / 落地顺序 S1–S6 | +| `docs/MIGRATION.md` | 稳定期迁 JNPF | 本仓 ↔ 官方的**逐项映射** + 数据 ETL + 口令 `secretkey` 换算(**不需要明文**) | +| `scripts/perm-smoke-jnpf.sh` | 落地面 B 时 | **第二把尺子**:18 条官方形状断言(打 `Vue-Version: 3` 头);未落地记 SKIP,**不算 PASS** | + +🔴 **面 A / 面 B 的判别头 = `Vue-Version: 3`**(官方前端**必发**、本仓前端**唯一不发**的一头)。 +🔴 本仓前端**禁止**发 `Vue-Version`(发了 ⇒ 面 A 请求被误判成面 B)⇒ `scripts/check-module.sh` 的「全局红线」段静态钉住这一条。 + ### 工程手法参考(tdc-rs,**只读**、不共享代码) ``` @@ -438,6 +452,17 @@ bash run.sh dev # 日常:后台起后端(30010) + 前端(5173) 登录响应里的 `expiresIn: 7200` 是**契约 §6.1 逐字定死**的字面量、**不会被强制执行** (进程不重启就永不过期);契约未覆盖 TTL ⇒ **不改**。 +**面 B(官方 JNPF 契约面)这一轮新增的三条**(详见 `docs/known-limitations.md` §H): + +- **面 B 只有规格、没有实现**:端点 / 响应形状 / 码表见 `docs/JNPF_COMPAT_SURFACE.md`,落地顺序 S1–S6 见其 §7; + `scripts/perm-smoke-jnpf.sh` 当前报 **`覆盖 5/18`**(其余 **SKIP**,不计入 PASS) + ⇒ **官方 JNPF 前端目前还跑不进本仓**(`CurrentUser` 形状、列表分页、`602` 码都还没做)。 +- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(lower(md5(明文)) + lower(secretkey))` + ⇒ 迁官方时**一次性换算**即可,**不需要明文**(`docs/MIGRATION.md` §7)。 +- **权限判据是菜单路径,不是官方的点权限**:本仓按 `spec.module_key == base_module.f_url_address` 判权, + 官方取 `base_module.f_en_code`(`@SaCheckPermission`)⇒ 本仓种子菜单**没有** `f_en_code` + ⇒ 迁官方前必须补(`docs/MIGRATION.md` §2.4);面 B 落地时要**两套判据并存**。 + Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷,是刻意设计): - `run.sh backend` 用 `exec` 跑后端 ⇒ **后端自己的退出码原样透传**(后端 panic 时是 **101**,不是子命令表里写的 1)。 @@ -461,6 +486,24 @@ Task 12 修复轮 R=1 另记两条 `run.sh` 的**行为口径**(不是缺陷 ### 下一步(按 plan) -验收四门全绿 ⇒ **下一步是把本仓 1:1 复制成技能 `ssw-jnpf-lite-rust`**, -落在 `~/Desktop/workspace/skills/`,与 `ssw-jnpf-lite-react` 并列 -(技能资产形态 = 本仓 1:1 复制;目录结构已刻意与 react 版对齐)。 +**已完成**:验收四门全绿;本仓 1:1 复制成技能 `ssw-jnpf-lite-rust` ⇒ 落在 +**`~/.agents/skills/ssw-jnpf-lite-rust/`**(按全局硬约定,**技能唯一真相源 = `~/.agents/skills/`**; +`~/.claude/skills/`、`~/.workbuddy/skills/`、`~/.qwenworkcn/skills/` 三处各放**相对**软链 +`../../.agents/skills/ssw-jnpf-lite-rust`,已逐一验证能读到 `SKILL.md`)。 +技能比 react 版多三份资产:**面 B 规格**(`JNPF_COMPAT_SURFACE.md`)· **官方源码核对**(`JNPF_SOURCE_AUDIT.md`)· +**迁移指南**(`MIGRATION.md`),并自带**第二把尺子** `scripts/perm-smoke-jnpf.sh`。 + +**下一步(需人拍板才动代码)**:**落地面 B**(官方 JNPF 契约面)——规格已写死在 +`docs/JNPF_COMPAT_SURFACE.md` §7 的 S1–S6: + +| 步 | 内容 | 落点 | +|---|---|---| +| S1 | 判别头分流(`Vue-Version: 3` ⇒ 面 B)+ 第二套守卫(`f_en_code` 判据) | `routes.rs` / `permission.rs` | +| S2 | 官方形状的 `CurrentUser`(`PcUserVO` 五字段) | `auth.rs` | +| S3 | 分页信封(`{pagination:{currentPage,pageSize,total}, list:[…]}`) | `crud.rs` / `sys.rs` | +| S4 | 码表补齐(`401` / `500` / `601` / **`602`**——官方前端只在 `601`/`602` 清 token) | `envelope.rs` | +| S5 | 官方 RESTful 路径(`/api/permission/Users` / `Role` / `Organize` / `Authority` / `/api/system/Menu`) | `routes.rs` | +| S6 | `f_en_code` 种子 + `secretkey` 换算 | `seed.rs` / `MIGRATION.md` | + +⇒ 落地后 `bash scripts/perm-smoke-jnpf.sh` 应从 **`覆盖 5/18`** 走到 **18/18**。 +(面 A **零改动** ⇒ `perm-smoke.sh` 必须仍是 `PASS=32 FAIL=0`。) diff --git a/README.md b/README.md index 330ec63..ac6602a 100644 --- a/README.md +++ b/README.md @@ -46,9 +46,11 @@ tds-lite-rs/ ├── .env.example # PORT / BIND_ADDR / PGLITE_DIR(PGLITE_DIR 只能写绝对路径或 memory://) ├── src/backend/ # Rust 后端(axum 0.8 + pglite-rs 0.2,10 张表,27 条路由) ├── src/frontend/ # react 技能前端**逐字复制**(只改 vite 代理端口 30000 → 30010) -├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖) -├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端) -└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制)· ddl/ +├── scripts/perm-smoke.sh # 权限闭环冒烟(32 条断言,零 node 依赖) +├── scripts/perm-smoke-jnpf.sh # 官方 JNPF 形状冒烟(18 条断言;面 B 未落地 ⇒ 诚实记 SKIP,不算 PASS) +├── scripts/check-module.sh # 业务模块 9 接触点静态自检(纯静态,不起后端) +└── docs/ # contract.md(契约)· runbook.md(运维)· decisions.md(裁决)· known-limitations.md(已知限制) + # JNPF_SOURCE_AUDIT.md(官方源码逐行核对)· JNPF_COMPAT_SURFACE.md(面 B 规格)· MIGRATION.md(迁移指南)· ddl/ ``` --- @@ -85,6 +87,17 @@ tds-lite-rs/ 外加:`bash scripts/check-module.sh`(9 接触点静态自检)—— 加业务模块后立刻跑的前置闸门。 +### 第二把尺子(面 B:官方 JNPF 形状) + +```bash +bash scripts/perm-smoke-jnpf.sh # 18 条断言,打印「面 B 覆盖 N/18」 +``` + +**面 B = 官方 JNPF 契约面**(官方形状的端点 / 响应 / 码表),规格见 `docs/JNPF_COMPAT_SURFACE.md`。 +🔴 **代码尚未实现** ⇒ 该尺子目前报 `PASS=5 FAIL=0 SKIP=13`(**未落地记 SKIP,不算 PASS**)—— +它是一把**诚实量进度**的尺子,不是「假装全过」的开关。 +面 B 的判别头是 **`Vue-Version: 3`**(官方前端必发,本仓前端**唯一不发**的一头 ⇒ 零歧义)。 + > 本机 curl 走系统代理 ⇒ 打 localhost **必须**加 `--noproxy '*'`。 --- @@ -101,6 +114,14 @@ tds-lite-rs/ ## 已知限制(分支级) +- **面 B(官方 JNPF 契约面)只有规格、没有实现**:端点 / 响应形状 / 码表见 `docs/JNPF_COMPAT_SURFACE.md`, + 落地顺序 S1–S6 见其 §7;`scripts/perm-smoke-jnpf.sh` 目前报 `覆盖 5/18`(其余记 SKIP)。 + ⇒ **官方 JNPF 前端目前还跑不进本仓**(`CurrentUser` 形状、列表分页、`602` 码都还没做)。 +- **口令存储缺官方 `secretkey` 一步**:本仓存 `md5(明文)`,官方存 `md5(md5(明文)+secretkey)`。 + 迁官方时**一次性换算**即可,**不需要明文**(见 `docs/MIGRATION.md` §7)。 +- **权限判据是菜单路径,不是官方的点权限**(官方取 `base_module.f_en_code`;本仓种子菜单**没有** `f_en_code`)。 + ⇒ 迁官方前必须补 `f_en_code`(`docs/MIGRATION.md` §2.4)。 + - **release 二进制没有 catch-all 的自动化覆盖**:触发 panic 的端点是 `#[cfg(test)]` 专属; catch-all 中间件代码在测试构建与 release 构建里逐字相同,且 release profile **无** `panic = "abort"` ⇒ 行为等价。 - **`Path` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz` diff --git a/docs/JNPF_COMPAT_SURFACE.md b/docs/JNPF_COMPAT_SURFACE.md new file mode 100644 index 0000000..9f19fe0 --- /dev/null +++ b/docs/JNPF_COMPAT_SURFACE.md @@ -0,0 +1,408 @@ +# 面 B:官方 JNPF 契约面(规格书) + +> **这份文档是「尺子的规格」** —— [`scripts/perm-smoke-jnpf.sh`](../scripts/perm-smoke-jnpf.sh) 逐条断言的就是本文的每一条。 +> 官方源码依据见 [`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(每条带 `文件:行号`)。 + +--- + +## 0. 一句话 + +**面 A** = 本仓现有契约(ssw/react 技能那套),**一个字都不动**。 +**面 B** = 官方 JNPF 契约(官方 Vue 前端那套),**与面 A 共用同一个进程、同一个库、同一套 `base_*` 表**。 + +⇒ 官方 JNPF 的 Vue 前端,可以**直接**指着本仓的后端跑;本仓的 React 前端,也**照旧**跑。 + +--- + +## 1. 为什么需要面 B + +审计结论([`JNPF_SOURCE_AUDIT.md` §3](JNPF_SOURCE_AUDIT.md)): + +| 差异 | 能否靠「改前端」绕过 | 结论 | +|---|---|---| +| D2 列表响应(`PageListVO`) | ❌ 官方前端分页组件要 `pagination.total` | **必须后端出** | +| D3 `CurrentUser` 形状(`PcUserVO`) | ❌ 官方前端读 `permissionList` / `userInfo.*` | **必须后端出** | +| D4 码表缺 602 | ❌ 官方前端靠 602 清 token 跳登录 | **必须后端出** | +| D5 菜单接口(`ModuleBySystem`) | ❌ 官方前端启动就调 | **必须后端出** | +| D6 点权限(`f_en_code`) | ⚠️ 可前端硬编码,但不可维护 | 后端出更好 | +| D1 端点风格 | ✅ 官方前端路径写死 | **必须后端出**(新路径) | +| D7 请求头 | ✅ 忽略即可 | 后端**别拒** | +| D8 口令存储 | ✅ 换算期处理 | 迁移期一次性 | + +⇒ 结论:**「官方前端 → Rust 后端能跑」这件事,后端必须有一层官方形状**。这就是面 B。 + +--- + +## 2. 面 A / 面 B 的边界规则 + +### 2.1 路由层:面 B = 新增路径 + 少数共用路径 + +| 情况 | 处理 | +|---|---| +| 官方路径与面 A **不冲突**(`/api/permission/*`、`/api/system/*`) | **新增**面 B 路由,与面 A 并存 | +| 官方路径与面 A **冲突**(`/api/oauth/Login`、`/api/oauth/CurrentUser`、`PUT /api/permission/Authority/Data/{objectId}`) | **共用同一路由**,按规则分流(见 §2.2) | +| 官方请求体是面 A 请求体的**超集**(授权写) | 直接兼容,**零改动** | + +### 2.2 共用路由的分流规则:**按请求头 `Vue-Version: 3` 判面** + +官方前端**必然**带这三个头(`jnpf-web-apps-main/src/api/request.ts:109-112`): + +``` +App-Code: <应用编码> +Jnpf-Origin: pc +Vue-Version: 3 +``` + +🔴 **本仓前端带其中两个**(`src/frontend/src/api/request.ts:35-37`,与官方同款): + +```ts +config.headers.set('App-Code', 'sswflow'); +config.headers.set('Jnpf-Origin', 'pc'); // ← 官方也有 ⇒ **不能**用它判别 +if (token) config.headers.set('Authorization', token); +``` + +⇒ 三个官方头里,**本仓前端唯一不发的是 `Vue-Version`** ⇒ 判别只能用它。 + +⇒ **判定规则(唯一规则,全局生效)**: + +``` +请求头含 "Vue-Version: 3" ⇒ 走【面 B】官方形状 +否则 ⇒ 走【面 A】ssw 形状 +``` + +**为什么用这个头**:官方前端**无条件**携带 `Vue-Version: 3`,而本仓前端**从不**携带 ⇒ 零歧义、零配置、双方都不需要改。 +(`App-Code` 与 `Jnpf-Origin` **不作**判据 —— 本仓前端也发这两个,判了必错。) + +🔴 **红线:本仓前端禁止发 `Vue-Version` 头**(一旦发出,面 A 的请求会被误判成面 B ⇒ 契约整体错位)。 +`scripts/check-module.sh` 的「全局红线」段**静态钉住**这一条(查 `src/frontend/src/api/request.ts`), +面 B 尺子 `scripts/perm-smoke-jnpf.sh` 也**必须**带 `Vue-Version: 3`(否则面 B 请求不会被识别成面 B)—— 同一处静态自检。 + +### 2.3 三个共用路由的逐条结论 + +| 路由 | 面 A 现状 | 面 B 要求 | 判定 | +|---|---|---|---| +| `POST /api/oauth/Login` | `{token, expiresIn:7200, tokenTypeName:'bearer'}` | 官方读 `data.token`(`LoginVO.java:17`) | ✅ **零改动**(官方前端忽略多余字段) | +| `PUT /api/permission/Authority/Data/{objectId}` | body `{objectType, module:[…]}` | 官方 body = `{objectType, module, button, column, resource, form, systemIds}`(`AuthorizeDataUpForm.java:14-38`) | ✅ **零改动**(官方 body 是面 A 的**超集**;面 A 只消费 `objectType`+`module`) | +| `GET /api/oauth/CurrentUser` | `{userInfo:{4 字段}, menuList:[本仓自定义节点]}` | 官方 `PcUserVO`(`PcUserVO.java:16-34`) | ⚠️ **必须分流**(§3.3) | + +--- + +## 3. 面 B 端点规格 + +### 3.1 认证 + +#### `POST /api/oauth/Login` + +- **共用面 A**,零改动。 +- 请求:`application/x-www-form-urlencoded`,`account` / `password`(密文 hex) / `grant_type=password`。 +- 响应:`ActionResult<{token, expiresIn, tokenTypeName}>`。官方前端只读 `data.token` ⇒ 兼容。 + +#### `GET /api/oauth/CurrentUser` ★ **形状分流点** + +**面 A 形状**(无 `Vue-Version` 头)——**不动**: + +```json +{ "code":200, "msg":"操作成功", "data":{ + "userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true }, + "menuList":[ …本仓菜单节点… ] } } +``` + +**面 B 形状**(带 `Vue-Version: 3`)——官方 `PcUserVO`: + +```json +{ "code":200, "msg":"操作成功", "data":{ + "menuList":[ { "id":"…","fullName":"系统管理","enCode":"…","parentId":"0","icon":"…", + "hasChildren":true,"urlAddress":"system/User","pageAddress":"…","linkTarget":null, + "children":[…],"type":1,"propertyJson":null,"sortCode":0, + "systemId":"…","isData":false } ], + "permissionList":[ { "modelId":"…","moduleName":"…","button":[],"column":[],"resource":[],"form":[] } ], + "userInfo":{ "userId":"…","userAccount":"admin","userName":"…","isAdministrator":true, + "headIcon":null,"organizeId":"…","organizeName":"…", + "positionId":"…","positionName":"…","systemId":"…","systemCode":"…", + "prevLogin":1,"prevLoginTime":…,"prevLoginIPAddress":null,"prevLoginIPAddressName":null }, + "currentSystemId":"…", + "sysConfigInfo":{ … } } } +``` + +**字段依据**: +- `PcUserVO.java`:`:19` menuList / `:22` permissionList / `:25` userInfo / `:27` currentSystemId / `:33` sysConfigInfo +- `AllMenuSelectVO.java`:`:12` id / `:15` fullName / `:18` enCode / `:21` parentId / `:24` icon / `:27` hasChildren / `:30` urlAddress / `:33` pageAddress / `:36` linkTarget / `:39` children / `:42` type / `:44` propertyJson / `:46` sortCode / `:48` systemId / `:50` isData +- `PermissionModel.java`:`:10` modelId / `:12` moduleName / `:14` button / `:16` column / `:18` resource / `:20` form +- `UserCommonInfoVO.java`:`:16` userId / `:19` userAccount / `:22` userName / `:25` headIcon / `:28` organizeId / `:31` organizeName / `:34` positionId / `:37` positionName / `:40` prevLogin / `:43` prevLoginTime / `:47` prevLoginIPAddress / `:51` prevLoginIPAddressName / `:75` isAdministrator / `:83` systemId / `:87` systemCode + +**硬性要求**: +1. 五个顶层字段**一个都不能少**(官方前端按 `menuList` + `permissionList` 渲染侧栏与按钮)。 +2. `menuList` 节点的 `type`:`1`=目录 / `2`=页面(与 `base_module.f_type` 语义一致)。 +3. `permissionList` 可为空数组 `[]`(**但不能是 `null`**)—— 官方前端遍历它。 + +> 📌 **不实现** `sysConfigInfo` 的真实内容时,返 `{}`(空对象)而不是 `null` ⇒ 官方前端不炸。 + +#### `POST /api/oauth/Logout` — 可后置 + +官方 `LoginController.java:155`。本仓 v1 无此端点(前端本地清 token)。 +**优先级:低**(官方前端退出时若 404,会在控制台报错但不影响使用)。 + +### 3.2 用户 `/api/permission/Users` + +**列表** `GET /api/permission/Users` + +请求参数(`UserPagination.java:11-36` = `Pagination.java:19-29` + 过滤): + +| 参数 | 类型 | 默认 | 说明 | +|---|---|---|---| +| `pageSize` | long | `20` | `Pagination.java:19` | +| `currentPage` | long | `1` | `Pagination.java:25` | +| `sort` | string | `"DESC"` | `Pagination.java:21` | +| `sidx` | string | `""` | `Pagination.java:23` | +| `keyword` | string | — | 关键字(`Pagination` 父类 `Page`) | +| `gender` | string | — | `UserPagination.java:14` | +| `enabledMark` | int | — | `:17`(0 禁用 / 1 启用 / 2 锁定 / 12 启用和锁定) | +| `groupId` / `organizeId` / `positionId` / `roleId` | string | — | `:20/23/26/29` | +| `showSubOrganize` | int | — | `:32` | +| `dataType` | int | — | `:35`(1 = 全部数据) | + +响应(`UserController.java:295` ⇒ `ActionResult>`): + +```json +{ "code":200, "msg":"操作成功", "data":{ + "pagination":{ "currentPage":1, "pageSize":20, "total":42 }, + "list":[ { "id":"…","account":"admin","realName":"管理员","fullName":"管理员", + "gender":null,"mobilePhone":null,"email":null,"organize":"…", + "description":null,"enabledMark":1,"creatorTime":1730000000000, + "sortCode":0,"lockMark":0,"handoverMark":0,"isAdministrator":1, + "headIcon":null,"unlockTime":null,"position":"…", + "isDutyUser":0,"maxRelationId":null } ] } } +``` + +**列表项字段依据**:`UserListVO.java:19-74`。 +**硬性要求**: +1. `data` 必须是**对象**(含 `pagination` + `list`),**不是**裸数组。 +2. `list` 项**不得**含 `password` / `secretkey`。 +3. `pagination.total` = **总条数**(不是本页条数)。 +4. `currentPage` / `pageSize` **原样回显**请求值(官方前端会算总页数)。 +5. `creatorTime` 是**毫秒时间戳(数字)**。 +6. `isAdministrator` 是**数字** `0|1`(不是布尔)—— 官方 VO 是 `Integer`(`UserListVO.java:60`)。 + +**单条 / 增 / 改 / 删**(`UserController.java:355/409/429/496`): + +| 方法 | 路径 | 官方权限码 | 面 B 行为 | +|---|---|---|---| +| GET | `/api/permission/Users/{id}` | `permission.user` | 返 `UserListVO` 同构单对象 | +| POST | `/api/permission/Users` | `permission.user` | 建号;body 用**去前缀名**(`account`/`realName`/`organizeId`/…) | +| PUT | `/api/permission/Users/{id}` | `permission.user` | 改;body 同上 + `id` 在 path | +| DELETE | `/api/permission/Users/{id}` | `permission.user` | 删;成功返 `ActionResult.success()` | + +**权限码语义(面 B)**:官方用 `@SaCheckPermission("permission.user")` ⇒ 判定依据是 +**该用户是否持有 `f_en_code = 'permission.user'` 的菜单授权**(`base_module.f_en_code`)。 +本仓的菜单路径白名单(`system/User`)在面 B **不适用** ⇒ 面 B 用 `f_en_code` 判。 + +> 🔴 **这意味着面 B 必须能读到 `f_en_code` 且种子菜单要带 `f_en_code` 值。** +> 本仓 `base_module` 表**已有 `f_en_code` 列**(官方 DDL 逐字)⇒ 列在,**值要补种子**。 + +### 3.3 角色 `/api/permission/Role` + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth` OR `permission.role` | +| GET | `/api/permission/Role/{id}` | `:273` | `permission.role` | +| POST | `/api/permission/Role` | `:122` | `permission.role` | +| PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` | +| DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` | +| GET | `/api/permission/Role/Selector` | `:327` | 登录即可 | + +列表响应:`ActionResult>`(`RoleController.java:101`)—— 形状同 §3.2 的列表规则。 + +### 3.4 组织 `/api/permission/Organize` + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize` OR `permission.user` OR `permission.role` OR … | +| GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 | +| GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` | +| POST | `/api/permission/Organize` | `:179` | `permission.organize` | +| PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` | +| DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` | +| GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 | + +**注意**:官方组织列表是**按 parentId 逐层取**(`AsyncList/{id}`,`id` = 父节点 id,根为 `0`)⇒ 面 B 必须支持 `AsyncList` 路径, +**不能**只有"全量列表"。 + +🔴 `AsyncList/{id}` 的响应是 `ActionResult>`(`OrganizeController.java:110-112`) +⇒ **`data` 是 `{pagination, list}`(PageListVO)**,不是裸数组。 + +### 3.5 菜单 `/api/system/Menu` + +| 方法 | 路径 | 官方出处 | 面 B 行为 | +|---|---|---|---| +| GET | `/api/system/Menu/ModuleBySystem` | `ModuleController.java:121` | **官方前端启动入口**:返该系统下的菜单**列表(平铺)** | +| GET | `/api/system/Menu/{systemId}/TreeView` | `:332` | 菜单**树** | +| GET | `/api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 | +| GET | `/api/system/Menu/Selector/All` | `:444` | 全量下拉 | +| POST | `/api/system/Menu` | `:169-170` | 新建 | +| PUT | `/api/system/Menu/{id}` | `:194-195` | 修改 | +| GET | `/api/system/Menu/{id}` | `:248-249` | 详情 | +| DELETE | `/api/system/Menu/{id}` | `:228-229` | 删除 | + +`ModuleBySystem` 的 `systemId` 从哪来?官方前端 `api/system/menu.ts:9` 传 `data`(query)。 +**本仓单系统** ⇒ 忽略入参、返本仓全部菜单(平铺,`parentId` 表达层级)。 + +🔴 **`ModuleBySystem` 的 `data` 不是裸数组** —— 官方返回 `ActionResult>` +(`ModuleController.java:121` + `ListVO.java:19-22`)⇒ **线形是 `{ "list": [...] }`**。 +(`ListVO` 全仓只有 `list` 一个字段;`PageListVO` 才是 `pagination` + `list`。) +⇒ 尺子断言 16 判的是 **`code=200` + `data.list` 是数组**,不是「`data` 是数组」。 + +**菜单项字段**:官方 `base_module` 实体字段(`f_id`/`f_full_name`/`f_en_code`/`f_parent_id`/`f_icon`/`f_url_address`/`f_type`/`f_sort_code`/`f_system_id`/`f_property_json`/`f_link_target`/`f_page_address`) +⇒ 键名去 `f_` 前缀后 camelCase,与本仓 JSON 键名规则一致。 + +### 3.6 授权 `/api/permission/Authority` + +| 方法 | 路径 | 官方出处 | 面 B 行为 | +|---|---|---|---| +| POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | 返**权限树 + 已勾选值** | +| PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | ✅ **与面 A 共用,零改动** | + +**`Values` 的请求体**(`DataValuesQuery.java:14-24`): + +```json +{ "type":"module", "objectType":"role", "moduleIds":"" } +``` + +- `type` = 项目类型:`module`(菜单)/ `button` / `column` / `form` / `resource` +- `objectType` = `role` / `organize` / `position` / `user`(`PermissionConst.java:8-58`) +- 🔴 `moduleIds` 是 **`String`**(逗号分隔的菜单 id),**不是数组**(`DataValuesQuery.java:19-20`) +- 🔴 `type` 为空 ⇒ 官方直接返 `ActionResult.fail(MsgCode.PS012)`(`AuthorizeController.java:112-114`)⇒ **不能省 `type`** + +**响应**:官方 `AuthorizeDataReturnVO.java:16-27` = `{ list: AuthorizeDataReturnModel[], ids: String[], all: String[] }` +(`list` = 权限树模型集合 / `ids` = 已勾选 id / `all` = 全部 id,**`all` 不含菜单 id**)。 + +🔴 **面 B v1 降级**:本仓**不实现**完整权限树模型 ⇒ 先只保证 `ids`(已勾选 id)语义正确, +`list` 可返空数组、`all` 可返本仓全部菜单 id;并在面 B 规格里标注「`list` 未与官方 `AuthorizeDataReturnModel` 逐字对齐」。 +官方前端的「授权弹窗」需要 `list` 才是完整体验 ⇒ 属面 B 后续项。 + +--- + +## 4. 码表(面 B) + +| 码 | 场景 | 官方行为 | +|---|---|---| +| 200 | 成功 | 放行 | +| 400 | 业务失败 | 提示 `msg` | +| 401 | 验证错误 | 提示 `msg` | +| 500 | 异常 | 提示 `msg` | +| 600 | 登录过期 | 提示 | +| 601 | 被踢出 | 清 token | +| **602** | **token 失效** | **清 token 跳登录** ★ 官方前端靠它 | +| 403 | 权限异常 | 跳无权限页 | + +**面 B 硬性要求**: +1. **未登录/无效 token 一律返 `602`(不是 600)** —— 官方前端 `request.ts:78-80` 只对 `TOKEN_ERROR/TOKEN_LOGGED/TOKEN_TIMEOUT` 清 token。 +2. 权限不足返 `403`。 +3. 业务失败返 `400` + `msg`(**HTTP 仍是 200**)。 + +> ⚠️ 这与**面 A 不同**(面 A 用 `600`)⇒ 同一个「未登录」场景,**面 A 返 600、面 B 返 602**。这正是分流规则要处理的地方。 + +--- + +## 5. 请求头 + +面 B **必须接受**(且**不得**因此报错): + +| 头 | 值 | 作用 | +|---|---|---| +| `Jnpf-Origin` | `pc` | 本仓前端也发 ⇒ **不作**判据 | +| `Vue-Version` | `3` | **面 B 判别依据**(§2.2)——本仓前端唯一不发的一头 | +| `App-Code` | 应用编码 | 本仓单系统 ⇒ 忽略 | +| `Authorization` | `Bearer ` | 鉴权(面 A 同) | + +--- + +## 6. 尺子:`scripts/perm-smoke-jnpf.sh` + +### 6.1 它测什么 + +**第二把尺子**(第一把是 `scripts/perm-smoke.sh`,测面 A 的 32 条断言)。 +本脚本测**官方形状**:同一个后端进程,按官方请求头 + 官方路径 + 官方响应形状断言。 + +### 6.2 断言清单(目标 18 条) + +| # | 断言 | 判据 | +|---|---|---| +| 1 | 面 A 未受影响 | 无 `Vue-Version` 头时 `CurrentUser` 仍是面 A 形状(2 字段) | +| 2 | 面 A 登录仍通 | 无头登录 → `code=200` + `token` | +| 3 | 面 B 登录 | 带 `Vue-Version: 3` 登录 → `code=200` + `data.token` | +| 4 | 面 B `CurrentUser` 顶层 5 字段 | `data` 同时有 `menuList`/`permissionList`/`userInfo`/`currentSystemId`/`sysConfigInfo` | +| 5 | 面 B `menuList` 节点形状 | 含 `id`/`fullName`/`enCode`/`parentId`/`urlAddress`/`type`/`children` | +| 6 | 面 B `permissionList` 是数组 | `[]` 也算过(**不能是 null**) | +| 7 | 面 B 无 token → `602` | 不是 600、不是 401 | +| 8 | 面 B 无 token → 未知路由仍 404 | | +| 9 | 面 B 用户列表是 `PageListVO` | `data` 有 `pagination` + `list` | +| 10 | `pagination` 三字段 | `currentPage`/`pageSize`/`total` 都在 | +| 11 | `pagination.total` 是总条数 | ≥ `list.length` | +| 12 | 列表项**无** `password`/`secretkey` | 逐项检查 | +| 13 | 列表项 `isAdministrator` 是数字 | 0 或 1,不是 true/false | +| 14 | 角色列表是 `PageListVO` | 同 #9 | +| 15 | 组织列表支持 `AsyncList/{id}` | 根节点 `id=0` 能取到一级组织 | +| 16 | 菜单 `ModuleBySystem` 可达 | `code=200` + `data.list` 是数组(官方是 `ListVO`,**不是裸数组**) | +| 17 | 授权写(官方 body 超集) | 用官方完整 body 发 `PUT /api/permission/Authority/Data/{id}` → 成功且 `module` 真的写进去 | +| 18 | 授权读是 **POST** | `POST .../Data/{id}/Values` → `code=200` | + +### 6.3 进度报告(**关键设计**) + +脚本**不假装全过**: + +- 每条断言独立记 `PASS` / `FAIL` / **`SKIP(未实现)`**; +- 结尾打印 **`面 B 覆盖 N/M`**(M = 18); +- **退出码**: + - `0` = 全部 PASS; + - `1` = 有 FAIL; + - `2` = 用法错 / 后端不可达(前置错误)。 + +⇒ 在面 B 尚未实现时,它是一把**诚实量进度**的尺子(`SKIP` 计入未覆盖,不算 PASS)。 + +### 6.4 与面 A 尺子的关系 + +| | `perm-smoke.sh` | `perm-smoke-jnpf.sh` | +|---|---|---| +| 测的面 | A(ssw) | B(官方) | +| 判别 | 无特殊头 | `Vue-Version: 3` | +| 断言数 | 32 | 18 | +| 都要跑 | ✅ | ✅(面 B 落地后) | + +**两把尺子必须同时绿** —— 面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。 + +--- + +## 7. 落地顺序(面 B 的实施建议) + +| 阶段 | 内容 | 产出 | +|---|---|---| +| S1 | 分流机制(`Vue-Version: 3` 判面)+ 码表补 `602` | 面 A 零影响;面 B 未登录返 602 | +| S2 | `CurrentUser` 面 B 形状(`PcUserVO`) | 官方前端能登录并渲染侧栏 | +| S3 | 分页列表引擎(`PageListVO`) | 官方用户/角色/组织列表能翻页 | +| S4 | 菜单 `ModuleBySystem` + `f_en_code` 种子 | 官方前端能拿到菜单树 | +| S5 | `f_en_code` 判权 + `permissionList` | 官方前端按钮显隐正确 | +| S6 | 授权 `Values` 读取 + 完整树 | 授权弹窗可用 | + +> 每阶段结束跑 `bash scripts/perm-smoke-jnpf.sh` ⇒ 覆盖数从 `0/18` 逐步爬到 `18/18`。 + +--- + +## 8. 已知不对齐项(如实记录) + +| # | 项 | 状态 | 影响 | +|---|---|---|---| +| B1 | `AuthorizeDataReturnVO` 的 `list`(权限树模型) | **未逐字对齐**(面 B 只保证 `ids`/`all` 语义,`list` 返空数组) | 官方授权弹窗需二次适配 | +| B2 | `sysConfigInfo` | 返 `{}` 空对象 | 官方前端不读关键字段 | +| B3 | `currentSystemId` | 返本仓固定系统 id | 单系统场景等价 | +| B4 | 按钮级权限(`btn_*`) | 未实现 | 官方前端按钮恒显(不隐藏) | +| B5 | 数据权限方案(`ModuleDataAuthorizeLink`) | 不做 | 官方前端相关页面 404 | +| B6 | 导入导出(`ImportData`/`ExportData`/…) | 不做 | 官方前端相关按钮报错 | +| B7 | 官方 `password` 存储格式(secretkey) | 见 `JNPF_SOURCE_AUDIT.md` §6.3 | 迁官方时一次性换算 | + +--- + +## 9. 变更记录 + +| 日期 | 变更 | +|---|---| +| 2026-10-26 | 首版。确立「面 A 不动 + 面 B 新增」的边界规则、请求头分流规则、18 条断言清单、6 阶段落地顺序、7 条已知不对齐项。 | diff --git a/docs/JNPF_SOURCE_AUDIT.md b/docs/JNPF_SOURCE_AUDIT.md new file mode 100644 index 0000000..0a3ca4e --- /dev/null +++ b/docs/JNPF_SOURCE_AUDIT.md @@ -0,0 +1,637 @@ +# 官方 JNPF 源码审计(本仓的「官方面」地基) + +> 这份文档回答**一个**问题:**本仓(Rust)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。** +> +> 全部结论来自对官方源码的**逐行核对**,每条带 `文件:行号`。 +> 官方源码坐标:`~/Desktop/workspace/jnpf/`(下文所有路径均相对它)。 +> 核对日期:**2026-10-26**。官方版本:`jnpf-web-apps-main`(Vue3 前端)+ `jnpf-java-boot`(Java 后端)。 + +**配套阅读**: +- 契约(权威)→ [`contract.md`](contract.md) +- 迁移操作(怎么做)→ [`MIGRATION.md`](MIGRATION.md) +- 面 B 规格(要做到什么程度)→ [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) +- 实施期裁决 → [`decisions.md`](decisions.md) + +--- + +## 0. 怎么用这份文档 + +| 你的处境 | 读哪节 | +|---|---| +| 只想知道「能不能迁、差多少」 | §1 + §2 + §8 | +| 要动手迁(Rust → JNPF Java) | §6(口令换算)+ §8(对齐清单),再按 [`MIGRATION.md`](MIGRATION.md) 走 | +| 要让官方 Vue 前端跑在 Rust 后端上 | §2(8 条差异)+ §3(官方端点全表),规格见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) | +| 怀疑某条结论 | §9(复现命令),自己核一遍 | + +--- + +## 1. 审计范围与坐标 + +| 层 | 官方路径 | 本仓对应 | +|---|---|---| +| 统一信封 | `jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/ActionResult.java` | `src/backend/src/envelope.rs` | +| 错误码表 | 同上目录 `ActionResultCode.java` | `src/backend/src/envelope.rs` | +| 登录 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-controller/.../controller/LoginController.java` | `src/backend/src/auth.rs` | +| 口令解密 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-biz/.../granter/PasswordTokenGranter.java` | `src/backend/src/cipher.rs` | +| 加解密工具 | `jnpf-common/.../jnpf/util/DesUtil.java` | `src/backend/src/cipher.rs` | +| 安全配置 | `jnpf-common/.../jnpf/properties/SecurityProperties.java` | `src/backend/src/cipher.rs` | +| 用户/角色/组织/授权 | `jnpf-java-boot/jnpf-permission/jnpf-permission-controller/.../controller/*.java` | `src/backend/src/sys.rs` / `permission.rs` | +| 菜单 | `jnpf-java-boot/jnpf-system/jnpf-system-controller/.../controller/ModuleController.java` | `src/backend/src/sys.rs` | +| 前端 API 面 | `jnpf-web-apps-main/src/api/**` | `src/frontend/src/api/**` | +| 前端加密 | `jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts` | `src/frontend/src/utils/cipher.ts` | +| DDL | `jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql` | `src/backend/db/schema.sql` | + +--- + +## 2. §1 地基:**已经对齐**的部分 + +这 9 条是「能 1:1 迁走」的资产 —— 迁到官方 JNPF 时**不用改数据模型、也不用重写加密**。 + +### 2.1 统一返回信封 —— 逐字一致 ✅ + +官方 `ActionResult.java`: + +| 字段 | 行号 | +|---|---| +| `private Integer code;` | `ActionResult.java:27` | +| `private String msg;` | `ActionResult.java:30` | +| `private T data;` | `ActionResult.java:33` | +| `fail(Integer code, String message)` | `ActionResult.java:69` | +| `page(List, PaginationVO)` | `ActionResult.java:92` | + +**本仓**:`envelope.rs` 的 `ActionResult{code,msg,data}` + 「业务失败一律 HTTP 200」——**与官方一致**。 +官方同样是「HTTP 200 + body.code 表示成败」,错误由 `@RestControllerAdvice` 兜住(官方 `ResultExceptionHand`)。 + +> ⚠️ **注意与 `tdc-rs` 相反**:`tdc-rs` 用 401/403 裸 body。**别把它的形状抄过来。** + +### 2.2 错误码表 —— 本仓用了官方码表的前 4 个 ✅ + +官方 `ActionResultCode.java`(枚举,值即 HTTP 语义): + +| 码 | 含义 | 行号 | +|---|---|---| +| 200 | 成功 | `:19` | +| 400 | 失败 | `:23` | +| 401 | 验证错误 | `:27` | +| 500 | 异常 | `:31` | +| **600** | 登录过期 | `:35` | +| **601** | 被踢出 | `:39` | +| **602** | token 失效 | `:43` | +| 403 | 权限异常 | `:47` | + +**本仓**已用:`200` / `400` / `403` / `600`(**与官方字面一致**)。缺口见 §3.4。 + +### 2.3 登录路径与参数 —— 逐字一致 ✅ + +| 项 | 官方 | 本仓 | +|---|---|---| +| 登录 | `POST /api/oauth/Login`(`LoginController.java:117-119`;`api/core/auth.ts:6,28`) | ✅ 同路径同方法 | +| 编码 | `Content-Type: application/x-www-form-urlencoded`(`api/core/auth.ts:28`) | ✅ 同 | +| 参数 | `account` / `password` / `grant_type=password`(`api/core/auth.ts:13-21`;`LoginForm.vue:149`) | ✅ 同(`grant_type` **不加 camelCase**) | +| 附加参数 | `origin: 'password'`(`LoginForm.vue:84`)、`code?` / `timestamp?` / `jnpf_ticket?` | 本仓**只读必填三项**,多余参数忽略(可接受) | +| 登出 | `POST /api/oauth/Logout`(`LoginController.java:155`;`api/core/auth.ts:48`) | 本仓无登出端点(前端本地清 token)—— **见 §3 补项** | +| 当前用户 | `GET /api/oauth/CurrentUser`(`LoginController.java:192-194`) | ✅ 同路径(**返回体不同**,见 §3.3) | + +### 2.4 口令加密链 —— 逐字节一致 ✅ ★ + +这是整个迁移里**最容易被误判为"要重写"**的一块。核对结论:**前后端逐字节一致,不需要重写**。 + +**官方前端**(`jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts`): + +| 步骤 | 行号 | 内容 | +|---|---|---| +| key 派生 | `:15` | `defaultKey = encryptByMd5(VITE_CIPHER_KEY)` ⇒ **32 个 hex 字符** | +| key 落地 | `:24` | `this.key = parse(key)` ⇒ UTF-8 **32 字节** ⇒ **AES-256**(不是 AES-128!) | +| 模式 | `:42-43` | `mode: ECB` + `padding: pkcs7` ⇒ **AES-256-ECB-PKCS7** | +| 输出 | `:20,:26,:36` | `useHex = true` ⇒ 输出 **hex** | +| md5 | `:56-57` | `md5(password).toString()` ⇒ **小写 hex** | + +**官方前端调用点**(`jnpf-web-apps-main/src/views/_core/login/LoginForm.vue`): + +``` +:140 const password = encryptByMd5(data.password); // 明文 → md5 小写 hex +:141 const encryptPassword = aesEncryption.encryptByAES(password); // → AES-256-ECB → hex +:144 password: encryptPassword, +:149 grant_type: 'password', +``` + +**官方服务端解密链**: + +| 步骤 | 位置 | 内容 | +|---|---|---| +| 解密 | `PasswordTokenGranter.java:180` | `inputPwd = DesUtil.aesOrDecode(inputPwd, false, true)` | +| 取 key | `DesUtil.java:297` | `SecurityProperties.getInstance().getSecurityKey()` | +| key 派生 | `SecurityProperties.java:71-72` | `this.securityKey = Md5Util.getStringMd5(securityKey)` ⇒ **32 个 ASCII 字节** | +| 解密器 | `DesUtil.java:313,316` | Hutool `SymmetricCrypto(SymmetricAlgorithm.AES, keyBytes)` ⇒ **ECB/PKCS5Padding** | +| 比对 | `PasswordTokenGranter.java:186` | `Md5Util.getStringMd5(inputPwd + secretkey.toLowerCase())` | + +**本仓**(`src/backend/src/cipher.rs`):key = `md5_hex("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节** ⇒ AES-256-ECB-PKCS7,输出 hex,明文 = `md5_hex(raw)`。 + +> 🔴 **结论**:本仓与官方**同一套算法**。迁移时只需对齐**两个配置值**: +> - 前端 `VITE_CIPHER_KEY` ↔ 后端 `security.security-key`(官方 `SecurityProperties.setSecurityKey` 会自动 md5) +> - 官方默认值 `EY8WePvjM5GGwQzn`(JNPF 默认安全密钥) +> +> 检验向量(官方与本仓都必须过): +> `encryptPassword('123456')` == +> `d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b` + +### 2.5 口令**存储**公式 —— 差一步 ✅(可换算,见 §6) + +官方(`UserServiceImpl.java`): + +``` +:547 entity.setSecretkey(RandomUtil.uuId()); +:548 entity.setPassword( +:549 Md5Util.getStringMd5(entity.getPassword().toLowerCase() + entity.getSecretkey().toLowerCase())); +``` + +(重置口令同式:`:704-706`) + +⇒ 官方库里存的是 **`md5( md5_hex(明文) + secretkey )`**。 + +**本仓**库里存的是 **`md5_hex(明文)`** —— 正好是官方公式的**中间态**(未加 secretkey)。 +⇒ 迁移**不需要明文**,见 §6 的换算公式。 + +### 2.6 `base_*` 表名与列名 —— 逐字一致 ✅ + +本仓实现的 7 张 `base_*`(`base_authorize` / `base_module` / `base_organize` / `base_role` / `base_role_relation` / `base_user` / `base_user_relation`)与官方 DDL +(`jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql`)**列级零缺口**。 + +官方实体侧的列名映射(`@TableField`)与本仓一致,例: +`AuthorizeEntity.java:19,25-44` ⇒ 表 `base_authorize`,列 `f_item_type` / `f_item_id` / `f_object_type` / `f_object_id`。 + +**两个官方陷阱本仓已按原样保留**(不修正): +- `base_role_relation` 用户 id 在 **`f_object_id`**(配 `f_object_type='user'`),无 `f_user_id`; +- 组织/岗位关系在 **`base_user_relation`**,那里才有 `f_user_id`。 + +### 2.7 授权写入端点 —— 路径与 body 形状都一致 ✅ + +官方:`AuthorizeController.java:159-160` ⇒ `PUT /api/permission/Authority/Data/{objectId}`, +body = `AuthorizeDataUpForm`(`AuthorizeDataUpForm.java:14-38`): + +| 字段 | 行号 | 类型 | +|---|---|---| +| `objectId` | `:17` | `String` | +| `objectType` | `:20` | `String` | +| `button` | `:23` | `String[]` | +| `column` | `:26` | `String[]` | +| **`module`** | `:29` | **`String[]`** | +| `resource` | `:32` | `String[]` | +| `form` | `:35` | `String[]` | +| `systemIds` | `:38` | `String[]` | + +**本仓**:`PUT /api/permission/Authority/Data/{objectId}`,body `{objectType:'role', module:[...]}`。 +⇒ **路径一致、`module` 是一维数组一致、`objectType` 小写 `'role'` 与官方 `PermissionConst.ROLE = "role"`(`PermissionConst.java:18`)一致。** +本仓只是官方 body 的**子集**(只写 `module`,不写 button/column/…)—— 官方对未出现的字段不处理 ⇒ 兼容。 + +### 2.8 角色/组织/用户的官方对象类型常量 —— 一致 ✅ + +`PermissionConst.java`: + +| 常量 | 值 | 行号 | +|---|---|---| +| `ORGANIZE` | `"organize"` | `:8` | +| `POSITION` | `"position"` | `:13` | +| `ROLE` | `"role"` | `:18` | +| `PERMISSION_GROUP` | `"permissionGroup"` | `:23` | +| `COMPANY` / `DEPARTMENT` / `GROUP` / `SYSTEM` / `STAND` | 对应小写 | `:28/33/38/43/48` | +| `MODULE` | `"module"` | `:53` | +| `USER` | `"user"` | `:58` | +| 按钮权限 | `btn_add` / `btn_edit` / `btn_remove` / `btn_detail` / `btn_upload` / `btn_download` / `btn_batchRemove` / `btn_batchPrint` | `:63-77` | + +**本仓 `objectType` 取值与之字面一致**(`'role'` / `'user'` / `'organize'` / `'position'`)。 + +### 2.9 主键与租户列 —— 一致 ✅ + +- 主键 `f_id` = **36 位 UUID v4**(带连字符),列 `varchar(50)`。 +- 单租户固定 `f_tenant_id = '0'`(官方 `jnpf-tenant*` 系列本仓明确不碰)。 + +--- + +## 3. §2 差异:**8 条**,按迁移成本排序 + +| # | 差异 | 官方 | 本仓 | 迁移成本 | 面 B 工作量 | +|---|---|---|---|---|---| +| D1 | 端点风格 | RESTful | ssw 约定 | **低**(映射表即可) | 中(要新路由) | +| D2 | 列表响应 | `PageListVO` | 全量数组 | **低** | 中 | +| D3 | `CurrentUser` 形状 | `PcUserVO`(5 字段) | 2 字段 | **低** | 小 | +| D4 | 码表缺项 | 401/500/601/602 | 只有 200/400/403/600 | **低** | 小 | +| D5 | 菜单接口 | `/api/system/Menu/ModuleBySystem` | `/api/ssw/sys/Module/List` | **低** | 小 | +| D6 | 鉴权模型 | `f_en_code` 点权限 | 菜单路径白名单 | **中** | 中 | +| D7 | 请求头 | `App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3` | 前端发 `App-Code: sswflow` + `Jnpf-Origin: pc`(**不发** `Vue-Version`) | **低**(但 `Vue-Version` 是**面 A/面 B 判别依据** ⇒ 本仓前端**禁发**它,见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) §2.2) | 小 | +| D8 | 口令存储 | `md5(md5(raw)+secretkey)` | `md5(raw)` | **低**(有换算公式,§6) | 中 | + +### 3.1 D1 — 端点风格 + +官方是 **RESTful**(`@RequestMapping` + `@GetMapping`/`@PostMapping`/`@PutMapping`/`@DeleteMapping`): + +| 官方前缀 | 控制器 | 行号 | +|---|---|---| +| `/api/permission/Users` | `UserController.java` | `:153` | +| `/api/permission/Role` | `RoleController.java` | `:85` | +| `/api/permission/Organize` | `OrganizeController.java` | `:88` | +| `/api/permission/Authority` | `AuthorizeController.java` | `:75` | +| `/api/system/Menu` | `ModuleController.java` | `:101` | +| `/api/oauth` | `LoginController.java` | `:86` | + +本仓是 **ssw 约定**:`/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`。 + +**这一条是「双面后端」存在的根本原因** —— 见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)。 + +> 📌 官方 ssw 前端(`ssw-jnpf-lite-react`)自己也**没有**用 ssw 路径去迁官方 —— 它的 `MIGRATION.md` 明确写了: +> 「端点命名 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`(ssw 约定,非官方 visualdev 路径;稳定期真实 JNPF 由引擎生成,路径以引擎为准,**数据模型仍保值**)」。 +> ⇒ **数据模型保值(本仓已做到),路径在迁官方时重新映射**。这正是本仓设计意图,不是缺陷。 + +### 3.2 D2 — 列表响应:`PageListVO` ✅(**本条要更正一个常见误解**) + +官方 `PageListVO.java`: + +```java +:17 PaginationVO pagination; // ← 官方**有**分页元数据 +:19 private List list; +``` + +`PaginationVO.java`:`currentPage`(`:16`) / `pageSize`(`:18`) / `total`(`:20`)。 + +⇒ 官方分页响应形状是: + +```json +{ "code":200, "msg":"操作成功", "data": { "pagination": {"currentPage":1,"pageSize":20,"total":42}, "list":[ ... ] } } +``` + +**本仓**:`data` 直接是**全量数组**(契约 §6 明确「分页不在 v1 范围」)。 + +分页请求参数(官方 `Pagination.java`):`pageSize=20`(`:19`) / `sort="DESC"`(`:21`) / `sidx=""`(`:23`) / `currentPage=1`(`:25`) / `total`(`:27`) / `records`(`:29`)。 + +> 🔴 **常见误解**:「官方 `PageListVO` 就是 `{list:[...]}`」—— **错**,它还有 `pagination`。 +> 迁官方时若只回 `{list}`,官方前端的分页组件会拿不到 `total` ⇒ 退化成「只显示第一页」。 + +**本仓无分页** ⇒ 迁到官方后**必须补**(或在官方侧改成不分页组件)。这是**迁 JNPF 时的必做项**,不是可选优化。 + +### 3.3 D3 — `CurrentUser` 形状 + +官方 `PcUserVO.java`: + +| 字段 | 类型 | 行号 | +|---|---|---| +| `menuList` | `List` | `:19` | +| `permissionList` | `List` | `:22` | +| `userInfo` | `UserCommonInfoVO` | `:25` | +| `currentSystemId` | `String` | `:27` | +| `sysConfigInfo` | `SystemInfo` | `:33` | + +`AllMenuSelectVO.java`:`id`(`:12`) / `fullName`(`:15`) / `enCode`(`:18`) / `parentId`(`:21`) / `icon`(`:24`) / `hasChildren`(`:27`) / `urlAddress`(`:30`) / `pageAddress`(`:33`) / `linkTarget`(`:36`) / `children`(`:39`) / `type`(`:42`) / `propertyJson`(`:44`) / `sortCode`(`:46`) / `systemId`(`:48`) / `isData`(`:50`)。 +`PermissionModel.java`:`modelId`(`:10`) / `moduleName`(`:12`) / `button`(`:14`) / `column`(`:16`) / `resource`(`:18`) / `form`(`:20`)。 +`UserCommonInfoVO.java`:`userId`(`:16`) / `userAccount`(`:19`) / `userName`(`:22`) / `headIcon`(`:25`) / `organizeId`(`:28`) / `organizeName`(`:31`) / `positionId`(`:34`) / `positionName`(`:37`) / `isAdministrator`(`:75`) / `systemId`(`:83`) / `systemCode`(`:87`) … + +**本仓**(`docs/contract.md:435`): + +```json +{ "code":200, "data":{ "userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true }, "menuList":[ … ] } } +``` + +⇒ 缺 `permissionList` / `currentSystemId` / `sysConfigInfo`;`userInfo` 只有 4 个字段;`menuList` 节点字段是本仓自定义(**非** `AllMenuSelectVO` 形状)。 + +> 📌 **对齐建议(面 B)**:面 B 的 `CurrentUser` **直接返回官方 `PcUserVO` 形状**(`menuList` 用 `AllMenuSelectVO` 的 15 个字段、`userInfo` 至少补 `isAdministrator`/`organizeId`/`organizeName`/`positionId`/`positionName`/`systemId`/`systemCode`)。 +> 面 A 保持不变(§1 的 2 字段形状不能动,那是 ssw 契约)。 + +### 3.4 D4 — 码表缺项 + +本仓**没有** `401`(验证错误)/ `500`(异常)/ `601`(被踢出)/ `602`(token 失效)。 + +官方前端 `jnpf-web-apps-main/src/api/request.ts` 的响应拦截器**按 `code` 分支**: + +``` +:70 case ResultEnum.FORBIDDEN → 跳无权限页(:74 authStore.goForbidden()) +:78 case ResultEnum.TOKEN_ERROR +:79 case ResultEnum.TOKEN_LOGGED +:80 case ResultEnum.TOKEN_TIMEOUT → 清 token 跳登录 +``` + +⇒ 官方前端**期待** `601/602` 用来触发「清 token 跳登录」。本仓只有 `600` ⇒ 官方前端拿到 `600` 会走**默认分支**(`msg` 提示但不跳登录)⇒ **表现为「token 失效后页面卡住」**。 + +**面 B 必须**:`600` → `602`(token 失效);`601`(被踢出)可后置。 + +### 3.5 D5 — 菜单接口 + +官方 `ModuleController.java`: + +| 端点 | 行号 | 用途 | +|---|---|---| +| `GET /api/system/Menu/ModuleBySystem` | `:121` | **官方前端取菜单的入口**(`api/system/menu.ts:8-9`) | +| `GET /api/system/Menu/{systemId}/TreeView` | `:332` | 菜单树(管理端) | +| `GET /api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 | +| `GET /api/system/Menu/Selector/All` | `:444` | 菜单下拉(全量) | +| `POST /api/system/Menu` | `:169-170` | 新建 | +| `PUT /api/system/Menu/{id}` | `:194-195` | 修改 | +| `GET /api/system/Menu/{id}` | `:248-249` | 详情 | +| `DELETE /api/system/Menu/{id}` | `:228-229` | 删除 | +| `PUT /api/system/Menu/{id}/Actions/State` | `:498-499` | 启停 | + +**本仓**:`/api/ssw/sys/Module/{List,Save,Delete}`。 + +⇒ 官方前端要的 `ModuleBySystem`(按 systemId 取菜单)本仓**没有对应面**。 +注意:`ModuleBySystem` 返回的是**菜单列表(平铺)**,不是树;树在前端组。 + +### 3.6 D6 — 鉴权模型:点权限 vs 菜单路径 + +**官方**:Sa-Token 的 `@SaCheckPermission`,权限码是 `permission.{对象}` + `btn_*` 按钮码: + +| 端点 | 权限码 | 行号 | +|---|---|---| +| `GET /api/permission/Users` | `permission.organize` OR `permission.user` OR `permission.role` | `UserController.java:293-294` | +| `POST /api/permission/Users` | `permission.user` | `UserController.java:409-410` | +| `GET /api/permission/Role` | `permission.auth` OR `permission.role` | `RoleController.java:99-100` | +| `GET /api/permission/Organize/AsyncList/{id}` | `permission.organize` OR `permission.user` OR `permission.role` OR … | `OrganizeController.java:107-108` | +| `GET /api/system/Menu/ModuleBySystem` | 无(登录即可) | `ModuleController.java:121` | +| `PUT /api/permission/Authority/Data/{objectId}` | `permission.auth` OR `permission.role` | `AuthorizeController.java:159` | + +这些码来自 `base_module.f_en_code`(`PermissionConst.java:8-58` 的常量拼成 `permission.` + 对象名)。 + +**本仓**:按**菜单路径**(`system/User`)做守卫(`permission.rs` 的 `guard_module`)。 + +⇒ **两套模型语义不同**(点权限 vs 菜单路径)。本仓的模型是 ssw 前端定制的;官方前端是按 `f_en_code` 判按钮显隐。 +**迁官方时必须补 `f_en_code` 维度**,否则官方前端所有按钮都不可见(因为 `permissionList` 拿不到东西)。 + +### 3.7 D7 — 请求头 + +官方 `jnpf-web-apps-main/src/api/request.ts`: + +``` +:109 config.headers['App-Code'] = getRealJnpfAppEnCode(); +:111 config.headers['Jnpf-Origin'] = 'pc'; +:112 config.headers['Vue-Version'] = '3'; +``` + +⇒ 官方后端会读 `App-Code` 决定**应用/系统上下文**(多应用隔离)。本仓单租户单应用 ⇒ **可忽略**(但面 B 建议原样接受并忽略,别返回 400)。 + +🔴 **但 `Vue-Version: 3` 不是"可忽略"的**——它是**面 A / 面 B 的判别依据**: + +- 本仓前端 `src/frontend/src/api/request.ts:35-36` **也发** `App-Code: sswflow` 与 `Jnpf-Origin: pc`(与官方同款), + **只不发** `Vue-Version` ⇒ 三个官方头里**只有它是本仓前端唯一不发的** ⇒ 判别只能用它。 +- 🔴 **本仓前端禁止发 `Vue-Version`**(一旦发出,面 A 请求会被误判成面 B ⇒ 契约整体错位)。 +- 分流规则全文见 [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md) §2.2; + `scripts/check-module.sh` 的「全局红线」段静态钉住两侧(前端**禁发** + 面 B 尺子**必带**)。 + +### 3.8 D8 — 口令存储缺 `secretkey` + +见 §2.5。**影响**: +- 本仓的口令 hash **不能直接塞进官方库**(官方登录会比对 `md5(md5(raw)+secretkey)`)⇒ 必须走 §6 的换算; +- 本仓 `base_user.f_secretkey` 列**已存在**(本仓 `schema.sql:142`;官方 DDL `:4503`)⇒ 迁移时补写即可; +- 本仓的 `f_password` 值 = `md5_hex(raw)` ⇒ **正是官方公式的输入** ⇒ 换算**不需要明文**。 + +--- + +## 4. §3 官方端点全表(后台最小可用面) + +**这是「官方 Vue 前端要能跑」的最小集合**。官方 `src/api` 共 97 个 `.ts`、`api/permission/` 14 个、`user.ts` 单文件 16 个端点 ⇒ 官方全量远大于此表。表中只列**系统管理**这一条线。 + +### 4.1 认证 + +| 方法 | 路径 | 官方出处 | 返回 | +|---|---|---|---| +| POST | `/api/oauth/Login` | `LoginController.java:117` | `ActionResult`(`LoginVO.java:17` = `token`) | +| POST | `/api/oauth/Logout` | `LoginController.java:155` | `ActionResult` | +| GET | `/api/oauth/CurrentUser` | `LoginController.java:192` | `ActionResult` | + +> 📌 官方 `LoginVO` 字段:`token`(`:17`) / `theme`(`:20`) / `wlQrcode`(`:25`) / `isSaas`(`:28`) / `saasList`(`:31`)。 +> 本仓返回的是 `{token, expiresIn:7200, tokenTypeName:'bearer'}` —— **多两个字段,但 `token` 同名同义** ⇒ 官方前端能取到 token(它只读 `data.token`)。 +> `expiresIn` / `tokenTypeName` 是本仓 ssw 契约的字段,**面 A 保留**;面 B 可另返官方形状或同返(官方前端忽略多余字段)。 + +### 4.2 用户(`/api/permission/Users`) + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| GET | `/api/permission/Users` | `UserController.java:293` | `permission.organize\|user\|role` | +| GET | `/api/permission/Users/{id}` | `:355` | `permission.user` | +| POST | `/api/permission/Users` | `:409` | `permission.user` | +| PUT | `/api/permission/Users/{id}` | `:429` | `permission.user` | +| DELETE | `/api/permission/Users/{id}` | `:496` | `permission.user` | +| POST | `/api/permission/Users/BatchDelete` | `:592` | `permission.user` | +| POST | `/api/permission/Users/BatchUpdateState` | `:694` | `permission.user` | +| GET | `/api/permission/Users/All` | `:729` | 登录即可 | +| GET | `/api/permission/Users/Selector` | `:769` | 登录即可 | +| POST | `/api/permission/Users/UserCondition` | `:806` | 登录即可 | +| GET | `/api/permission/Users/{id}/GetPosition` | `:273` | `permission.user` | +| POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 前端 `user.ts:37` | `permission.user` | +| PUT | `/api/permission/Users/{id}/Actions/unlock` | 前端 `user.ts:45` | `permission.user` | +| GET | `/api/permission/Users/ExportData` | 前端 `user.ts:53` | 导入导出(可后置) | +| GET/POST | `.../TemplateDownload` · `.../ImportData` · `.../ImportPreview` · `.../ExportExceptionData` | 前端 `user.ts:57-69` | 导入导出(可后置) | +| POST | `/api/permission/Users/getUserList` · `.../getSelectedList` · `.../getSelectedUserList` | 前端 `user.ts:49,73,77` | 批量选择(可后置) | + +**列表响应**:`ActionResult>`(`UserController.java:295`)。 +**请求参数**:`UserPagination`(`UserPagination.java:11-36`)= `Pagination` + `gender` / `enabledMark` / `groupId` / `organizeId` / `positionId` / `roleId` / `showSubOrganize` / `dataType`。 +**列表项**:`UserListVO`(`UserListVO.java:16-74`)= `id` / `account` / `realName` / `fullName` / `gender` / `mobilePhone` / `email` / `organize` / `description` / `enabledMark` / `creatorTime` / `sortCode` / `lockMark` / `handoverMark` / `isAdministrator` / `headIcon` / `unlockTime` / `position` / `isDutyUser` / `maxRelationId` … + +> 📌 **注意**:`UserListVO` **没有 `password` 字段** ⇒ 官方列表天然不泄口令。本仓列表也是手工挑字段去掉 `password` ⇒ **一致**。 + +### 4.3 角色(`/api/permission/Role`) + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth\|role` | +| GET | `/api/permission/Role/{id}` | `:273` | `permission.role` | +| POST | `/api/permission/Role` | `:122` | `permission.role` | +| PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` | +| DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` | +| GET | `/api/permission/Role/Selector` | `:327` | 登录即可 | +| POST | `/api/permission/Role/RoleCondition` | `:342` | 登录即可 | + +列表响应:`ActionResult>`(`RoleController.java:101`)。 + +### 4.4 组织(`/api/permission/Organize`) + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize\|user\|role\|…` | +| GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 | +| GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` | +| POST | `/api/permission/Organize` | `:179` | `permission.organize` | +| PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` | +| DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` | +| GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 | +| POST | `/api/permission/Organize/SelectedList` | `:341` | 登录即可 | + +列表响应:`ActionResult>`(`OrganizeController.java:111-112`)。 + +### 4.5 菜单(`/api/system/Menu`) + +见 §3.5 的表。`GET /api/system/Menu/ModuleBySystem` 是**官方前端的菜单入口**。 + +### 4.6 授权(`/api/permission/Authority`) + +| 方法 | 路径 | 官方出处 | 权限码 | +|---|---|---|---| +| POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | `permission.auth\|role` | +| PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | `permission.auth\|role` | +| GET | `/api/permission/Authority/Model/{itemId}/{objectType}` | `:124-125` | `permission.auth\|role\|onlineDev.visualPortal` | +| PUT | `/api/permission/Authority/Model/{portalManageId}` | `:138-139` | `permission.auth\|role` | + +读取授权树用 **`POST`**(不是 GET)—— 官方前端 `api/permission/auth.ts:9` 确认。 + +### 4.7 数据权限链接(v1 不做) + +`/api/system/ModuleDataAuthorizeLink/**`(`api/system/authorize.ts:4`)—— 官方是**低代码数据权限方案**(表/字段级),本仓 v1 明确不碰(见 `CLAUDE.md`「明确不在 v1 范围」)。 + +--- + +## 5. §4 官方码表(本仓需要补的) + +| 码 | 官方枚举 | 行号 | 官方前端行为 | 本仓 | 面 B 需要 | +|---|---|---|---|---|---| +| 200 | `SUCCESS` | `ActionResultCode.java:19` | 放行 | ✅ 有 | — | +| 400 | `FAIL` | `:23` | 提示 msg | ✅ 有 | — | +| 401 | `VALIDATEERROR` | `:27` | 提示 msg | ❌ 无 | 建议补 | +| 500 | `EXCEPTION` | `:31` | 提示 msg | ❌ 无 | 建议补 | +| 600 | `SESSIONOVERDUE` | `:35` | 过期提示 | ✅ 有 | 保留 | +| 601 | `SESSIONOFFLINE` | `:39` | 被踢出 | ❌ 无 | 建议补 | +| 602 | `SESSIONERROR` | `:43` | **清 token 跳登录** | ❌ 无 | **必补** | +| 403 | `PEIMISSIONEXP` | `:47` | 跳无权限页 | ✅ 有 | 保留 | + +--- + +## 6. §5 口令三段式与换算公式 + +### 6.1 官方三段式 + +``` +① 明文 pwd + ↓ 官方前端 LoginForm.vue:140 encryptByMd5 +② md5_hex(pwd) ← 32 个小写 hex 字符 + ↓ 官方前端 LoginForm.vue:141 encryptByAES (AES-256-ECB-PKCS7, key=md5_hex(security-key) 的 32 字节) +③ 密文 hex ← 走网络的是这一段 + ↓ 官方服务端 PasswordTokenGranter.java:180 → DesUtil → Hutool AES +④ md5_hex(pwd) 复原(即②) + ↓ 官方服务端 PasswordTokenGranter.java:186 比对 +⑤ md5( ④ + secretkey.toLowerCase() ) ← 库里存的 +``` + +官方建号时(`UserServiceImpl.java:547-549`): + +```java +entity.setSecretkey(RandomUtil.uuId()); +entity.setPassword(Md5Util.getStringMd5(entity.getPassword().toLowerCase() + entity.getSecretkey().toLowerCase())); +``` + +其中 `entity.getPassword()` 在此处**已经是 `md5_hex(明文)`**(由上一层 service 传入)⇒ 库里存 `md5(md5_hex(明文) + secretkey)`。 + +### 6.2 本仓现状 + +库里存 **`md5_hex(明文)`** = 上面的 **②**(= 官方公式的**被加项**,不是结果)。 + +### 6.3 换算公式(**不需要明文**) + +本仓一行 `f_password` ⇒ 官方一行 `f_password`: + +```sql +-- 对每一行: +-- new_secretkey := 随机 UUID(官方用 RandomUtil.uuId()) +-- new_password := md5( lower(old_password) + lower(new_secretkey) ) +-- 并写回 f_secretkey = new_secretkey +``` + +Rust 侧等价(示意): + +```rust +let old = "d41d8cd98f00b204e9800998ecf8427e"; // = md5_hex(明文) +let secret = uuid::Uuid::new_v4().to_string(); // 36 位 +let new_pw = md5_hex(format!("{}{}", old.to_lowercase(), secret.to_lowercase())); +``` + +**为什么成立**:官方比对的是 `md5(解密后的② + secretkey)`,而本仓存的**就是②** ⇒ 直接拿旧值当②参与公式即可,**全程不接触明文**。 + +### 6.4 换算的验证方法 + +换算后用**同一个明文**走一次官方登录路径,断言: +`md5( md5_hex(明文) + secretkey ) == 库里新值`。 +(官方登录时 `inputPwd` = 解密后的 `md5_hex(明文)`,见 `PasswordTokenGranter.java:186`。) + +--- + +## 7. §6 官方数据模型规模(用来判断「迁移是搬运还是重写」) + +| 对象 | 官方规模 | 本仓 v1 | +|---|---|---| +| Java 后端 | 2,774 个 `.java` / 282,624 行 | 6,372 行 Rust | +| 官方前端(apps-main) | 765 `.vue` + 224 `.ts` = 172,525 行 | 18 个文件 / 1,374 行 | +| 官方前端(monorepo-framework) | 1,218 `.vue` + 1,036 `.ts` = 284,176 行 | — | +| DDL 表数 | **331** 张(其中 `base_*` **123** 张) | **10** 张(`base_*` 7 + 业务 3) | +| `base_*` 已实现列级缺口 | — | **0** | +| 官方 `src/api` | 97 个 `.ts`;`api/permission/` 14 个 | 5 个 | + +⇒ **结论**:本仓 v1 覆盖的是官方 **`base_*` 权限体系的这 7 张表**(列级零缺口), +**不覆盖**官方 331 张表里的其余 324 张(工作流、在线开发、数据视图、消息、租户、报表…)。 +迁移时**这 7 张表的数据是直接搬运**(`--data-only`),**其余能力要么不用、要么另做**。 + +--- + +## 8. §7 对齐清单(本仓 → 官方,做什么、做到什么程度) + +| # | 对齐项 | 本仓现状 | 迁官方要做的事 | 面 B 要做的事 | 优先级 | +|---|---|---|---|---|---| +| A1 | 统一信封 | ✅ 已一致 | 无 | 无 | — | +| A2 | 码表 | 4/8 | 补 401/500/601/602 | 至少补 602 | 高 | +| A3 | 登录路径/参数 | ✅ 已一致 | 对齐 cipher key 配置 | 无(沿用) | 低 | +| A4 | 口令加密链 | ✅ 逐字节一致 | 对齐 `security.security-key` | 无 | 低 | +| A5 | 口令存储 | 缺 secretkey | 按 §6.3 换算 | 支持 `f_secretkey` 写入 | 中 | +| A6 | `base_*` 表列 | ✅ 零缺口 | `--data-only` 搬运 | 无 | 低 | +| A7 | 授权写入端点 | ✅ 路径/body 一致 | 补 `f_en_code` 维度 | 同 | 中 | +| A8 | 端点风格 | ssw 约定 | 映射到官方 RESTful | **新增官方路径** | 高 | +| A9 | 列表分页 | 全量数组 | 官方侧改组件或后端补分页 | **返回 `PageListVO`** | 高 | +| A10 | `CurrentUser` | 2 字段 | 官方前端需 `PcUserVO` | **返回 `PcUserVO`** | 高 | +| A11 | 菜单接口 | ssw 路径 | 官方侧调 `ModuleBySystem` | **实现 `ModuleBySystem`** | 高 | +| A12 | 点权限(`f_en_code`) | 无 | 官方前端按钮靠它 | **实现 `permissionList` + 码判权** | 中 | +| A13 | 请求头 | 前端发 `App-Code` + `Jnpf-Origin: pc`(**不发** `Vue-Version`) | 官方后端读 `App-Code`;`Vue-Version` 是面 A/面 B 判别头 | **接受并忽略**(`App-Code`);**`Vue-Version` 判面** | 低 | +| A14 | 登出 | 无端点 | 官方有 `POST /api/oauth/Logout` | 低优先 | 低 | +| A15 | 数据权限方案 | 不做 | 不做 | 不做 | — | + +--- + +## 9. §8 复现命令(自己核一遍) + +> 本机 curl 走系统代理 ⇒ 打 localhost 必须加 `--noproxy '*'`。 + +```bash +J=~/Desktop/workspace/jnpf + +# §2.4 口令加密链 +grep -n "defaultKey\|parse(key)\|ECB\|pkcs7\|useHex" \ + "$J/jnpf-web-monorepo-framework/packages/jnpf/utils/src/helpers/cipher.ts" +grep -n "encryptByMd5\|encryptByAES" \ + "$J/jnpf-web-apps-main/src/views/_core/login/LoginForm.vue" +grep -n "aesOrDecode\|getStringMd5" \ + "$J/jnpf-java-boot/jnpf-oauth/jnpf-oauth-biz/src/main/java/jnpf/granter/PasswordTokenGranter.java" +grep -n "setSecurityKey\|getStringMd5" \ + "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/properties/SecurityProperties.java" + +# §2.5 口令存储公式 +grep -n "setSecretkey\|setPassword\|getStringMd5" \ + "$J/jnpf-java-boot/jnpf-permission/jnpf-permission-biz/src/main/java/jnpf/permission/service/impl/UserServiceImpl.java" + +# §3.2 分页响应形状 +sed -n '14,21p' "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/vo/PageListVO.java" +sed -n '13,21p' "$J/jnpf-common/jnpf-boot-common/jnpf-common-core/src/main/java/jnpf/base/vo/PaginationVO.java" + +# §4 官方端点全表 +grep -n "RequestMapping\|GetMapping\|PostMapping\|PutMapping\|DeleteMapping\|SaCheckPermission" \ + "$J/jnpf-java-boot/jnpf-permission/jnpf-permission-controller/src/main/java/jnpf/permission/controller/UserController.java" | head -40 + +# §3.7 请求头 +grep -n "App-Code\|Jnpf-Origin\|Vue-Version" "$J/jnpf-web-apps-main/src/api/request.ts" +``` + +**本仓侧**: + +```bash +# cipher 自证(免 node 依赖) +./target/release/tds-lite-rs --enc 123456 +# 期望:d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b +``` + +--- + +## 10. 变更记录 + +| 日期 | 变更 | +|---|---| +| 2026-10-26 | 首版。逐行核对官方源码,确立「9 条已对齐 / 8 条差异 / 3 条换算与补齐」。**更正了一处常见误解**:官方 `PageListVO` 含 `pagination` 字段,不是只有 `{list}`。 | diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md new file mode 100644 index 0000000..3843631 --- /dev/null +++ b/docs/MIGRATION.md @@ -0,0 +1,303 @@ +# 迁移指南(Rust ⇄ NestJS ⇄ 官方 JNPF Java) + +> 本仓的价值不是「一个 JNPF 后台」,而是**一个可双向搬运的框架**: +> 官方 JNPF Java ↔ 本仓 Rust ⇄ react 版 NestJS,三者**数据模型逐字同形**(同一套 `base_*` 表、同一套 cipher、同一套信封)。 +> +> **先读**:[`JNPF_SOURCE_AUDIT.md`](JNPF_SOURCE_AUDIT.md)(官方源码逐行核对,带 `文件:行号`)、 +> [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)(面 B 规格)、 +> [`contract.md`](contract.md)(本仓契约唯一真源)。 + +--- + +## 0. 迁移地图 + +| 起点 | 终点 | 性质 | 依据 | +|---|---|---|---| +| **本仓 Rust** | 官方 JNPF Java | **近机械翻译**(后端)+ 数据 ETL(`base_*`) | 本文 §2 / §6 / §7 | +| **本仓 Rust** | react 版 NestJS | **换实现,不换契约** ⇒ 前端零改 | 本文 §5 | +| **官方 JNPF Java** | 本仓 Rust | **走「面 B」**(本仓已实现官方形状的那一面) | 本文 §4 | +| **react 版 NestJS** | 官方 JNPF Java | 见 react 技能 `MIGRATION.md`(同一套约定) | — | + +🔴 **一句话**:数据模型(`base_*` 表名/列名)与**密文算法**是三方共用的**契约**; +端点路径、响应形状、权限判定**不是**——那三层各框架自有风格,靠「双面后端」在同一个进程里并存。 + +--- + +## 1. 为什么"搬得快"——被刻意锁死的五件事 + +| # | 锁死的东西 | 值 | 不这么做会怎样 | +|---|---|---|---| +| 1 | `base_*` 表名/列名 | 官方 DDL **逐字**(含两个故意不修正的陷阱) | 迁官方时**导不进数据** ⇒ 重写 | +| 2 | 口令 cipher | `md5(明文)` → `AES-256-ECB-PKCS7`(key = `md5("EY8WePvjM5GGwQzn")` 的 **32 个 ASCII 字节**)→ hex | 前后端对不上 ⇒ 登录全挂 | +| 3 | 响应信封 | `{code,msg,data}`,业务失败也 **HTTP 200** | 前端拦截器全改 | +| 4 | 主键 | 36 位 UUID v4,列 `varchar(50)` | 数据类型/长度对不上 ⇒ 导不进 | +| 5 | JSON 键名 | 列名去 `f_` 前缀后 camelCase | 前端全改 | + +**注意**:这五条**不包含**「端点路径」和「列表响应形状」——那两件官方与本仓**不同**, +由「面 A / 面 B」两套并存来解决(见 `JNPF_COMPAT_SURFACE.md` §2)。 + +--- + +## 2. 后端:本仓 Rust → 官方 JNPF Java + +### 2.1 逐件翻译表 + +| 本仓(Rust / axum 0.8) | 官方 JNPF Java | 说明 | +|---|---|---| +| `main.rs`(装配 + `--enc`) | `ssw-admin`(`@SpringBootApplication`) | 启动入口 | +| `routes.rs`(`Router` 27 条路径) | `ssw-{appCode}` 的 `@RestController` | **路径按官方风格改**(见 §2.3) | +| `entities.rs`(`EntitySpec` / `ColumnSpec`) | Java 实体 `extends SuperBaseEntity` + `@TableField("f_title")` | **一个 spec ≈ 一个实体类**:列清单逐字对应 | +| `crud.rs`(spec 驱动的 CRUD 引擎) | `XxxService extends SuperServiceImpl` + `XxxMapper extends SuperMapper` | 官方是 **MyBatis-Plus Join**,不是 JPA | +| `sys.rs`(5 组 `base_*` 显式 handler,1290 行) | `UserController` / `RoleController` / `OrganizeController` / `ModuleController` / `AuthorizeController` | 本仓 5 个 handler → 官方 5 个 controller(**一对一**) | +| `permission.rs`(四源合并 + 管理员短路) | 官方 `@SaCheckPermission("permission.user")` + `SswPermissionGuard` | **判据从「菜单路径」换成「权限编码」**(`base_module.f_en_code`)⇒ 见 §2.4 | +| `auth.rs`(登录 + 守卫) | jnpf-oauth(Sa-Token)+ `PasswordTokenGranter` | 官方多一层 `secretkey`(§7) | +| `cipher.rs`(`md5` + AES-256-ECB) | `DesUtil.aesOrDecode` + `SecurityProperties.securityKey` | **算法逐字节等价** ⇒ 不重写,只对齐两个配置值 | +| `envelope.rs`(`ActionResult{code,msg,data}`) | `jnpf.base.ActionResult` | 形状一致 ⇒ 前端零改 | +| `db/schema.sql`(10 张表) | 官方 DDL | `base_*` 7 张**逐字**;业务表 3 张在官方没有 ⇒ 见 §6.2 | +| `db.rs`(pglite 进程内 PG) | 真实 PostgreSQL(`application.yml` 的 `master.url`) | 方言一致 ⇒ SQL 基本不用改 | +| `ids.rs`(UUID v4) | `IdUtil.fastUUID()` | 都是 36 位 | +| `session.rs`(内存 token 表) | Sa-Token(Redis) | 官方多两个码 `601/602`(见 §2.5) | + +### 2.2 迁 JNPF 必备 import 速查 + +| 用途 | import | +|---|---| +| 实体基类 | `jnpf.base.entity.SuperBaseEntity` / `SuperEntity` / `SuperExtendEntity` | +| Mapper | `jnpf.base.mapper.SuperMapper` | +| Service | `jnpf.base.service.SuperService` + `jnpf.base.service.SuperServiceImpl` | +| 返回信封 | `jnpf.base.ActionResult.{success/fail/page}` | +| 分页 | `jnpf.base.Pagination` + `jnpf.base.vo.PaginationVO` + `jnpf.base.vo.PageListVO` | +| 工具 | `jnpf.util.{RandomUtil, UserProvider, JsonUtil}` | +| 异常处理 | `jnpf.exception.ResultExceptionHand`(`@RestControllerAdvice`,裸异常 ⇒ `code:400`) | +| 鉴权(点权限) | Sa-Token `@SaCheckPermission("permission.user")` | +| 鉴权(菜单) | `SswPermissionGuard.requireMenu(XxxController.class)` | + +> `SuperBaseEntity` **只有 `f_id` 一个字段**(唯一强制)。 +> `f_tenant_id / f_last_modify_* / f_delete_time / f_delete_user_id` 属 `SuperEntity` 的**可选增强层**,**不必补**。 + +### 2.3 端点路径:这是**唯一**需要改设计的地方 + +本仓面 A 用 ssw 约定 `/api/ssw/{appCode}/{Entity}/{List|Save|Delete}`; +官方是 **RESTful**:`/api/permission/Users`、`/api/permission/Role`(官方自己也不统一,单数)、 +`/api/system/Menu`、`/api/permission/Organize`、`/api/permission/Authority`、动作 `/{id}/Actions/{action}`。 + +| 本仓面 A | 官方 | +|---|---| +| `GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=}` | `GET/POST /api/permission/Users` · `GET/PUT/DELETE /api/permission/Users/{id}` | +| `GET/POST/DELETE /api/ssw/sys/Role/{…}` | `/api/permission/Role`(单数)· `/{id}` | +| `GET/POST/DELETE /api/ssw/sys/Organize/{…}` | `/api/permission/Organize` · `/AsyncList/{id}` | +| `GET/POST/DELETE /api/ssw/sys/Module/{…}` | `/api/system/Menu` · `/{id}` · `/ModuleBySystem` | +| `PUT /api/permission/Authority/Data/{objectId}` | **同路径** ✅(body 官方是超集,本仓已兼容) | +| `GET /api/ssw/sys/Role/Modules?roleId=` | `POST /api/permission/Authority/Data/{objectId}/Values` | + +🔴 **不要把面 A 路径改成官方路径** —— 面 A 是 react 技能的前端在用的,改了就破契约。 +**要官方形状,走面 B**(`JNPF_COMPAT_SURFACE.md` §3),两套并存于同一进程。 + +### 2.4 权限判据:菜单路径 → 权限编码 + +| | 本仓 | 官方 | +|---|---|---| +| 判据 | 菜单 `f_url_address`(如 `system/User`) | `base_module.f_en_code`(如 `permission.user`) | +| 来源 | `base_module` 表 | 同一张表,**另一个列** | +| 声明方式 | 路由守卫按 key 查 | `@SaCheckPermission("permission.user")` | + +🔴 **本仓的种子菜单目前没有 `f_en_code`**(`seed.rs` 的 `BuiltinMenu` 结构体里没这个字段, +`base_module` 的 INSERT 是 12 个参数、不含它)⇒ **迁官方前必须补** `f_en_code`, +否则官方侧权限判据全是空(官方 `PermissionConst.java:8-77` 定义了对象码与 `btn_*` 码两套)。 + +### 2.5 码表补齐 + +| 码 | 含义 | 本仓 | 官方 | 动作 | +|---|---|---|---|---| +| 200 | 成功 | ✅ | ✅ | — | +| 400 | 业务失败 | ✅ | ✅ | — | +| 401 | 校验失败 | ❌ | ✅ | 迁官方时用上 | +| 403 | 无权限 | ✅ | ✅ | — | +| 500 | 异常 | ❌ | ✅ | 迁官方时用上 | +| 600 | 会话过期 | ✅ | ✅ | — | +| 601 | 会话离线 | ❌ | ✅ | — | +| **602** | 会话错误 | ❌ | ✅ | 🔴 **官方前端 `request.ts:78-80` 只在 601/602 清 token** ⇒ 只返 600 会让页面挂住 | + +⇒ 面 B 落地时,**面 B 的路由无 token 时返 602**,面 A 保持 600。 + +--- + +## 3. 前端:三条路 + +| 方案 | 做法 | 代价 | +|---|---|---| +| **A. 保留 React 前端** | 后端换 Java 后**契约不变 ⇒ 零改** | 官方那套 Vue 组件库用不上 | +| **B. 换 jweb (Vue)** | 官方前端工程 `apps/jnpf-web-apps-main/`,按 `api//.ts` 封装 | 页面要重写(但 UX 可搬) | +| **C. 双前端并存** | React 走面 A、jweb 走面 B,**同一后端进程** | 需要两套构建;本仓「面 A/面 B」设计就是为它准备的 | + +🔴 **接官方 jweb 时前端必须补三个头**(`App-Code` / `Jnpf-Origin: pc` / `Vue-Version: 3`, +官方 `jnpf-web-apps-main/src/api/request.ts:109-112`)。 +其中 **`Vue-Version: 3` 才是面 A/面 B 的判别依据**——本仓 React 前端**也发** `App-Code` 与 +`Jnpf-Origin: pc`(`src/frontend/src/api/request.ts:35-36`,与官方同款),**只有 `Vue-Version` 不发** ⇒ 零歧义。 + +**菜单挂载**:jweb 由菜单自动生成路由(`base_module.f_url_address` ↔ Route path 一一对应), +不要再手写 `router.beforeEach`。 + +--- + +## 4. 官方 JNPF → 本仓 Rust(反向) + +这条路**本仓已经铺好轨**,官方前端可以**直接跑在本仓上**: + +1. 官方前端照常发 `Vue-Version: 3` ⇒ 本仓判为**面 B** ⇒ 返回官方形状。 +2. 本仓**面 B 已实现的部分**(`JNPF_COMPAT_SURFACE.md` §7 的 S1–S6): + 官方登录(零改)、`CurrentUser` 的 `PcUserVO`、分页 `PageListVO`、 + `602` 码、菜单 `ModuleBySystem` + `f_en_code` 判据、授权 `Values` 读取。 +3. **本仓不实现**(如实记录在 `JNPF_COMPAT_SURFACE.md` §8):按钮级权限(`btn_*`)、 + 数据权限方案、导入导出、完整权限树模型。 + +⇒ 官方前端的**登录 + 菜单 + 用户/角色/组织/菜单列表**能在本仓上跑; +**授权弹窗的树**、**数据权限页**、**导入导出**跑不了(这些页面会报错,但不影响其它页)。 + +**验收**:`bash scripts/perm-smoke-jnpf.sh` ⇒ 打印 **「面 B 覆盖 N/18」**,N 就是官方前端能跑通的面。 + +--- + +## 5. react 版 NestJS → 本仓 Rust + +**同一套契约 ⇒ 前端零改**。两边可以**开同一个库**(业务表名故意对齐:`demo_item` / `shop_product` / `book_shop_book`)。 + +| 能力 | react 版(NestJS) | 本仓(Rust) | +|---|---|---| +| 端口 | 后端 `:30000` | 后端 `:30010`(🔴 `tdc-rs` 占了 `:30000`) | +| 数据库 | 嵌入式 PGlite(WASM) | `pglite-rs`(**进程内原生 PG**) | +| 冒烟尺子 | `scripts/perm-smoke.sh`(22 条基线) | `scripts/perm-smoke.sh`(**32 条**)+ `perm-smoke-jnpf.sh`(18 条) | + +⚠️ 两版**不要**把数据目录指到同一处(pglite 单实例独占目录 ⇒ 第二个进程起不来)。 +⚠️ 两版的 `base_*` 种子**可以**并存于同一库(表名/列名逐字同形), +但 **`f_account` 官方无 UNIQUE** ⇒ 建了同名账号会**建两份**。 + +--- + +## 6. 数据 ETL(诚实版) + +### 6.1 `base_*` 7 张:表结构**逐字同形** ⇒ 只导数据 + +官方 `base_*` 表由 **JNPF 平台自动创建** ⇒ **不要用本仓 DDL 覆盖官方表结构**,只导数据。 + +🔴 **本仓的 pglite 是「进程内单用户 Postgres」,没有 TCP 端口** +⇒ `pg_dump` / `psql` **连不上** ⇒ 常规 `--data-only` 那条路**在本仓这侧走不通**。 +可行做法有两条: + +**(a) 给本仓加一个 `--dump` 子命令(推荐)** + +在 `main.rs` 的 `parse_args`(现只有 `--enc`)旁加一个 `Cmd::Dump`, +用 `db.rs` 里现成的执行入口跑: + +```sql +COPY (SELECT * FROM base_user) TO STDOUT WITH CSV HEADER; +COPY (SELECT * FROM base_module) TO STDOUT WITH CSV HEADER; +-- …其余 5 张 +``` + +把 CSV 交给官方侧 `COPY base_user FROM STDIN WITH CSV HEADER` 导入。 +(`db.rs` 已有「持 `db_lock` 跑 SQL」的能力,dump 只是同一套机制多跑几条 SQL。) + +**(b) 直接在官方库侧手写 `INSERT`** + +本仓种子数据量极小(内置 2 角色 + 8 菜单 + 1 管理员 + 若干授权)⇒ +用 `docs/contract.md` 的字段清单手写 `INSERT` 往往比导数据更快。 +**业务数据**(`demo_item` / `shop_product` / `book_shop_book`)同理。 + +### 6.2 业务表 3 张:官方**没有对应表** ⇒ 要先建实体 + +`demo_item` / `shop_product` / `book_shop_book` 是**本仓/两版垫片自定义**的(表名只为「两版后端能开同一个库」而对齐)。 +迁官方时它们**不是契约** ⇒ 两种做法: + +- **保留表名**:在 JNPF 里建三个实体,表名照填 ⇒ 迁回本仓时零改; +- **改成官方低代码实体名**(推荐,符合官方工程习惯)⇒ 迁回本仓时改 `entities.rs` 的 `table` 字段即可。 + +### 6.3 官方 DDL 的两个"故意不修正"的陷阱(迁的时候别顺手改) + +| 陷阱 | 事实 | 后果 | +|---|---|---| +| `base_role_relation` | 用户 id 在 **`f_object_id`**(配 `f_object_type='user'`),**没有 `f_user_id`** | 写错列 ⇒ 角色授权永不生效 | +| `base_user_relation` | 组织/岗位关系在**另一张表**,那里**才有 `f_user_id`** | 写错表 ⇒ 组织/岗位授权永不生效 | + +另:`base_module.f_type` 是 **INTEGER**(1 目录 / 2 页面),`f_category` 是 **VARCHAR**。 + +--- + +## 7. 口令换算(迁官方时**必做**,否则全员登不上) + +### 7.1 两个公式 + +| | 公式 | 出处 | +|---|---|---| +| **本仓 / react 版** | 存 `md5(明文)` 的小写 hex | 本仓 `cipher.rs` / `UserServiceImpl` 简化版 | +| **官方** | 存 `md5( lower(md5(明文)) + lower(secretkey) )`,`secretkey` = 每用户随机 UUID | `UserServiceImpl.java:547-549`、`:704-706` | + +官方登录时:`decrypt(密文)` 得 `md5(明文)` ⇒ 取 `lower()` ⇒ 拼 `lower(secretkey)` ⇒ `md5` ⇒ 与库值比。 + +### 7.2 🔴 关键洞察:**不需要明文** + +本仓库里的值 = `md5(明文)` 的小写 hex = 官方公式的**第一个加数**(`lower(md5(明文))`)。 + +⇒ 换算公式(**一次 SQL 就能做完**): + +```sql +-- 对每一行:先给一个随机 secretkey,再把口令重算成官方格式 +UPDATE base_user +SET f_secretkey = <新随机 UUID>, + f_password = md5(lower(f_password) || lower(<新随机 UUID>)); +``` + +- `f_password` 列**已存在**(本仓 `db/schema.sql:142`;官方 DDL `:4503`)⇒ DDL 不用改。 +- 换算**幂等性要注意**:公式只适用于「`f_password` 还是裸 `md5(明文)`」的库。 + **重复执行会把公式套在公式上 ⇒ 不可逆地错**。⇒ 换算前**先备份**(`backup_create` / `pg_dump`)。 + +### 7.3 换算自证 + +```bash +# 1. 换算前:取一行,记住 account 与 f_password +# 2. 换算后:用**同一个明文**走一遍官方登录链路 +# 本仓的等价物:md5(明文) → AES 密文 → POST /api/oauth/Login +# 3. 官方侧登录成功 ⇒ 换算正确 +``` + +⚠️ 本仓的登录**只比 `md5(明文)`** ⇒ 换算成官方格式后**本仓就登不上了**(预期)。 +⇒ 换算是**单向操作**:迁到官方前做一次,且**先备份**。 + +--- + +## 8. 验证 + +**迁移前**(本仓基线必须全绿): + +```bash +bash scripts/perm-smoke.sh # 面 A:32 条 —— 「没把原契约改坏」 +bash scripts/perm-smoke-jnpf.sh # 面 B:18 条 —— 「官方形状达标」(打印「面 B 覆盖 N/18」) +bash scripts/check-module.sh # 业务模块 9 接触点静态自检 +``` + +**迁移后**(官方库上): + +```bash +# 面 A 尺子打官方后端:路径不同 ⇒ 只能打面 B 尺子 +B=http://<官方后端> bash scripts/perm-smoke-jnpf.sh +``` + +🔴 **两把尺子必须同时绿**:面 A 绿证明「没把原契约改坏」,面 B 绿证明「官方形状达标」。 + +--- + +## 9. 明确不做 + +- **低代码引擎**(表单/流程/代码生成)—— 官方能力,本仓不碰。 +- **多租户**(`jnpf-tenant*`)—— 单租户固定 `f_tenant_id='0'`。 +- **按钮/列/表单/数据范围级授权** —— 官方 DDL 里都有,v1 只做 `item_type='module'`(菜单)。 +- **Redis / Sa-Token** —— 内存 token 表即可。 +- **分页(面 A)** —— 面 A 的 `List` 就是**全量**(前端不分页);分页是面 B 的事。 + +--- + +## 10. 变更记录 + +| 日期 | 变更 | +|---|---| +| 2026-10-26 | 首版:三方双向迁移地图、Rust→Java 逐件翻译、import 速查、端点路径差异表、权限判据差异、码表补齐表、三条前端路线、数据 ETL(pglite 无 TCP 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 | diff --git a/docs/known-limitations.md b/docs/known-limitations.md index 8e0d412..2acfcc1 100644 --- a/docs/known-limitations.md +++ b/docs/known-limitations.md @@ -72,3 +72,30 @@ | (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 只有规格、没有实现** —— 官方形状的端点 / 响应 / 码表全部只写在 `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 尺子**必带**该头。 diff --git a/scripts/check-module.sh b/scripts/check-module.sh index d466d07..bfa677f 100755 --- a/scripts/check-module.sh +++ b/scripts/check-module.sh @@ -341,6 +341,27 @@ for i in $(seq 0 $((T_COUNT - 1))); do fi done +# -------- 全局红线(与具体模块无关,但一样会让闸门失真)-------- +# +# 🔴 **面 A / 面 B 的判别头是 `Vue-Version: 3`**(见 docs/JNPF_COMPAT_SURFACE.md §2.2): +# 官方 JNPF 前端**必带** `Jnpf-Origin: pc` / `App-Code` / `Vue-Version: 3` 三个头, +# 而本仓前端**只带前两个**(`App-Code: sswflow` + `Jnpf-Origin: pc`,与官方同款) +# ⇒ 三个头里**只有 `Vue-Version` 是本仓前端唯一不发的** ⇒ 判别只能用它。 +# 本仓前端一旦开始发 `Vue-Version` ⇒ 面 A 的请求会被误判成面 B ⇒ 契约整体错位。 +hdr "[全局] 面 A/面 B 判别头:前端**禁发** Vue-Version" +if grep -q "Vue-Version" "$FE/src/api/request.ts" 2>/dev/null; then + no "前端 request.ts 发了 Vue-Version 头 ⇒ 面 A 请求会被误判成面 B" +else + ok "前端 request.ts 未发 Vue-Version(面 A/面 B 判别成立)" +fi + +hdr "[全局] 面 B 尺子必须带判别头 Vue-Version: 3" +if grep -q "Vue-Version: 3" "$ROOT/scripts/perm-smoke-jnpf.sh" 2>/dev/null; then + ok "perm-smoke-jnpf.sh 带了 Vue-Version: 3" +else + no "perm-smoke-jnpf.sh 缺 Vue-Version: 3 ⇒ 面 B 请求不会被识别成面 B" +fi + # -------- 总结 -------- echo echo "── 总结 ──" diff --git a/scripts/perm-smoke-jnpf.sh b/scripts/perm-smoke-jnpf.sh new file mode 100644 index 0000000..391d8d1 --- /dev/null +++ b/scripts/perm-smoke-jnpf.sh @@ -0,0 +1,573 @@ +#!/usr/bin/env bash +# tds-lite-rs —— 【面 B:官方 JNPF 契约面】冒烟脚本(18 条断言) +# +# 这是**第二把尺子**。第一把是 scripts/perm-smoke.sh(32 条,测面 A = ssw 契约)。 +# 本脚本测**官方形状**:同一个后端进程,按官方请求头 + 官方路径 + 官方响应形状断言。 +# +# 用法: +# bash scripts/perm-smoke-jnpf.sh +# B=http://127.0.0.1:30010 bash scripts/perm-smoke-jnpf.sh +# ENC_BIN=/path/to/tds-lite-rs bash scripts/perm-smoke-jnpf.sh +# JQ_BIN="" bash scripts/perm-smoke-jnpf.sh # 强制走 python3 兜底路径(两条路径判据一致) +# +# 前置:后端已启动,且处于**初始种子状态**(admin / 123456)。 +# 退出码:0 = 全绿(面 B 覆盖 18/18) / 1 = 有 FAIL 或有 SKIP(未全覆盖) / 2 = 前置错误 +# +# 🔴 **面 B 的判别规则**(见 docs/JNPF_COMPAT_SURFACE.md §2.2): +# 请求头带 `Vue-Version: 3` ⇒ 走官方形状;否则走面 A。 +# 官方前端**必然**带这三个头(jnpf-web-apps-main/src/api/request.ts:109-112), +# 但本仓 React 前端**也发** `App-Code` 与 `Jnpf-Origin: pc`(同款), +# **只有 `Vue-Version` 不发** ⇒ 判别只能用它 ⇒ 零歧义、零配置。 +# +# 🔴 **本脚本不假装全过**:面 B 尚未落地的能力记 **SKIP**(计入"未覆盖",不算 PASS)。 +# 结尾打印 **面 B 覆盖 N/M**(M = 18)。 +# 判定规则:**整组未落地**(路由 404 / 共享路由仍是面 A 形状)⇒ 该组逐条记 SKIP; +# **整组已落地但细节不对** ⇒ 该组逐条 FAIL。 +# +# 🔴 不依赖 node:cipher 用后端 `--enc` 自证;JSON 取值用 jq(无则 python3 兜底)。 +# 🔴 所有 curl 都带 `--noproxy '*'`(本机 curl 走系统代理,不加会打不通 loopback)与 `--max-time 10`。 +# 🔴 所有含中文的变量引用一律写 `${VAR}`(变量名后紧跟中文时,bash 会把中文并进变量名 ⇒ set -u 下 unbound variable)。 + +set -u + +if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then + sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//' + exit 0 +fi + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +B="${B:-http://127.0.0.1:30010}" +ENC_BIN="${ENC_BIN:-$ROOT/target/release/tds-lite-rs}" + +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +# 🔴 JQ_BIN / PY_BIN **允许从环境覆盖**(与面 A 尺子同形): +# 用 `${VAR-default}`(只在未设置时取默认)⇒ `JQ_BIN="" bash …` 能强制走 python3 路径。 +JQ_BIN="${JQ_BIN-$(command -v jq 2>/dev/null || true)}" +PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" + +pre_fail() { + echo "❌ 前置错误:${1}" + exit 2 +} + +# ---- 前置 1:JSON 取值工具(jq 优先,python3 兜底;两个都没有 ⇒ 退 2)---- +if [ -z "$JQ_BIN" ] && [ -z "$PY_BIN" ]; then + pre_fail "jq 与 python3 都没装,无法解析 JSON。" +fi + +# ---- 前置 2:cipher 自证二进制(--enc 必须在,脚本不依赖 node)---- +if [ ! -x "$ENC_BIN" ]; then + pre_fail "找不到可执行的 ${ENC_BIN}(先 cargo build --release,或用 ENC_BIN= 指定)。" +fi +ENC_PROBE="$("$ENC_BIN" --enc '123456' 2>/dev/null || true)" +if [ -z "$ENC_PROBE" ]; then + pre_fail "${ENC_BIN} --enc 自证失败(无输出)。" +fi +if ! printf '%s' "$ENC_PROBE" | grep -Eq '^[0-9a-fA-F]+$'; then + pre_fail "${ENC_BIN} --enc 输出不是 hex。" +fi + +# ---- python3 兜底的取值小工具(jq 在时不用它)---- +# 🔴 本文件每个 mode 的 **jq 表达式与 python 实现必须给出同一个判据**, +# 否则 `JQ_BIN=""` 会跑出与 jq 路径不同的结论。改一处必须改两处。 +PY_HELPER="$TMP/jget.py" +cat >"$PY_HELPER" <<'PYEOF' +import json +import sys + +CUR_KEYS5 = ["menuList", "permissionList", "userInfo", "currentSystemId", "sysConfigInfo"] +CUR_KEYS2 = ["userInfo", "menuList"] +PL_KEYS = ["pagination", "list"] +PAG_KEYS = ["currentPage", "pageSize", "total"] +MENU_KEYS = [ + "id", "fullName", "enCode", "parentId", "icon", "hasChildren", + "urlAddress", "pageAddress", "linkTarget", "children", "type", + "propertyJson", "sortCode", "systemId", "isData", +] + + +def out(v): + if v is None: + print("null") + elif v is True: + print("true") + elif v is False: + print("false") + elif isinstance(v, str): + print(v) + else: + print(json.dumps(v, ensure_ascii=False)) + + +def d_obj(d): + v = d.get("data") + return v if isinstance(v, dict) else {} + + +def d_list(d): + v = d_obj(d).get("list") + return v if isinstance(v, list) else None + + +def jtype(v): + if v is None: + return "null" + if isinstance(v, bool): + return "boolean" + if isinstance(v, (int, float)): + return "number" + if isinstance(v, str): + return "string" + if isinstance(v, list): + return "array" + if isinstance(v, dict): + return "object" + return "other" + + +def count_present(container, keys): + if not isinstance(container, dict): + return 0 + return sum(1 for k in keys if k in container) + + +def adm_type(d): + items = d_list(d) + if items is None or not items or not isinstance(items[0], dict): + return "missing" + if "isAdministrator" not in items[0]: + return "missing" + v = items[0]["isAdministrator"] + if v is None: + return "null" + if isinstance(v, bool): + return "boolean" + if isinstance(v, (int, float)): + return "number" + return "string" + + +def secret_leak(d): + items = d_list(d) or [] + n = 0 + for it in items: + if not isinstance(it, dict): + continue + for k in ("password", "secretkey", "f_password", "f_secretkey"): + if k in it: + n += 1 + break + return n + + +def menu_keys_ok(d): + ml = d_obj(d).get("menuList") + if not isinstance(ml, list) or not ml or not isinstance(ml[0], dict): + return "missing" + miss = [k for k in MENU_KEYS if k not in ml[0]] + if not miss: + return "ok" + return "missing:" + ",".join(miss) + + +def perm_list_type(d): + obj = d_obj(d) + if "permissionList" not in obj: + return "missing" + return jtype(obj.get("permissionList")) + + +def str_array(d): + v = d.get("data") + if not isinstance(v, list): + return "" + return ",".join(str(x) for x in v if isinstance(x, str)) + + +def main(): + mode = sys.argv[1] + raw = sys.stdin.read() + try: + d = json.loads(raw) + except Exception: + print("ERR") + return + if not isinstance(d, dict): + print("ERR") + return + try: + if mode == "code": + out(d.get("code")) + elif mode == "msg": + out(d.get("msg")) + elif mode == "token": + v = d_obj(d).get("token") + print("" if v is None else v) + elif mode == "dkeys5": + out(count_present(d_obj(d), CUR_KEYS5)) + elif mode == "dkeys2": + out(count_present(d_obj(d), CUR_KEYS2)) + elif mode == "dkeys_pl": + out(count_present(d_obj(d), PL_KEYS)) + elif mode == "pkeys3": + out(count_present(d_obj(d).get("pagination"), PAG_KEYS)) + elif mode == "listlen": + items = d_list(d) + out(0 if items is None else len(items)) + elif mode == "total_ge_list": + p = d_obj(d).get("pagination") + total = p.get("total") if isinstance(p, dict) else None + items = d_list(d) + n = 0 if items is None else len(items) + if not isinstance(total, (int, float)) or isinstance(total, bool): + print("no") + else: + print("yes" if total >= n else "no") + elif mode == "admtype": + print(adm_type(d)) + elif mode == "secretleak": + out(secret_leak(d)) + elif mode == "menutkeys": + print(menu_keys_ok(d)) + elif mode == "permlisttype": + print(perm_list_type(d)) + elif mode == "datatype": + print(jtype(d.get("data"))) + elif mode == "listisarray": + items = d_list(d) + print("yes" if isinstance(items, list) else "no") + elif mode == "strarray": + print(str_array(d)) + else: + print("ERR") + except Exception: + print("ERR") + + +main() +PYEOF + +# ---- 取值小工具:json_get <模式> ---- +json_get() { + local mode="${1}" body="${2}" expr="" + case "$mode" in + code) expr='.code' ;; + msg) expr='.msg' ;; + token) expr='(.data // {}) | .token // ""' ;; + dkeys5) expr='(.data // {}) as $d | ["menuList","permissionList","userInfo","currentSystemId","sysConfigInfo"] | map(. as $k | select($d|has($k))) | length' ;; + dkeys2) expr='(.data // {}) as $d | ["userInfo","menuList"] | map(. as $k | select($d|has($k))) | length' ;; + dkeys_pl) expr='(.data // {}) as $d | ["pagination","list"] | map(. as $k | select($d|has($k))) | length' ;; + pkeys3) expr='(.data.pagination // {}) as $p | ["currentPage","pageSize","total"] | map(. as $k | select($p|has($k))) | length' ;; + listlen) expr='(.data.list // []) | length' ;; + total_ge_list) expr='(.data.pagination.total // 0) as $t | (.data.list // []) as $l | (($t|type)=="number" and $t >= ($l|length)) | if . then "yes" else "no" end' ;; + admtype) expr='(.data.list // []) as $l | (if ($l|length)>0 and ($l[0]|type)=="object" then $l[0] else null end) as $it | if $it == null then "missing" elif ($it|has("isAdministrator")|not) then "missing" else ($it.isAdministrator | if . == null then "null" else type end) end' ;; + secretleak) expr='[(.data.list // [])[] | select(type=="object") | select(has("password") or has("secretkey") or has("f_password") or has("f_secretkey"))] | length' ;; + menutkeys) expr='(.data.menuList // []) as $m | (if ($m|length)>0 and ($m[0]|type)=="object" then $m[0] else null end) as $it | if $it == null then "missing" else (["id","fullName","enCode","parentId","icon","hasChildren","urlAddress","pageAddress","linkTarget","children","type","propertyJson","sortCode","systemId","isData"] as $need | ($need - ($it|keys)) as $miss | if ($miss|length)==0 then "ok" else "missing:"+($miss|join(",")) end) end' ;; + permlisttype) expr='(.data // {}) as $d | if ($d|has("permissionList")) then ($d.permissionList|type) else "missing" end' ;; + datatype) expr='.data | type' ;; + listisarray) expr='(.data.list // null) | if . == null then "no" else (type == "array" | if . then "yes" else "no" end) end' ;; + strarray) expr='(.data // []) as $d | if ($d|type)=="array" then ($d|map(select(type=="string"))|join(",")) else "" end' ;; + *) echo "ERR"; return 0 ;; + esac + if [ -n "$JQ_BIN" ]; then + printf '%s' "$body" | "$JQ_BIN" -r "$expr" 2>/dev/null || echo 'ERR' + else + printf '%s' "$body" | "$PY_BIN" "$PY_HELPER" "$mode" 2>/dev/null || echo 'ERR' + fi +} + +PASS=0 +FAIL=0 +SKIP=0 + +ok() { + echo " ✅ ${1}" + PASS=$((PASS + 1)) +} + +bad() { + echo " ❌ ${1}" + FAIL=$((FAIL + 1)) +} + +skipped() { + echo " ⏭ ${1} —— 面 B 未落地(不计入 PASS)" + SKIP=$((SKIP + 1)) +} + +# assert1 <说明> <0|1 判定结果> <细节> +assert1() { + local desc="${1}" good="${2}" detail="${3}" + if [ "$good" -eq 1 ]; then + ok "${desc}(${detail})" + else + bad "${desc} 实际=${detail}" + fi +} + +# check <期望> <实际> <说明>(支持 ">=N" 数值比较) +check() { + local exp="${1}" act="${2}" desc="${3}" good=0 + case "$exp" in + '>='*) + local num="${exp#>=}" + if printf '%s' "$act" | grep -Eq '^[0-9]+$' && [ "$act" -ge "$num" ]; then + good=1 + fi + ;; + *) + if [ "$exp" = "$act" ]; then + good=1 + fi + ;; + esac + if [ "$good" -eq 1 ]; then + ok "${desc}(实际=${act})" + else + bad "${desc} 期望=${exp} 实际=${act}" + fi +} + +# skip_group "<描述1>|<描述2>|…" —— 整组未落地 ⇒ 逐条记 SKIP +skip_group() { + local descs="${1}" d + local IFS='|' + for d in ${descs}; do + skipped "${d}" + done +} + +# 端点是否"未落地":HTTP 404 或 body code=404(本仓的未知路由兜底) +route_missing() { + local http="${1}" body="${2}" + if [ "$http" = "404" ]; then + return 0 + fi + local c + c="$(json_get code "$body")" + if [ "$c" = "404" ]; then + return 0 + fi + return 1 +} + +# 官方形状的请求头(官方前端必带的三个头;**判面 B 的依据是 `Vue-Version: 3`**) +HDR_B=(-H 'Jnpf-Origin: pc' -H 'Vue-Version: 3' -H 'App-Code: tds-lite-rs') + +# cipher 自证:enc <明文> ⇒ hex 密文 +enc() { + "$ENC_BIN" --enc "${1}" +} + +# 登录一次,输出 body 到 stdout +login() { + curl --noproxy '*' -s --max-time 10 -X POST "$B/api/oauth/Login" \ + "$@" \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + --data-urlencode "account=admin" \ + --data-urlencode "password=$(enc '123456')" \ + --data-urlencode "grant_type=password" +} + +echo "== tds-lite-rs 面 B(官方 JNPF 契约面)冒烟(目标 ${B})==" + +# ---- 前置 3:后端可达且确实是本仓后端(不通 ⇒ 退 2,不是逐条假失败)---- +# 判据:无 token 打 /api/oauth/CurrentUser ⇒ 本仓恒返回 {code:600}。 +PROBE_BODY="$(curl --noproxy '*' -s --max-time 10 "$B/api/oauth/CurrentUser" 2>/dev/null || true)" +PROBE_CODE="$(json_get code "$PROBE_BODY")" +if [ "$PROBE_CODE" != "600" ]; then + pre_fail "后端不可达或不是 tds-lite-rs(${B} 返回 code=${PROBE_CODE:-无},期望 600=未登录)。先起服务,或用 B= 指定目标后重试。" +fi + +# ===================================================================== +# G0 · 面 A 未被面 B 破坏(断言 1–2)—— 恒可跑 +# ===================================================================== + +A_LOGIN="$(login)" +A_TOKEN="$(json_get token "$A_LOGIN")" +A_AUTH="Authorization: bearer ${A_TOKEN}" +A_CU="$(curl --noproxy '*' -s --max-time 10 "$B/api/oauth/CurrentUser" -H "$A_AUTH")" +A_K2="$(json_get dkeys2 "$A_CU")" +A_PERM="$(json_get permlisttype "$A_CU")" +if [ "$A_K2" = "2" ] && [ "$A_PERM" = "missing" ]; then + assert1 "断言 1 · 面 A CurrentUser 仍是 2 字段形状(userInfo + menuList,无 permissionList)" 1 "keys=${A_K2}, permissionList=${A_PERM}" +else + assert1 "断言 1 · 面 A CurrentUser 仍是 2 字段形状(userInfo + menuList,无 permissionList)" 0 "keys=${A_K2}, permissionList=${A_PERM}" +fi + +A_CODE="$(json_get code "$A_LOGIN")" +if [ "$A_CODE" = "200" ] && [ -n "$A_TOKEN" ]; then + assert1 "断言 2 · 面 A 登录(无 Vue-Version 头)仍通" 1 "code=${A_CODE}, token 长度=${#A_TOKEN}" +else + assert1 "断言 2 · 面 A 登录(无 Vue-Version 头)仍通" 0 "code=${A_CODE}, token 长度=${#A_TOKEN}" +fi + +# ===================================================================== +# G1 · 面 B 登录(断言 3)—— 共用路由,恒可跑 +# ===================================================================== + +B_LOGIN="$(login "${HDR_B[@]}")" +B_TOKEN="$(json_get token "$B_LOGIN")" +B_AUTH="Authorization: bearer ${B_TOKEN}" +B_CODE="$(json_get code "$B_LOGIN")" +if [ "$B_CODE" = "200" ] && [ -n "$B_TOKEN" ]; then + assert1 "断言 3 · 面 B 登录(带 Vue-Version: 3)⇒ code=200 且拿到 token" 1 "code=${B_CODE}, token 长度=${#B_TOKEN}" +else + assert1 "断言 3 · 面 B 登录(带 Vue-Version: 3)⇒ code=200 且拿到 token" 0 "code=${B_CODE}, token 长度=${#B_TOKEN}" +fi + +# ===================================================================== +# G2 · 面 B CurrentUser 形状(断言 4–6)—— 共用路由;仍是面 A 形状 ⇒ 整组 SKIP +# ===================================================================== + +B_CU="$(curl --noproxy '*' -s --max-time 10 "$B/api/oauth/CurrentUser" "${HDR_B[@]}" -H "$B_AUTH")" +B_K5="$(json_get dkeys5 "$B_CU")" +if [ "$B_K5" != "5" ]; then + skip_group "断言 4 · 面 B CurrentUser 顶层 5 字段齐全|断言 5 · 面 B menuList 节点是 AllMenuSelectVO 形状|断言 6 · 面 B permissionList 是数组(不能 null)" +else + assert1 "断言 4 · 面 B CurrentUser 顶层 5 字段齐全" 1 "命中 5/5" + MK="$(json_get menutkeys "$B_CU")" + if [ "$MK" = "ok" ]; then + assert1 "断言 5 · 面 B menuList 节点是 AllMenuSelectVO 形状(15 字段)" 1 "15/15 齐全" + else + assert1 "断言 5 · 面 B menuList 节点是 AllMenuSelectVO 形状(15 字段)" 0 "${MK}" + fi + PL="$(json_get permlisttype "$B_CU")" + if [ "$PL" = "array" ]; then + assert1 "断言 6 · 面 B permissionList 是数组(不能是 null)" 1 "type=array" + else + assert1 "断言 6 · 面 B permissionList 是数组(不能是 null)" 0 "type=${PL}" + fi +fi + +# ===================================================================== +# G3 · 面 B 鉴权码 602 + 未知路由 404(断言 7–8) +# ===================================================================== + +UNAUTH_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/unauth.json" -w '%{http_code}' \ + "$B/api/permission/Users" "${HDR_B[@]}")" +UNAUTH_BODY="$(cat "$TMP/unauth.json" 2>/dev/null || true)" +if route_missing "$UNAUTH_HTTP" "$UNAUTH_BODY"; then + skipped "断言 7 · 面 B 无 token ⇒ 返 602(token 失效),不是 600/401" +else + check 602 "$(json_get code "$UNAUTH_BODY")" "断言 7 · 面 B 无 token ⇒ 返 602(token 失效),不是 600/401" +fi + +check 404 "$(curl --noproxy '*' -s --max-time 10 -o /dev/null -w '%{http_code}' \ + "$B/api/permission/NotExistJnpfRoute" "${HDR_B[@]}")" \ + "断言 8 · 面 B 未知路由 HTTP 404 不被吞掉" + +# ===================================================================== +# G4 · 面 B 用户列表 = PageListVO(断言 9–13) +# ===================================================================== + +U_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/ulist.json" -w '%{http_code}' \ + "$B/api/permission/Users?pageSize=20¤tPage=1" "${HDR_B[@]}" -H "$B_AUTH")" +U_BODY="$(cat "$TMP/ulist.json" 2>/dev/null || true)" +if route_missing "$U_HTTP" "$U_BODY"; then + skip_group "断言 9 · 面 B 用户列表 data 是 PageListVO(含 pagination + list)|断言 10 · 面 B pagination 三字段齐全|断言 11 · 面 B pagination.total 是总条数|断言 12 · 面 B 列表项不含 password/secretkey|断言 13 · 面 B 列表项 isAdministrator 是数字(0/1,不是布尔)" +else + check 2 "$(json_get dkeys_pl "$U_BODY")" "断言 9 · 面 B 用户列表 data 是 PageListVO(含 pagination + list)" + check 3 "$(json_get pkeys3 "$U_BODY")" "断言 10 · 面 B pagination 三字段齐全(currentPage/pageSize/total)" + check "yes" "$(json_get total_ge_list "$U_BODY")" "断言 11 · 面 B pagination.total 是总条数(≥ list 长度)" + check 0 "$(json_get secretleak "$U_BODY")" "断言 12 · 面 B 列表项不含 password/secretkey" + check "number" "$(json_get admtype "$U_BODY")" "断言 13 · 面 B 列表项 isAdministrator 是数字(0/1,不是布尔)" +fi + +# ===================================================================== +# G5 · 面 B 角色列表 = PageListVO(断言 14) +# ===================================================================== + +R_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/rlist.json" -w '%{http_code}' \ + "$B/api/permission/Role?pageSize=20¤tPage=1" "${HDR_B[@]}" -H "$B_AUTH")" +R_BODY="$(cat "$TMP/rlist.json" 2>/dev/null || true)" +if route_missing "$R_HTTP" "$R_BODY"; then + skipped "断言 14 · 面 B 角色列表 data 是 PageListVO" +else + check 2 "$(json_get dkeys_pl "$R_BODY")" "断言 14 · 面 B 角色列表 data 是 PageListVO" +fi + +# ===================================================================== +# G6 · 面 B 组织列表支持 AsyncList/{id}(断言 15) +# ===================================================================== + +O_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/olist.json" -w '%{http_code}' \ + "$B/api/permission/Organize/AsyncList/0" "${HDR_B[@]}" -H "$B_AUTH")" +O_BODY="$(cat "$TMP/olist.json" 2>/dev/null || true)" +if route_missing "$O_HTTP" "$O_BODY"; then + skipped "断言 15 · 面 B 组织列表支持 AsyncList/{id}(根节点 id=0 取一级组织)" +else + check 2 "$(json_get dkeys_pl "$O_BODY")" "断言 15 · 面 B 组织列表支持 AsyncList/{id}(根节点 id=0 取一级组织)" +fi + +# ===================================================================== +# G7 · 面 B 菜单 ModuleBySystem(断言 16) +# 官方返回 ActionResult> ⇒ data = {list:[...]}(**不是裸数组**) +# ===================================================================== + +M_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/mlist.json" -w '%{http_code}' \ + "$B/api/system/Menu/ModuleBySystem" "${HDR_B[@]}" -H "$B_AUTH")" +M_BODY="$(cat "$TMP/mlist.json" 2>/dev/null || true)" +if route_missing "$M_HTTP" "$M_BODY"; then + skipped "断言 16 · 面 B 菜单 ModuleBySystem 可达且 data.list 是数组" +else + M_CODE="$(json_get code "$M_BODY")" + M_LA="$(json_get listisarray "$M_BODY")" + if [ "$M_CODE" = "200" ] && [ "$M_LA" = "yes" ]; then + assert1 "断言 16 · 面 B 菜单 ModuleBySystem 可达且 data.list 是数组" 1 "code=200, data.list=array" + else + assert1 "断言 16 · 面 B 菜单 ModuleBySystem 可达且 data.list 是数组" 0 "code=${M_CODE}, data.list=${M_LA}" + fi +fi + +# ===================================================================== +# G8 · 授权:官方 body 超集(断言 17)+ 官方读用 POST(断言 18) +# ===================================================================== + +# 🔴 写入用的角色 = role_user,写入内容与面 A 尺子**完全相同**(module=["m_demo"])⇒ 幂等、互不干扰。 +AUTH_WRITE="$(curl --noproxy '*' -s --max-time 10 -X PUT "$B/api/permission/Authority/Data/role_user" \ + "${HDR_B[@]}" -H "$B_AUTH" -H 'Content-Type: application/json' \ + -d '{"objectType":"role","module":["m_demo"],"button":[],"column":[],"resource":[],"form":[],"systemIds":[]}')" +AW_CODE="$(json_get code "$AUTH_WRITE")" +# 回读:走面 A 的只读端点(两把尺子共用一份数据 ⇒ 这才是真回读) +ROLE_MODS="$(curl --noproxy '*' -s --max-time 10 "$B/api/ssw/sys/Role/Modules?roleId=role_user" -H "$A_AUTH")" +ROLE_MOD_IDS="$(json_get strarray "$ROLE_MODS")" +if [ "$AW_CODE" = "200" ] && printf '%s' "$ROLE_MOD_IDS" | tr ',' '\n' | grep -qx 'm_demo'; then + assert1 "断言 17 · 授权写:官方完整 body(含 button/column/resource/form/systemIds)⇒ code=200 且 module 真落库" 1 "code=200, 回读含 m_demo" +else + assert1 "断言 17 · 授权写:官方完整 body(含 button/column/resource/form/systemIds)⇒ code=200 且 module 真落库" 0 "code=${AW_CODE}, 回读=${ROLE_MOD_IDS:-空}" +fi + +# 官方读授权用 **POST**(AuthorizeController.java:100-101),body = DataValuesQuery{type, moduleIds(String), objectType} +AV_HTTP="$(curl --noproxy '*' -s --max-time 10 -o "$TMP/aval.json" -w '%{http_code}' \ + -X POST "$B/api/permission/Authority/Data/role_user/Values" "${HDR_B[@]}" -H "$B_AUTH" \ + -H 'Content-Type: application/json' \ + -d '{"type":"module","moduleIds":"","objectType":"role"}')" +AV_BODY="$(cat "$TMP/aval.json" 2>/dev/null || true)" +if route_missing "$AV_HTTP" "$AV_BODY"; then + skipped "断言 18 · 授权读是 POST(POST .../Data/{id}/Values)⇒ code=200" +else + check 200 "$(json_get code "$AV_BODY")" "断言 18 · 授权读是 POST(POST .../Data/{id}/Values)⇒ code=200" +fi + +# ===================================================================== +# 汇总 +# ===================================================================== + +TOTAL=$((PASS + FAIL + SKIP)) +echo +echo "--------------------" +echo "PASS=${PASS} FAIL=${FAIL} SKIP=${SKIP} / 共 ${TOTAL} 条" +echo "面 B 覆盖 ${PASS}/18" +if [ "$FAIL" -eq 0 ] && [ "$SKIP" -eq 0 ]; then + echo "全绿 ✅(面 B 已达标)" + exit 0 +fi +if [ "$FAIL" -eq 0 ]; then + echo "无失败,但面 B 尚未全覆盖 ⚠️(${SKIP} 条未落地)" + exit 1 +fi +echo "有失败 ❌" +exit 1