9850bfcfd1
P4 阶段交付物： - services/content: 内容资源服务（NestJS） - textbooks: 教材 CRUD + 知识图谱绑定 - config/neo4j.ts: Neo4j driver 单例 - textbooks.service.ts: MySQL CRUD + Neo4j 知识图谱（createKnowledgeGraph/getPrerequisites） - package.json: 补充 @opentelemetry/sdk-node + exporter-trace-otlp-http - services/data-ana: 数据分析服务（Python FastAPI） - main.py: FastAPI + /healthz + class_performance + student_weakness 骨架 - clickhouse_client.py: ClickHouse 客户端封装 - config.py: 环境变量配置 - packages/shared-proto/proto/content.proto: TextbookService + KnowledgeGraphService 契约 - packages/shared-proto/proto/analytics.proto: AnalyticsService 契约（class_performance/student_weakness）
59 lines
1.7 KiB
Markdown
59 lines
1.7 KiB
Markdown
# 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`。
|