# data-ana 问题记录

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

---

## §0 已有仲裁核查记录（2026-07-10）

> ai11 在编写 objections 前对 coord.md 与 coord-cross-review.md 中涉及 data-ana 的仲裁逐项核查落实状态。

### 0.1 coord.md 仲裁核查

| 编号    | 主题                       | 涉及 data-ana | 核查结论            |
| ------- | -------------------------- | ------------- | ------------------- |
| ARB-001 | teacher-bff GraphQL schema | ❌ 否         | 不涉及，无需 action |
| ARB-002 | MF Shell 暴露清单          | ❌ 否         | 不涉及，无需 action |

**结论**：coord.md 无 data-ana 直接仲裁。

### 0.2 coord-cross-review.md 仲裁核查（8 项涉及 data-ana）

| #   | 审查章节        | 裁决内容                                                                 | 责任方 | 核查结论                                                                                                   |
| --- | --------------- | ------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| 1   | §2.2 #3         | iam 新增 `GetEffectiveDataScope` RPC，P4 补全，data-ana gRPC 调用        | iam    | ⚠️ **未落实**：iam.proto 当前仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），无 GetEffectiveDataScope |
| 2   | §2.3 P4 行      | content + data-ana P4 启用 gRPC server                                   | ai11   | ⏳ 未到 P4 阶段，待执行                                                                                    |
| 3   | §3.2            | 补登 `edu.insight.ai.usage` topic + events.proto 补 AIUsageEvent         | coord  | ⚠️ **未落实**：events.proto 当前仅 4 message（Class/Exam/Homework/GradeEvent），缺 AIUsageEvent            |
| 4   | §3.3            | Python 服务 Outbox 豁免（MasteryUpdated / WarningTriggered）             | coord  | ✅ **已对齐**：01/02 文档已声明豁免，引用 coord-cross-review.md §3.3                                       |
| 5   | §4.3            | data-ana HTTP=3006 / gRPC=50055                                          | coord  | ✅ **已对齐**：01/02 文档端口声明一致                                                                      |
| 6   | §5.3            | Python 服务信封改为 ActionState（degraded 放 details 子字段）            | ai11   | ✅ **已对齐**：02 §4.3 ActionState 实现已修正，degraded 移至顶层 details                                   |
| 7   | §6 #4           | 同 #6，ai06 修正 data-ana/ai 02 文档 + 代码                              | ai11   | ✅ **已对齐（文档）**：02 已修正；代码待 P4 实现阶段重构                                                   |
| 8   | §6 #7/#8/#9/#10 | coord 在 004 §7.2 补登 topic + §1.2 端口列 + §4.1 gRPC 矩阵 + §12.2 豁免 | coord  | ⚠️ **未落实**：004 正文无 §4.2/§7.2 补登段/§11.4/§11.5，01/02 引用断裂已临时改为引 coord-cross-review.md   |

### 0.3 coord-cross-review §8.2 批次 0 产出声明核查

coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文件核查实际状态：

| 声明产出项           | 声明状态                    | 实际文件状态（ai11 核查）                                            | 核查结论    |
| -------------------- | --------------------------- | -------------------------------------------------------------------- | ----------- |
| iam.proto 12 RPC     | ✅ 12 RPC                   | **4 RPC**（Register/Login/RefreshToken/GetUserInfo）                 | ⚠️ 严重不符 |
| analytics.proto 扩展 | ✅ 12 RPC（含 Stream）      | **3 RPC**（GetClassPerformance/GetStudentWeakness/GetLearningTrend） | ⚠️ 严重不符 |
| events.proto 补全    | ✅ 9 message（+AuditEvent） | **4 message**（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent）       | ⚠️ 严重不符 |
| core_edu.proto 补全  | ✅ 5 service                | 未由 ai11 核查（非本模块边界）                                       | —           |
| buf.gen.yaml 插件    | ✅ go + python              | 未由 ai11 核查（coord 维护）                                         | —           |

