# 模块架构设计文档 — iam

> 模块：IAM（身份认证与权限）
> 版本：v1.0（最终态，对齐 coord-final-decisions I1-I8 + president §2.15/§2.16/§3.2/§5.5）
> 日期：2026-07-10
> 关联：
>
> - [004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)
> - [仲裁决策](../../../docs/architecture/coord-final-decisions.md)
> - [总裁裁决](../../../docs/architecture/president-final-rulings.md)
> - [iam 对接契约](../../../docs/architecture/issues/contracts/iam_contract.md)

---

## 1. 模块内部分层图

### 1.1 调用链总览

```mermaid
flowchart TB
    subgraph Client["客户端 / Gateway / BFF"]
        REST[HTTP 请求<br/>带 x-user-id / x-user-roles / x-user-data-scope 头]
        GRPC[gRPC 调用<br/>next_edu_cloud.iam.v1]
    end

    subgraph NestJS["iam 服务（NestJS Hybrid App）"]
        direction TB
        MW[AuthMiddleware<br/>已注册：me/logout/viewports/<br/>permissions/roles/audit/children]
        Guard[PermissionGuard<br/>APP_GUARD 全局守卫<br/>DB 驱动 + Redis 缓存]
        Filter[GlobalErrorFilter<br/>全局异常过滤器]

        subgraph Controllers["Controller 层（双入口）"]
            IamCtl[IamController<br/>REST /v1/iam/*]
            RbacCtl[RbacController<br/>REST /v1/iam/roles, /permissions]
            AuditCtl[AuditController<br/>REST /v1/iam/audit]
            JwksCtl[JwksController<br/>GET /v1/iam/.well-known/jwks.json]
            GrpcCtl[IamGrpcController<br/>12 RPC @ GrpcMethod]
        end

        subgraph Services["Application Service 层"]
            IamSvc[IamService<br/>认证 + RBAC + 审计编排<br/>REST 与 gRPC 共用]
            CacheSvc[PermissionCacheService<br/>Redis 权限缓存 TTL 5min]
            BlacklistSvc[TokenBlacklistService<br/>Redis jti 黑名单]
            JwksSvc[JwksService<br/>PEM→JWK 转换]
        end

        subgraph Repo["Repository 层"]
            IamRepo[IamRepository<br/>Drizzle 查询 10 表]
        end

        subgraph Outbox["Outbox 模块（shared-ts）"]
            OutboxPub[OutboxPublisher<br/>事务内写入]
            OutboxRelay[OutboxRelayWorker<br/>后台轮询 + Kafka 投递]
        end

        subgraph Infra["基础设施"]
            Db[(MySQL<br/>iam_db)]
            Redis[(Redis<br/>权限缓存 + token 黑名单)]
            Kafka[(Kafka<br/>edu.iam.* topics)]
        end
    end

    REST --> MW
    MW --> Guard
    GRPC --> Guard
    Guard --> Controllers
    Controllers --> IamSvc
    IamSvc --> IamRepo
    IamSvc --> CacheSvc
    IamSvc --> BlacklistSvc
    IamSvc --> OutboxPub
    IamRepo --> Db
    CacheSvc --> Redis
    BlacklistSvc --> Redis
    OutboxPub --> OutboxRelay
    OutboxRelay --> Kafka
    Controllers -.异常.-> Filter
```

### 1.2 中间件 / Guard / Filter 拦截顺序

```
请求进入
  → AuthMiddleware（注册于 me/logout/viewports/permissions/roles/audit/children）
  → PermissionGuard（APP_GUARD，data_scope=all 直放行 + DB 驱动 + Redis 缓存）
  → Controller Handler（Zod 校验 body / @GrpcMethod）
  → Application Service（业务编排：Repository + Cache + Outbox + 审计）
  → Repository（Drizzle 查询）
  → 异常抛出
  → GlobalErrorFilter（统一兜底，注入 traceId）
  → 响应返回
```

### 1.3 目录结构（最终态）

