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

ai 问题记录

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

---

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

任务要求：对已有的仲裁进行核查。coord.md 当前仅含 ARB-001 / ARB-002；另在 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 §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 §2 gRPC 接口提供方矩阵写 "ai (ai12) | 50057"，§8 就绪信号跟踪表写 "ai gRPC 50057"。但 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 执行）

---