> **核查说明**：ai11 仅核查与 data-ana 直接相关的 proto（iam/analytics/events）。§8.2 声明与实际文件严重不符，可能原因：(a) 声明为计划态但未执行；(b) 执行后未提交到本 worktree 分支；(c) 在其他分支已执行但未合并。无论哪种原因，data-ana 的 P4 实现依赖这些 proto 补全，当前实际状态构成 P4 阻塞。

---

## §1 问题列表

### ISSUE-001-ai11：iam.proto 缺 GetEffectiveDataScope RPC（P4 阻塞）

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：coord-cross-review.md §2.2 #3 已仲裁"iam P4 补全 `GetEffectiveDataScope` RPC，data-ana gRPC 调用"，但 iam.proto 当前仅 4 RPC，无此 RPC。data-ana 的 DataScope 6 级过滤（SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL）依赖此 RPC 解析用户可见数据范围，是 P4 实现的硬阻塞项。
- **建议方案**：coord 确认 iam.proto 补全进度。若 iam 侧尚未实现，data-ana P4 阶段将使用硬编码 DataScope 降级（按 role 映射默认 scope），并标注 `details.degraded: true`，待 iam 就绪后切换。
- **状态**：待 coord 仲裁（核查已有仲裁 §0.2 #1 未落实）

---

### ISSUE-002-ai11：events.proto 缺 AIUsageEvent message（P5 阻塞，P4 预备）

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失
- **描述**：coord-cross-review.md §3.2 已仲裁"补登 `edu.insight.ai.usage` topic + events.proto 补 `AIUsageEvent` message"，但 events.proto 当前仅 4 message（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent），缺 AIUsageEvent。data-ana 需消费此事件落 `ai_usage_log` 宽表，供管理员仪表盘展示 AI 用量统计。
- **建议方案**：coord 在 events.proto 补 `AIUsageEvent` message，字段建议：`{event_id, request_id, user_id, provider, model, prompt_tokens, completion_tokens, total_tokens, latency_ms, success, cost_cents, occurred_at}`。P5 前补全即可，P4 仪表盘 AI 用量区块显示"暂无数据"。
- **状态**：待 coord 仲裁（核查已有仲裁 §0.2 #3 未落实）

---

### ISSUE-003-ai11：analytics.proto 仅 3 RPC，coord-cross-review §8.2 声称已扩展至 12 RPC 但实际未落实（P4 阻塞）

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：前置依赖缺失 + 声明与实际不符
- **描述**：coord-cross-review.md §8.2 声称"analytics.proto 扩展 ✅ 12 RPC（含 Stream）"，但实际文件仅 3 RPC（GetClassPerformance/GetStudentWeakness/GetLearningTrend）。ai-allocation.md §5 与 matrix.md §2 均要求 data-ana 提供 12 RPC，02-architecture-design.md §4.2 已设计完整 12 RPC 清单（含 4 端 Dashboard + Warning + Mastery + Server Streaming），但 proto 未补全导致无法生成 stub。
- **建议方案**：coord 确认 analytics.proto 扩展进度。ai11 可提供 12 RPC 的完整 message 定义提案（见 [02-architecture-design.md §4.2](../../../services/data-ana/docs/02-architecture-design.md)），coord 审议后合并到 analytics.proto。若 coord 未补全，ai11 在 P4 阶段自行补全 proto（本分支内），提请 coord 合并。
- **状态**：待 coord 仲裁

---

### ISSUE-004-ai11：coord-cross-review §6 整改清单 coord 责任项未落实，导致 004 章节引用断裂

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：coord-cross-review.md §6 整改清单中标注"coord"责任的 4 项整改未在 004 正文中落实：
  - #7：004 §7.2 补登 6 个 topic + CDC 命名规范 → 004 正文无对应段落
  - #8：004 §1.2 新增 HTTP/gRPC 端口两列 → 004 §1.2 服务清单无端口列
  - #9：004 §4.1 补充 gRPC 启用阶段矩阵 → 004 正文无 §4.2 子节
  - #10：004 §12.2 补充派生数据事件 Outbox 豁免条款 → 004 §12.2 未补充

  这导致 01-understanding.md 和 02-architecture-design.md 中引用 004 §4.2/§11.4/§11.5/§15.3 等章节均断裂（004 正文仅到 §14，§15 在 004-p6-addendum.md 但内容不同）。ai11 已在 v2.1 修订中临时改为引用 coord-cross-review.md 对应裁决章节，但这是过渡方案。

