Files
ssw-platform/JNPF_SOURCE_AUDIT.md
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

657 lines
35 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 官方 JNPF 源码审计(本技能的「官方面」地基)
> 这份文档回答**一个**问题:**本技能(Rust 模板)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。**
>
> 全部结论来自对官方源码的**逐行核对**,每条带 `文件:行号`。
> 官方源码坐标:`~/Desktop/workspace/jnpf/`(下文所有路径均相对它)。
> 核对日期:**2026-10-26**。官方版本:`jnpf-web-apps-main`(Vue3 前端)+ `jnpf-java-boot`(Java 后端)。
**配套阅读**:
- 契约红线(权威)→ [`SKILL.md`](SKILL.md) §契约红线 + [`PERMISSION.md`](PERMISSION.md)
- 迁移操作(怎么做)→ [`MIGRATION.md`](MIGRATION.md)
- 面 B 规格(要做到什么程度)→ [`JNPF_COMPAT_SURFACE.md`](JNPF_COMPAT_SURFACE.md)
- 实施期裁决 → 参照实现仓的 `docs/decisions.md`(`~/Desktop/workspace/ssw-jnpf-lite-rust/docs/decisions.md`)
> 📌 下文的「本仓」= 本技能的 Rust 模板(`src/backend` + `src/frontend`)。
> 模板与参照实现仓 `~/Desktop/workspace/ssw-jnpf-lite-rust/` 的 `src/` **逐字节一致**(只差 `data/` 与 `dist/`)。
---
## 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/platform/envelope.rs` |
| 错误码表 | 同上目录 `ActionResultCode.java` | `src/backend/src/platform/envelope.rs` |
| 登录 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-controller/.../controller/LoginController.java` | `src/backend/src/platform/auth.rs` |
| 口令解密 | `jnpf-java-boot/jnpf-oauth/jnpf-oauth-biz/.../granter/PasswordTokenGranter.java` | `src/backend/src/platform/cipher.rs` |
| 加解密工具 | `jnpf-common/.../jnpf/util/DesUtil.java` | `src/backend/src/platform/cipher.rs` |
| 安全配置 | `jnpf-common/.../jnpf/properties/SecurityProperties.java` | `src/backend/src/platform/cipher.rs` |
| 用户/角色/组织/授权 | `jnpf-java-boot/jnpf-permission/jnpf-permission-controller/.../controller/*.java` | `src/backend/src/platform/sys.rs` / `permission.rs` |
| 菜单 | `jnpf-java-boot/jnpf-system/jnpf-system-controller/.../controller/ModuleController.java` | `src/backend/src/platform/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/platform/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` 拿不到东西)。
> ✅ **2026-10-26 已处理**:面 B(官方 JNPF 契约面)落地 ⇒ 本仓**两套判据并存**:
> 面 A 仍按菜单路径(`f_url_address`),面 B 按 `f_en_code` 点权限
> (`permission.rs` 的 `has_en_code_permission`,种子已补 8 条 `f_en_code`)。
> 🔴 **按钮级权限(`btn_*`)仍未实现**(面 B `permissionList` 的四个数组恒空)⇒ 见
> `JNPF_COMPAT_SURFACE.md` §8 的 B4。
### 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 个端点 ⇒ 官方全量远大于此表。表中只列**系统管理**这一条线。
🔴 **本表是「散文版」;机器可读的覆盖账本在 [`docs/contract.md`](docs/contract.md) 附录 A 的
`[OFFICIAL]` 区段**(53 行,含每个官方端点的 `status` 与官方出处 `文件:行号`)⇒
由 `scripts/check-contract.sh` 的 **CC10** 与**代码里真实注册的路由双向对账** ⇒
**「官方端点覆盖 N/M」是算出来的,不是人数的**(当前 **8/47**)。
🔴 **两处要一起改**:官方端点表改了 ⇒ `[OFFICIAL]` 对应的行也要改(否则 CC10 判漂移)。
### 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 对齐清单(本仓 → 官方,做什么、做到什么程度)
> ✅ **2026-10-26 更新**:A2 / A8 / A9 / A10 / A11 / A12 的「面 B 要做的事」**已全部落地**
> (`src/backend/src/platform/jnpf.rs`,尺子 `perm-smoke-jnpf.sh` = **18/18**)。
> 下表的「面 B 要做的事」列保留原样作为**历史记录**,**当前状态看这一段 + `JNPF_COMPAT_SURFACE.md` §7/§8**。
| # | 对齐项 | 本仓现状 | 迁官方要做的事 | 面 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/ssw-jnpf-lite-rust --enc 123456
# 期望:d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b
```
---
## 10. 变更记录
| 日期 | 变更 |
|---|---|
| 2026-10-26 | 首版。逐行核对官方源码,确立「9 条已对齐 / 8 条差异 / 3 条换算与补齐」。**更正了一处常见误解**:官方 `PageListVO` 含 `pagination` 字段,不是只有 `{list}`。 |