- 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/:前端接口清单、页面依赖反查、运行时探针
183 lines
11 KiB
Markdown
183 lines
11 KiB
Markdown
# 权限模版(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/<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**:
|
||
|
||
```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` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。
|