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:
SpecialX
2026-07-08 01:38:35 +08:00
parent 23246ade6d
commit 9850bfcfd1
28 changed files with 936 additions and 0 deletions

View File

@@ -0,0 +1,58 @@
# data-ana 数据分析服务
> 版本0.1P4 骨架)
> 端口3006
## 职责
数据分析限界上下文Python 实现),消费 core-edu 与 content 的领域事件,
构建 ClickHouse 学情宽表,计算知识点掌握度。
对外提供学情仪表盘查询、班级/年级/学校维度报表、个性化推荐数据支撑。
## 技术栈
- Python 3.12+ / FastAPI 0.115+
- clickhouse-connectClickHouse 宽表查询)
- 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`