# data-ana 数据分析服务

> 版本：0.1（P4 骨架）
> 端口：3006

## 职责

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

## 技术栈

- Python 3.12+ / FastAPI 0.115+
- clickhouse-connect（ClickHouse 宽表查询）
- pydantic + pydantic-settings（运行时校验与配置）
- structlog（结构化日志）
- prometheus-client（指标）
- OpenTelemetry（分布式追踪）

## 开发

```bash
uv sync
uv run uvicorn src.data_ana.main:app --host 0.0.0.0 --port 3006 --reload
```

## 配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PORT` | 3006 | 服务端口 |
| `CLICKHOUSE_HOST` | localhost | ClickHouse 主机 |
| `CLICKHOUSE_PORT` | 8123 | ClickHouse HTTP 端口 |
| `CLICKHOUSE_DATABASE` | edu_analytics | ClickHouse 数据库 |
| `OTEL_ENDPOINT` | http://localhost:4318 | OpenTelemetry 端点 |
| `LOG_LEVEL` | info | 日志级别 |

## 模块结构

```
src/data_ana/
├─ __init__.py
├─ main.py              # FastAPI 入口（健康检查 + 分析端点骨架）
├─ config.py            # pydantic-settings 配置
└─ clickhouse_client.py # ClickHouse 客户端单例
```

## 关键端点

- `GET /healthz` 健康检查
- `GET /metrics` Prometheus 指标
- `GET /analytics/class/{class_id}/performance` 班级成绩分析（P4 骨架）
- `GET /analytics/student/{student_id}/weakness` 学生薄弱知识点分析（P4 骨架）

## 对外契约

gRPC 服务 `AnalyticsService` 定义见 `packages/shared-proto/proto/analytics.proto`。