# 官方 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, 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 list; ``` `PaginationVO.java`:`currentPage`(`:16`) / `pageSize`(`:18`) / `total`(`:20`)。 ⇒ 官方分页响应形状是: ```json { "code":200, "msg":"操作成功", "data": { "pagination": {"currentPage":1,"pageSize":20,"total":42}, "list":[ ... ] } } ``` **本仓**:`data` 直接是**全量数组**(契约 §6 明确「分页不在 v1 范围」)。 分页请求参数(官方 `Pagination.java`):`pageSize=20`(`:19`) / `sort="DESC"`(`:21`) / `sidx=""`(`:23`) / `currentPage=1`(`:25`) / `total`(`:27`) / `records`(`:29`)。 > 🔴 **常见误解**:「官方 `PageListVO` 就是 `{list:[...]}`」—— **错**,它还有 `pagination`。 > 迁官方时若只回 `{list}`,官方前端的分页组件会拿不到 `total` ⇒ 退化成「只显示第一页」。 **本仓无分页** ⇒ 迁到官方后**必须补**(或在官方侧改成不分页组件)。这是**迁 JNPF 时的必做项**,不是可选优化。 ### 3.3 D3 — `CurrentUser` 形状 官方 `PcUserVO.java`: | 字段 | 类型 | 行号 | |---|---|---| | `menuList` | `List` | `:19` | | `permissionList` | `List` | `:22` | | `userInfo` | `UserCommonInfoVO` | `:25` | | `currentSystemId` | `String` | `:27` | | `sysConfigInfo` | `SystemInfo` | `:33` | `AllMenuSelectVO.java`:`id`(`:12`) / `fullName`(`:15`) / `enCode`(`:18`) / `parentId`(`:21`) / `icon`(`:24`) / `hasChildren`(`:27`) / `urlAddress`(`:30`) / `pageAddress`(`:33`) / `linkTarget`(`:36`) / `children`(`:39`) / `type`(`:42`) / `propertyJson`(`:44`) / `sortCode`(`:46`) / `systemId`(`:48`) / `isData`(`:50`)。 `PermissionModel.java`:`modelId`(`:10`) / `moduleName`(`:12`) / `button`(`:14`) / `column`(`:16`) / `resource`(`:18`) / `form`(`:20`)。 `UserCommonInfoVO.java`:`userId`(`:16`) / `userAccount`(`:19`) / `userName`(`:22`) / `headIcon`(`:25`) / `organizeId`(`:28`) / `organizeName`(`:31`) / `positionId`(`:34`) / `positionName`(`:37`) / `isAdministrator`(`:75`) / `systemId`(`:83`) / `systemCode`(`:87`) … **本仓**(`docs/contract.md:435`): ```json { "code":200, "data":{ "userInfo":{ "userId":"…","userAccount":"admin","userName":"admin","isAdministrator":true }, "menuList":[ … ] } } ``` ⇒ 缺 `permissionList` / `currentSystemId` / `sysConfigInfo`;`userInfo` 只有 4 个字段;`menuList` 节点字段是本仓自定义(**非** `AllMenuSelectVO` 形状)。 > 📌 **对齐建议(面 B)**:面 B 的 `CurrentUser` **直接返回官方 `PcUserVO` 形状**(`menuList` 用 `AllMenuSelectVO` 的 15 个字段、`userInfo` 至少补 `isAdministrator`/`organizeId`/`organizeName`/`positionId`/`positionName`/`systemId`/`systemCode`)。 > 面 A 保持不变(§1 的 2 字段形状不能动,那是 ssw 契约)。 ### 3.4 D4 — 码表缺项 本仓**没有** `401`(验证错误)/ `500`(异常)/ `601`(被踢出)/ `602`(token 失效)。 官方前端 `jnpf-web-apps-main/src/api/request.ts` 的响应拦截器**按 `code` 分支**: ``` :70 case ResultEnum.FORBIDDEN → 跳无权限页(:74 authStore.goForbidden()) :78 case ResultEnum.TOKEN_ERROR :79 case ResultEnum.TOKEN_LOGGED :80 case ResultEnum.TOKEN_TIMEOUT → 清 token 跳登录 ``` ⇒ 官方前端**期待** `601/602` 用来触发「清 token 跳登录」。本仓只有 `600` ⇒ 官方前端拿到 `600` 会走**默认分支**(`msg` 提示但不跳登录)⇒ **表现为「token 失效后页面卡住」**。 **面 B 必须**:`600` → `602`(token 失效);`601`(被踢出)可后置。 ### 3.5 D5 — 菜单接口 官方 `ModuleController.java`: | 端点 | 行号 | 用途 | |---|---|---| | `GET /api/system/Menu/ModuleBySystem` | `:121` | **官方前端取菜单的入口**(`api/system/menu.ts:8-9`) | | `GET /api/system/Menu/{systemId}/TreeView` | `:332` | 菜单树(管理端) | | `GET /api/system/Menu/Selector/{id}` | `:267` | 上级菜单下拉 | | `GET /api/system/Menu/Selector/All` | `:444` | 菜单下拉(全量) | | `POST /api/system/Menu` | `:169-170` | 新建 | | `PUT /api/system/Menu/{id}` | `:194-195` | 修改 | | `GET /api/system/Menu/{id}` | `:248-249` | 详情 | | `DELETE /api/system/Menu/{id}` | `:228-229` | 删除 | | `PUT /api/system/Menu/{id}/Actions/State` | `:498-499` | 启停 | **本仓**:`/api/ssw/sys/Module/{List,Save,Delete}`。 ⇒ 官方前端要的 `ModuleBySystem`(按 systemId 取菜单)本仓**没有对应面**。 注意:`ModuleBySystem` 返回的是**菜单列表(平铺)**,不是树;树在前端组。 ### 3.6 D6 — 鉴权模型:点权限 vs 菜单路径 **官方**:Sa-Token 的 `@SaCheckPermission`,权限码是 `permission.{对象}` + `btn_*` 按钮码: | 端点 | 权限码 | 行号 | |---|---|---| | `GET /api/permission/Users` | `permission.organize` OR `permission.user` OR `permission.role` | `UserController.java:293-294` | | `POST /api/permission/Users` | `permission.user` | `UserController.java:409-410` | | `GET /api/permission/Role` | `permission.auth` OR `permission.role` | `RoleController.java:99-100` | | `GET /api/permission/Organize/AsyncList/{id}` | `permission.organize` OR `permission.user` OR `permission.role` OR … | `OrganizeController.java:107-108` | | `GET /api/system/Menu/ModuleBySystem` | 无(登录即可) | `ModuleController.java:121` | | `PUT /api/permission/Authority/Data/{objectId}` | `permission.auth` OR `permission.role` | `AuthorizeController.java:159` | 这些码来自 `base_module.f_en_code`(`PermissionConst.java:8-58` 的常量拼成 `permission.` + 对象名)。 **本仓**:按**菜单路径**(`system/User`)做守卫(`permission.rs` 的 `guard_module`)。 ⇒ **两套模型语义不同**(点权限 vs 菜单路径)。本仓的模型是 ssw 前端定制的;官方前端是按 `f_en_code` 判按钮显隐。 **迁官方时必须补 `f_en_code` 维度**,否则官方前端所有按钮都不可见(因为 `permissionList` 拿不到东西)。 > ✅ **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.java:17` = `token`) | | POST | `/api/oauth/Logout` | `LoginController.java:155` | `ActionResult` | | GET | `/api/oauth/CurrentUser` | `LoginController.java:192` | `ActionResult` | > 📌 官方 `LoginVO` 字段:`token`(`:17`) / `theme`(`:20`) / `wlQrcode`(`:25`) / `isSaas`(`:28`) / `saasList`(`:31`)。 > 本仓返回的是 `{token, expiresIn:7200, tokenTypeName:'bearer'}` —— **多两个字段,但 `token` 同名同义** ⇒ 官方前端能取到 token(它只读 `data.token`)。 > `expiresIn` / `tokenTypeName` 是本仓 ssw 契约的字段,**面 A 保留**;面 B 可另返官方形状或同返(官方前端忽略多余字段)。 ### 4.2 用户(`/api/permission/Users`) | 方法 | 路径 | 官方出处 | 权限码 | |---|---|---|---| | GET | `/api/permission/Users` | `UserController.java:293` | `permission.organize\|user\|role` | | GET | `/api/permission/Users/{id}` | `:355` | `permission.user` | | POST | `/api/permission/Users` | `:409` | `permission.user` | | PUT | `/api/permission/Users/{id}` | `:429` | `permission.user` | | DELETE | `/api/permission/Users/{id}` | `:496` | `permission.user` | | POST | `/api/permission/Users/BatchDelete` | `:592` | `permission.user` | | POST | `/api/permission/Users/BatchUpdateState` | `:694` | `permission.user` | | GET | `/api/permission/Users/All` | `:729` | 登录即可 | | GET | `/api/permission/Users/Selector` | `:769` | 登录即可 | | POST | `/api/permission/Users/UserCondition` | `:806` | 登录即可 | | GET | `/api/permission/Users/{id}/GetPosition` | `:273` | `permission.user` | | POST | `/api/permission/Users/{id}/Actions/ResetPassword` | 前端 `user.ts:37` | `permission.user` | | PUT | `/api/permission/Users/{id}/Actions/unlock` | 前端 `user.ts:45` | `permission.user` | | GET | `/api/permission/Users/ExportData` | 前端 `user.ts:53` | 导入导出(可后置) | | GET/POST | `.../TemplateDownload` · `.../ImportData` · `.../ImportPreview` · `.../ExportExceptionData` | 前端 `user.ts:57-69` | 导入导出(可后置) | | POST | `/api/permission/Users/getUserList` · `.../getSelectedList` · `.../getSelectedUserList` | 前端 `user.ts:49,73,77` | 批量选择(可后置) | **列表响应**:`ActionResult>`(`UserController.java:295`)。 **请求参数**:`UserPagination`(`UserPagination.java:11-36`)= `Pagination` + `gender` / `enabledMark` / `groupId` / `organizeId` / `positionId` / `roleId` / `showSubOrganize` / `dataType`。 **列表项**:`UserListVO`(`UserListVO.java:16-74`)= `id` / `account` / `realName` / `fullName` / `gender` / `mobilePhone` / `email` / `organize` / `description` / `enabledMark` / `creatorTime` / `sortCode` / `lockMark` / `handoverMark` / `isAdministrator` / `headIcon` / `unlockTime` / `position` / `isDutyUser` / `maxRelationId` … > 📌 **注意**:`UserListVO` **没有 `password` 字段** ⇒ 官方列表天然不泄口令。本仓列表也是手工挑字段去掉 `password` ⇒ **一致**。 ### 4.3 角色(`/api/permission/Role`) | 方法 | 路径 | 官方出处 | 权限码 | |---|---|---|---| | GET | `/api/permission/Role` | `RoleController.java:99-100` | `permission.auth\|role` | | GET | `/api/permission/Role/{id}` | `:273` | `permission.role` | | POST | `/api/permission/Role` | `:122` | `permission.role` | | PUT | `/api/permission/Role/{id}` | `:165` | `permission.role` | | DELETE | `/api/permission/Role/{id}` | `:298` | `permission.role` | | GET | `/api/permission/Role/Selector` | `:327` | 登录即可 | | POST | `/api/permission/Role/RoleCondition` | `:342` | 登录即可 | 列表响应:`ActionResult>`(`RoleController.java:101`)。 ### 4.4 组织(`/api/permission/Organize`) | 方法 | 路径 | 官方出处 | 权限码 | |---|---|---|---| | GET | `/api/permission/Organize/AsyncList/{id}` | `OrganizeController.java:107-110` | `permission.organize\|user\|role\|…` | | GET | `/api/permission/Organize` | 前端 `organize.ts:14` | 登录即可 | | GET | `/api/permission/Organize/{id}` | `:290` | `permission.organize` | | POST | `/api/permission/Organize` | `:179` | `permission.organize` | | PUT | `/api/permission/Organize/{id}` | `:212` | `permission.organize` | | DELETE | `/api/permission/Organize/{id}` | `:315` | `permission.organize` | | GET | `/api/permission/Organize/Selector` | `:145` | 登录即可 | | POST | `/api/permission/Organize/SelectedList` | `:341` | 登录即可 | 列表响应:`ActionResult>`(`OrganizeController.java:111-112`)。 ### 4.5 菜单(`/api/system/Menu`) 见 §3.5 的表。`GET /api/system/Menu/ModuleBySystem` 是**官方前端的菜单入口**。 ### 4.6 授权(`/api/permission/Authority`) | 方法 | 路径 | 官方出处 | 权限码 | |---|---|---|---| | POST | `/api/permission/Authority/Data/{objectId}/Values` | `AuthorizeController.java:99-100` | `permission.auth\|role` | | PUT | `/api/permission/Authority/Data/{objectId}` | `:159-160` | `permission.auth\|role` | | GET | `/api/permission/Authority/Model/{itemId}/{objectType}` | `:124-125` | `permission.auth\|role\|onlineDev.visualPortal` | | PUT | `/api/permission/Authority/Model/{portalManageId}` | `:138-139` | `permission.auth\|role` | 读取授权树用 **`POST`**(不是 GET)—— 官方前端 `api/permission/auth.ts:9` 确认。 ### 4.7 数据权限链接(v1 不做) `/api/system/ModuleDataAuthorizeLink/**`(`api/system/authorize.ts:4`)—— 官方是**低代码数据权限方案**(表/字段级),本仓 v1 明确不碰(见 `CLAUDE.md`「明确不在 v1 范围」)。 --- ## 5. §4 官方码表(本仓需要补的) | 码 | 官方枚举 | 行号 | 官方前端行为 | 本仓 | 面 B 需要 | |---|---|---|---|---|---| | 200 | `SUCCESS` | `ActionResultCode.java:19` | 放行 | ✅ 有 | — | | 400 | `FAIL` | `:23` | 提示 msg | ✅ 有 | — | | 401 | `VALIDATEERROR` | `:27` | 提示 msg | ❌ 无 | 建议补 | | 500 | `EXCEPTION` | `:31` | 提示 msg | ❌ 无 | 建议补 | | 600 | `SESSIONOVERDUE` | `:35` | 过期提示 | ✅ 有 | 保留 | | 601 | `SESSIONOFFLINE` | `:39` | 被踢出 | ❌ 无 | 建议补 | | 602 | `SESSIONERROR` | `:43` | **清 token 跳登录** | ❌ 无 | **必补** | | 403 | `PEIMISSIONEXP` | `:47` | 跳无权限页 | ✅ 有 | 保留 | --- ## 6. §5 口令三段式与换算公式 ### 6.1 官方三段式 ``` ① 明文 pwd ↓ 官方前端 LoginForm.vue:140 encryptByMd5 ② md5_hex(pwd) ← 32 个小写 hex 字符 ↓ 官方前端 LoginForm.vue:141 encryptByAES (AES-256-ECB-PKCS7, key=md5_hex(security-key) 的 32 字节) ③ 密文 hex ← 走网络的是这一段 ↓ 官方服务端 PasswordTokenGranter.java:180 → DesUtil → Hutool AES ④ md5_hex(pwd) 复原(即②) ↓ 官方服务端 PasswordTokenGranter.java:186 比对 ⑤ md5( ④ + secretkey.toLowerCase() ) ← 库里存的 ``` 官方建号时(`UserServiceImpl.java:547-549`): ```java entity.setSecretkey(RandomUtil.uuId()); entity.setPassword(Md5Util.getStringMd5(entity.getPassword().toLowerCase() + entity.getSecretkey().toLowerCase())); ``` 其中 `entity.getPassword()` 在此处**已经是 `md5_hex(明文)`**(由上一层 service 传入)⇒ 库里存 `md5(md5_hex(明文) + secretkey)`。 ### 6.2 本仓现状 库里存 **`md5_hex(明文)`** = 上面的 **②**(= 官方公式的**被加项**,不是结果)。 ### 6.3 换算公式(**不需要明文**) 本仓一行 `f_password` ⇒ 官方一行 `f_password`: ```sql -- 对每一行: -- new_secretkey := 随机 UUID(官方用 RandomUtil.uuId()) -- new_password := md5( lower(old_password) + lower(new_secretkey) ) -- 并写回 f_secretkey = new_secretkey ``` Rust 侧等价(示意): ```rust let old = "d41d8cd98f00b204e9800998ecf8427e"; // = md5_hex(明文) let secret = uuid::Uuid::new_v4().to_string(); // 36 位 let new_pw = md5_hex(format!("{}{}", old.to_lowercase(), secret.to_lowercase())); ``` **为什么成立**:官方比对的是 `md5(解密后的② + secretkey)`,而本仓存的**就是②** ⇒ 直接拿旧值当②参与公式即可,**全程不接触明文**。 ### 6.4 换算的验证方法 换算后用**同一个明文**走一次官方登录路径,断言: `md5( md5_hex(明文) + secretkey ) == 库里新值`。 (官方登录时 `inputPwd` = 解密后的 `md5_hex(明文)`,见 `PasswordTokenGranter.java:186`。) --- ## 7. §6 官方数据模型规模(用来判断「迁移是搬运还是重写」) | 对象 | 官方规模 | 本仓 v1 | |---|---|---| | Java 后端 | 2,774 个 `.java` / 282,624 行 | 6,372 行 Rust | | 官方前端(apps-main) | 765 `.vue` + 224 `.ts` = 172,525 行 | 18 个文件 / 1,374 行 | | 官方前端(monorepo-framework) | 1,218 `.vue` + 1,036 `.ts` = 284,176 行 | — | | DDL 表数 | **331** 张(其中 `base_*` **123** 张) | **10** 张(`base_*` 7 + 业务 3) | | `base_*` 已实现列级缺口 | — | **0** | | 官方 `src/api` | 97 个 `.ts`;`api/permission/` 14 个 | 5 个 | ⇒ **结论**:本仓 v1 覆盖的是官方 **`base_*` 权限体系的这 7 张表**(列级零缺口), **不覆盖**官方 331 张表里的其余 324 张(工作流、在线开发、数据视图、消息、租户、报表…)。 迁移时**这 7 张表的数据是直接搬运**(`--data-only`),**其余能力要么不用、要么另做**。 --- ## 8. §7 对齐清单(本仓 → 官方,做什么、做到什么程度) > ✅ **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}`。 |