Edu/services/data-ana

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（分布式追踪）

开发

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。