Files
ssw-platform/PERMISSION.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

11 KiB
Raw Permalink Blame History

权限模版(MVP 期就按 JNPF 形态钉死)

权限是迁移最硬的一块。本仓从第一天起就把 base_* 的表名/列名/语义照官方 DDL 抄死, 使稳定期换 Java 后端时不用动表(只导数据)。端点路径与列表形状故意没锁(那是面 A/面 B 的事)。

一、数据模型(7 张表,字段名与官方逐字一致)

表 用途 关键列
base_user 用户 f_id / f_account / f_password / f_real_name / f_is_administrator / f_delete_mark / f_secretkey
base_role 角色 f_id / f_en_code(应用层唯一) / f_full_name / f_delete_mark
base_module 菜单 f_id / f_full_name / f_url_address(= 前端 Route path 去前导斜杠) / f_parent_id / f_type(INTEGER:1 目录 2 页面) / f_en_code(官方点权限用,本仓种子为空)
base_authorize 授权 f_object_type / f_object_id / f_item_type / f_item_id
base_role_relation 用户↔角色 f_role_id / f_object_id(用户 id!) / f_object_type='user'
base_user_relation 用户↔组织/岗位 f_user_id / f_object_id / f_object_type('organize' / 'position')
base_organize 机构 f_parent_id 树

所有表复合主键 (f_id, f_tenant_id),单租户固定 f_tenant_id='0'。

⚠️ 两个高频字段名陷阱(官方原样保留,别"优化")

陷阱 事实 写错的后果
base_role_relation 用户 id 存在 f_object_id(配 f_object_type='user'),没有 f_user_id 角色授权永远不生效(且不报错)
base_user_relation 组织/岗位关系在另一张表,那里才有 f_user_id 组织/岗位授权永远不生效(且不报错)

🔴 这两个坑都是静默失败 ⇒ 必须有测试钉住(本仓 permission_it.rs 钉了)。

权威来源(不要凭记忆写列名)

  • 官方 DDL:~/Desktop/workspace/jnpf/jnpf-database/PostgreSQL/JNPF-PostgreSQL.sql (base_authorize:812 / base_module:2209 / base_organize:3178 / base_role:3686 / base_role_relation:3729 / base_user:4479 / base_user_relation:4707) (同目录另有 9 个 init 文件,只读)
  • 本仓落地:src/backend/db/schema.sql
  • 逐行核对报告:JNPF_SOURCE_AUDIT.md §2.6

二、四源合并(已实现,src/backend/src/platform/permission.rs)

权限 = 用户直授 + 角色 + 组织 + 岗位,四条路都查:

源 路径
1. 直授 base_authorize(f_object_type='user')⇒ 菜单 id
2. 角色 base_role_relation(f_object_type='user')⇒ f_role_id ⇒ base_authorize(f_object_type='role')
3. 组织 base_user_relation(f_object_type='organize')⇒ f_object_id ⇒ base_authorize(f_object_type='organize')
4. 岗位 base_user_relation(f_object_type='position')⇒ f_object_id ⇒ base_authorize(f_object_type='position')

🔴 只查角色会漏授权——组织/岗位授权最容易被忽略。 🔴 管理员短路在查 SQL 之前(f_is_administrator=1 ⇒ 直接放行,不查任何授权表)。 🔴 只有 base_authorize 过滤 f_delete_mark = 0;base_role_relation / base_user_relation 不过滤(对齐官方 SQL 的过滤习惯)。

判权:菜单路径,不是点权限

本仓的守卫 = spec.module_key == 菜单 f_url_address:

spec.module_key  ==  menu.url_address  ==  前端 App.tsx 的 Route path(去前导斜杠)

🔴 菜单(url_address / f_en_code / parent_id / sort_code)由业务模块自己声明 (modules/<app>.rs 的 *_MENU: MenuSpec),再经 modules::ALL_MENUS 交给装配根 bootstrap::ensure_base 回灌 ⇒ 平台层不认识任何业务菜单(红线 12)。

🔴 官方是点权限(@SaCheckPermission("permission.user"),取自 base_module.f_en_code)—— 这是本仓与官方最大的鉴权模型差异(审计报告 D6)。 ⇒ 迁官方前必须给菜单补 f_en_code(MIGRATION.md §2.4)。 ⇒ 面 B 落地时要两套判据并存(路径判权给面 A,f_en_code 判权给面 B)。

未映射 ⇒ 放行(不是拒绝)

菜单未映射到 base_module ⇒ 放行(对齐官方 SswPermissionGuard 的 warn 路径)。 🔴 这条最容易写反,而且静默(不报错)⇒ 有测试钉住。

三、端点契约

方法 路径 守卫 返回
POST /api/oauth/Login 无 {token, expiresIn:7200, tokenTypeName:'bearer'}
GET /api/oauth/CurrentUser 登录 {userInfo:{userId,userAccount,userName,isAdministrator}, menuList}
GET/POST/DELETE /api/ssw/sys/User/{List,Save,Delete?id=} 登录 + 菜单 system/User 列表去掉 password,附 roleIds/roleNames
GET/POST/DELETE /api/ssw/sys/Role/{List,Save,Delete?id=} 登录 + 菜单 system/Role
GET /api/ssw/sys/Role/Modules?roleId= 登录 string[](菜单 id)
GET/POST/DELETE /api/ssw/sys/Organize/{List,Save,Delete?id=} 登录 + 菜单 system/Organize 有子机构时拒删(code=400)
GET/POST/DELETE /api/ssw/sys/Module/{List,Save,Delete?id=} 登录 + 菜单 system/Module
PUT /api/permission/Authority/Data/{objectId} 登录 body {objectType:'role', module:['m1','m2']}
GET /api/permission/Authority/RoleModules?roleId= 登录 string[]
GET/POST/DELETE /api/ssw/{app}/{Entity}/{List,Save,Delete?id=} 登录(+ 菜单,按 module_key)

