faaaf29f67
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
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 /metricsPrometheus 指标GET /analytics/class/{class_id}/performance班级成绩分析（P4 骨架）GET /analytics/student/{student_id}/weakness学生薄弱知识点分析（P4 骨架）
对外契约
gRPC 服务 AnalyticsService 定义见 packages/shared-proto/proto/analytics.proto。