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:
adminandClaude Code committed 2026-10-26 10:37:20 +08:00
1 parent ed106a272e
commit 5350fc6400
10 files changed
+2093 -9

No files matched your search

+40
View File
@@ -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`)。
+13 -2
View File
@@ -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
View File
@@ -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`。)
+24 -3
View File
@@ -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`
+408
View File
@@ -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 条已知不对齐项。 |
+637
View File
@@ -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}`。 |
+303
View File
@@ -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 的诚实版)、口令换算公式与幂等性警告、两把尺子的验证清单 |
+27
View File
@@ -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 尺子**必带**该头。
+21
View File
@@ -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 "── 总结 ──"
+573
View File
@@ -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&currentPage=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&currentPage=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