feat: auto committed

2026-07-10 15:05:37 +08:00
parent 9ba368477d
commit 033057a302
5 changed files with 612 additions and 117 deletions
--- a/docs/architecture/issues/contracts/data-ana_contract.md
+++ b/docs/architecture/issues/contracts/data-ana_contract.md
@@ -1,13 +1,15 @@
 # data-ana 对接契约

 > 负责人：ai11
-> 关联：[matrix.md](./matrix.md)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)
+> 关联：[matrix.md](../matrix.md)、[coord-cross-review.md](../../coord-cross-review.md)、[analytics.proto](../../../packages/shared-proto/proto/analytics.proto)、[events.proto](../../../packages/shared-proto/proto/events.proto)、[iam.proto](../../../packages/shared-proto/proto/iam.proto)
+> 对齐文档：[01-understanding.md](../../../services/data-ana/docs/01-understanding.md)、[02-architecture-design.md](../../../services/data-ana/docs/02-architecture-design.md)、[objections/data-ana_issue.md](../objections/data-ana_issue.md)、[worklines/data-ana_workline.md](../worklines/data-ana_workline.md)
+> 修订：v2（2026-07-10 by ai11）—— 修正 topic 命名 / gRPC 调用声明 / HTTP 端点声明 / 引用断裂，对齐 01/02 v2.1

 ---

 ## §1 我提供什么（对外接口）

-### 1.1 gRPC 接口（如有）
+### 1.1 gRPC 接口

 | Service          | RPC                    | 请求                          | 响应                      | 端口  |
 | ---------------- | ---------------------- | ----------------------------- | ------------------------- | ----- |
@@ -18,31 +20,71 @@
 | AnalyticsService | GetStudentDashboard    | GetStudentDashboardRequest    | StudentDashboard          | 50055 |
 | AnalyticsService | GetParentDashboard     | GetParentDashboardRequest     | ParentDashboard           | 50055 |
 | AnalyticsService | GetAdminDashboard      | GetAdminDashboardRequest      | AdminDashboard            | 50055 |
-| AnalyticsService | GetWarningList         | GetWarningListRequest         | WarningListResponse       | 50055 |
+| AnalyticsService | GetWarnings            | GetWarningsRequest            | WarningList               | 50055 |
 | AnalyticsService | TriggerWarning         | TriggerWarningRequest         | TriggerWarningResponse    | 50055 |
 | AnalyticsService | GetMasteryDistribution | GetMasteryDistributionRequest | MasteryDistribution       | 50055 |
 | AnalyticsService | GetStudentMastery      | GetStudentMasteryRequest      | StudentMastery            | 50055 |
 | AnalyticsService | SubscribeMasteryUpdate | SubscribeMasteryUpdateRequest | stream MasteryUpdateEvent | 50055 |

-### 1.2 HTTP 端点（如有）
+> **proto 状态**：analytics.proto 当前仅 3 RPC（GetClassPerformance / GetStudentWeakness / GetLearningTrend），扩展至 12 RPC 待 coord 补全或 ai11 在 P4 阶段自行补全（见 [ISSUE-003](../objections/data-ana_issue.md)）。完整 message 定义见 [02-architecture-design.md §4.2](../../../services/data-ana/docs/02-architecture-design.md)。
+> **gRPC 启用阶段**：P4 启用（coord-cross-review.md §2.3 裁决），P2-P3 仅 HTTP。
+> **响应信封**：所有 RPC 返回 ActionState[T]（coord-cross-review.md §5.3 P0 整改）。

-无对外 HTTP 端点，仅 gRPC（含 1 个 Server Streaming RPC）。
+### 1.2 HTTP 端点
+
+data-ana 保留 HTTP :3006 端点作 Gateway 直连降级（gRPC 不可用时 BFF 可走 HTTP）。共 14 端点（3 基础 + 11 业务）：
+
+| method | path                                         | 权限                          | 响应                                |
+| ------ | -------------------------------------------- | ----------------------------- | ----------------------------------- |
+| GET    | `/healthz`                                   | —                             | `{status, service}`                 |
+| GET    | `/readyz`                                    | —                             | `{status, ready, degraded, clickhouse, cdc_consumer, redis, iam_grpc}` |
+| GET    | `/metrics`                                   | —                             | Prometheus 格式                     |
+| GET    | `/analytics/class/{class_id}/performance`    | `ANALYTICS_CLASS_READ`        | `ActionState<ClassPerformanceData>` |
+| GET    | `/analytics/student/{student_id}/weakness`   | `ANALYTICS_STUDENT_READ`      | `ActionState<StudentWeaknessData>`  |
+| GET    | `/analytics/student/{student_id}/errorbook`  | `ANALYTICS_STUDENT_READ`      | `ActionState<StudentErrorBookData>` |
+| GET    | `/analytics/student/{student_id}/trend`      | `ANALYTICS_STUDENT_READ`      | `ActionState<LearningTrendData>`    |
+| GET    | `/analytics/student/{student_id}/attendance` | `ANALYTICS_STUDENT_READ`      | `ActionState<AttendanceData>`       |
+| GET    | `/analytics/dashboard/teacher/{user_id}`     | `ANALYTICS_TEACHER_DASHBOARD` | `ActionState<TeacherDashboardData>` |
+| GET    | `/analytics/dashboard/student/{user_id}`     | `ANALYTICS_STUDENT_DASHBOARD` | `ActionState<StudentDashboardData>` |
+| GET    | `/analytics/dashboard/parent/{user_id}`      | `ANALYTICS_PARENT_DASHBOARD`  | `ActionState<ParentDashboardData>`  |
+| GET    | `/analytics/dashboard/admin/{user_id}`       | `ANALYTICS_ADMIN_DASHBOARD`   | `ActionState<AdminDashboardData>`   |
+| GET    | `/analytics/warnings`                        | `ANALYTICS_WARNING_READ`      | `ActionState<WarningListData>`      |
+| GET    | `/analytics/mastery/distribution`            | `ANALYTICS_CLASS_READ`        | `ActionState<MasteryDistributionData>` |
+
+> 完整端点设计见 [02-architecture-design.md §4.1](../../../services/data-ana/docs/02-architecture-design.md)。

 ### 1.3 GraphQL schema（如 BFF）

