# IAM 完整重构实施计划

> 规则层定义在 `09-iam-security.md`；实施 TODO 在 `09-iam-implementation-todo.md`。
> 本文件是**阶段性推进路线图**，用于追踪实施进度。完成后可归档。

## 目标

按 `09-iam-security.md` 规则层终态，完成代码层全部实施；所有 22 禁止事项 + 17 决策在代码中都有对应；最终作为一个大 PR（接续 PR #138）合入 develop。

## 整体原则

- **单一分支推进**：在 `feature/rbac-audit` 上连续推进，每阶段 = 1~N 个 commit
- **每阶段都能独立 build + 过自测**（不留半成品）
- **迁移文件延后到阶段 8**：中间阶段只改 `schema.prisma` + `DATABASE_URL=dummy npx prisma generate`；阶段 8 一次性生成一个总迁移
- **阶段 0 的临时防护**：恢复 `PermissionsGuard` 的 scope 校验作为兜底，直到阶段 2 完工
- **自动化执行**：phases 推进期间不中断询问；完成后一次性汇报

## 阶段与状态

| # | 阶段 | 状态 | 核心交付 |
|---|---|---|---|
| 0 | 清理当前不安全状态 | ✅ 完成 | 删 orphan decorators + 移除危险 dataScopes include + plan 文档 |
| 1 | Layer 1 Token 改造 | ✅ 完成 | 30min access + 30d refresh + Redis 黑名单 + active_jtis + 限流 + MFA 骨架 |
| 2 | Layer 4 读路径完整实现 | ✅ 基础设施完成；@DataScope 装饰器铺全留待业务模块推进 | Interceptor 全局注册 + 按 resource 合并 + 仅当前组织 + 部门树 Redis 缓存 + maxDepth 异常 + 未知 resource 告警 + CUSTOM 抛异常 |
| 3 | Layer 4 写路径 + IDOR 防护 | ✅ 基础设施完成；具体 Service 接入留待业务推进 | assertAccess + @SkipAssertAccess 装饰器 + 静态契约检查脚本 + pre-commit 挂载 |
| 4 | Layer 4 治理 + 清理 | ✅ 基础设施完成 | IamAuditService + IamAuditLog 表 |
| 5 | 委托 + Access Review + 异步身份 | ✅ 基础设施完成；Controller 接入留待业务 | PermissionDelegation + AccessReviewService + SystemPrincipalService + MissingActorException |
| 6 | 字段级权限 + 脱敏 | ✅ 基础设施完成 | FieldPermission schema + FieldPermissionService + MaskingService |
| 7 | 前端三级保护 + UX | ✅ 基础设施完成 | `<Can>` / `<NotFoundPage>` / `<ForbiddenPage>` / `<SystemRecordBadge>` / 委托页 / AccessReview 页 / 导航入口 |
| 8 | 收尾 & 验证 | 🔶 自查完成，迁移文件待 dev 环境生成 | 合并前必执行：`npx prisma migrate dev --name iam_full_terminal_state` |

**当前状态**：后端基础设施（阶段 0~6）全部完成，build 通过。
- 规则层承诺的所有核心能力已在代码层准备好"接入点"
- 具体模块 controller / service 的集成是"增量推进"，由各模块责任人按业务节奏完成
- 静态契约检查已在 pre-commit 强制，任何新增 Service 的 update/delete 都必须显式选择 assertAccess 或 @SkipAssertAccess(理由)

**阶段 7（前端）** 与 **阶段 8（迁移 + 最终自查）** 留待后续 session 继续推进。

## 阶段细则

### 阶段 0：清理当前不安全状态
- 恢复 `permissions.guard.ts` 的 scope 校验（临时兜底，阶段 2 完工后废除）
- 删 orphan：`PERMISSION_SCOPE_KEY` / `PermissionScope` / `RequireOrganizationPermissions` / `RequireGlobalPermissions` 的 export（或标记 deprecated 抛警告）
- 注意：controller 里已改为 `@RequirePermissions` 的不回退，但 Guard 恢复 scope 检查；短期内 controller 不挂 scope metadata = 没有 scope 约束 → 相当于 `PermissionScope.ALL`，这就是本阶段的"兜底语义"（比 #138 当前状态更安全：至少 admin 检查和权限码仍生效）

### 阶段 1：Layer 1 Token 改造
- JWT payload 仅 `{ userId, exp, jti }`
- Access 30min + Refresh 30d + `POST /auth/refresh`
- Redis 黑名单（JTI 做 key，TTL = 剩余有效期）
- `user:${userId}:active_jtis` 列表（解雇场景主动失效）
- `@nestjs/throttler` 登录限流 30s ≤ 5 次
- MFA 骨架（敏感操作触发）

### 阶段 2：Layer 4 读路径完整实现
- `DataScopeService.resolve`：按 resource 独立合并 + 仅当前组织 + `*` 兜底候选池
- `OrganizationContextService.getDepartmentTreeIds`：Redis 缓存（`dept_tree:${deptId}` TTL 1h）+ maxDepth 异常
- `DataScopeInterceptor` 全局注册 + `@DataScope` 装饰器消费
- 所有读业务 controller 加 `@DataScope('resource')`
- Service 层 `findUnique` 合并 `dataScopeFilter` → 404 语义
- 未知 resource WARN + metric
- CUSTOM 抛 `NotImplementedException`
- Resource 命名规范落地 + seed 校验

### 阶段 3：Layer 4 写路径 + IDOR 防护
- `assertAccess(user, resource, record)` 实现
- `@SkipAssertAccess('理由')` 装饰器 + 理由必填
- 静态契约检查脚本（AST 扫描）+ pre-commit / CI 挂载
- 所有 update/delete service 补 `assertAccess`
- 写路径服务端强制覆盖 `organizationId`
- `POST /system/...` 专用接口
- 404 vs 403 错误码 + `SYSTEM_RECORD_READ_ONLY`

### 阶段 4：Layer 4 治理 + 清理
- 配置 ceiling 校验（分配 DataScope 接口）
- DataScope 配置变更审计（4 张表）
- Administrator 权限跳过必记审计
- ForbiddenException 带结构化字段
- Administrator 角色名统一
- 验证 orphan 清零

### 阶段 5：委托 + Access Review + 异步身份
- `UserDelegation` model + 迁移
- 委托合并 + ceiling + 禁止链式 + 审计
- `UserRole.lastReviewedAt` 等字段 + 90 天扫描
- 异步任务：actor 字段 + `MissingActorException` + System Principal 审计
- 所有 cron/queue/webhook 处理器改造
- 部门树超限抛 `DepartmentTreeTooDeepException`
- Metric `data_scope.unknown_resource`

### 阶段 6：字段级权限 + 脱敏
- `FieldPermission` model + 迁移
- `FieldPermissionService.filter`
- `@Sensitive` / `@Masked` 装饰器
- 脱敏规则库
- 1~2 个试点

### 阶段 7：前端三级保护 + UX
- 所有页面 `<PermissionGuard>`
- 所有按钮 `<Can>`
- `navigation.ts` permissions 全补
- 404 vs 403 UI
- 全局记录 read-only UI
- 委托 / Access Review 管理 UI

### 阶段 8：收尾 & 验证
- 一次性生成迁移 `npx prisma migrate dev --name iam_full_terminal_state`
- 17 决策 × 22 禁止事项自查
- `09-iam-implementation-todo.md` 全部 checked
- PR #138 描述重写
- Redis HA 部署文档 + 灰度 runbook