feat(data-ana): 完善学情诊断服务并添加ClickHouse降级模式
config.py ClickHouse连接改可选+加DEV_MODE/kafka_brokers clickhouse_client.py 降级模式: host为空时返回None main.py 端点先查ClickHouse降级返回骨架数据+新增errorbook 新增clickhouse-init.sql创建宽表和错题表 Gateway添加/analytics路由
This commit is contained in:
SpecialX
@@ -1,27 +1,218 @@
|
||||
"""ClickHouse 客户端."""
|
||||
"""ClickHouse 客户端（支持降级模式）.
|
||||
|
||||
import clickhouse_connect
|
||||
当 settings.clickhouse_host 为空字符串时，get_client() 返回 None，
|
||||
查询方法在 client 为 None 或查询失败时返回 None（降级模式），
|
||||
保证服务在 ClickHouse 不可用时仍可启动并响应骨架数据。
|
||||
"""
|
||||
|
||||
from typing import Any
|
||||
|
||||
import structlog
|
||||
|
||||
from .config import settings
|
||||
|
||||
_client = None
|
||||
logger = structlog.get_logger(__name__)
|
||||
|
||||
_client: Any | None = None
|
||||
# 标记是否已尝试初始化（避免对失败连接反复重试）
|
||||
_client_initialized: bool = False
|
||||
|
||||
|
||||
def get_client():
|
||||
"""获取 ClickHouse 客户端."""
|
||||
global _client
|
||||
if _client is None:
|
||||
_client = clickhouse_connect.get_client(
|
||||
def get_client() -> Any | None:
|
||||
"""获取 ClickHouse 客户端.
|
||||
|
||||
- 当 clickhouse_host 为空：返回 None（降级模式）
|
||||
- 当已初始化但失败：返回 None
|
||||
- 当 clickhouse_connect 未安装：返回 None
|
||||
"""
|
||||
global _client, _client_initialized
|
||||
|
||||
if not settings.clickhouse_host:
|
||||
# 未配置 ClickHouse，降级模式
|
||||
return None
|
||||
|
||||
if _client_initialized:
|
||||
return _client
|
||||
|
||||
_client_initialized = True
|
||||
try:
|
||||
import clickhouse_connect
|
||||
|
||||
kwargs: dict[str, Any] = {
|
||||
"host": settings.clickhouse_host,
|
||||
"port": settings.clickhouse_port,
|
||||
"database": settings.clickhouse_database,
|
||||
}
|
||||
if settings.clickhouse_user:
|
||||
kwargs["username"] = settings.clickhouse_user
|
||||
if settings.clickhouse_password:
|
||||
kwargs["password"] = settings.clickhouse_password
|
||||
_client = clickhouse_connect.get_client(**kwargs)
|
||||
logger.info(
|
||||
"clickhouse_client_initialized",
|
||||
host=settings.clickhouse_host,
|
||||
port=settings.clickhouse_port,
|
||||
database=settings.clickhouse_database,
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001
|
||||
# 任何初始化异常都进入降级模式，不抛出
|
||||
logger.warning("clickhouse_client_init_failed_degraded", error=str(exc))
|
||||
_client = None
|
||||
|
||||
return _client
|
||||
|
||||
|
||||
async def close_client() -> None:
|
||||
"""关闭客户端."""
|
||||
global _client
|
||||
if _client:
|
||||
_client.close()
|
||||
_client = None
|
||||
global _client, _client_initialized
|
||||
if _client is not None:
|
||||
try:
|
||||
_client.close()
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("clickhouse_client_close_failed", error=str(exc))
|
||||
finally:
|
||||
_client = None
|
||||
_client_initialized = False
|
||||
|
||||
|
||||
async def query_dashboard(student_id: str) -> dict | None:
|
||||
"""查询学生学情看板（宽表 student_dashboard_view）.
|
||||
|
||||
返回 None 表示降级模式（ClickHouse 不可用或查询失败）。
|
||||
"""
|
||||
client = get_client()
|
||||
if client is None:
|
||||
return None
|
||||
|
||||
try:
|
||||
rows = client.query(
|
||||
"SELECT student_id, class_id, exam_id, subject_id, score, "
|
||||
"rank_in_class, knowledge_point_id, mastery_level, error_count, "
|
||||
"last_updated "
|
||||
"FROM student_dashboard_view "
|
||||
"WHERE student_id = {sid:String} "
|
||||
"ORDER BY last_updated DESC "
|
||||
"LIMIT 50",
|
||||
parameters={"sid": student_id},
|
||||
).result_rows
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("query_dashboard_failed_degraded", error=str(exc), student_id=student_id)
|
||||
return None
|
||||
|
||||
columns = [
|
||||
"student_id",
|
||||
"class_id",
|
||||
"exam_id",
|
||||
"subject_id",
|
||||
"score",
|
||||
"rank_in_class",
|
||||
"knowledge_point_id",
|
||||
"mastery_level",
|
||||
"error_count",
|
||||
"last_updated",
|
||||
]
|
||||
records = [dict(zip(columns, row, strict=True)) for row in rows]
|
||||
return {
|
||||
"studentId": student_id,
|
||||
"records": records,
|
||||
"total": len(records),
|
||||
}
|
||||
|
||||
|
||||
async def query_class_performance(class_id: str) -> dict | None:
|
||||
"""查询班级成绩分析（聚合 student_dashboard_view）.
|
||||
|
||||
返回 None 表示降级模式。
|
||||
"""
|
||||
client = get_client()
|
||||
if client is None:
|
||||
return None
|
||||
|
||||
try:
|
||||
# 平均分、参考人数、及格率（>=60）
|
||||
agg_rows = client.query(
|
||||
"SELECT "
|
||||
" count() AS total_students, "
|
||||
" avg(score) AS average_score, "
|
||||
" countIf(score >= 60) / count() AS pass_rate "
|
||||
"FROM student_dashboard_view "
|
||||
"WHERE class_id = {cid:String}",
|
||||
parameters={"cid": class_id},
|
||||
).result_rows
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning(
|
||||
"query_class_performance_failed_degraded",
|
||||
error=str(exc),
|
||||
class_id=class_id,
|
||||
)
|
||||
return None
|
||||
|
||||
if not agg_rows:
|
||||
return {
|
||||
"classId": class_id,
|
||||
"averageScore": 0.0,
|
||||
"passRate": 0.0,
|
||||
"totalStudents": 0,
|
||||
}
|
||||
|
||||
total_students, average_score, pass_rate = agg_rows[0]
|
||||
return {
|
||||
"classId": class_id,
|
||||
"averageScore": float(average_score) if average_score is not None else 0.0,
|
||||
"passRate": float(pass_rate) if pass_rate is not None else 0.0,
|
||||
"totalStudents": int(total_students) if total_students is not None else 0,
|
||||
}
|
||||
|
||||
|
||||
async def query_student_errors(student_id: str) -> list[dict] | None:
|
||||
"""查询学生错题本（表 student_errors）.
|
||||
|
||||
返回 None 表示降级模式；返回空列表表示无错题数据。
|
||||
"""
|
||||
client = get_client()
|
||||
if client is None:
|
||||
return None
|
||||
|
||||
try:
|
||||
rows = client.query(
|
||||
"SELECT student_id, question_id, knowledge_point_id, error_count, "
|
||||
"last_error_time, content "
|
||||
"FROM student_errors "
|
||||
"WHERE student_id = {sid:String} "
|
||||
"ORDER BY last_error_time DESC "
|
||||
"LIMIT 100",
|
||||
parameters={"sid": student_id},
|
||||
).result_rows
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning(
|
||||
"query_student_errors_failed_degraded",
|
||||
error=str(exc),
|
||||
student_id=student_id,
|
||||
)
|
||||
return None
|
||||
|
||||
columns = [
|
||||
"student_id",
|
||||
"question_id",
|
||||
"knowledge_point_id",
|
||||
"error_count",
|
||||
"last_error_time",
|
||||
"content",
|
||||
]
|
||||
return [dict(zip(columns, row, strict=True)) for row in rows]
|
||||
|
||||
|
||||
async def ping() -> bool:
|
||||
"""ClickHouse 连通性检查（供 /readyz 使用）.
|
||||
|
||||
返回 True 表示可用；False 表示未配置或不可用。
|
||||
"""
|
||||
client = get_client()
|
||||
if client is None:
|
||||
return False
|
||||
try:
|
||||
client.query("SELECT 1")
|
||||
return True
|
||||
except Exception as exc: # noqa: BLE001
|
||||
logger.warning("clickhouse_ping_failed", error=str(exc))
|
||||
return False
|
||||
|
||||
Reference in New Issue
Block a user