-不适用。
+不适用。data-ana 是业务服务，不提供 GraphQL。BFF 层（teacher-bff / student-bff / parent-bff）聚合 data-ana gRPC 后对外暴露 GraphQL。

-### 1.4 Kafka 事件发布（如有）
+### 1.4 Kafka 事件发布

-| Topic                       | Event                                                     | 消费方         |
-| --------------------------- | --------------------------------------------------------- | -------------- |
-| edu.data_ana.mastery.events | MasteryEvent（action: mastery.updated/warning.triggered） | core-edu / msg |
+| Topic                            | Event           | 消费方                          | Outbox | 说明 |
+| -------------------------------- | --------------- | ------------------------------- | ------ | ---- |
+| `edu.insight.mastery.updated`    | MasteryUpdated  | core-edu（推荐个性化练习）/ msg | ❌ 豁免 | 掌握度计算完成触发 |
+| `edu.insight.warning.triggered`  | WarningTriggered | msg（推送通知）/ core-edu（标记关注） | ❌ 豁免 | 预警阈值触发 |

-> 注：MasteryEvent 豁免 Outbox 模式（派生数据事件，见 004 §12.2 + §15.3 #6）。
+> **Outbox 豁免**：派生数据事件（非业务事务写），豁免 Outbox 约束（[coord-cross-review.md §3.3](../../coord-cross-review.md) 已仲裁）。直接用 aiokafka AIOKafkaProducer 发布，`idempotent=true` + `transactional_id="data-ana-producer"`。
+>
+> **topic 命名说明**：按 004 §7.2 命名规范 `edu.<domain>.<aggregate>.<action>`，data-ana 属于 D6 智能洞察领域（domain=insight），故 `edu.insight.mastery.updated` 符合规范。matrix.md §4 中 `edu.analytics.mastery` 命名不符合规范（缺 action 层级，domain 用了服务名而非领域名），已提请 coord 统一（见 [ISSUE-005](../objections/data-ana_issue.md)）。

 ### 1.5 错误码前缀

-`DATA_ANA_`（如 DATA_ANA_DASHBOARD_UNAVAILABLE、DATA_ANA_MASTERY_NOT_COMPUTED）
+`DATA_ANA_`（如 DATA_ANA_DASHBOARD_UNAVAILABLE、DATA_ANA_MASTERY_NOT_COMPUTED、DATA_ANA_CLICKHOUSE_UNAVAILABLE）
+
+> 来源：[matrix.md §6](../matrix.md) 错误码前缀矩阵。
+
+### 1.6 ClickHouse 宽表（供 coord 统一管理 DDL）
+
+| 宽表名                    | 用途                 | 引擎                          |
+| ------------------------- | -------------------- | ----------------------------- |
+| student_dashboard_view    | 学生学情宽表         | ReplacingMergeTree(last_updated) |
+| student_errors            | 学生错题本           | ReplacingMergeTree(last_error_time) |
+| mastery_snapshot          | 知识点掌握度历史快照 | MergeTree                     |
+| attendance_logs           | 学生考勤记录         | ReplacingMergeTree(occurred_at) |
+| ai_usage_log              | AI 用量计费记录      | ReplacingMergeTree(occurred_at) |
+
+> DDL 由 coord 统一管理在 `infra/clickhouse/ddl/`（待 coord 建立），data-ana 提供内容。完整 DDL 见 [02-architecture-design.md §3](../../../services/data-ana/docs/02-architecture-design.md)。

 ---

@@ -50,29 +92,43 @@

 ### 2.1 gRPC 调用（同步）

-无主动 gRPC 调用上游。data-ana 通过 CDC + Kafka 事件接收数据，计算后发布 MasteryEvent。
+| 调用方   | 被调用方 | RPC                       | 用途                         | 端口  | 阶段 | 状态 |
+| -------- | -------- | ------------------------- | ---------------------------- | ----- | ---- | ---- |
+| data-ana | iam      | GetEffectiveDataScope     | DataScope 6 级过滤解析       | 50052 | P4   | ⚠️ iam.proto 当前未实现（ISSUE-001） |
+
+> **降级兜底**：iam GetEffectiveDataScope 未就绪时，data-ana 按 role 映射默认 DataScope（教师=CLASS，学生=SELF，管理员=SCHOOL），标注 `details.degraded: true`。结果 Redis 缓存 5min（key: `data_ana:datascope:{user_id}`）。
+>
+> **裁决依据**：coord-cross-review.md §2.2 #3 已仲裁 iam P4 补全此 RPC。

 ### 2.2 Kafka 事件订阅（异步）