```
services/iam/src/
├─ iam/                          # 限界上下文：认证 + RBAC + 审计
│  ├─ iam.controller.ts          # REST /v1/iam 入口
│  ├─ iam.grpc.controller.ts     # gRPC 12 RPC 入口
│  ├─ rbac.controller.ts         # REST /v1/iam/roles, /permissions
│  ├─ audit.controller.ts        # REST /v1/iam/audit
│  ├─ jwks.controller.ts         # REST /v1/iam/.well-known/jwks.json
│  ├─ jwks.service.ts            # PEM→JWK 转换
│  ├─ iam.service.ts             # Application Service（12 RPC + Outbox + 审计）
│  ├─ iam.repository.ts          # Drizzle 查询（10 表）
│  ├─ iam.schema.ts              # 10 张表 schema + DataScope/RoleType 枚举
│  └─ iam.dto.ts                 # Zod schema
├─ config/
│  ├─ database.ts                # Drizzle 池 + getDbInstance + closeDb
│  ├─ redis.ts                   # Redis 单例
│  ├─ jwt.ts                     # RS256 密钥加载 + ttlToSeconds
│  ├─ kafka.ts                   # Kafka producer 单例 + IAM_KAFKA_TOPICS
│  └─ env.ts                     # Zod 校验环境变量
├─ middleware/
│  ├─ auth.middleware.ts         # 解析 x-user-* 头
│  └─ permission.guard.ts        # DB 驱动 + Redis 缓存权限校验
├─ shared/
│  ├─ cache/
│  │  ├─ permission-cache.service.ts  # Redis 权限缓存
│  │  └─ token-blacklist.service.ts   # Redis jti 黑名单
│  ├─ errors/                    # ApplicationError 层次 + GlobalErrorFilter
│  ├─ health/                    # /healthz + /readyz（5 依赖检查）
│  ├─ lifecycle/                 # 优雅停机（Kafka→Redis→DB）
│  └─ observability/             # logger / metrics / tracer
├─ app.module.ts                 # 根模块（IamModule + HealthModule + OutboxModule + APP_GUARD）
└─ main.ts                       # Hybrid 启动（gRPC + HTTP）
```

## 2. 领域模型

### 2.1 聚合根与实体

```mermaid
classDiagram
    class UserEntity {
        -id: string
        -email: string
        -passwordHash: string
        -name: string
        -status: UserStatus
        -dataScope: DataScope
        -passwordChangedAt: Date
        +verifyPassword(plain) bool
    }

    class RoleEntity {
        -id: string
        -name: string
        -description: string?
        -roleType: RoleType
        -level: int
    }

    class Permission {
        +id: string
        +name: string
        +resource: string
        +action: string
    }

    class RoleViewport {
        +id: string
        +roleId: string
        +viewportKey: string
        +label: string
        +route: string
        +level: ViewportLevel
        +sortOrder: int
        +requiredPermission: string?
    }

    class RefreshToken {
        +id: string
        +userId: string
        +tokenHash: string
        +jti: string
        +expiresAt: Date
        +revokedAt: Date?
    }

    class StudentGuardian {
        +id: string
        +studentId: string
        +guardianId: string
        +relation: string
    }

    class AuditLog {
        +id: string
        +actorUserId: string?
        +action: string
        +resourceType: string
        +resourceId: string
        +beforeState: string?
        +afterState: string?
        +ipAddress: string?
        +userAgent: string?
    }

    UserEntity "1" --> "many" RefreshToken : 拥有
    UserEntity "1" --> "many" StudentGuardian : 作为 guardian
    RoleEntity "1" --> "many" Permission : 通过 role_permissions
    RoleEntity "1" --> "many" RoleViewport : 配置
    UserEntity "1" --> "many" AuditLog : 作为 actor
```

### 2.2 值对象（枚举）

```typescript
enum UserStatus {
  ACTIVE = "active",
  DISABLED = "disabled",
}

// DataScope 6 级（I8 裁决：SUBJECT 替代 DISTRICT）
enum DataScope {
  SELF = "self", // L0：仅自己
  SUBJECT = "subject", // L1：科目（教师所教科目+班级）
  CLASS = "class", // L2：班级（班主任所带班级）
  GRADE = "grade", // L3：年级
  SCHOOL = "school", // L4：全校
  ALL = "all", // L5：跨校（系统管理员）
}

// 三层角色模型（§2.15）
enum RoleType {
  SYSTEM = "system", // 系统预设（admin/teacher/student/parent），level=0
  ORGANIZATION = "organization", // 组织分配（年级组长/班主任/学科组长），level=1
  TEMPORARY = "temporary", // 临时授权（代课教师），level=2
}

enum ViewportLevel {
  ADMIN = "admin",
  TEACHER = "teacher",
  STUDENT = "student",
  PARENT = "parent",
}
```

### 2.3 聚合间通信

