# data-ana 数据分析服务

> 版本：0.1（骨架）
> 日期：2026-07-07
> 状态：P4 待交付
> 关联文档：[架构影响地图](../../architecture/004_architecture_impact_map.md)

---

## 1. 模块职责

data-ana 是数据分析限界上下文（Python 实现），管理 Report、Mastery、Dashboard 聚合。
消费 core-edu 与 content 的领域事件，构建 ClickHouse 学情宽表，计算知识点掌握度。
对外提供学情仪表盘查询、班级/年级/学校维度报表、个性化推荐数据支撑。

---

## 2. 技术栈

| 类别 | 技术 | 版本 | 用途 |
|------|------|------|------|
| 语言 | Python | 3.12+ | 数据分析 |
| 框架 | FastAPI | 0.110+ | 异步 API |
| ORM | SQLAlchemy | 2.x | ClickHouse 查询 |
| 分析库 | ClickHouse | - | 学情宽表、实时聚合 |
| 任务 | Celery | 5.x | 异步计算任务 |
| 校验 | pydantic | 2.x | 运行时校验 |
| 追踪 | OpenTelemetry | - | 分布式追踪 |

---

## 3. 架构图

```mermaid
graph TB
    BFF[BFF 聚合层] -->|gRPC| ANA[data-ana 服务]
    K[(Kafka)] -->|消费事件| ANA
    ANA --> PROJ[Projection<br/>事件 → ClickHouse]
    ANA --> CALC[MasteryCalculator<br/>掌握度计算]
    ANA --> RPT[ReportGenerator<br/>报表生成]
    ANA -->[(ClickHouse<br/>学情宽表)]
    ANA -.事件.-> K2[(Kafka<br/>edu.insight.mastery.updated)]
```

> 待 P4 交付时补充完整的分层架构图与事件消费管线图。

---

## 4. 核心流程图

```mermaid
sequenceDiagram
    participant K as Kafka
    participant ANA as data-ana
    participant CH as ClickHouse
    participant BFF as BFF

    K->>ANA: edu.teaching.grade.recorded
    ANA->>ANA: Projection 写入宽表
    ANA->>ANA: 触发掌握度计算（Celery）
    ANA->>CH: 更新 mastery 表
    ANA->>K: 发布 edu.insight.mastery.updated
    BFF->>ANA: gRPC GetDashboard(studentId)
    ANA->>CH: 查询宽表聚合
    ANA-->>BFF: DashboardDTO
```

> 待 P4 交付时补充：报表生成流程、掌握度算法流程、CDC 同步流程。

---

## 5. 对外契约

- **gRPC 服务**：DashboardService、MasteryService、ReportService（待 P4 定义 protobuf）
- **消费事件**：`edu.teaching.*`、`edu.content.*`
- **发布事件**：`edu.insight.mastery.updated`
- **ClickHouse 宽表**：student_wide_table、mastery_table、exam_analysis_table

> 待 P4 交付时补充完整 protobuf 定义与宽表 schema。

---

## 6. 依赖关系

- **上游**：teacher-bff、student-bff、parent-bff、ai（gRPC 查询学情）
- **下游**：ClickHouse、Kafka（消费与发布）、Celery（异步任务）
- **跨服务**：消费 core-edu/content 事件；发布掌握度事件被 core-edu 消费触发推荐

---

## 7. 架构约束

1. 查询必须走 ClickHouse 宽表，禁止实时计算
2. 事件消费必须幂等，基于 event_id 去重
3. 掌握度计算必须异步（Celery），不阻塞事件消费
4. 宽表查询响应时间 ≤ 5 秒

> 待 P4 交付时补充完整约束清单。

---

## 8. 架构决策

> 待 P4 交付时补充 ADR 记录，预计包括：Python+FastAPI 选型、ClickHouse 选型、Celery 异步框架选型、掌握度算法选型。