-| Topic                              | Event               | 发布方          | mock 策略                                         |
-| ---------------------------------- | ------------------- | --------------- | ------------------------------------------------- |
-| edu.exam.events                    | ExamEvent           | core-edu (ai08) | core-edu 就绪前使用 CDC 模拟数据 + 本地 stub 事件 |
-| edu.homework.events                | HomeworkEvent       | core-edu (ai08) | 同上                                              |
-| edu.grade.events                   | GradeEvent          | core-edu (ai08) | 同上                                              |
-| edu.class.events                   | ClassEvent          | core-edu (ai08) | 同上                                              |
-| edu.content.knowledge_point.events | KnowledgePointEvent | content (ai09)  | content 就绪前使用内置知识点维度表                |
-| edu.content.question.events        | QuestionEvent       | content (ai09)  | content 就绪前忽略                                |
-| edu.ai.usage.events                | AIUsageEvent        | ai (ai12)       | ai 就绪前忽略，AI 用量统计为空                    |
+| Topic                                  | Event               | 发布方          | mock 策略                                         |
+| -------------------------------------- | ------------------- | --------------- | ------------------------------------------------- |
+| `edu.teaching.exam.published`          | ExamEvent           | core-edu (ai08) | core-edu 就绪前使用 CDC 模拟数据 + 本地 stub 事件 |
+| `edu.teaching.homework.assigned`       | HomeworkEvent       | core-edu (ai08) | 同上                                              |
+| `edu.teaching.grade.recorded`          | GradeEvent          | core-edu (ai08) | 同上                                              |
+| `edu.teaching.class.transferred`       | ClassEvent          | core-edu (ai08) | 同上                                              |
+| `edu.content.kp.events`                | KnowledgePointEvent | content (ai09)  | content 就绪前使用内置知识点维度表                |
+| `edu.content.question.events`          | QuestionEvent       | content (ai09)  | content 就绪前忽略                                |
+| `edu.insight.ai.usage`                 | AIUsageEvent        | ai (ai12)       | ai 就绪前忽略，AI 用量统计为空（P5）              |
+
+> **topic 命名对齐**：core-edu 教学事件 topic 按 coord-cross-review.md §3.1 裁决统一为 `edu.teaching.<aggregate>.<action>` 风格。core-edu 代码实际发布 `edu.exam.events` 等，待 core-edu 整改后切换。
+>
+> **AIUsageEvent 缺失**：events.proto 当前缺 AIUsageEvent message（ISSUE-002），P5 前需 coord 补全。

 ### 2.3 HTTP 调用（如有）

-无。
+无。data-ana 不通过 HTTP 调用上游服务。

-### 2.4 CDC 数据源（补充）
+### 2.4 CDC 数据源

 | 数据源                                                | 用途                            | mock 策略                                                                   |
 | ----------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
 | core-edu MySQL（exams/homework/grades/attendance 表） | Debezium CDC → Kafka 同步读模型 | core-edu 就绪前使用 ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业） |
+| content MySQL（knowledge_points 表）                  | Debezium CDC → 知识点元数据同步 | content 就绪前使用内置固定知识点表（数学 50 个知识点）                      |
+| iam MySQL（users 表）                                 | Debezium CDC → 用户 dataScope 同步 | iam 就绪前使用硬编码 DataScope 降级                                         |
+
+> **CDC topic 命名**：`edu-cdc.next_edu_cloud.<table>`（coord-cross-review.md §3.2 裁决补登 CDC topic 命名规范段，待 coord 在 004 §7.2 落实）。

 ---

@@ -81,17 +137,23 @@
 ### 3.1 我依赖的上游就绪标志

 - [ ] core-edu gRPC 50053 启用（ai08）—— 业务事件 + CDC 数据源
- [ ] edu.exam.events / edu.homework.events / edu.grade.events / edu.class.events topic 有事件发布（ai08）
- [ ] content gRPC 50054 启用（ai09）—— 知识点维度
- [ ] edu.content.knowledge_point.events topic 有事件发布（ai09）
- [ ] ai gRPC 50057 启用（ai12）—— AI 用量统计（可选，仪表盘补全）
+- [ ] core-edu MySQL Debezium CDC 配置（ai08 + SRE）—— CDC 通道前提
+- [ ] `edu.teaching.exam.published` / `edu.teaching.homework.assigned` / `edu.teaching.grade.recorded` / `edu.teaching.class.transferred` topic 有事件发布（ai08）
+- [ ] content gRPC 50054 启用（ai09）—— 知识点维度 CDC
+- [ ] `edu.content.kp.events` topic 有事件发布（ai09）
+- [ ] iam.proto 补全 GetEffectiveDataScope RPC（ai06/coord，ISSUE-001）—— P4 阻塞项
+- [ ] analytics.proto 扩展至 12 RPC（coord/ai11，ISSUE-003）—— gRPC stub 生成前提
+- [ ] events.proto 补全 AIUsageEvent message（coord，ISSUE-002）—— P5 前补全
+- [ ] ai gRPC 50057 启用（ai12）—— AI 用量统计（P5，可选）

 ### 3.2 我的就绪标志（供下游消费）

