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

183 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 权限模版(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` 的真实算法**——本仓留位待迁移补(迁时一次性换算)。