chore(iam): merge iam full implementation into main

Merge feat/iam-ai06 with complete iam service implementation

docs/troubleshooting/known-issues.md

@@ -242,26 +242,32 @@
 | AppModule 注册   | HealthModule 必须在 `app.module.ts` imports 数组显式声明，否则 NestFactory 不扫描 HealthController |
 | 增量编译陷阱     | `tsconfig.json` 显式 `"incremental": false` 覆盖 base，避免 .tsbuildinfo 导致 nest watch 不 emit   |
 
-### 2.3 iam（TS/NestJS，P2）
+### 2.3 iam（TS/NestJS）
 
-| 场景              | 技术/规则                                                                                                                |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| 认证              | 登录/登出/JWT/2FA，RS256 非对称签名                                                                                      |
-| RBAC              | 角色/权限/角色-权限 CRUD + `getEffectivePermissions(userId)` API                                                         |
-| 视口配置          | 4 层模型（导航/路由/组件/数据），`role_viewports` 表                                                                     |
-| DataScope 解析    | 6 级数据范围，注入 JWT payload                                                                                           |
-| JWT payload       | `{ userId, roles, permissions(bitmap), dataScope, exp }`                                                                 |
-| Token TTL         | access 15min / refresh 7day，refresh 用 Redis 黑名单失效                                                                 |
-| 权限缓存          | `getEffectivePermissions` 结果 Redis 缓存 TTL 5 分钟，角色变更主动失效                                                   |
-| schema 表         | users / roles / permissions / role_permissions / role_viewports / parent_student_relations / class_subject_teachers      |
-| ESM 模式 DI       | `providers: [IamService, IamRepository]` + 构造器 `@Inject(IamRepository)` 显式注入，避免 `undefined` 运行时错误         |
-| Drizzle ORM API   | `inArray(col, vals)` 替代不存在的 `.in()`；select 返回字段名按 schema 定义（如 `r.iam_roles` 而非 `r.roles`）            |
-| 健康检查依赖      | `readyz` 用 `db.execute(sql\`SELECT 1\`)` 校验连接，不要依赖 typeorm DataSource（IAM 用 Drizzle，无 typeorm）            |
-| Gateway 身份传递  | Controller 直接读 `req.headers['x-user-id']` / `x-user-roles`，不要依赖未注册的 AuthMiddleware 的 `AuthenticatedRequest` |
-| DEV_MODE 登录     | DEV_MODE=true 时 Gateway 接受 `Bearer dev-token` 注入固定身份，IAM 仍支持真实 JWT（HS256，P2 应改 RS256）                |
-| P2 公开路径白名单 | Gateway `publicPaths` map 含 `/iam/register`/`/iam/login`/`/iam/refresh`，AuthMiddleware 跳过鉴权避免死锁                |
-| P2 视口过滤       | `getUserViewports` 按 `requiredPermission` 过滤 + `sortOrder` 字典序排序，无权限要求的视口全员可见                       |
-| P2 JWT payload    | HS256 签名含 `sub/email/roles/dataScope/type`，register 自动分配 teacher 角色（TEACHER_ROLE_ID 固定 UUID）               |
+| 场景                    | 技术/规则                                                                                                                                                                                     |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 双入口                  | REST `/v1/iam/*` + gRPC 50052（package `next_edu_cloud.iam.v1`），同一 IamService 实例共用（Hybrid app `connectMicroservice`）                                                                |
+| 认证                    | RS256 非对称签名，私钥本地文件（`IAM_PRIVATE_KEY_PATH`），公钥通过 JWKS 端点暴露给 Gateway                                                                                                    |
+| JWT payload             | `{ sub, email, roles, dataScope, type, iss, aud, jti(仅 refresh), kid(header) }`，register 自动分配 teacher 角色                                                                              |
+| Token TTL               | access 15min / refresh 7day，refresh 含 jti，轮换时旧 jti 加入 Redis 黑名单                                                                                                                   |
+| RBAC                    | 角色/权限/角色-权限查询 + `getEffectivePermissions(userId)` API，三层角色模型（system/organization/temporary，level 0/1/2）                                                                   |
+| 视口配置                | 4 层模型（导航/路由/组件/数据），`iam_role_viewports` 表含 `level` ENUM(admin/teacher/student/parent)                                                                                         |
+| DataScope 解析          | 6 级：self/subject/class/grade/school/all（SUBJECT 替代 DISTRICT），注入 JWT payload                                                                                                          |
+| 权限校验                | PermissionGuard（APP_GUARD）DB 驱动 + Redis 缓存 TTL 5min，`data_scope=all` 直放行，Key `iam:perm:{userId}`                                                                                   |
+| Token 黑名单            | Redis Key `iam:bl:{jti}` TTL 与 refresh_token 剩余有效期对齐，logout/refresh 时写入                                                                                                           |
+| 审计日志                | `iam_user_audit_log` 表 + `AuditCreated` Kafka 事件，登录/角色变更/密码修改等关键操作记录                                                                                                     |
+| 家长-学生关系           | `iam_student_guardians` 表（unique(studentId, guardianId)），`GetChildrenByParent` RPC + `GET /v1/iam/children` REST                                                                          |
+| schema 表               | iam_users / iam_roles / iam_user_roles / iam_permissions / iam_role_permissions / iam_refresh_tokens / iam_role_viewports / iam_student_guardians / iam_user_audit_log / iam_password_history |
+| Outbox                  | shared-ts `OutboxModule.forRoot({ config, db, kafkaProducer })`，表名 `iam_outbox`，topic `edu.iam.user.events`/`edu.iam.role.events`/`edu.iam.audit.created`                                 |
+| AuthMiddleware 注册     | `app.module.ts` `configure()` 注册于 me/logout/viewports/permissions/roles/audit/children 路由，解析 `x-user-*` 头                                                                            |
+| 公开路径                | register/login/refresh/jwks.json 无 `@RequirePermission()`，PermissionGuard 旁路                                                                                                              |
+| ESM 模式 DI             | `providers: [IamService, IamRepository]` + 构造器 `@Inject(IamRepository)` 显式注入，避免 `undefined` 运行时错误                                                                              |
+| Drizzle ORM API         | `inArray(col, vals)` 替代不存在的 `.in()`；`delete().where()` 不支持链式多次 where，用 `and(eq(...), eq(...))` 组合                                                                           |
+| Drizzle DataScope 类型  | `mysqlEnum` 推断类型为字面量联合，Repository 方法参数须用 `DataScope` 类型而非 `string`，否则 TS 报错                                                                                         |
+| ioredis 类型            | `import { Redis } from "ioredis"`（named import），`type RedisClient = InstanceType<typeof Redis>`，默认导入在 TS 中不可构造                                                                  |
+| jwt.sign expiresIn 类型 | `@types/jsonwebtoken` v9 `expiresIn` 类型为 `number \| StringValue`，普通 string 不兼容，用 `ttlToSeconds(ttl)` 返回 number                                                                   |
+| 健康检查依赖            | `/readyz` 5 依赖：DB(SELECT 1) / Redis(ping) / Kafka(producer 实例) / JWKS(密钥文件可读) / gRPC(进程内)                                                                                       |
+| 优雅停机                | 顺序：Kafka producer disconnect → Redis quit → DB pool end（LifecycleService `onApplicationShutdown`）                                                                                        |
 
 ### 2.4 core-edu（TS/NestJS，P3）