- **同服务内**：`IamService` 直接调用 `PermissionCacheService`、`TokenBlacklistService`、`JwksService`、`IamRepository`（NestJS DI）
- **跨服务**：通过 Kafka 事件（Outbox 发布），不直接访问其他服务 DB

## 3. 数据模型

### 3.1 表清单（10 张表）

| 表名                    | 用途                         | 主键 | 唯一索引                  |
| ----------------------- | ---------------------------- | ---- | ------------------------- |
| `iam_users`             | 用户主表                     | `id` | `email`                   |
| `iam_roles`             | 角色表（role_type + level）  | `id` | `name`                    |
| `iam_user_roles`        | 用户-角色绑定                | `id` | `(userId, roleId)`        |
| `iam_permissions`       | 权限点表                     | `id` | `name`                    |
| `iam_role_permissions`  | 角色-权限映射                | `id` | `(roleId, permissionId)`  |
| `iam_refresh_tokens`    | refresh token（含 jti）      | `id` | `jti`                     |
| `iam_role_viewports`    | 角色-视口配置（含 level）    | `id` | `(roleId, viewportKey)`   |
| `iam_student_guardians` | 学生-家长关系（I6 裁决表名） | `id` | `(studentId, guardianId)` |
| `iam_user_audit_log`    | 审计日志（§5.5）             | `id` | —                         |
| `iam_password_history`  | 密码重用限制                 | `id` | —                         |

### 3.2 索引策略

| 表                      | 索引                                                                         | 用途                             |
| ----------------------- | ---------------------------------------------------------------------------- | -------------------------------- |
| `iam_users`             | PK(`id`)、UNIQUE(`email`)                                                    | 主键查询、登录                   |
| `iam_user_roles`        | UNIQUE(`userId`,`roleId`)、INDEX(`roleId`)                                   | 防重、按角色查用户               |
| `iam_role_permissions`  | UNIQUE(`roleId`,`permissionId`)、INDEX(`permissionId`)                       | 防重、按权限查角色               |
| `iam_refresh_tokens`    | UNIQUE(`jti`)、INDEX(`userId`)、INDEX(`tokenHash`)                           | jti 黑名单、按用户、按 hash 校验 |
| `iam_role_viewports`    | UNIQUE(`roleId`,`viewportKey`)                                               | 防重                             |
| `iam_student_guardians` | UNIQUE(`studentId`,`guardianId`)、INDEX(`guardianId`)                        | 防重、按家长查学生               |
| `iam_user_audit_log`    | INDEX(`actorUserId`)、INDEX(`resourceType`,`resourceId`)、INDEX(`createdAt`) | 按操作者、按资源、按时间查审计   |
| `iam_password_history`  | INDEX(`userId`,`createdAt`)                                                  | 按用户查密码历史                 |

### 3.3 读写分离策略

- **写路径**：所有 Command 走 MySQL 主库（iam 独占库）
- **读路径**：MySQL 直接读（iam 读多写少但数据量小，无需 ClickHouse 读模型）
- **缓存层**：
  - `getEffectivePermissions` 结果走 Redis 缓存（TTL 5min），Key: `iam:perm:{userId}`
  - refresh token jti 黑名单走 Redis，Key: `iam:bl:{jti}`，TTL 与 refresh_token 剩余有效期对齐

## 4. API 设计

### 4.1 REST API 清单

| Method | Path                            | 权限              | 说明                                   |
| ------ | ------------------------------- | ----------------- | -------------------------------------- |
| POST   | `/v1/iam/register`              | 公开              | 注册                                   |
| POST   | `/v1/iam/login`                 | 公开              | 登录                                   |
| POST   | `/v1/iam/refresh`               | 公开              | 刷新令牌（轮换 + 旧 jti 加黑名单）     |
| POST   | `/v1/iam/logout`                | `IAM_USER_READ`   | 登出（refresh token 加黑名单）         |
| GET    | `/v1/iam/me`                    | `IAM_USER_READ`   | 当前用户信息                           |
| GET    | `/v1/iam/viewports`             | `IAM_USER_READ`   | 当前用户视口                           |
| GET    | `/v1/iam/permissions/effective` | `IAM_USER_READ`   | 当前用户有效权限                       |
| GET    | `/v1/iam/children`              | `IAM_USER_READ`   | 家长的孩子列表                         |
| GET    | `/v1/iam/roles`                 | `IAM_ROLE_MANAGE` | 角色列表                               |
| GET    | `/v1/iam/permissions`           | `IAM_ROLE_MANAGE` | 权限点列表                             |
| GET    | `/v1/iam/audit`                 | `IAM_AUDIT_READ`  | 审计日志（支持 actor/resource 查询）   |
| GET    | `/v1/iam/.well-known/jwks.json` | 公开              | RS256 公钥 JWK Set（Gateway 拉取验签） |

