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

# ai 问题记录

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

---

## §0 已有仲裁核查（ai12 复核，2026-07-10）

> 任务要求：对已有的仲裁进行核查。coord.md 当前仅含 ARB-001 / ARB-002；另在 [port-allocation.md](../../../../infra/port-allocation.md) §7、coord-final-decisions.md、president-final-rulings.md 中存在涉及 ai 的历史仲裁。逐项核查如下。

| 仲裁编号 / 来源                                            | 主题                                       | 涉及 ai？ | 核查结论                                                                                                                                                                                                                                        | 状态                |
| ---------------------------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| ARB-001（coord.md §1）                                     | teacher-bff GraphQL schema 第一版          | ❌ 否     | 与 ai 无关，不适用。                                                                                                                                                                                                                            | —                   |
| ARB-002（coord.md §2）                                     | MF Shell 暴露清单                          | ❌ 否     | 与 ai 无关，不适用。                                                                                                                                                                                                                            | —                   |
| port-allocation.md §7                                      | 50058 让给 ai（push-gateway 豁免 gRPC）    | ✅ 是     | **仲裁有效**：port-allocation.md §3/§5 已登记 ai = HTTP 3008 / gRPC 50058。ai 的 01/02 文档已按 50058 设计，一致。**但 [matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵、§8 就绪信号跟踪表仍写 50057，未同步** → 提请 coord 同步（见 ISSUE-01） | ⚠️ 仲裁有效但未同步 |
| coord-final-decisions §1-§4                                | iam P2 契约 / BFF 设计 / Gateway / content | ❌ 否     | 历史仲裁，与 ai 无直接约束。ai 仅消费 content/data-ana gRPC，需待其就绪。                                                                                                                                                                       | —                   |
| president-final-rulings §2.3                               | Temporal 用于 AI 编排                      | ✅ 是     | **部分仲裁**：004 §2.3 列出 Temporal。ai12 已在 02-architecture-design.md §8.3 建议简单 4 步工作流用 BackgroundTasks + Redis，长运行评估 Temporal。需 coord 在 P6 决策点确认（见 ISSUE-06）。                                                   | ⚠️ 部分仲裁         |
| 01/02 文档引用"004 §7.2 已确认 topic edu.insight.ai.usage" | ai 用量事件 topic                          | ✅ 是     | **核查不通过**：grep 004 全文未发现 `ai.usage` / `insight.ai` / `AIUsage` 任何字样，004 §7.2 并未确认 ai 的 topic。该引用无法证实，topic 命名实际处于三义未决状态（见 ISSUE-02）。                                                              | ❌ 引用失实         |
| 01/02 文档引用"004 §1.2 端口矩阵 HTTP+10050 规则"          | ai gRPC 端口推导规则                       | ✅ 是     | **核查不通过**：004 全文无端口矩阵；`HTTP+10050` 公式不成立（3008+10050=13058≠50058）。端口唯一源是 port-allocation.md（顺序分配），ai=50058。ai 文档应改引 port-allocation.md。                                                                | ❌ 引用失实         |

**核查总结**：coord.md 现有 2 项仲裁（ARB-001/002）均与 ai 无关；涉及 ai 的真实仲裁在 port-allocation.md（50058 已定）与 004 §2.3（Temporal 部分仲裁）。ai 文档对"004 §7.2/§1.2"的两处引用失实，需修正引用源。

---

## 问题列表

### ISSUE-01-ai12：matrix.md 端口 50057 与 port-allocation.md 50058 不同步

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：编号冲突 / 文档不同步
- **描述**：[matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵写 "ai (ai12) | 50057"，§8 就绪信号跟踪表写 "ai gRPC 50057"。但 [port-allocation.md](../../../../infra/port-allocation.md) §3/§5/§7 明确 ai = HTTP 3008 / gRPC 50058（2026-07-09 coord 仲裁"push-gateway 豁免 gRPC，释放 50057；50058 让给 ai"）。两份 coord 文件矛盾，matrix.md 过时。ai 01/02 文档与 workline.md §1/§4.12 已正确采用 50058。
- **建议方案**：coord 将 matrix.md §2 ai 行 gRPC 端口 50057 → 50058，§8 就绪信号"ai gRPC 50057"→ 50058。ai12 同步将 contracts/ai_contract.md 全部 50057 改 50058。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-02-ai12：ai 用量事件 Kafka topic 命名三义未决

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：ai 用量计费事件 topic 在三份文档中命名不一致，且无权威源：
  - 01-understanding.md §3.2 / 02-architecture-design.md §5.2：`edu.insight.ai.usage`（自称"004 §7.2 已确认"，但 004 中不存在）
  - matrix.md §4 Kafka 事件发布方矩阵：`edu.ai.usage`，事件 `AIUsageEvent`
  - contracts/ai_contract.md §1.4：`edu.ai.usage.events`

  events.proto 现状无 `AIUsageEvent` message，004 无 topic 记录。三义导致 data-ana 消费方无法对齐。

- **建议方案**：ai12 建议采用 `edu.ai.usage`（与 matrix.md 一致，最简短，符合 `edu.<domain>.<action>` 简洁约定）。请 coord 裁定并在 004 §7.2 补登 + events.proto 补 `AIUsageEvent` message（schema 见 02-architecture-design.md §3.3）。ai12 据裁决同步 01/02 文档与 contract。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-03-ai12：ai.proto 待补全（备课工作流 RPC + 字段扩展）

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：ai.proto 现状仅 4 RPC（Chat / StreamChat / GenerateQuestion / OptimizeExpression），且 `GenerateQuestionRequest` 仅 prompt/subject/difficulty 三字段。P5 交付需要：
  - 新增 RPC：`GenerateLessonPlan`、`StreamGenerateQuestion`（ai-allocation §5 "题目逐字生成"）
  - `GenerateQuestionRequest` 扩展字段：grade / knowledge_point_ids / question_type / count
  - `ChatRequest` 扩展可选字段：user_id / session_id / data_scope

  关于 RPC 总数存在分歧：matrix.md §2 与 contract 写 6 RPC；02-architecture-design.md §4.2 单方面扩到 8 RPC（追加 GetLessonPlanStatus / ConfirmLessonPlan）。需 coord 裁定 P5 目标 RPC 清单。

- **建议方案**：ai12 建议 P5 目标 6 RPC（Chat / StreamChat / GenerateQuestion / StreamGenerateQuestion / OptimizeExpression / GenerateLessonPlan）。备课工作流的"查询状态/确认入库"用 HTTP 端点（`GET /ai/v1/lesson/preparation/{id}` + `POST .../confirm`）实现，避免 RPC 膨胀；如 coord 认为查询/确认也需 gRPC，则定为 8 RPC。请 coord 在 P5 启动前升级 ai.proto 到 v1 完整版。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-04-ai12：events.proto 缺 AIUsageEvent message

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 前置依赖缺失
- **描述**：004 §12.2 + §15.3 #6 仲裁 ai 用量事件豁免 Outbox（派生数据），但 events.proto 现状仅有 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent，**无 AIUsageEvent**。data-ana 消费方无 schema 可循。01/02 文档已提请（A3），matrix.md §4 已列事件名，但 proto 未落地。
- **建议方案**：coord 在 events.proto 新增 `AIUsageEvent` message，建议 schema 见 02-architecture-design.md §3.3（含 event_id / user_id / school_id / provider / model / operation / prompt_tokens / completion_tokens / total_tokens / latency_ms / success / degraded / metadata）。与 ISSUE-02 一并裁决。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-05-ai12：contracts/ai_contract.md 与设计文档多处矛盾（ai12 自查自纠清单）

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 文档不同步
- **描述**：现有 contracts/ai_contract.md（coord 模板，ai12 接管前未细化）与 01/02 设计文档存在 5 处矛盾：
  1. §1.1 gRPC 端口 50057（应为 50058，见 ISSUE-01）
  2. §1.2 "无对外 HTTP 端点，仅 gRPC"——错误。api-gateway 代理 `/api/v1/ai/*` → ai HTTP（main.py 已实现 /ai/* 端点 + SSE 流式），HTTP 保留作 Gateway 直连降级
  3. §1.4 topic `edu.ai.usage.events`（三义，见 ISSUE-02）
  4. §1.5 错误码示例 `AI_PROVIDER_UNAVAILABLE` / `AI_TOKEN_LIMIT_EXCEEDED` / `AI_CONTENT_FILTERED` 与 02-architecture-design.md §6.2 清单（`AI_LLM_UNAVAILABLE` / `AI_QUOTA_EXCEEDED` / `AI_CONTENT_MODERATION_REJECTED`）命名不一致
  5. §2.2 列出 ai 消费 2 个 content Kafka 事件，与 01/02 §5.1 "ai 不消费任何事件（无状态）"矛盾

- **建议方案**：ai12 在本次工作中直接重写 contracts/ai_contract.md 对齐设计文档（端口 50058 / 补 HTTP 端点 / topic 待 ISSUE-02 裁决后填 / 错误码对齐 02 §6.2 / 删除消费事件或标注 P6+ 评估）。仅 RPC 数与 topic 命名待 coord 裁决后最终定稿。
- **状态**：ai12 自纠中（依赖 ISSUE-01/02/03 裁决的字段待补）

### ISSUE-06-ai12：备课工作流是否引入 Temporal（P6 决策点）

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：工作量超批 / 前置依赖缺失
- **描述**：004 §2.3 列出 Temporal 用于"AI 编排"，属部分仲裁。ai12 在 02-architecture-design.md §8.3 建议：P5 用 FastAPI BackgroundTasks + Redis（24h TTL）实现 4 步备课工作流；P6 评估迁移 Temporal（支持长运行跨天审核 + 复杂状态机）。需 coord 在 P6 决策点确认是否引入，避免 P5 实现被推翻重做。
- **建议方案**：P5 采用 BackgroundTasks + Redis（02-architecture-design.md §2.4 状态机已设计）；P6 由 coord 评估 Temporal 引入时机。请 coord 在 roadmap 标注 P6 决策点。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-07-ai12：iam GetEffectiveDataScope gRPC RPC 待 P4 补全

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：ai 多租户用量配额校验需调用 `IamService.GetEffectiveDataScope` 查询用户 DataScope。01/02 文档已提请（A4），coord 已仲裁 P4 补全（§15.3 #5），但 iam.proto 现状未见此 RPC。ai P5 实施时依赖，若 P4 未补全将阻塞配额校验功能。
- **建议方案**：请 coord 确认 iam (ai06) 在 P4 已补全 `GetEffectiveDataScope` RPC；ai12 在 P5 实施时调用，Redis 缓存 5min。若 P4 未补全，ai 降级为"仅按 user_id 配额，不按 school_id"。
- **状态**：待 coord 确认 P4 补全情况

### ISSUE-08-ai12：proto package 命名不符合 project_rules §5

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：契约不明确 / 架构约束
- **描述**：project_rules §5 规定 proto 包名规范 `edu.<domain>.v1`（如 `edu.iam.v1`、`edu.core_edu.v1`）。但 ai.proto 现状 package 为 `next_edu_cloud.ai.v1`，events.proto 为 `next_edu_cloud.events.v1`，均不符合规范。01/02 文档未指出此偏离。此为全局 proto 命名问题（涉及全部 proto 文件），非 ai 独有，但 ai12 在审查中发现需提请。
- **建议方案**：请 coord 裁定是否统一迁移 proto package 至 `edu.<domain>.v1`（全局变更，需 buf breaking 评估）；或保留现状作为历史包袱。ai12 在 ai.proto 补全 RPC 时遵循最终裁定。
- **状态**：已裁决（见 coord.md §12）

### ISSUE-09-ai12：响应信封偏离 ActionState 强制整改（P0）

- **提请方**：ai12
- **日期**：2026-07-10
- **类型**：架构约束
- **描述**：004 §11.5 强制响应信封为 ActionState（`{success, data, error:{code,message,details,traceId}}`）。ai 当前 main.py 违反：返回 `{success:true, data:..., degraded:false}` 顶层 degraded 字段（见 main.py:89/201-210/233-244）。01/02 文档已提请（A5），contracts 未记录。P5 实施必须整改。
- **建议方案**：P5 实施时所有 HTTP 端点 + gRPC RPC 返回值改为 ActionState；degraded 作为 `error.details.degraded` 子字段。请 coord 在 known-issues §2.9 ai 分区记录此约束（01 文档已提请，需 coord 落地 known-issues）。
- **状态**：待 coord 在 known-issues 记录约束（整改由 ai12 P5 执行）

---

<!--
追加条目格式：

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

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