- [ ] data-ana gRPC 50055 启用（HealthService.Check 返回 SERVING）
- [ ] AnalyticsService 12 RPC 可调用（含 4 端 Dashboard + Server Streaming SubscribeMasteryUpdate）
- [ ] GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard 返回结构化数据
- [ ] edu.data_ana.mastery.events topic 可发布（mastery.updated / warning.triggered）
+- [ ] **P4 就绪**：data-ana gRPC 50055 启用（HealthService.Check 返回 SERVING）
+- [ ] **P4 就绪**：AnalyticsService 12 RPC 可调用（含 4 端 Dashboard + Warning + Mastery + Server Streaming SubscribeMasteryUpdate）
+- [ ] **P4 就绪**：GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard 返回结构化数据
+- [ ] **P4 就绪**：`edu.insight.mastery.updated` topic 可发布（mastery.updated / warning.triggered）
+- [ ] **P5 就绪**：SubscribeMasteryUpdate server-streaming RPC 可订阅
+- [ ] **P6 就绪**：CDC 多实例水平扩展 + ExamCache Redis 化完成

 ---

@@ -106,16 +168,17 @@
  - GetStudentDashboard 返回固定仪表盘（avg_score=85.0, class_rank=5, weak_points 3 个）
  - GetParentDashboard 返回固定仪表盘（child_avg_score=85.0, child_class_rank=5）
  - GetAdminDashboard 返回固定仪表盘（total_teachers=50, total_students=1200, school_avg_score=80.0）
-  - GetWarningList 返回固定 5 条预警（severity: warning/critical）
+  - GetWarnings 返回固定 5 条预警（severity: warning/critical）
  - GetMasteryDistribution 返回固定分布（mastered=20, progressing=7, weak=3）
  - SubscribeMasteryUpdate 返回固定流（每 5 秒推 1 个 MasteryUpdateEvent）
- **Kafka mock**：data-ana 就绪前不发布真实 MasteryEvent，msg 使用本地 stub 预警
+- **Kafka mock**：data-ana 就绪前不发布真实 MasteryUpdated / WarningTriggered，msg 使用本地 stub 预警

 ### 4.2 我消费的 mock

 在真实上游就绪前，data-ana 使用以下 mock：

- 业务数据：ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业 × 30 天出勤），不依赖 core-edu CDC
- 知识点维度：内置固定知识点表（数学 50 个知识点），不依赖 content 事件
- AI 用量：AIUsageEvent 为空，仪表盘 AI 用量区块显示"暂无数据"
- CDC 通道：core-edu 就绪前 Debezium 不启动，使用 ClickHouse 批量导入模拟数据
+- **业务数据**：ClickHouse 内置模拟数据集（30 学生 × 5 考试 × 10 作业 × 30 天出勤），不依赖 core-edu CDC
+- **知识点维度**：内置固定知识点表（数学 50 个知识点），不依赖 content 事件
+- **AI 用量**：AIUsageEvent 为空，仪表盘 AI 用量区块显示"暂无数据"
+- **CDC 通道**：core-edu 就绪前 Debezium 不启动，使用 ClickHouse 批量导入模拟数据
+- **DataScope**：iam GetEffectiveDataScope 未就绪前，按 role 映射默认 DataScope 降级（教师=CLASS，学生=SELF，管理员=SCHOOL），标注 `details.degraded: true`
--- a/docs/architecture/issues/objections/data-ana_issue.md
+++ b/docs/architecture/issues/objections/data-ana_issue.md
@@ -1,24 +1,129 @@
 # data-ana 问题记录

 > 负责人：ai11
