# 平台超级管理员与双域鉴权开发文档

## 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 访问租户域接口被拒绝。