xiner/Edu

Files

SpecialX 5b06bdbc52 feat(data-ana): docker 本地测试通过 + gRPC 修复 + nextstep 上下游依赖文档

2026-07-13 23:57:48 +08:00

18 KiB

Raw Blame History

data-ana 模块上下游依赖与工作清单（Next Steps）

模块：data-ana（智能洞察域，数据分析服务）负责人：ai11 更新日期：2026-07-13 关联文档：01-understanding.md、02-architecture-design.md、data-ana_contract.md、data-ana_workline.md

1. 模块当前状态

data-ana 已完成 P2-P5 全部代码实现，P6 硬化期未开始。当前服务包含：

HTTP 14 端点（3 基础 + 11 业务），端口 3006
gRPC 12 RPC（11 unary + 1 server-streaming），端口 50055
CDC 消费者：Debezium binlog → ClickHouse 5 宽表，手动 commit + Redis 去重
ClickHouse 宽表：student_dashboard_view / student_errors / mastery_snapshot / ai_usage_log / attendance_logs
Kafka 生产者：MasteryEvent + WarningTriggered（Outbox 豁免）
iam gRPC 集成：GetEffectiveDataScope + Redis 缓存 + role 降级兜底
降级模式：ClickHouse/Kafka/Redis/iam 任一不可达时服务仍可启动

2. 上游依赖（data-ana 依赖谁）

2.1 iam 服务（ai06 负责）— P0

#	依赖项	用途	状态
1	gRPC `GetEffectiveDataScope(userId)` :50052	DataScope 6 级过滤（SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL）	✅ 已就绪（iam.proto 已补全）
2	REST `GET /healthz` :3002	/readyz 下游健康检查	⏳ 待 iam 容器启动
3	JWT RS256 公钥	（data-ana 不直接验签，由 api-gateway 验签后注入 x-user-* header）	—

环境变量：DATA_ANA_IAM_GRPC_TARGET=iam:50052 降级策略：iam 不可达时按 role 映射默认 DataScope + degraded: true

2.2 ClickHouse（基础设施）— P0

#	依赖项	用途	状态
1	ClickHouse :8123	5 宽表读写（分析查询核心存储）	✅ Docker 已启动
2	DDL 建表	5 宽表 schema	✅ 已创建 `scripts/clickhouse_ddl.sql`
3	种子数据	mock 数据集	✅ 已创建 `scripts/seed_clickhouse.py`

环境变量：DATA_ANA_CLICKHOUSE_HOST=clickhouse、DATA_ANA_CLICKHOUSE_PORT=8123、DATA_ANA_CLICKHOUSE_DATABASE=edu_analytics 降级策略：ClickHouse 不可达时服务启动跳过，查询返回 degraded 空数据

2.3 Kafka（基础设施）— P1

#	依赖项	用途	状态
1	Kafka :29092 消费	CDC topic（edu-cdc.next_edu_cloud.* 等 7 topic）	✅ Docker 已启动
2	Kafka :29092 生产	edu.insight.mastery.updated + edu.insight.warning.triggered	✅ Docker 已启动

环境变量：DATA_ANA_KAFKA_BROKERS=kafka:29092 降级策略：Kafka 不可达时 CDC 消费者不启动，事件发布静默失败

2.4 Redis（基础设施）— P1

#	依赖项	用途	状态
1	Redis :6379	DataScope 缓存（5min TTL）+ CDC event_id 去重 + Warning bitmap 去重	✅ Docker 已启动

环境变量：DATA_ANA_REDIS_URL=redis://redis:6379 降级策略：Redis 不可达时跳过缓存，每次直查 iam gRPC

2.5 core-edu 服务（ai07 负责）— P1（CDC 依赖）

#	依赖项	用途	状态
1	MySQL binlog（core_edu 库）	CDC 消费 grades/exams/homework/attendance/classes 变更	⏳ 待 core-edu MySQL 就绪
2	Debezium Connect	MySQL → Kafka CDC 管道	⏳ 待 Debezium 部署