- **建议方案**：coord 按整改清单 #7/#8/#9/#10 补全 004 对应章节，使 004 成为可信的架构设计意图唯一源。各 AI 文档随后将引用从 coord-cross-review.md 回切到 004 对应章节。
- **状态**：待 coord 仲裁

---

### ISSUE-005-ai11：data-ana 发布的 MasteryEvent topic 命名三处不一致

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：契约不明确
- **描述**：data-ana 发布的掌握度/预警事件 topic 命名在三个文档中不一致：

  | 文档                                            | topic 命名                                                      |
  | ----------------------------------------------- | --------------------------------------------------------------- |
  | 01-understanding.md / 02-architecture-design.md | `edu.insight.mastery.updated` + `edu.insight.warning.triggered` |
  | matrix.md §4                                    | `edu.analytics.mastery`                                         |
  | contracts/data-ana_contract.md（修正前）        | `edu.data_ana.mastery.events`                                   |

  按 004 §7.2 命名规范 `edu.<domain>.<aggregate>.<action>`，data-ana 属于 D6 智能洞察领域（domain=insight），故 `edu.insight.mastery.updated` 符合规范。matrix.md 的 `edu.analytics.mastery` 不符合命名规范（缺 action 层级，且 domain 用了服务名而非领域名）。

- **建议方案**：coord 裁决统一为 `edu.insight.mastery.updated` + `edu.insight.warning.triggered`，coord 修正 matrix.md §4。ai11 已在 contract.md 中采用此命名。
- **状态**：待 coord 仲裁

---

### ISSUE-006-ai11：coord-cross-review §8.2 批次 0 产出声明与 proto 实际文件状态严重不符

- **提请方**：ai11
- **日期**：2026-07-10
- **类型**：其他（声明与实际不符）
- **描述**：coord-cross-review.md §8.2 声称批次 0 已完成 iam.proto（12 RPC）/ analytics.proto（12 RPC）/ events.proto（9 message）补全，但 ai11 逐文件核查发现实际均未补全（详见 §0.3 核查表）。这影响所有依赖这些 proto 的下游 AI 的排期评估——若 AI 信任 §8.2 声明，会在排期中忽略 proto 补全的等待时间，导致排期失真。
- **建议方案**：coord 核实 §8.2 声明真实性。若实际已补全但未合并到各 worktree 分支，请协调合并；若实际未补全，请更新 §8.2 状态为"计划中"或"待执行"，并明确补全时间点，以便下游 AI 据此排期。
- **状态**：已裁决（见 [coord.md §11 ARB-009](../coord.md#11-arb-009data-ana-模块-6-项-issue-仲裁)）

---

## §2 仲裁结论（2026-07-10 coord）

> 详见 [coord.md §11 ARB-009](../coord.md#11-arb-009data-ana-模块-6-项-issue-仲裁)

| ISSUE | 仲裁结论                                                                           | 执行方 |
| ----- | ---------------------------------------------------------------------------------- | ------ |
| 001   | ✅ coord 批次 0 补全 iam.proto 12 RPC（ARB-007，含 GetEffectiveDataScope）         | coord  |
| 002   | ✅ coord 补全 events.proto AIUsageEvent（ARB-011）                                 | coord  |
| 003   | ✅ coord 批次 0 补全 analytics.proto 至 12 RPC（ARB-012）                          | coord  |
| 004   | ✅ coord 补全 004 §7.2/§1.2/§4.1/§12.2 对应章节                                    | coord  |
| 005   | ✅ 统一 `edu.insight.mastery.updated` + `edu.insight.warning.triggered`（ARB-013） | coord  |
| 006   | ✅ coord 更正 coord-cross-review.md §8.2 状态为"待执行"                            | coord  |