### 4.2 gRPC API 清单（12 RPC，package `next_edu_cloud.iam.v1`）

| RPC                       | 请求                      | 响应                   | 说明                       |
| ------------------------- | ------------------------- | ---------------------- | -------------------------- |
| `Register`                | `{email, password, name}` | `{user, tokens}`       | 注册                       |
| `Login`                   | `{email, password}`       | `{user, tokens}`       | 登录                       |
| `RefreshToken`            | `{refreshToken}`          | `{tokens}`             | 刷新令牌                   |
| `Logout`                  | `{refreshToken, userId}`  | `{success}`            | 登出                       |
| `GetUserInfo`             | `{userId}`                | `UserInfo`             | 查询用户信息               |
| `BatchGetUsers`           | `{userIds[]}`             | `{users[]}`            | 批量查询用户（BFF 聚合用） |
| `GetEffectivePermissions` | `{userId}`                | `{permissions[]}`      | 用户有效权限               |
| `GetEffectiveAccess`      | `{userId, permission}`    | `{allowed, dataScope}` | 用户对某权限的有效访问判定 |
| `GetEffectiveDataScope`   | `{userId}`                | `{dataScope}`          | 用户数据范围               |
| `GetViewports`            | `{userId}`                | `{viewports[]}`        | 用户视口                   |
| `GetPublicKey`            | —                         | `{kid, alg, pem}`      | 公钥拉取（备用 JWKS）      |
| `GetChildrenByParent`     | `{parentId}`              | `{children[]}`         | 家长的孩子列表             |

### 4.3 JWT Payload（RS256 签发）

```typescript
interface JwtPayload {
  sub: string; // userId
  email: string;
  roles: string[]; // ['teacher', 'grade_leader']
  dataScope: DataScope; // 'class' | 'grade' | ...
  type: "access" | "refresh";
  iat: number; // 签发时间
  exp: number; // 过期时间
  iss: "next-edu-cloud";
  aud: "next-edu-cloud";
  jti: string; // JWT ID（仅 refresh token，用于黑名单）
  kid: string; // 密钥 ID（header，支持 JWKS 轮换）
}
```

- **access_token**：TTL 15min（`ACCESS_TOKEN_TTL`），RS256 签名
- **refresh_token**：TTL 7day（`REFRESH_TOKEN_TTL_DAYS`），RS256 签名，含 jti
- **密钥**：本地文件（`IAM_PRIVATE_KEY_PATH` / `IAM_PUBLIC_KEY_PATH`），启动时一次性加载

## 5. 事件设计

### 5.1 我发布的领域事件

| 事件           | 触发时机                             | Topic                   | 消费者         |
| -------------- | ------------------------------------ | ----------------------- | -------------- |
| `UserCreated`  | 注册成功                             | `edu.iam.user.events`   | core-edu / msg |
| `AuditCreated` | 关键操作（登录/角色变更/密码修改等） | `edu.iam.audit.created` | data-ana       |
| `RoleChanged`  | 角色绑定变更                         | `edu.iam.role.events`   | msg / 缓存失效 |

### 5.2 事件 Schema（events.proto）

```protobuf
message UserEvent {
  string event_id = 1;
  string aggregate_id = 2;
  string event_type = 3;
  int64 occurred_at = 4;
  string user_id = 5;
  string email = 6;
  string name = 7;
  repeated string roles = 8;
  string data_scope = 9;
  string action = 10;
  map<string, string> metadata = 11;
}

message RoleEvent {
  string event_id = 1;
  string aggregate_id = 2;
  string event_type = 3;
  int64 occurred_at = 4;
  string role_id = 5;
  string role_name = 6;
  string action = 7;
  map<string, string> metadata = 8;
}

message AuditEvent {
  string event_id = 1;
  string actor_user_id = 2;
  string action = 3;
  string resource_type = 4;
  string resource_id = 5;
  int64 occurred_at = 6;
  string ip_address = 7;
  map<string, string> metadata = 8;
}
```

### 5.3 我消费的事件

无。iam 是权限中枢，单向发布，不消费业务事件。

### 5.4 Outbox 实现策略