2.6 content 服务（ai08 负责）— P2（CDC 依赖）

#	依赖项	用途	状态
1	MySQL binlog（content 库）	CDC 消费 content_knowledge_points 变更 → Redis 知识点缓存	⏳ 待 content MySQL 就绪

2.7 ai 服务（ai12 负责）— P2（事件消费）

#	依赖项	用途	状态
1	Kafka topic `edu.insight.ai.usage`	消费 AIUsageEvent → ai_usage_log 宽表	✅ events.proto 已补全 AIUsageEvent

3. 下游依赖（谁依赖 data-ana）

3.1 teacher-bff（ai03 负责）— P0

#	gRPC RPC	用途	状态
1	`GetStudentWeakness(classId)` :50055	`studentWeakness` 查询	✅ 已实现
2	`GetLearningTrend(classId)` :50055	`learningTrend` 查询	✅ 已实现
3	`GetClassPerformance(classId)` :50055	`classPerformance` 查询	✅ 已实现
4	`GetAdminDashboard(input)` :50055	`adminDashboard` AI 用量区块	✅ 已实现

需求来源：teacher-bff nextstep.md §2.4 环境变量（teacher-bff 侧）：DATA_ANA_GRPC_TARGET=data-ana:50055

3.2 student-bff（ai04 负责）— P0

#	gRPC RPC	用途	状态
1	`GetStudentWeakness(studentId)` :50055	`myWeakness` 查询	✅ 已实现
2	`GetLearningTrend(studentId)` :50055	`myTrend` 查询	✅ 已实现
3	`GetStudentMastery(studentId)` :50055	`myMasterySummary` 查询	✅ 已实现
4	`GetStudentDashboard(studentId)` :50055	`studentDashboard` 查询	✅ 已实现
5	`GetMasteryDistribution(classId)` :50055	班级掌握度分布	✅ 已实现
6	HTTP `GET /analytics/student/{id}/errorbook` :3006	`myErrorBook` 查询	✅ 已实现

需求来源：student-bff nextstep.md §3.4 说明：student-bff nextstep.md 中列出的 GetStudentGrowth/GetAssignmentAnalysis/ListDiagnosticReports/ListErrorBookItems/ListPracticeSessionsByStudent/StartPracticeSession/SubmitPracticeAnswer 等 RPC 在 analytics.proto 中未定义，data-ana 通过现有 12 RPC + HTTP 端点覆盖这些需求。

3.3 parent-bff（ai05 负责）— P1

#	gRPC RPC	用途	状态
1	`GetStudentWeakness(studentId)` :50055	`childWeakness` 查询	✅ 已实现
2	`GetLearningTrend(studentId)` :50055	`childTrend` 查询	✅ 已实现
3	`GetClassPerformance(classId)` :50055	`classRank`/`classAverage` 计算	✅ 已实现

需求来源：parent-bff nextstep.md §4.3 说明：parent-bff nextstep.md 中列出的 childGrowthArchive/childLearningPath/childErrorBookStats/childTopWrongQuestions/childWeakKps/childMasterySummary/childDiagnosticReports/childPracticeStats/childPracticeSessions 等查询在当前 RPC 中未直接覆盖，parent-bff 通过降级模式返回空数据。data-ana 可通过 HTTP 端点 /analytics/student/{id}/errorbook 等补充覆盖。

3.4 api-gateway（ai01 负责）— P0

#	路由	用途	状态
1	`/api/v1/analytics/*` → data-ana:3006	data-ana HTTP 端点代理	✅ api-gateway 已配置
2	`/api/v1/dashboard/*` → data-ana:3006	仪表盘代理	✅ api-gateway 已配置

需求来源：api-gateway nextstep.md §5.2

4. Docker 本地测试

4.1 镜像构建

