xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
21f2485749924d550223bc722567ab0a0b7efb8e
Edu/docs/architecture/issues/objections/iam_issue.md
SpecialX c6362f4b04
Some checks failed
CI / quality-ts (push) Failing after 53s
Details
CI / quality-go (push) Failing after 7s
Details
CI / quality-proto (push) Failing after 3s
Details
CI / deploy (push) Has been skipped
Details
docs(docs): 更新 issue 仲裁状态 + 生成集成测试阶段规划 
- 14 个 issue.md 状态字段更新为"已裁决"
  - 对应 coord.md ARB-001~022 章节
  - 共 104 处状态字段更新
- 新增 integration-test-phase.md
  - 集成测试与部署验证阶段(P7)规划
  - 6 个批次任务分解
  - 8 条核心 E2E 链路定义
  - 验收标准和退出标准

Coord-AI
2026-07-10 22:05:37 +08:00

143 lines
15 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.md §3）
### 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.md §3）
### 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.md §3）
### 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.md §3）
### 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.md §3）
### 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.md §3）
### 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.md §3）
---
## 问题列表
<!--
追加条目格式：
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：已裁决（见 coord.md §X）
-->
见上方 §2 新提请异议（ISSUE-001 ~ ISSUE-007）。
Reference in New Issue View Git Blame Copy Permalink