Edu/docs/architecture/issues/objections/iam_issue.md

# iam 问题记录

> 负责人：ai06
> 关联：[coord.md](../coord.md)、[contracts/iam_contract.md](../contracts/iam_contract.md)
> 规则：AI 遇到问题时在此追加条目，coord 仲裁后更新状态

---

## §1 已有仲裁核查

> 对已生效的仲裁（coord-final-decisions I1-I8、president-final-rulings 相关条款、coord.md ARB-001/ARB-002）逐条核查落地情况。

### 1.1 coord-final-decisions I1-I8（iam 专项）核查

| 裁决 | 内容摘要                                                                         | 核查结论                                                                                                                                                                                                  | 证据                                                                                                                                                |
| ---- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| I1   | P2 即启用 gRPC server 50052，REST + gRPC 并存                                    | ⚠️ **02 文档未回写**：[02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) §1/§7.1/§8.1 决策点 5 仍写"P2 仅 REST，P3 随 core-edu 引入 gRPC"；iam.proto 仅 4 RPC 未补全       | [iam.proto](../../../packages/shared-proto/proto/iam.proto) 仅 4 RPC；[02 文档 §8.1](../../../services/iam/docs/02-architecture-design.md) 决策点 5 |
| I2   | 直接建 shared-ts Outbox 工具包，iam 首次实现即用                                 | ✅ **工具包已建立**：`packages/shared-ts/src/outbox/` 存在 outbox.service.ts + outbox.module.ts；⚠️ 02 文档 §8.1 决策点 4 仍写"iam 自建轻量 Outbox"，未回写                                               | [shared-ts/outbox](../../../packages/shared-ts/src/outbox/)                                                                                         |
| I3   | 首次实现即 DB 驱动 + Redis 缓存，废弃本地 map                                    | ❌ **源码未改造**：[permission.guard.ts](../../../services/iam/src/middleware/permission.guard.ts) 第 30-39 行仍用硬编码 `ROLE_PERMISSIONS` map（admin/teacher）；02 文档 §8.1 决策点 9 描述为"待改造"    | [permission.guard.ts](../../../services/iam/src/middleware/permission.guard.ts)                                                                     |
| I4   | 首次实现即注册 AuthMiddleware，Controller 用 @Req() 注入                         | ❌ **源码未注册**：[app.module.ts](../../../services/iam/src/app.module.ts) 仅注册 PermissionGuard 为 APP_GUARD，未在 configure() 消费 AuthMiddleware；02 文档 §1.1/§1.2/§8.1 决策点 10 仍写"P2 仍不注册" | [app.module.ts](../../../services/iam/src/app.module.ts)                                                                                            |
| I5   | P2 本地文件 IAM_PRIVATE_KEY_PATH / IAM_PUBLIC_KEY_PATH                           | ⚠️ **源码未实现**：[iam.service.ts](../../../services/iam/src/iam/iam.service.ts) 第 170-186 行仍用 `env.JWT_SECRET`（HS256 单密钥）；02 文档 §8.1 决策点 1 已对齐（本地文件→P6 Vault）但未落地           | [iam.service.ts](../../../services/iam/src/iam/iam.service.ts)                                                                                      |
| I6   | P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC + GET /iam/children | ❌ **02 文档表名错误**：[02 文档 §3.1.2](../../../services/iam/docs/02-architecture-design.md) 用 `iam_parent_student_relations`，裁决表名为 `iam_student_guardians`；源码未实现                          | 02 文档 §3.1.2                                                                                                                                      |
| I7   | 采用 /iam/v1/* 前缀，Gateway 透传                                                | ❌ **02 文档未回写**：[02 文档 §4.1](../../../services/iam/docs/02-architecture-design.md) REST API 清单全部用 `/iam/*` 无 `/v1` 前缀；源码 Controller 用 `@Controller("iam")` 无版本前缀                 | [iam.controller.ts](../../../services/iam/src/iam/iam.controller.ts)、[rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts)        |
| I8   | 统一 GET /iam/permissions/effective                                              | ✅ **源码已对齐**：[rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts) 第 33 行用 `@Get("permissions/effective")`                                                                      | [rbac.controller.ts](../../../services/iam/src/iam/rbac.controller.ts)                                                                              |

### 1.2 president-final-rulings 相关条款核查

| 条款  | 内容摘要                                                                       | 核查结论                                                                                                                                                          |
| ----- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| §2.15 | /iam/v1/* 版本化规则（Controller 加 v1 前缀）                                  | ❌ 同 I7，未落地                                                                                                                                                  |
| §2.16 | gRPC 与 REST 双入口策略（gateway HTTP 透传 + BFF gRPC 调用）                   | ⚠️ 02 文档未体现双入口设计，仅描述 REST 单入口；contract.md §1.2 写"无对外 HTTP 端点，仅 gRPC"与此冲突                                                            |
| §3.2  | iam P2 拆分 P2.1（8 RPC 核心）+ P2.2（扩展）                                   | ⚠️ workline.md 仅粗略列出 P2.1，P2.2-P6 未细化（见 worklines/iam_workline.md）                                                                                    |
| §5.5  | 审计日志归 iam（AuditEvent + edu.iam.audit.created topic + user_audit_log 表） | ❌ 02 文档未包含审计日志设计；events.proto 未定义 AuditEvent message                                                                                              |
| §5.1  | events.proto 补全 UserEvent/RoleEvent                                          | ❌ events.proto 实际仅含 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent，缺 UserEvent/RoleEvent/AuditEvent（coord-final-decisions §5.1 标注"✅ 已补全"与实际不符） |

### 1.3 coord.md ARB-001 / ARB-002 核查

| 仲裁    | 内容摘要                                     | 核查结论                                                                                         |
| ------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| ARB-001 | teacher-bff GraphQL schema 第一版（5 Query） | ✅ schema 中 `me: User!`、`viewports` 依赖 iam，与 iam GetUserInfo/GetViewports RPC 对齐，无冲突 |
| ARB-002 | MF Shell 暴露清单                            | ✅ 不涉及 iam 直接交付物，无冲突                                                                 |

---

## §2 新提请异议

### ISSUE-001-ai06：01/02 文档未回写 I1-I8 裁决，中间过渡方案残留

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确 / 其他
- **描述**：coord-final-decisions §0.1 强制覆盖声明要求各 AI 在 3 个工作日内回写 02 文档，删除所有"中间过渡方案"。president-final-rulings §3.4 也明确要求 ai06 回写 iam 02（I1-I8，§3.4）。但当前 [01-understanding.md](../../../services/iam/docs/01-understanding.md) 和 [02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) 仍残留大量过渡方案：
  - 02 §1/§7.1/§8.1 决策点 5：P2 仅 REST → P3 gRPC（违反 I1）
  - 02 §8.1 决策点 4：iam 自建 Outbox（违反 I2）
  - 02 §8.1 决策点 9：PermissionGuard 待改造（违反 I3）
  - 02 §1.1/§1.2/§8.1 决策点 10：AuthMiddleware P2 不注册（违反 I4）
  - 02 §3.1.2：表名 iam_parent_student_relations（违反 I6）
  - 02 §4.1：API 路径无 /v1 前缀（违反 I7）
  - 01 §1：teacher-bff HTTP 调用 iam（违反 B2，应 gRPC）
- **建议方案**：ai06 立即回写 01/02 文档，删除全部中间过渡方案描述，对齐 I1-I8 + §2.15/§2.16/§5.5 最终方案。
- **状态**：待 coord 仲裁（确认回写范围与验收标准）

### ISSUE-002-ai06：events.proto 缺少 UserEvent/RoleEvent/AuditEvent message

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：coord-final-decisions §5.1 标注"events.proto ✅ 已补全（UserEvent/RoleEvent/NotificationEvent/MasteryEvent/AIUsageEvent/KnowledgePointEvent/QuestionEvent）"，president §5.5 也要求"events.proto 补 AuditEvent 在批次 0.10 完成"。但实际 [events.proto](../../../packages/shared-proto/proto/events.proto) 仅定义 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent 4 个 message，**完全缺少** UserEvent/RoleEvent/AuditEvent 等 iam 依赖的事件契约。这直接阻塞 iam Outbox 事件发布（iam 无法写入未定义 schema 的事件）。
- **建议方案**：coord 立即补全 events.proto，至少新增 UserEvent、RoleEvent、AuditEvent 三个 message（按 02 文档 §5.2 和 president §5.5 的字段定义）。
- **状态**：待 coord 仲裁

### ISSUE-003-ai06：Topic 命名三方不一致（edu.identity.* vs edu.iam.*）

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：iam 事件 Topic 命名存在三方不一致：
  - [004 §7.2](../../../docs/architecture/004_architecture_impact_map.md) 行 620-621：`edu.identity.user.created` / `edu.identity.user.updated`（用 `identity` 域名）
  - [matrix.md §4](../matrix.md) / [iam_contract.md §1.4](../contracts/iam_contract.md)：`edu.iam.user.events` / `edu.iam.role.events` / `edu.iam.audit.created`（用 `iam` 域名）
  - president §5.5：`edu.iam.audit.created`（用 `iam` 域名）
  - coord-final-decisions G16 规则：`edu.<domain>.<aggregate>.<action>`
- **建议方案**：统一用 `edu.iam.*`（服务名为 iam，非 identity），coord 同步修正 004 §7.2 的 `edu.identity.*` → `edu.iam.*`。同时明确 Topic 粒度：matrix.md 用聚合 topic（`edu.iam.user.events` 含多 action），004 §7.2 用具体动作 topic（`edu.iam.user.created`），需统一为一种风格。
- **状态**：待 coord 仲裁

### ISSUE-004-ai06：DataScope 枚举三方不一致

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：DataScope 6 级枚举存在三方不一致：
  - [004 §5.3 表](../../../docs/architecture/004_architecture_impact_map.md) 行 463-470：SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL
  - [004 §5.3](../../../docs/architecture/004_architecture_impact_map.md) 行 505：all/grade_managed/class_taught/children/owned + 自定义（语义命名，与表不同）
  - president §3.2 P2.2：ALL/SCHOOL/GRADE/CLASS/SUBJECT/SELF（**SUBJECT 替代 DISTRICT**）
  - 源码 [iam.schema.ts](../../../services/iam/src/iam/iam.schema.ts) 第 16-25 行：self/class/grade/school/district/all（与 004 表一致，与 president 不一致）
- **建议方案**：coord 统一裁定最终枚举值。若采用 president 的 SUBJECT（学科级数据范围，K12 场景更实用），需同步修改源码 schema + 004 §5.3 表 + 02 文档；若保留 DISTRICT，需修正 president §3.2。同时修正 004 行 505 的语义命名使其与枚举表一致。
- **状态**：待 coord 仲裁

### ISSUE-005-ai06：iam.proto 仅 4 RPC，未补全至 12 RPC

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：coord-final-decisions §5.1 要求 iam.proto 在"P2 启动前"补全 8 个新 RPC（GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent），president §6 批次 0 任务 0.3 也明确"coord 补全 iam.proto 8 RPC"。但实际 [iam.proto](../../../packages/shared-proto/proto/iam.proto) 仍仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），未补全。这阻塞 iam P2.1 的 8 RPC 实现（proto 是契约先行前提）。
- **建议方案**：coord 立即补全 iam.proto 至 12 RPC（含对应 message 定义），对齐 [iam_contract.md §1.1](../contracts/iam_contract.md) 的 12 RPC 清单。
- **状态**：待 coord 仲裁

### ISSUE-006-ai06：01/02 文档 AI 身份署名错误

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：其他
- **描述**：[01-understanding.md](../../../services/iam/docs/01-understanding.md) 和 [02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) 署名"AI：ai02（TS / 身份认证）"、"AI Agent: ai02 (iam-module)"。但 coord-final-decisions §3.1、president §3.2、[matrix.md](../matrix.md)、[workline.md](../workline.md)、[iam_workline.md](../worklines/iam_workline.md)、[iam_contract.md](../contracts/iam_contract.md) 全部指明 iam 由 **ai06** 负责。ai02 实际负责 push-gateway（coord-final-decisions §3.7）。文档署名错误会导致多 AI 协作时身份混淆。
- **建议方案**：回写时将 01/02 文档署名从 ai02 改为 ai06。
- **状态**：待 coord 仲裁

### ISSUE-007-ai06：contract.md §1.2 与双入口策略冲突

- **提请方**：ai06
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：[iam_contract.md §1.2](../contracts/iam_contract.md) 写"无对外 HTTP 端点，仅 gRPC"。但 president §2.16 裁决双入口策略：REST 供 gateway 透传 + gRPC 供 BFF 聚合调用，"gateway 保持 HTTP 透传"。若 iam 不暴露 HTTP 端点，gateway 无法透传（gateway 不改为 gRPC 客户端）。
- **建议方案**：修正 contract.md §1.2，补充 REST 端点清单（/iam/v1/* 系列），标明"REST 供 gateway 透传 + admin-portal 直连，gRPC 供 BFF 聚合调用"。
- **状态**：待 coord 仲裁

---

## 问题列表

<!--
追加条目格式：

### ISSUE-[编号]-[AI标识]：[标题]

- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->

见上方 §2 新提请异议（ISSUE-001 ~ ISSUE-007）。