# 在仓库根目录执行（Docker Hub 不可达时先 docker pull + docker tag python:3.12-slim）
docker build -t edu/data-ana:test -f services/data-ana/Dockerfile services/data-ana/

4.2 容器启动（接入 edu-full_default 网络）

docker run -d \
  --name edu-data-ana-test \
  --network edu-full_default \
  -p 3006:3006 -p 50055:50055 \
  -e DATA_ANA_CLICKHOUSE_HOST=clickhouse \
  -e DATA_ANA_CLICKHOUSE_PORT=8123 \
  -e DATA_ANA_CLICKHOUSE_DATABASE=edu_analytics \
  -e DATA_ANA_KAFKA_BROKERS=kafka:29092 \
  -e DATA_ANA_REDIS_URL=redis://redis:6379 \
  -e DATA_ANA_DEV_MODE=true \
  -e OTEL_TRACES_EXPORTER=none \
  -e OTEL_METRICS_EXPORTER=none \
  -e OTEL_LOGS_EXPORTER=none \
  edu/data-ana:test

4.3 健康检查验证

# liveness
curl http://localhost:3006/healthz

# readiness（下游不可达时返回 degraded）
curl http://localhost:3006/readyz

4.4 ClickHouse DDL + 种子数据

# 建表
docker exec edu-clickhouse clickhouse-client --password clickhouse --multiquery < services/data-ana/scripts/clickhouse_ddl.sql

# 种子数据（需安装 clickhouse-connect）
cd services/data-ana && python scripts/seed_clickhouse.py

4.5 测试结果（2026-07-13 已通过）

#	测试项	结果	说明
1	Docker 镜像构建	✅	`edu/data-ana:test` 构建成功
2	容器启动 + 健康检查	✅	`/healthz` 200 OK, `/readyz` ready=true
3	ClickHouse 5 表 DDL	✅	4 ReplacingMergeTree + 1 MergeTree
4	种子数据写入	✅	student_dashboard_view(8) + student_errors(3) + mastery_snapshot(6)
5	HTTP `/analytics/student/stu-001/weakness`	✅	返回 2 个薄弱知识点（kp-math-002 mastery=0.35/0.45）
6	HTTP `/analytics/student/dashboard`	✅	返回 8 条学情记录 + 薄弱点 + 趋势 + 掌握度
7	HTTP `/analytics/student/stu-001/trend`	✅	返回 8 个趋势点
8	HTTP `/analytics/student/stu-001/errorbook`	✅	返回 3 条错题记录
9	HTTP `/analytics/student/stu-001/mastery`	✅	返回 4 个知识点掌握度，overallMastery=0.6875
10	gRPC `GetStudentWeakness` :50055	✅	返回 2 个 weak_points
11	gRPC `GetStudentMastery` :50055	✅	返回 4 个 knowledge_points，overall_mastery=0.6875
12	gRPC `GetLearningTrend` :50055	✅	返回 8 个 trend points
13	ruff lint	✅	零错误

降级说明：iam gRPC 未配置（not_configured），HTTP 响应标记 degraded: true + degraded_reason: iam_grpc_unavailable_fallback，但 ClickHouse 真实数据正常返回。班级级查询（class/performance、class/mastery-distribution）因 DataScope 校验降级返回空数据，iam 就绪后自动恢复。

5. 环境变量清单（Docker 部署）