- **shared-ts OutboxModule**（I4 裁决）：`OutboxModule.forRoot({ config, db, kafkaProducer })`
- **表名**：`iam_outbox`
- **topic**：`edu.iam.user.events`（默认）/ `edu.iam.role.events` / `edu.iam.audit.created`
- **轮询间隔**：1000ms，批量 20 条，最大重试 5 次，退避 1000ms
- **幂等性**：producer `idempotent=true` + `transactionalId: "iam-tx"`，consumer 基于 `event_id` 去重

```mermaid
sequenceDiagram
    participant Ctl as Controller
    participant Svc as IamService
    participant DB as MySQL
    participant Pub as OutboxPublisher
    participant Relay as OutboxRelayWorker
    participant Kafka as Kafka

    Ctl->>Svc: register(dto)
    Svc->>DB: BEGIN TX
    Svc->>DB: INSERT iam_users
    Svc->>DB: INSERT iam_user_roles
    Svc->>DB: INSERT iam_user_audit_log
    Svc->>Pub: publish(UserCreated + AuditCreated)
    Pub->>DB: INSERT iam_outbox
    Svc->>DB: COMMIT TX
    Svc-->>Ctl: {user, tokens}

    loop 每 1000ms 轮询
        Relay->>DB: SELECT pending LIMIT 20
        Relay->>Kafka: produce(topic, payload)
        Kafka-->>Relay: ack
        Relay->>DB: UPDATE status='published'
    end
```

## 6. 横切关注点对齐清单

### 6.1 权限装饰器

每个 Controller 方法用 `@RequirePermission()` 装饰器声明权限点。权限点常量：

```typescript
export const Permissions = {
  IAM_USER_READ: "iam:user:read",
  IAM_USER_MANAGE: "iam:user:manage",
  IAM_ROLE_MANAGE: "iam:role:manage",
  IAM_AUDIT_READ: "iam:audit:read",
  IAM_VIEWPORT_READ: "iam:viewport:read",
} as const;
```

### 6.2 错误码清单

| 错误码                  | HTTP | 触发条件                                             |
| ----------------------- | ---- | ---------------------------------------------------- |
| `IAM_VALIDATION_ERROR`  | 400  | Zod 校验失败                                         |
| `IAM_UNAUTHORIZED`      | 401  | 未登录、密码错误、token 失效、refresh token 在黑名单 |
| `IAM_PERMISSION_DENIED` | 403  | 缺少所需权限点                                       |
| `IAM_NOT_FOUND`         | 404  | 用户/角色/权限/视口不存在                            |
| `IAM_CONFLICT`          | 409  | 邮箱已注册、角色名重复、家长-学生关系已存在          |
| `IAM_BUSINESS_ERROR`    | 422  | 账号禁用、系统角色禁止删除、refresh token 已撤销     |
| `IAM_DATABASE_ERROR`    | 500  | Drizzle 操作失败                                     |
| `IAM_INTERNAL_ERROR`    | 500  | 未预期异常                                           |
| `IAM_OUTBOX_ERROR`      | 500  | Outbox 写入或投递失败                                |

### 6.3 可观测性

- **日志**：pino，`base: { service: 'iam', version: '0.2.0' }`，`level: env.LOG_LEVEL`，注入 traceId
- **指标**：prom-client，`/metrics` 端点
  - `iam_login_attempts_total`、`iam_login_duration_seconds`
  - `iam_jwt_issued_total`（type=access/refresh）
  - `iam_permission_cache_hits_total` / `iam_permission_cache_misses_total`
  - `iam_outbox_pending`、`iam_outbox_publish_duration_seconds`
- **链路**：OpenTelemetry SDK + OTLP exporter，serviceName: `iam`

### 6.4 健康检查

- **`/healthz`**：liveness，仅返回进程存活
  - 响应：`{ status: 'ok', service: 'iam', timestamp: ISO }`
- **`/readyz`**：readiness，5 依赖检查
  - DB：`SELECT 1`
  - Redis：`ping`
  - Kafka：producer 实例存在且已连接
  - JWKS：密钥文件可读
  - gRPC：进程内 microservice 存在
  - 失败：HTTP 503，响应体含失败项详情

### 6.5 优雅关闭顺序

```typescript
async onApplicationShutdown(signal?: string) {
  // 1. 停止接收新请求（NestJS 自动）
  // 2. 停止 OutboxRelayWorker（shared-ts 自动）
  // 3. 关闭 Kafka producer
  await closeKafkaProducer();
  // 4. 关闭 Redis 连接
  await closeRedis();
  // 5. 关闭 MySQL 连接池
  await closeDb();
}
```

