feat: auto committed

2026-07-10 15:06:09 +08:00
parent 9ba368477d
commit 06e0f9139b
3 changed files with 296 additions and 47 deletions
--- a/docs/architecture/issues/worklines/iam_workline.md
+++ b/docs/architecture/issues/worklines/iam_workline.md
@@ -3,54 +3,154 @@
 > 负责人：ai06
 > 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
 > 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
+> 裁决依据：[coord-final-decisions](../../coord-final-decisions.md) I1-I8、[president-final-rulings](../../president-final-rulings.md) §3.2/§2.15/§2.16/§5.5

 ---

 ## §1 总览

-iam 是身份认证服务，全阶段目标：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope + 审计日志 + Outbox。
+iam 是身份认证服务，全阶段目标：gRPC 50052 + 12 RPC + REST 双入口 + /readyz 深度 + iam_student_guardians + DataScope 6 级 + 审计日志 + Outbox + RBAC CRUD 完整化。
+
+**核心裁决约束**（coord-final-decisions I1-I8）：
+
+- I1：P2 即启用 gRPC server 50052（REST + gRPC 双入口并存，非"P2 仅 REST → P3 gRPC"）
+- I2：直接用 shared-ts Outbox 工具包（非 iam 自建）
+- I3：首次实现即 DB 驱动 + Redis 缓存 PermissionGuard（废弃硬编码 ROLE_PERMISSIONS map）
+- I4：首次实现即注册 AuthMiddleware（Controller 通过 @Req() 注入用户上下文）
+- I5：P2 本地文件 RS256 密钥（IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH），P6 迁 Vault
+- I6：P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children
+- I7：/iam/v1/* 前缀（Controller 加 v1 前缀，Gateway 透传）
+- I8：统一 GET /iam/permissions/effective
+
+**工作量分级**（president §3.2）：iam 实际工作量 26-27 天，拆分 P2.1（核心，阻塞批次 2）+ P2.2（扩展，P3 期间持续补，不阻塞）。

 ---

-## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
+## §2 全阶段甘特图（P2-P6）

 ```mermaid
 gantt
-    title ai06 iam 全阶段排期
+    title ai06 iam 全阶段排期（P2.1/P2.2 拆分版）
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

-    section P2.1 核心
-    gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
-    12 RPC实现 :crit, a6b, after a6a, 4d
-    /readyz深度(5依赖) :a6c, after a6b, 1d
-    iam_student_guardians+DataScope :a6d, after a6b, 1d
+    section P2.1 核心（阻塞批次2）
+    1.1 proto 契约确认(依赖coord补全iam.proto) :crit, a1, 2026-07-10, 1d
+    1.2 gRPC server 50052 + AuthMiddleware注册 :crit, a2, after a1, 2d
+    1.3 8 RPC实现(GetViewports/GetEffectivePermissions/GetEffectiveAccess/Logout/GetPublicKey/BatchGetUsers/GetEffectiveDataScope/GetChildrenByParent) :crit, a3, after a2, 4d
+    1.4 JWT RS256本地文件+refresh轮换 :crit, a4, after a2, 2d
+    1.5 /iam/v1/*前缀迁移+端点统一(I7/I8) :crit, a5, after a3, 1d
+    1.6 iam_student_guardians表+GetChildrenByParent(I6) :crit, a6, after a3, 1d
+    1.7 shared-ts Outbox接入+事件发布(I2) :crit, a7, after a3, 2d
+    1.8 DB驱动PermissionGuard基础(I3) :crit, a8, after a3, 2d
+    1.9 /readyz深度(5依赖:DB/Redis/Kafka/gRPC/JWKS) :a9, after a8, 1d
+    1.10 02文档回写(I1-I8对齐) :crit, a10, 2026-07-10, 1d

-    section P2.2-P6 扩展
-    审计日志+Outbox :a6e, after a6d, 3d
-    持续补全 :a6f, after a6e, 5d
+    section P2.2 扩展（P3期间持续补）
+    2.1 三层角色模型(system/organization/temporary) :b1, after a8, 3d
+    2.2 DataScope 6级实现(待ISSUE-004裁决) :b2, after a8, 2d
+    2.3 视口4层+getEffectivePermissions完整 :b3, after b1, 3d
+    2.4 审计日志(user_audit_log表+AuditEvent发布) :b4, after b1, 3d
+    2.5 Redis缓存完整实现(I3完整) :b5, after b1, 2d
+    2.6 密码策略(强度/过期/重用限制) :b6, after b4, 2d
+    2.7 单元测试+集成测试(覆盖率≥80%) :b7, after b6, 3d
+
+    section P3-P6 持续优化
+    3.1 RBAC CRUD完整化(角色/权限/视口增删改) :c1, after b3, 3d
+    3.2 2FA实现(TOTP) :c2, after b6, 3d
+    3.3 JWT密钥迁移Vault(P6) :c3, after c2, 2d
+    3.4 /readyz硬化+性能优化 :c4, after c1, 2d
 ```

-> **注意**：以上为 coord 初始规划，ai06 接管后必须自行细化为完整 P2-P6 排期。
-
 ---

 ## §3 详细任务

-### P2.1：gRPC + 12 RPC + /readyz + DataScope
+### P2.1：gRPC + 8 RPC + RS256 + AuthMiddleware + Outbox（阻塞批次 2）

 - **负责人**：ai06
+- **批次**：批次 1（P2）
+- **预估**：5-7 天
+- **前置依赖**：
+  - coord 补全 iam.proto 至 12 RPC（ISSUE-005，阻塞项）
+  - coord 补全 events.proto UserEvent/RoleEvent（ISSUE-002，阻塞 Outbox 事件发布）
+  - shared-ts Outbox 工具包已就绪（✅ 已存在）
 - **交付物**：
-  - gRPC server 50052 + 12 RPC（见 iam.proto）
-  - /readyz 5 项依赖检查
-  - iam_student_guardians 表 + DataScope=CHILDREN
- **依赖**：iam.proto（批次 0 已完成）
- **验收标准**：12 RPC 全部可用 + /readyz 返回 5 项状态
- **完整 P2.2-P6 任务**：⚠️ 由 ai06 自行补充
+  1. gRPC server 50052 启用（NestJS gRPC transport）
+  2. 8 RPC 实现：GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent
+  3. AuthMiddleware 注册（app.module.ts configure 消费），Controller 改用 @Req() 注入用户上下文（I4）
+  4. JWT RS256 本地文件加载（IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH）+ refresh token 轮换 + 旧 token 黑名单（I5）
+  5. /iam/v1/* 前缀迁移（Controller `@Controller('v1/iam')`）+ 端点路径统一 I8（I7）
+  6. iam_student_guardians 表 + GET /iam/v1/children REST + GetChildrenByParent gRPC（I6）
+  7. shared-ts Outbox 接入，发布 UserEvent/RoleEvent（I2）
+  8. DB 驱动 PermissionGuard 基础（废弃 permission.guard.ts 硬编码 ROLE_PERMISSIONS map，改调 IamService.getEffectivePermissions）（I3）
+  9. /readyz 深度检查 5 项依赖（DB SELECT 1 / Redis PING / Kafka 连接 / gRPC 自身可达 / JWKS 可读）
+  10. 01/02 文档回写（删除全部中间过渡方案，对齐 I1-I8 + §2.15/§2.16/§5.5）
+- **验收标准**：
+  - gRPC 50052 HealthService.Check 返回 SERVING
+  - 8 RPC 全部可调用并返回正确响应
+  - GetPublicKey 返回 RS256 PEM 公钥（供 api-gateway 验签）
+  - GetChildrenByParent 返回学生列表（供 parent-bff P4 消费）
+  - /iam/v1/* 前缀生效，旧路径不保留
+  - AuthMiddleware 注入 req.user（userId/roles/dataScope）
+  - /readyz 返回 5 项依赖状态
+- **就绪信号**：gRPC 50052 启用 + GetPublicKey RPC 可用 + HealthService.Check 返回 SERVING
+
+### P2.2：三层角色 + DataScope + 视口 + 审计 + 缓存（P3 期间持续补，不阻塞）
+
+- **负责人**：ai06
+- **批次**：批次 2-3 期间（P3 进行中持续补）
+- **预估**：12-15 天
+- **前置依赖**：P2.1 完成 + ISSUE-004（DataScope 枚举裁决）
+- **交付物**：
+  1. 三层角色模型（system / organization / temporary，iam_roles 表扩展 role_type + level 字段）
+  2. DataScope 6 级实现（ALL / SCHOOL / GRADE / CLASS / SUBJECT|DISTRICT / SELF，待 ISSUE-004 裁决）
+  3. 视口 4 层（admin / teacher / student / parent）+ getEffectivePermissions 完整聚合
+  4. 审计日志（user_audit_log 表 + AuditEvent 发布到 edu.iam.audit.created topic，president §5.5）
+  5. Redis 缓存完整实现（getEffectivePermissions TTL 5min + 角色变更主动 DEL + getUserViewports 缓存）
+  6. 密码策略（强度校验 / 过期提醒 / 重用限制）
+  7. 单元测试 + 集成测试（覆盖率 ≥ 80%，对齐 classes 黄金模板）
+- **验收标准**：
+  - 三层角色可创建/分配/查询
+  - DataScope 在 Repository 层动态注入 WHERE 条件
+  - 审计事件可发布到 Kafka
+  - Redis 缓存命中率可观测（iam_permission_cache_hits_total 指标）
+  - 测试覆盖率 ≥ 80%
+
+### P3-P6：RBAC CRUD + 2FA + Vault 迁移 + 硬化
+
+- **负责人**：ai06
+- **批次**：批次 4-5（P5-P6 期间）
+- **预估**：8-10 天
+- **交付物**：
+  1. RBAC CRUD 完整化（角色/权限/视口增删改，系统角色禁止删除）
+  2. 2FA 实现（TOTP，pending-features §P2 提及）
+  3. JWT 密钥迁移 Vault（P6，president X8）
+  4. /readyz 硬化 + 性能优化（连接池调优、缓存策略优化）
+- **验收标准**：
+  - RBAC CRUD 全部端点可用 + 权限装饰器覆盖
+  - 2FA 可启用/验证/禁用
+  - Vault 密钥轮换不中断服务

 ---

 ## §4 依赖与就绪信号

- **我依赖**：无（iam 是基础服务）
- **我的就绪信号**：gRPC 50052 启用 + GetPublicKey RPC 可用 + HealthService.Check 返回 SERVING
+### 4.1 我依赖的上游就绪标志
+
+| 依赖项 | 提供方 | 就绪标志 | 状态 |
+| ------ | ------ | -------- | ---- |
+| iam.proto 补全至 12 RPC | coord | proto 文件含 12 RPC + 全部 message | ❌ 仅 4 RPC（ISSUE-005） |
+| events.proto 补全 UserEvent/RoleEvent/AuditEvent | coord | proto 文件含 3 个 message | ❌ 缺失（ISSUE-002） |
+| shared-ts Outbox 工具包 | coord | outbox.service.ts + outbox.module.ts 可导入 | ✅ 已就绪 |
+| shared-ts Redis 工具包 | coord | redis client 单例可导入 | ⏳ 待确认 |
+
+### 4.2 我的就绪信号（供下游消费）
+
+- [ ] iam gRPC 50052 启用（HealthService.Check 返回 SERVING）
+- [ ] IamService 12 RPC 全部可调用（Register/Login/RefreshToken/Logout/GetUserInfo/BatchGetUsers/GetEffectivePermissions/GetEffectiveAccess/GetEffectiveDataScope/GetViewports/GetPublicKey/GetChildrenByParent）
+- [ ] IamService.GetPublicKey 可用（返回 RS256 PEM 公钥，供 api-gateway 验签）
+- [ ] IamService.GetChildrenByParent 可用（供 parent-bff 查孩子列表）
+- [ ] edu.iam.user.events / edu.iam.role.events / edu.iam.audit.created topic 可发布
+- [ ] JWT RS256 签发链路打通（access_token 15min + refresh_token 7day 轮换）
+- [ ] /iam/v1/* REST 端点可用（供 gateway 透传 + admin-portal 直连）