# IAM 治理后台 — 使用指南

> **module**: iam-admin
> **doc_type**: UserGuide
> **status**: Draft（模块本身规划中）
> **owner**: FFOA Team
> **audience**: 系统管理员 / 安全负责人 / IT 运维
> **upstream_docs**: 01-prd.md
> **last_verified**: 2026-05-11

> ⚠️ **当前状态**：本模块的前端管理 UI 仍在规划中（详见 [01-prd.md](01-prd.md)）。本指南覆盖**已落地的能力**（emergency-bypass / audit-logs）+ **规划中的能力**（data-scopes / role-data-scopes / field-permissions），规划中的部分以 🚧 标注。

---

## 目录

1. [系统概览](#1-系统概览)
2. [IAM 四层模型与核心概念](#2-iam-四层模型与核心概念)
3. [角色与权限](#3-角色与权限)
4. [Part 1 — 日常治理操作](#4-part-1--日常治理操作)
5. [Part 2 — 紧急豁免](#5-part-2--紧急豁免)
6. [Part 3 — IAM 审计与追溯](#6-part-3--iam-审计与追溯)
7. [常见问题（FAQ）](#7-常见问题-faq)

---

## 1. 系统概览

IAM 治理后台是**系统管理员**用于管理 FFOA 平台所有权限治理动作的统一入口。它把原本散落在 SQL / seed / Redis CLI 里的运维动作（DataScope 绑定、字段脱敏规则、紧急豁免、委托、复核）收口到 UI，并通过 IAM 审计日志保证所有 admin 操作可追溯。

**解决的问题**：

- 数据权限要靠跑 SQL 才能改 → UI 化
- 紧急豁免要 SSH 调 Redis CLI → UI 化
- IAM 操作没有专门审计 → 独立审计日志 + 查询页

**与"角色与权限"基础设施的区别**：

| 维度 | 基础 RBAC（organization 模块） | IAM 治理后台（本模块） |
|------|------|------|
| 管什么 | 角色、权限点、用户分配 | **数据可见范围（行级）+ 字段级脱敏 + 委托 + 复核 + 豁免** |
| 受众 | 一般管理员 | 高级别管理员 / 安全负责人 |
| 频率 | 日常 | 低频但关键 |

---

## 2. IAM 四层模型与核心概念

FFOA 权限治理分为四层（L1-L4），每层对应不同问题：

| 层 | 名称 | 回答的问题 | 例子 |
|---|---|---|---|
| **L1** | Role / Permission | 谁能调用这个接口？ | `Sales` 角色拥有 `order:read` |
| **L2** | OrganizationScope | 谁能看哪个组织的数据？ | 上海分公司销售只能看上海订单 |
| **L3** | DataScope | 谁能看哪些行？ | 部门主管可看本部门 + 下级部门的订单 |
| **L4** | FieldPermission | 谁能看哪些字段？ | 普通销售看不到客户手机号（脱敏 `138****1234`） |

**核心概念**：

| 概念 | 说明 |
|------|------|
| **DataScope** | 数据可见范围定义。内置类型：`ALL` / `ORGANIZATION` / `DEPARTMENT_TREE`（本部门 + 下级）/ `SELF`（仅本人）。`CUSTOM` 类型**永久未实现**（详见 PRD §3） |
| **role × resource → DataScope 绑定** | 同一角色对不同资源可绑不同 DataScope。例：`Sales` 对 `Order` 绑 `DEPARTMENT_TREE`，对 `Customer` 绑 `ORGANIZATION` |
| **FieldPermission** | 字段级访问规则；可按 `roleId` + `accessLevel`（`READ` / `READ_MASKED` / `HIDDEN`）配 |
| **EmergencyBypass** | 紧急豁免：管理员临时给某个 endpoint 开后门（带 TTL），所有调用走审计。**严格按规约使用** |
| **委托（Delegation）** | 员工请假期间把权限临时委托给同事 |
| **Access Review（复核）** | 周期性复核：审视谁有哪些角色，确认是否仍需要，避免权限蠕变 |
| **iam_audit_log** | IAM 治理操作专用审计表，与业务审计（audit-system）独立；记录 DataScope 改动、豁免启用、审批通过等动作 |

---

## 3. 角色与权限

| 角色 | 可见 | 操作 |
|------|------|------|
| **Administrator**（系统管理员） | 全部 | IAM 治理后台所有功能 |
| **SecurityAdmin / SOX 负责人** | 全部 | 同上；复核与审计查询为日常 |
| **IT 运维** | 紧急豁免 + 审计查询 | 应急处置 |
| **业务用户** | 仅自己的委托 | 在 `organization/delegations` 看本人委托记录 |

**关键权限点**：

| 权限码 | 控制 |
|------|------|
| `iam_admin:read` | 查看 IAM 治理后台数据 |
| `iam_admin:manage` | 修改 DataScope / FieldPermission / 豁免 / 复核 |
| `system:admin` | 系统超管，可绕过部分检查；与上面任一组合都可访问 |

---

## 4. Part 1 — 日常治理操作

### 4.1 入口总览

| 页面 | 路由 | 状态 | 用途 |
|------|------|------|------|
| Dashboard | `/iam-admin` | 🚧 规划 | 治理动作概览、入口卡片 |
| DataScope 管理 | `/iam-admin/data-scopes` | 🚧 规划 | DataScope 定义 CRUD |
| 角色 × DataScope 矩阵 | `/iam-admin/role-data-scopes` | 🚧 规划 | 矩阵：角色 × resource → DataScope 绑定 |
| 字段权限 | `/iam-admin/field-permissions` | 🚧 规划 | FieldPermission CRUD |
| 紧急豁免 | `/iam-admin/emergency-bypass` | ✅ 已落地 | 豁免启用 / 查看 / 解除 |
| 审计日志 | `/iam-admin/audit-logs` | ✅ 已落地 | iam_audit_log 查询 |

### 4.2 配 DataScope（🚧 规划）

**场景**：销售经理需要看到本部门 + 下级部门的所有订单。

1. `/iam-admin/data-scopes` → 确认存在 `DEPARTMENT_TREE` 定义（内置，不需新建）
2. `/iam-admin/role-data-scopes` → 选 `SalesManager` 角色
3. 在 `Order` 这一行绑定 `DEPARTMENT_TREE`
4. 提交 → 自动写 iam_audit_log

⚠️ **CUSTOM 类型不可用**：选 CUSTOM 会被前端禁用，后端永久返回 NotImplementedException。

### 4.3 配字段级脱敏（🚧 规划）

**场景**：普通销售不应看到客户手机号。

1. `/iam-admin/field-permissions` → 添加规则
2. resource = `Customer`，field = `phone`，roleId = `Sales`，accessLevel = `READ_MASKED`
3. 提交后该角色调相关 API 时 `phone` 自动渲染为 `138****1234`
4. 解除：删除该规则

### 4.4 升级委托/复核 UX（🚧 PR-A 进行中）

委托页和复核页（在 `organization` 模块）正在升级：

- 委托：UUID 输入框 → `UserSelector`；fixed modal → shadcn `Dialog`；列表拆 Tab（我发起的 / 我收到的 / 全部）
- 复核：`prompt(...)` 取 comment → Dialog + textarea；`alert(...)` 报错 → toast

升级落地后本节会更新对应页面入口。

---

## 5. Part 2 — 紧急豁免

### 5.1 什么时候用

仅在以下情况启用：

1. 某关键业务流程因权限误配卡死，影响业务运转
2. 修正权限配置需要时间（涉及多角色调整或上线）
3. **必须有责任人 + 写明原因 + 设置短 TTL**

### 5.2 操作步骤

1. `/iam-admin/emergency-bypass` → "新建豁免"
2. endpoint = 例如 `/api/v1/orders/approve`
3. reason = "Y 系统迁移导致 X 角色误失 approve 权限，限 2h 内修复正式权限"
4. TTL = 7200（秒）
5. 提交 → 即时生效（Redis），TTL 到期自动失效

### 5.3 监控与回收

- 列表实时展示所有 active 豁免 + 剩余 TTL
- 修复完成后**立即手动解除**，不要等 TTL 自动过期
- 每条豁免在 iam_audit_log 留下 `EMERGENCY_BYPASS_GRANTED` / `_REVOKED` 记录
- 所有走豁免通过的请求会在主审计日志标 `ADMIN_BYPASS`

### 5.4 红线

- 不允许长期豁免（TTL 上限通常 24h）
- 不允许跨模块"一把梭"豁免
- 不允许私自启用——必须有书面 / IM 记录沟通过

---

## 6. Part 3 — IAM 审计与追溯

### 6.1 入口

`/iam-admin/audit-logs` — 已落地。

### 6.2 字段

每条 iam_audit_log 包含：

- **actor**：操作人
- **action**：动作类型（`DATA_SCOPE_CREATED` / `_UPDATED` / `_DELETED` / `ROLE_BINDING_CHANGED` / `FIELD_PERMISSION_CHANGED` / `EMERGENCY_BYPASS_GRANTED` / `_REVOKED` / `DELEGATION_CREATED` / `ACCESS_REVIEW_COMPLETED` 等）
- **resource**：影响的资源
- **before / after**：变更前后值
- **timestamp**
- **traceId**：与主审计日志可关联

### 6.3 典型查询

- 按 actor：「某 admin 上周做了哪些 IAM 操作」
- 按 action：「最近 30 天所有 EMERGENCY_BYPASS_GRANTED 是谁开的」
- 按 resource：「`Order` 的 DataScope 配置变更历史」
- 按时间范围：复核期间审视一段时间的全部 IAM 改动

### 6.4 与业务审计的关系

| 数据 | 归属 |
|------|------|
| IAM 治理动作（改权限规则） | **iam_audit_log**（本表） |
| 实际业务操作（订单审批通过） | audit-system 主表 |
| 走 EmergencyBypass 通过的请求 | **两边都有**：本表记豁免动作，主审计记请求本身（标 ADMIN_BYPASS） |

---

## 7. 常见问题（FAQ）

### Q1：DataScope 的 CUSTOM 类型什么时候做？

**永久不做**。规则 §5.3.4 已明确禁用，CUSTOM 等于"自定义 SQL 片段"，会带来安全风险和性能不可预期，不在路线图。

### Q2：能给一个用户单独配 DataScope 吗？

不能，**只能按角色配**。如果某用户需要特殊范围，给他单独建一个角色，绑该 DataScope，再把该角色授予他。

### Q3：紧急豁免会不会被滥用？

会有这个风险，所以：
- 操作走 iam_audit_log
- TTL 上限通常 24h
- 列表实时可见所有 active 豁免
- 每个豁免请求在主审计日志也留痕

定期复核（access review）应包含"上周期内是否有不合理的 EMERGENCY_BYPASS"项。

### Q4：iam_audit_log 和 audit_log 重复吗？

不重复。一个记 IAM 治理动作（改权限规则本身），一个记业务操作（基于权限规则做事）。两个表关注的责任人和事件类型不同，分开查询效率更高。

### Q5：MFA 配置在哪里？

🚫 **本期不做**。`MfaService` 后端已引入但未挂 login 流程，UI 后续才会建。

### Q6：复核（Access Review）多久跑一次？

建议每季度一次。复核流程：
1. 系统生成「待复核角色 / 用户」清单
2. 责任人逐项确认"仍需保留 / 撤销"
3. 撤销项立即生效
4. 复核报告归档

### Q7：能批量改 DataScope 吗？

🚧 规划中。当前只能逐角色绑。批量需求多了再加。

### Q8：本模块和组织架构模块（organization）什么关系？

- organization：管 RBAC 基础（角色、权限点、用户、部门）
- iam-admin（本模块）：管治理层（数据范围、字段脱敏、豁免、复核）

委托页和复核页代码物理上还在 `organization` 模块下，但功能归 IAM 治理；后续可能整合到本模块。

---

## 关联文档

- [01-prd.md](01-prd.md) — 完整 PRD（含 PR-A / PR-B 拆分）
- [organization 模块](../organization/) — RBAC 基础设施
- [audit-system](../audit-system/11-user-guide.md) — 业务审计指南