## 7. 与其他模块的交互点（契约清单）

| 方向   | 对方服务    | 协议  | 接口/事件                                         | 用途                            |
| ------ | ----------- | ----- | ------------------------------------------------- | ------------------------------- |
| 被调用 | api-gateway | HTTP  | `POST /v1/iam/register` 等                        | Gateway 反向代理 `/iam/v1/*`    |
| 被调用 | api-gateway | HTTP  | `GET /v1/iam/.well-known/jwks.json`               | Gateway 拉取 RS256 公钥校验 JWT |
| 被调用 | teacher-bff | gRPC  | `GetUserInfo`、`BatchGetUsers`、`GetViewports` 等 | BFF 聚合用户身份与视口          |
| 被调用 | student-bff | gRPC  | 同上                                              | 同上                            |
| 被调用 | parent-bff  | gRPC  | `GetChildrenByParent`                             | 家长视角聚合孩子信息            |
| 发布   | —           | Kafka | `edu.iam.user.events`                             | core-edu / msg 消费             |
| 发布   | —           | Kafka | `edu.iam.role.events`                             | msg / 缓存失效                  |
| 发布   | —           | Kafka | `edu.iam.audit.created`                           | data-ana 消费                   |

### 7.1 端口分配

| 服务     | 端口  | 备注                 |
| -------- | ----- | -------------------- |
| iam HTTP | 3002  | REST 入口            |
| iam gRPC | 50052 | gRPC 入口（I1 裁决） |

### 7.2 Topic 命名

- `edu.iam.user.events`
- `edu.iam.role.events`
- `edu.iam.audit.created`

## 8. 仲裁裁决对齐

### 8.1 I1-I8 裁决

| 裁决 | 内容                                 | 实现位置                                          |
| ---- | ------------------------------------ | ------------------------------------------------- |
| I1   | 双入口（REST + gRPC），gRPC 50052    | main.ts Hybrid app + iam.grpc.controller.ts       |
| I2   | JWT RS256 本地文件密钥               | config/jwt.ts + env IAM_PRIVATE/PUBLIC_KEY_PATH   |
| I3   | DB 驱动 + Redis 缓存 PermissionGuard | permission.guard.ts + permission-cache.service.ts |
| I4   | shared-ts OutboxModule 接入          | app.module.ts OutboxModule.forRoot                |
| I5   | /iam/v1/* 前缀                       | iam.controller.ts @Controller("v1/iam")           |
| I6   | iam_student_guardians 表名           | iam.schema.ts + iam-init.sql                      |
| I7   | jti 黑名单                           | token-blacklist.service.ts                        |
| I8   | DataScope SUBJECT 替代 DISTRICT      | iam.schema.ts DataScope enum                      |

### 8.2 总裁裁决

| 裁决  | 内容                                          | 实现位置                                     |
| ----- | --------------------------------------------- | -------------------------------------------- |
| §2.15 | 三层角色模型（system/organization/temporary） | iam.schema.ts RoleType + iam_roles.level     |
| §2.16 | 双入口策略（同一 IamService）                 | iam.service.ts REST 与 gRPC 共用             |
| §3.2  | AuthMiddleware 注册                           | app.module.ts configure()                    |
| §5.5  | 审计日志（iam_user_audit_log + AuditEvent）   | iam.schema.ts + iam.service.ts writeAuditLog |

## 9. 技术风险

| 风险                 | 影响                               | 缓解措施                                                 |
| -------------------- | ---------------------------------- | -------------------------------------------------------- |
| Redis 不可用         | 权限校验回退到 DB 查询，性能下降   | `getEffectivePermissions` catch 后走 DB，不抛错          |
| Kafka 不可用         | Outbox 事件积压，下游服务感知延迟  | Relay Worker 重试 + `status='failed'` 记录，不阻塞主流程 |
| RS256 密钥泄露       | 任何人可伪造 JWT                   | 密钥文件权限 600 + 容器 Secret 挂载                      |
| 权限缓存与 DB 不一致 | 用户角色变更后 5min 内旧权限仍生效 | 角色变更主动 DEL + 短 TTL                                |
| Outbox 表膨胀        | 磁盘占用增长                       | 已发布事件定期清理（保留 7 天）                          |

---

**模块**: iam-service（@edu/iam-service v0.2.0）
**分支**: feat-implement-iam-module
**入口**: HTTP 3002 + gRPC 50052