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

services/data-ana/src/data_ana/grpc_server.py

@@ -508,6 +508,7 @@ async def start_grpc_server() -> Any | None:
 
     try:
         import grpc  # type: ignore[import-not-found]
+
         from generated_proto import analytics_pb2_grpc  # type: ignore[import-not-found]
     except ImportError as exc:
         logger.warning("grpc_dependencies_not_installed_degraded", error=str(exc))

services/data-ana/src/data_ana/repository/clickhouse_repository.py

@@ -291,13 +291,14 @@ async def query_mastery_snapshot(student_id: str, subject_id: str = "") -> dict
     where_clause = " AND ".join(where_parts)
     try:
         # argMax 获取每个 knowledge_point_id 的最新 mastery_level
+        # 注意：别名不能与 argMax 的第二个参数名相同，否则 ClickHouse 将别名解析为聚合函数
         result = await asyncio.to_thread(
             client.query,
             f"SELECT "
             f"  knowledge_point_id, "
             f"  argMax(mastery_level, calculated_at) AS mastery_level, "
             f"  argMax(subject_id, calculated_at) AS subject_id, "
-            f"  max(calculated_at) AS calculated_at "
+            f"  max(calculated_at) AS latest_calculated_at "
             f"FROM mastery_snapshot "
             f"WHERE {where_clause} "
             f"GROUP BY knowledge_point_id "

services/data-ana/src/data_ana/repository/iam_client.py

@@ -45,6 +45,7 @@ async def _init_grpc() -> tuple[Any, Any] | None:
     _grpc_initialized = True
     try:
         import grpc  # type: ignore[import-not-found]
+
         from generated_proto import iam_pb2_grpc  # type: ignore[import-not-found]
 
         _grpc_channel = grpc.aio.insecure_channel(