- 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/:前端接口清单、页面依赖反查、运行时探针
35 KiB
官方 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_*)仍未实现(面 BpermissionList的四个数组恒空)⇒ 见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}。 |