104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 平台超级管理员与双域鉴权开发文档
|
||
|
||
## 1. 背景与目标
|
||
|
||
当前系统采用租户内 RBAC（`用户 -> 角色 -> 权限`），但“系统超级管理员”职责属于平台级，不应绑定任何租户。
|
||
本迭代目标是在不破坏现有租户业务能力的前提下，建立“平台域 + 租户域”的双域鉴权模型。
|
||
|
||
## 2. 设计原则
|
||
|
||
- 平台域与租户域严格隔离，避免越权访问。
|
||
- 平台账号不落入任何租户，不依赖 `tenant_id`。
|
||
- 租户业务接口只允许租户令牌访问。
|
||
- 平台管理接口只允许平台令牌访问。
|
||
- 兼容现有租户登录接口与权限模型，按迭代逐步替换。
|
||
|
||
## 3. 总体方案
|
||
|
||
### 3.1 身份域模型
|
||
|
||
- `TENANT`：租户业务身份（必须携带 `tenantId`）。
|
||
- `PLATFORM`：平台管理身份（不携带 `tenantId`）。
|
||
|
||
### 3.2 Token 约定
|
||
|
||
- 租户令牌 claims：`uid`、`tid`、`scope=TENANT`。
|
||
- 平台令牌 claims：`uid`、`scope=PLATFORM`。
|
||
|
||
### 3.3 权限注解扩展
|
||
|
||
`@RequirePermission` 新增 `domain` 字段：
|
||
|
||
- `domain=TENANT`（默认）
|
||
- `domain=PLATFORM`
|
||
|
||
### 3.4 平台 RBAC 数据模型
|
||
|
||
新增表：
|
||
|
||
- `platform_user`
|
||
- `platform_role`
|
||
- `platform_permission`
|
||
- `platform_user_role`
|
||
- `platform_role_permission`
|
||
|
||
## 4. 迭代拆分
|
||
|
||
### Iteration 1（已启动）
|
||
|
||
目标：落地双域鉴权底座，打通平台登录和租户管理平台化访问。
|
||
|
||
- [x] 增加鉴权域枚举：`AuthScope`、`PermissionDomain`
|
||
- [x] `AuthContext` 增加 `scope` 上下文
|
||
- [x] JWT 支持租户/平台两类 token
|
||
- [x] 新增平台登录接口：`POST /api/auth/platform-login`
|
||
- [x] 拦截器按 `scope + domain` 双维度鉴权
|
||
- [x] 租户管理接口切换到平台域权限：`platform.tenant.manage`
|
||
- [x] 增加平台 RBAC 初始化迁移：`V40__platform_admin_rbac.sql`
|
||
|
||
### Iteration 2（进行中）
|
||
|
||
目标：收敛租户默认兜底逻辑，修正平台日志归属。
|
||
|
||
- [x] 清理所有 `tenantId == null ? 1L : tenantId` 兜底逻辑
|
||
- [x] 平台操作审计增加 `scope` 字段（`TENANT/PLATFORM`）并完成查询分流
|
||
- [x] 平台接口统一路由前缀（新增 `/api/platform/tenants`、`/api/platform/audit-logs`）
|
||
- [x] 为平台接口补齐权限码与元数据校验（`domain=PLATFORM`）
|
||
|
||
### Iteration 3（待开发）
|
||
|
||
目标：前后端联动与灰度上线。
|
||
|
||
- [x] 前端增加登录入口切换（平台 / 租户）
|
||
- [x] 平台工作台页面（已接入租户管理、平台审计日志基础页面）
|
||
- [x] 平台菜单动态化（`platform_menu`、`platform_role_menu` + `/api/platform/menus/current`）
|
||
- [x] 平台菜单管理页（新增/编辑/排序/菜单绑定角色）
|
||
- [x] 平台 IAM 页面（平台用户管理、平台角色管理、平台权限查看）
|
||
- [ ] 双域登录回归测试与权限压测
|
||
- [ ] 发布灰度与回滚预案
|
||
|
||
## 5. 初始账号与权限
|
||
|
||
初始化数据（`V40`）：
|
||
|
||
- 平台角色：`PLATFORM_SUPER_ADMIN`
|
||
- 平台权限：`platform.tenant.manage`、`platform.user.manage`、`platform.audit.read`、`platform.menu.manage`、`platform.role.read`、`platform.role.manage`、`platform.permission.read`
|
||
- 平台管理员账号：
|
||
- 手机号：`13900000000`
|
||
- 密码：`123456`
|
||
|
||
> 上线前必须改密，并接入密码加密存储。
|
||
|
||
## 6. 风险与注意事项
|
||
|
||
- 已完成租户默认 `1L` 兜底清理；后续仍需补齐平台独立审计模型，避免平台操作与租户审计混用。
|
||
- `tenant.manage` 与 `platform.tenant.manage` 属于不同域权限码，前后端配置需同步。
|
||
- 建议后续引入统一 `domain` 中间件拦截，禁止跨域访问。
|
||
|
||
## 7. 验收标准（Iteration 1）
|
||
|
||
- 平台管理员可通过 `/api/auth/platform-login` 获取 `scope=PLATFORM` token。
|
||
- 平台管理员可访问租户管理接口（`/api/tenants`）。
|
||
- 租户 token 访问平台域接口被拒绝。
|
||
- 平台 token 访问租户域接口被拒绝。
|