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

35 KiB
Raw Blame History

官方 JNPF 源码审计(本技能的「官方面」地基)

这份文档回答一个问题:本技能(Rust 模板)的契约与官方 JNPF(Java)到底差在哪、哪些已经对齐了。

全部结论来自对官方源码的逐行核对,每条带 文件:行号。 官方源码坐标:~/Desktop/workspace/jnpf/(下文所有路径均相对它)。 核对日期:2026-10-26。官方版本:jnpf-web-apps-main(Vue3 前端)+ jnpf-java-boot(Java 后端)。

配套阅读:

  • 契约红线(权威)→ SKILL.md §契约红线 + PERMISSION.md
  • 迁移操作(怎么做)→ MIGRATION.md
  • 面 B 规格(要做到什么程度)→ 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 走
要让官方 Vue 前端跑在 Rust 后端上 §2(8 条差异)+ §3(官方端点全表),规格见 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 §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。

📌 官方 ssw 前端(ssw-jnpf-lite-react)自己也没有用 ssw 路径去迁官方 —— 它的 MIGRATION.md 明确写了: 「端点命名 /api/ssw/{appCode}/{Entity}/{List|Save|Delete}(ssw 约定,非官方 visualdev 路径;稳定期真实 JNPF 由引擎生成,路径以引擎为准,数据模型仍保值)」。 ⇒ 数据模型保值(本仓已做到),路径在迁官方时重新映射。这正是本仓设计意图,不是缺陷。

3.2 D2 — 列表响应:PageListVO ✅(本条要更正一个常见误解)

官方 PageListVO.java:

:17   PaginationVO pagination;      // ← 官方**有**分页元数据
:19   private List<T> list;

PaginationVO.java:currentPage(:16) / pageSize(:18) / total(:20)。

⇒ 官方分页响应形状是:

{ "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):

{ "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 §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 附录 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):

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:

-- 对每一行:
--   new_secretkey := 随机 UUID(官方用 RandomUtil.uuId())
--   new_password  := md5( lower(old_password) + lower(new_secretkey) )
--   并写回 f_secretkey = new_secretkey

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 '*'。

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"

本仓侧:

# cipher 自证(免 node 依赖)
./target/release/ssw-jnpf-lite-rust --enc 123456
#   期望:d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b

10. 变更记录

日期 变更
2026-10-26 首版。逐行核对官方源码,确立「9 条已对齐 / 8 条差异 / 3 条换算与补齐」。更正了一处常见误解:官方 PageListVO 含 pagination 字段,不是只有 {list}。