-> 关联：[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
+> 关联：[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 的仲裁逐项核查落实状态。

-### ISSUE-[编号]-[AI标识]：[标题]
+### 0.1 coord.md 仲裁核查

- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁 / 已裁决（见 coord.md §X）
-->
+| 编号    | 主题                         | 涉及 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 仲裁
--- a/docs/architecture/issues/worklines/data-ana_workline.md
+++ b/docs/architecture/issues/worklines/data-ana_workline.md
@@ -1,18 +1,34 @@
 # data-ana 工作排期

 > 负责人：ai11
-> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
-> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
+> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/data-ana_contract.md](../contracts/data-ana_contract.md)、[objections/data-ana_issue.md](../objections/data-ana_issue.md)
+> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
+> 基线日期：批次 0 已完成（2026-07-09），批次 1（P2）2026-07-10 启动

 ---

 ## §1 总览

-data-ana 是数据分析服务，提供 AnalyticsService（12 个 RPC），基于 ClickHouse 列存查询与 CDC 消费实现实时分析。全阶段目标：P2 ClickHouse 接入+CDC 消费 → P3 AnalyticsService 12 RPC → P4-P6 持续优化。
+data-ana 是 D6 智能洞察领域的纯读模型服务（Python/FastAPI），基于 ClickHouse ReplacingMergeTree 宽表 + Debezium CDC 消费实现实时学情分析。
+
+**核心交付物**：
+- gRPC server :50055 + AnalyticsService 12 RPC（含 1 个 Server Streaming）
+- HTTP :3006 14 端点（3 基础 + 11 业务，保留作 Gateway 直连降级）
+- ClickHouse 5 宽表（student_dashboard_view / student_errors / mastery_snapshot / attendance_logs / ai_usage_log）
+- CDC 消费者（core-edu MySQL binlog → Kafka → ClickHouse 宽表投影）
+- 掌握度计算（加权滑动平均 + 遗忘曲线）+ 预警评估
+- 派生数据事件发布（edu.insight.mastery.updated / edu.insight.warning.triggered，豁免 Outbox）
+
+**阶段里程碑**：
+- P2 预备：ClickHouse 接入 + CDC 骨架 + ActionState 信封重构 + mock 数据集
+- P3 预备：CDC 通道接入 + 掌握度算法 v1 + Repository 封装
+- P4 主战场：gRPC 50055 启用 + 12 RPC + 4 端 Dashboard + Warning + DataScope + 事件发布
+- P5 扩展：SubscribeMasteryUpdate stream + AI 用量消费 + 手动 commit
+- P6 硬化：CDC 水平扩展 + 容量规划 + 数据治理 + 监控告警

 ---

-## §2 全阶段甘特图（P2-P6，各 AI 自行细化）
+## §2 全阶段甘特图（P2-P6）

 ```mermaid
 gantt
@@ -20,26 +36,317 @@ gantt
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

-    section P2-P6
-    [阶段任务] :a11a, 2026-07-10, Xd
+    section P2 预备（与批次1并行）
+    2.1 ClickHouse DDL 5宽表建表 :a11a, 2026-07-10, 2d
+    2.2 CDC消费骨架(aiokafka) :a11b, after a11a, 2d
+    2.3 mock数据集(30学生×5考试×10作业) :a11c, after a11a, 1d
+    2.4 ActionState信封重构(P0整改) :crit, a11d, 2026-07-10, 2d
+    2.5 config.py修正(env/Redis/gRPC) :a11e, after a11d, 1d
+
+    section P3 预备（与批次2并行）
+    3.1 gRPC server骨架(3 RPC,不启用) :a11f, after a11b, 2d
+    3.2 core-edu CDC通道接入(grades/exams/homework) :a11g, after a11b, 3d
+    3.3 ExamCache内存LRU :a11h, after a11g, 1d
+    3.4 掌握度算法v1(weighted_moving_avg) :a11i, after a11g, 2d
+    3.5 ClickHouseRepository(FINAL/argMax) :a11j, after a11i, 2d
+
+    section P4 主战场（批次3, 11d）
+    4.1 gRPC 50055正式启用 :crit, a11k, after a11j, 1d
+    4.2 analytics.proto扩展12 RPC :crit, a11l, after a11k, 2d
+    4.3 4端Dashboard RPC实现 :a11m, after a11l, 3d
+    4.4 WarningService+TriggerWarning :a11n, after a11l, 2d
+    4.5 GetMasteryDistribution+GetStudentMastery :a11o, after a11m, 1d
+    4.6 iam.GetEffectiveDataScope集成(降级兜底) :crit, a11p, after a11k, 2d
+    4.7 DataScope 6级WHERE注入 :a11q, after a11p, 1d
+    4.8 attendance+content CDC消费 :a11r, after a11g, 2d
+    4.9 MasteryEvent+WarningTriggered发布 :a11s, after a11n, 1d
+    4.10 HTTP 14端点+readyz硬化 :a11t, after a11m, 2d
+
+    section P5 扩展（批次4并行）
+    5.1 SubscribeMasteryUpdate stream RPC :a11u, after a11t, 3d
+    5.2 AIUsageEvent消费→ai_usage_log :a11v, after a11u, 2d
+    5.3 手动commit替换auto_commit :a11w, after a11v, 1d
+    5.4 Admin Dashboard AI用量区块 :a11x, after a11v, 2d
+
+    section P6 硬化（批次5并行）
+    6.1 CDC多实例水平扩展 :a11y, after a11x, 3d
+    6.2 ExamCache Redis化 :a11z, after a11y, 2d
+    6.3 容量规划+TTL归档策略 :a11aa, after a11z, 2d
+    6.4 监控告警(consumer lag HPA) :a11ab, after a11aa, 2d
+    6.5 readyz深度硬化 :a11ac, after a11ab, 1d
 ```

-> **注意**：以上为 coord 初始规划，ai11 接管后必须自行细化为完整 P2-P6 排期。
+> **关键路径**（crit）：ActionState 信封重构 → gRPC 50055 启用 → analytics.proto 扩展 → iam GetEffectiveDataScope 集成
+> **总工期**：约 51 天（2026-07-10 ~ 2026-08-30），其中 P4 主战场 11 天为关键交付期

 ---

 ## §3 详细任务

-### 全阶段任务
+### 3.1 P2 预备期（2026-07-10 ~ 2026-07-18，8d）
+
+#### 任务 2.1：ClickHouse DDL 5 宽表建表

 - **负责人**：ai11
- **交付物**：⚠️ 由 ai11 自行补充
- **依赖**：见 [contracts/data-ana_contract.md](../contracts/data-ana_contract.md)
- **验收标准**：⚠️ 由 ai11 自行补充
+- **依赖**：无（ClickHouse 实例就绪，由 infra 提供）
+- **交付物**：`infra/clickhouse/ddl/data_ana.sql`（5 宽表 DDL：student_dashboard_view / student_errors / mastery_snapshot / attendance_logs / ai_usage_log）
+- **验收标准**：5 表在 ClickHouse 中创建成功，ReplacingMergeTree 引擎 + ORDER BY + PARTITION BY 符合 02 §3 DDL 设计
+
+#### 任务 2.2：CDC 消费骨架
+
+- **负责人**：ai11
+- **依赖**：Kafka 就绪
+- **交付物**：`src/data_ana/cdc_consumer.py` 重构（aiokafka AIOKafkaConsumer + EventHandler 路由框架）
+- **验收标准**：能消费 mock CDC 事件并打印路由日志，consumer group = `data-ana-cdc`
+
+#### 任务 2.3：mock 数据集
+
+- **负责人**：ai11
+- **依赖**：任务 2.1
+- **交付物**：`scripts/seed_clickhouse.py`（批量导入 30 学生 × 5 考试 × 10 作业 × 30 天出勤模拟数据）
+- **验收标准**：ClickHouse 5 表有数据，可查询返回非空结果
+
+#### 任务 2.4：ActionState 信封重构（P0 整改，coord-cross-review §5.3）
+
+- **负责人**：ai11
+- **依赖**：无
+- **交付物**：`src/data_ana/shared/action_state.py`（ActionState[T] 泛型 + ActionStateError + ok()/fail() 类方法）
+- **验收标准**：main.py 所有端点返回 `ActionState[T]`，degraded 标记在顶层 `details.degraded`（非 error.details），ruff 零错误
+
+#### 任务 2.5：config.py 修正
+
+- **负责人**：ai11
+- **依赖**：无
+- **交付物**：`src/data_ana/config.py` 修正（env_prefix 补 Redis / gRPC / ClickHouse 配置项，pydantic-settings 校验）
+- **验收标准**：配置项覆盖 02 §13 配置清单，环境变量缺失时 pydantic-settings 报错
+
+---
+
+### 3.2 P3 预备期（2026-07-18 ~ 2026-07-26，8d）
+
+#### 任务 3.1：gRPC server 骨架（3 RPC，不正式启用）
+
+- **负责人**：ai11
+- **依赖**：analytics.proto 当前 3 RPC（无需 coord 补全）
+- **交付物**：`src/data_ana/grpc_server.py`（grpc.aio Server 骨架 + 3 RPC 实现，绑定 :50055 但不启动对外）
+- **验收标准**：本地可启动 gRPC server，3 RPC 可调用返回 mock 数据
+
+#### 任务 3.2：core-edu CDC 通道接入
+
+- **负责人**：ai11
+- **依赖**：core-edu MySQL 就绪 + Debezium CDC 配置（core-edu 就绪前用 mock binlog 事件）
+- **交付物**：`src/data_ana/cdc_consumer.py` 完善（EventHandler 处理 grades/exams/homework/classes 表 CDC 事件）
+- **验收标准**：消费 CDC 事件 → 解析 Debezium JSON → 查 ExamCache 填 class_id → upsert ClickHouse 宽表
+
+#### 任务 3.3：ExamCache 内存 LRU
+
+- **负责人**：ai11
+- **依赖**：任务 3.2
+- **交付物**：`src/data_ana/exam_cache.py`（内存 LRU dict，max 10000 条，exam_id → {class_id, subject_id}）
+- **验收标准**：CDC exams 事件触发 ExamCache 更新，grades 事件查 ExamCache 获取 class_id
+
+#### 任务 3.4：掌握度算法 v1
+
+- **负责人**：ai11
+- **依赖**：任务 3.2
+- **交付物**：`src/data_ana/mastery_service.py`（加权滑动平均算法，权重 w_i = 0.6^i，归一化）
+- **验收标准**：输入学生近期 N 次成绩 → 输出 mastery_level (0.0-1.0) → 写 mastery_snapshot 表
+
+#### 任务 3.5：ClickHouseRepository 封装
+
+- **负责人**：ai11
+- **依赖**：任务 2.1
+- **交付物**：`src/data_ana/clickhouse_client.py` 重构（查询封装 + FINAL/argMax 去重 + DataScope WHERE 注入接口）
+- **验收标准**：查询 student_dashboard_view 返回去重后最新版本数据
+
+---
+
+### 3.3 P4 主战场期（2026-07-26 ~ 2026-08-06，11d，批次 3）
+
+#### 任务 4.1：gRPC 50055 正式启用
+
+- **负责人**：ai11
+- **依赖**：任务 3.1
+- **交付物**：main.py lifespan 启动 gRPC server :50055，HealthService.Check 返回 SERVING
+- **验收标准**：gRPC server 对外可访问，HealthService.Check = SERVING
+
+#### 任务 4.2：analytics.proto 扩展 12 RPC
+
+- **负责人**：ai11（本分支内补全 proto，提请 coord 合并）
+- **依赖**：ISSUE-003 解决（coord 确认或 ai11 自行补全）
+- **交付物**：`packages/shared-proto/proto/analytics.proto` 扩展至 12 RPC（3 现有 + 9 新增 message 定义）
+- **验收标准**：`buf lint` 零错误，`buf generate` 生成 Python stub 成功，12 RPC 全部可调用
+
+#### 任务 4.3：4 端 Dashboard RPC 实现
+
+- **负责人**：ai11
+- **依赖**：任务 4.2
+- **交付物**：GetTeacherDashboard / GetStudentDashboard / GetParentDashboard / GetAdminDashboard 4 RPC 实现
+- **验收标准**：4 RPC 返回 ActionState[DashboardData]，DataScope 过滤生效，降级时返回骨架数据 + degraded: true
+
+#### 任务 4.4：WarningService + TriggerWarning
+
+- **负责人**：ai11
+- **依赖**：任务 3.4（掌握度算法）
+- **交付物**：`src/data_ana/warning_service.py`（预警阈值评估 + TriggerWarning RPC + GetWarnings RPC）
+- **验收标准**：掌握度 < 0.4 触发 LOW_MASTERY 预警，成绩环比下降 20% 触发 SCORE_DROP，缺勤 ≥ 3 次/周触发 ABSENT_FREQUENT
+
+#### 任务 4.5：GetMasteryDistribution + GetStudentMastery
+
+- **负责人**：ai11
+- **依赖**：任务 3.4 + 任务 4.2
+- **交付物**：2 RPC 实现（班级掌握度分布 + 学生知识点掌握度明细）
+- **验收标准**：返回 mastered/progressing/weak 三档分布数据
+
+#### 任务 4.6：iam.GetEffectiveDataScope 集成（降级兜底）
+
+- **负责人**：ai11
+- **依赖**：ISSUE-001 解决（iam.proto 补全 GetEffectiveDataScope）。若 P4 时 iam 未就绪，使用降级兜底
+- **交付物**：`src/data_ana/iam_client.py`（gRPC 调 iam.GetEffectiveDataScope + Redis 缓存 5min + 降级兜底）
+- **验收标准**：iam 可用时调 gRPC 获取 DataScope；iam 不可用时按 role 映射默认 DataScope + degraded: true
+
+#### 任务 4.7：DataScope 6 级 WHERE 注入
+
+- **负责人**：ai11
+- **依赖**：任务 4.6 + 任务 3.5
+- **交付物**：ClickHouseRepository 查询方法注入 DataScope WHERE 子句（SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL）
+- **验收标准**：教师只能查自己班级数据，学生只能查自己数据，管理员可查全校数据
+
+#### 任务 4.8：attendance + content CDC 消费
+
+- **负责人**：ai11
+- **依赖**：任务 3.2（CDC 框架）
+- **交付物**：EventHandler 扩展 attendance_logs 表 CDC + content_knowledge_points 表 CDC
+- **验收标准**：考勤事件落 attendance_logs 表，知识点事件更新 mastery_snapshot 元数据
+
+#### 任务 4.9：MasteryEvent + WarningTriggered 事件发布
+
+- **负责人**：ai11
+- **依赖**：任务 3.4 + 任务 4.4
+- **交付物**：`src/data_ana/kafka_producer.py`（aiokafka AIOKafkaProducer + idempotent + transactional_id）
+- **验收标准**：掌握度计算完成发布 `edu.insight.mastery.updated`，预警触发发布 `edu.insight.warning.triggered`，豁免 Outbox
+
+#### 任务 4.10：HTTP 14 端点 + readyz 硬化
+
+- **负责人**：ai11
+- **依赖**：任务 4.3 + 任务 4.4 + 任务 4.5
+- **交付物**：main.py 14 个 HTTP 端点全部实现（3 基础 + 11 业务）+ /readyz 检查 4 依赖（clickhouse/cdc_consumer/redis/iam_grpc）
+- **验收标准**：14 端点返回 ActionState[T]，/readyz 依赖检查正确反映服务状态
+
+---
+
+### 3.4 P5 扩展期（2026-08-06 ~ 2026-08-19，13d，批次 4 并行）
+
+#### 任务 5.1：SubscribeMasteryUpdate Server Streaming RPC
+
+- **负责人**：ai11
+- **依赖**：任务 4.2 + 任务 4.9
+- **交付物**：SubscribeMasteryUpdate RPC 实现（server-streaming，客户端订阅 student_id/class_id，掌握度更新时推送）
+- **验收标准**：客户端订阅后，掌握度计算完成时收到 MasteryUpdateEvent 流
+
+#### 任务 5.2：AIUsageEvent 消费 → ai_usage_log
+
+- **负责人**：ai11
+- **依赖**：ISSUE-002 解决（events.proto 补 AIUsageEvent）+ ai 服务发布 `edu.insight.ai.usage` topic
+- **交付物**：EventHandler 扩展 AIUsageEvent 消费 → 落 ai_usage_log 表
+- **验收标准**：ai 服务发布用量事件后，ai_usage_log 表有数据，Admin Dashboard AI 用量区块可展示
+
+#### 任务 5.3：手动 commit 替换 auto_commit
+
+- **负责人**：ai11
+- **依赖**：任务 3.2
+- **交付物**：cdc_consumer.py 改为 `enable_auto_commit=False` + 手动 commit（at-least-once）
+- **验收标准**：ClickHouse 写入成功后才 commit offset，重启后无重复消费（依赖 ReplacingMergeTree 去重）
+
+#### 任务 5.4：Admin Dashboard AI 用量区块
+
+- **负责人**：ai11
+- **依赖**：任务 5.2
+- **交付物**：GetAdminDashboard RPC 补全 AI 用量统计区块（按 provider/model/时间窗聚合）
+- **验收标准**：Admin Dashboard 返回 AI 用量数据，无数据时显示"暂无数据"
+
+---
+
+### 3.5 P6 硬化期（2026-08-19 ~ 2026-08-30，11d，批次 5 并行）
+
+#### 任务 6.1：CDC 多实例水平扩展
+
+- **负责人**：ai11
+- **依赖**：任务 5.3（手动 commit）
+- **交付物**：CdcConsumer 支持多实例分摊 partition（consumer group 不变）
+- **验收标准**：2+ 实例消费同一 topic 无重复无遗漏
+
+#### 任务 6.2：ExamCache Redis 化
+
+- **负责人**：ai11
+- **依赖**：任务 6.1
+- **交付物**：exam_cache.py 改为 Redis 实现（key: `data_ana:exam:{exam_id}` TTL 30 天）
+- **验收标准**：多实例共享 ExamCache，重启后缓存不丢失
+
+#### 任务 6.3：容量规划 + TTL 归档策略
+
+- **负责人**：ai11
+- **依赖**：无
+- **交付物**：ClickHouse TTL 策略（student_dashboard_view 保留 2 年，ai_usage_log 保留 1 年）+ 冷热数据分离方案
+- **验收标准**：TTL 配置生效，过期数据自动清理
+
+#### 任务 6.4：监控告警完善
+
+- **负责人**：ai11
+- **依赖**：任务 6.1
+- **交付物**：Prometheus 指标补全（consumer lag histogram + 慢查询 counter + ClickHouse 连接池 gauge）+ Grafana dashboard
+- **验收标准**：consumer lag 超阈值触发 HPA，慢查询超阈值告警
+
+#### 任务 6.5：readyz 深度硬化
+
+- **负责人**：ai11
+- **依赖**：任务 4.10
+- **交付物**：/readyz 检查项完善（ClickHouse 查询超时 1s + Redis ping + iam gRPC 超时 2s + CDC consumer lag < 1000）
+- **验收标准**：任一依赖不健康时 /readyz 返回 503，K8s 摘流量

 ---

 ## §4 依赖与就绪信号

- **我依赖**：⚠️ 由 ai11 自行补充（见 contract.md）
- **我的就绪信号**：⚠️ 由 ai11 自行补充
+### 4.1 我依赖的上游就绪标志
+
+- [ ] **core-edu gRPC 50053 启用**（ai08，批次 2）—— CDC 数据源（grades/exams/homework/attendance 表 binlog）
+- [ ] **core-edu MySQL Debezium CDC 配置**（ai08 + SRE）—— CDC 通道前提
+- [ ] **content gRPC 50054 启用**（ai09，批次 3）—— 知识点维度 CDC
+- [ ] **iam.proto 补全 GetEffectiveDataScope RPC**（ai06/coord，ISSUE-001）—— DataScope 解析
+- [ ] **analytics.proto 扩展至 12 RPC**（coord/ai11，ISSUE-003）—— gRPC stub 生成前提
+- [ ] **events.proto 补全 AIUsageEvent message**（coord，ISSUE-002）—— AI 用量消费（P5）
+- [ ] **ai 服务发布 `edu.insight.ai.usage` topic**（ai12，批次 4）—— AI 用量统计（P5）
+
+> **降级兜底**：core-edu / content / iam 未就绪时，使用 ClickHouse 内置 mock 数据集 + 硬编码 DataScope 降级，标注 `details.degraded: true`
+
+### 4.2 我的就绪信号（供下游消费）
+
+- [ ] **P4 就绪**：data-ana gRPC 50055 启用（HealthService.Check = SERVING）+ AnalyticsService 12 RPC 可调用 + 4 端 Dashboard 返回结构化数据
+- [ ] **P4 就绪**：`edu.insight.mastery.updated` topic 可发布（mastery.updated / warning.triggered）
+- [ ] **P5 就绪**：SubscribeMasteryUpdate server-streaming RPC 可订阅
+- [ ] **P6 就绪**：CDC 多实例水平扩展 + ExamCache Redis 化完成
+
+### 4.3 下游消费方
+
+| 下游                       | 消费接口                                                         | 就绪依赖阶段 |
+| -------------------------- | ---------------------------------------------------------------- | ------------ |
+| teacher-bff（ai03）        | gRPC 50055 GetTeacherDashboard / GetClassPerformance 等          | P4           |
+| student-bff（ai04）        | gRPC 50055 GetStudentDashboard / GetStudentWeakness 等           | P4           |
+| parent-bff（ai05）         | gRPC 50055 GetParentDashboard                                    | P4           |
+| ai 服务（ai12）            | gRPC 50055 反向调用查学情（GetStudentMastery / GetLearningTrend） | P5           |
+| core-edu（ai08）           | Kafka `edu.insight.mastery.updated`（推荐个性化练习）            | P4           |
+| msg（ai10）                | Kafka `edu.insight.warning.triggered`（推送通知）                | P4           |
+
+---
+
+## §5 风险与缓解
+
+| 风险                                         | 影响 | 缓解措施                                                                                   |
+| -------------------------------------------- | ---- | ------------------------------------------------------------------------------------------ |
+| iam.proto 未补全 GetEffectiveDataScope       | P4   | 降级兜底：按 role 映射默认 DataScope + degraded: true（ISSUE-001）                        |
+| analytics.proto 未扩展 12 RPC                | P4   | ai11 本分支自行补全 proto，提请 coord 合并（ISSUE-003）                                    |
+| core-edu CDC 通道未就绪                      | P3-P4 | mock 数据集降级 + 本地 stub CDC 事件                                                       |
+| ClickHouse ReplacingMergeTree 去重延迟       | P4   | 查询加 FINAL / argMax 强制去重（02 §3.6 已设计）                                          |
+| 单实例 CDC 消费者单点故障                     | P4   | P6 演进为多实例 + Redis ExamCache；P4 阶段监控 consumer lag 告警                          |
+| 掌握度算法精度不足                            | P4   | v1 用加权滑动平均，P5+ 评估引入遗忘曲线 max 叠加（02 §9 已设计 MasteryMethod 枚举预留）    |