feat(p4): content analysis service with Neo4j knowledge graph and ClickHouse analytics
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)
This commit is contained in:
58
services/data-ana/README.md
Normal file
58
services/data-ana/README.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# 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`。
|
||||
Reference in New Issue
Block a user