feat(spec): 官方 JNPF 对齐三件套 + 第二把尺子(面 B 规格落地前的地基)
- docs/JNPF_SOURCE_AUDIT.md:官方 Java/Vue 源码逐行核对(标 文件:行号), 差异清单 D1–D8(端点风格 / 列表响应 / CurrentUser 形状 / 码表 / 菜单接口 / 鉴权模型 / 请求头 / 口令存储)。 - docs/JNPF_COMPAT_SURFACE.md:面 B 规格 —— 官方形状的端点 / 响应 / 码表 / 分流规则 / 落地顺序 S1–S6。 - docs/MIGRATION.md:本仓 ↔ 官方逐项映射 + 数据 ETL + 口令 secretkey 换算 (一次性换算即可,不需要明文)。 - scripts/perm-smoke-jnpf.sh:第二把尺子,18 条官方形状断言;未落地记 SKIP 且不计入 PASS(当前 PASS=5 FAIL=0 SKIP=13 ⇒ 覆盖 5/18)。 fix(spec): 面 A/面 B 判别头纠错 —— 改用 `Vue-Version: 3` 规格初稿断言「本仓前端一个官方头都不带」并用 `Jnpf-Origin: pc` 判面, 但本仓前端 request.ts:35-36 **也发** App-Code 与 Jnpf-Origin(与官方同款) ⇒ 按字面实现会把每个面 A 请求都误判成面 B。三个官方头里只有 Vue-Version 是本仓前端唯一不发的 ⇒ 判别只能用它。已在规格(§2.2 / D7 / A13 / §3.7) 统一改正,并在 check-module.sh 的「全局红线」段静态钉住两侧: 本仓前端禁发该头 + 面 B 尺子必带该头。 docs: 导航文档补链 + 已知限制新增 §H CLAUDE.md 红线加第 9 条(判别头)、README.md 目录与「第二把尺子」、 HANDOFF.md §0/§6/§9(已知限制 + 下一步 S1–S6)、known-limitations.md §H (面 B 只有规格没有实现 / 缺 secretkey 一步 / 判据是菜单路径不是点权限 / 码表缺 602)。 验证:cargo test 179 passed / 0 failed;check-module.sh PASS=57 FAIL=0; perm-smoke.sh(面 A)PASS=32 FAIL=0;perm-smoke-jnpf.sh PASS=5 SKIP=13。 Co-Authored-By: Claude Code <[email protected]>
This commit is contained in:
1 parent
ed106a272e
commit
5350fc6400
10 files changed
+2093
-9
No files matched your search
@@ -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`)。
|
||||
@@ -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 依赖)
|
||||
```
|
||||
|
||||
+47
-4
@@ -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`。)
|
||||
@@ -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<String>` 遇畸形百分号编码** ⇒ **实测 axum 0.8.9 接受该转义**:`PUT /api/permission/Authority/Data/%zz`
|
||||
|
||||
@@ -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<PageListVO<UserListVO>>`):
|
||||
|
||||
```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<PageListVO<RoleListVO>>`(`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<PageListVO<OrganizeListVO>>`(`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<ListVO<MenuListVO>>`
|
||||
(`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 <token>` | 鉴权(面 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 条已知不对齐项。 |
|
||||
@@ -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<T>, 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<T> 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<AllMenuSelectVO>` | `:19` |
|
||||
| `permissionList` | `List<PermissionModel>` | `: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>`(`LoginVO.java:17` = `token`) |
|
||||
| POST | `/api/oauth/Logout` | `LoginController.java:155` | `ActionResult<LogoutResultModel>` |
|
||||
| GET | `/api/oauth/CurrentUser` | `LoginController.java:192` | `ActionResult<PcUserVO>` |
|
||||
|
||||
> 📌 官方 `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<PageListVO<UserListVO>>`(`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<PageListVO<RoleListVO>>`(`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<PageListVO<OrganizeListVO>>`(`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}`。 |
|
||||
@@ -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, XxxEntity>` + `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<M, T>` |
|
||||
| 返回信封 | `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/<module>/<entity>.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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 |
|
||||
@@ -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 尺子**必带**该头。
|
||||
@@ -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 "── 总结 ──"
|
||||
|
||||
@@ -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 文本> ----
|
||||
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=<url> 指定目标后重试。"
|
||||
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<ListVO<MenuListVO>> ⇒ 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
|
||||
Reference in new issue
Block a user