# data-ana 工作排期

> 负责人：ai11
> 关联：[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 是 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）

```mermaid
gantt
    title ai11 data-ana 全阶段排期
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    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
```

> **关键路径**（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
- **依赖**：无（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 依赖与就绪信号

### 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 枚举预留）    |