变量	必填	示例值	说明
`DATA_ANA_HTTP_PORT`	是	`3006`	HTTP 监听端口
`DATA_ANA_GRPC_PORT`	是	`50055`	gRPC 监听端口
`DATA_ANA_DEV_MODE`	否	`true`/`false`	开发模式（跳过部分校验）
`DATA_ANA_CLICKHOUSE_HOST`	是	`clickhouse`	ClickHouse 主机
`DATA_ANA_CLICKHOUSE_PORT`	否	`8123`	ClickHouse HTTP 端口
`DATA_ANA_CLICKHOUSE_DATABASE`	否	`edu_analytics`	ClickHouse 数据库
`DATA_ANA_KAFKA_BROKERS`	是	`kafka:29092`	Kafka broker 地址
`DATA_ANA_REDIS_URL`	是	`redis://redis:6379`	Redis 连接地址
`DATA_ANA_IAM_GRPC_TARGET`	是	`iam:50052`	iam gRPC 目标
`OTEL_TRACES_EXPORTER`	否	`none`	禁用 OTel traces（collector 不可达时）

6. 剩余工作

6.1 Docker 本地测试（已完成 2026-07-13）

#	工作项	状态
1	Docker 镜像构建	✅ 已通过
2	ClickHouse 容器启动 + DDL 建表	✅ 已通过
3	种子数据写入	✅ 已通过
4	data-ana 容器启动 + 健康检查	✅ 已通过
5	HTTP 端点测试（无 mock 数据）	✅ 已通过
6	gRPC 端点测试	✅ 已通过

6.2 P6 硬化任务

#	工作项	状态
1	CDC 多实例水平扩展	⏳ 未开始
2	ExamCache Redis 化	⏳ 未开始
3	容量规划 + TTL 归档策略	⏳ 未开始
4	监控告警完善（Prometheus + Grafana）	⏳ 未开始
5	readyz 深度硬化（超时控制）	⏳ 未开始

6.3 端到端联调

#	工作项	阻塞条件	状态
1	teacher-bff gRPC 联调	teacher-bff 配置 DATA_ANA_GRPC_TARGET	⏳
2	student-bff gRPC 联调	student-bff 配置 DATA_ANA_GRPC_TARGET	⏳
3	parent-bff gRPC 联调	parent-bff 配置 DATA_ANA_GRPC_TARGET	⏳
4	CDC 通道联调	core-edu MySQL + Debezium 就绪	⏳
5	AIUsageEvent 消费联调	ai 服务发布事件	⏳

7. 关键文件路径

文件	用途
`services/data-ana/src/data_ana/main.py`	HTTP 14 端点 + lifespan（gRPC + CDC 启动）
`services/data-ana/src/data_ana/grpc_server.py`	gRPC 12 RPC（含 server-streaming）
`services/data-ana/src/data_ana/cdc_consumer.py`	CDC 消费者（5 表 + AIUsageEvent）
`services/data-ana/src/data_ana/analytics_service.py`	4 端 Dashboard + DataScope 注入
`services/data-ana/src/data_ana/mastery_service.py`	掌握度算法（加权滑动平均 + 遗忘曲线）
`services/data-ana/src/data_ana/warning_service.py`	5 类预警 + Redis 去重
`services/data-ana/src/data_ana/config.py`	全配置项（DATA_ANA_ 前缀）
`services/data-ana/src/data_ana/repository/clickhouse_repository.py`	ClickHouse 查询（FINAL/argMax 去重）
`services/data-ana/src/data_ana/repository/iam_client.py`	iam gRPC + Redis 缓存 + 降级
`services/data-ana/src/data_ana/repository/kafka_producer.py`	Kafka 事件发布（idempotent）
`services/data-ana/src/generated_proto/`	Python protobuf 生成代码（analytics/iam/events）
`services/data-ana/scripts/clickhouse_ddl.sql`	5 宽表建表脚本
`services/data-ana/scripts/seed_clickhouse.py`	种子数据脚本
`services/data-ana/Dockerfile`	多阶段构建（python:3.12-slim）
`packages/shared-proto/proto/analytics.proto`	gRPC 12 RPC 契约

本文件由 ai11 维护。data-ana 已完成 P2-P5 全部代码实现 + Docker 本地测试通过（无 mock 数据，真实 ClickHouse 查询）。等待 iam 容器就绪后即可端到端联调。

18 KiB Raw Blame History Unescape Escape