# 权限模版(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`](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/.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**: ```bash # 🔴 pglite 是**进程内单用户 PG、无 TCP 监听** ⇒ psql / pg_dump **连不上** # ⇒ 走应用内导出(新增一个 --dump 子命令跑 COPY ... TO STDOUT),或手写 INSERT ``` 详见 [`MIGRATION.md`](MIGRATION.md) §6。 ## 七、验证(可重复执行) ```bash 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` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。