授权写接口的三个坑

  1. objectType 必须小写 'role' —— 官方对大小写错误是静默忽略(返 200 但一行不写)。
  2. module 传一维数组 ['m1','m2',…](半选节点合进同一数组,对齐官方 MenuAuth.vue)。
  3. 官方 body 是本仓的超集(多 button/column/resource/form/systemIds)⇒ 本仓照单全收, 只消费 objectType + module ⇒ 官方前端直接调本仓即可(零改动)。

四、ActionResult 码表

本仓已用官方 ActionResultCode 的前 4 个:

code 含义 何时
200 成功
400 业务失败 账号重复、参数错、有子机构拒删……
403 无菜单权限 已登录但菜单未授权
600 未登录(会话过期) 无 token / token 无效

🔴 业务失败恒 HTTP 200——成败只看 body 的 code。禁止 401/403 裸 body。 🔴 未知路由保留 HTTP 404(body 仍是信封形状)——不要用全局 404 兜底把它变成 200。

官方还有、本仓缺的(面 B 要补,见 JNPF_COMPAT_SURFACE.md §4):

code 官方常量 说明
401 VALIDATEERROR 官方 MsgCode.PS012 之类的校验失败
500 EXCEPTION 未捕获异常
601 SESSIONOFFLINE 被踢下线
602 SESSIONERROR 会话异常

🔴 官方前端 request.ts:78-80 只在 601/602 时清 token ⇒ 只返 600 会让页面卡住不跳登录。 ⇒ 面 B 无 token 必须返 602(不是 600)。

五、口令

  • 加密链(前端 → 后端):md5(明文) → AES-256-ECB-PKCS7(key = md5("EY8WePvjM5GGwQzn") 的 32 个 ASCII 字节)→ hex。
  • 检验向量:encryptPassword('123456') == d4958348e22108119b3ef57b022c83f4bf857dd0b247eaab15b9a43d47ee3c503900f7135bf0de255bc33620c3cdc02b。 一行自证:./target/release/ssw-jnpf-lite-rust --enc 123456。
  • 库内存 md5(明文) 的小写 hex;登录时 decrypt(密文) 得到 md5(明文) ⇒ 大小写不敏感比较。
  • 🔴 密文只在请求体里出现,永不回显;用户列表手工挑字段去掉 password。
  • 🔴 官方多一步 secretkey(md5(lower(md5(明文)) + lower(secretkey)))⇒ 迁官方要换算, 但不需要明文(MIGRATION.md §7)。

六、迁移映射(稳定期)

本仓 官方
permission.rs 的四源合并 @SaCheckPermission + SswPermissionGuard.requireMenu(判据从路径换成 f_en_code)
auth.rs 的内存 token jnpf-oauth / Sa-Token(内存模式同代)
cipher.rs DesUtil + SecurityProperties.setSecurityKey(逐字节一致)
envelope.rs ActionResult + ResultExceptionHand
sys.rs 的 5 组显式 handler 5 个官方 Controller(/api/permission/Users / Role / Organize / Authority / /api/system/Menu)
db/schema.sql 的 7 张 base_* 官方 DDL(逐字同形)⇒ 只导数据,不导结构
seed.rs 的两段式种子 官方建表后灌数据(补 f_en_code + f_secretkey)

数据 ETL:

# 🔴 pglite 是**进程内单用户 PG、无 TCP 监听** ⇒ psql / pg_dump **连不上**
#    ⇒ 走应用内导出(新增一个 --dump 子命令跑 COPY ... TO STDOUT),或手写 INSERT

详见 MIGRATION.md §6。

七、验证(可重复执行)

bash scripts/perm-smoke.sh        # 面 A 32 条(含权限闭环)
bash scripts/perm-smoke-jnpf.sh   # 面 B 18 条(官方形状)
cargo test                        # 220 条单测(含两个陷阱的回归)

面 A 尺子覆盖的权限闭环: 未登录 600 · 加密登录 · 菜单树 · 建用户 · 重复账号返 400 而非 500 · 写授权(一维/二维兼容)· 非管理员菜单收窄 · 非管理员访问系统管理返 403 · 已授权业务返 200 · 未知路由 404 · 三个业务模块全链路。

🔴 判读原则:返回了数据不能证明权限生效 (管理员短路 / 菜单没映射 / 缓存没清 / 异常降级放行,四条路径全是"放行")。 「菜单收窄 + 403 拦截」才是有说服力的信号。

八、MVP 未做的部分(迁移时补,不是遗漏)

  • 按钮 / 列 / 表单 / 数据范围级授权(base_module_button / _column / _form / _data)—— 官方 DDL 里都有,v1 只做 item_type='module'(菜单)一类。
  • 多租户(jnpf-tenant*)——单租户固定 f_tenant_id='0'。
  • Redis / Sa-Token——内存 token 表即可。
  • 分页——契约里的 List 就是全量;要分页是 JNPF 稳定期的 SuperServiceImpl.page。
  • 低代码引擎(表单 / 流程 / 代码生成)——官方能力,不碰。
  • 点权限(f_en_code)——本仓按菜单路径判权;面 B 才引入 f_en_code 判据。
  • base_user.secretkey 的真实算法——本仓留位待迁移补(迁时一次性换算)。