feat(data-ana): 完整实现 data-ana 数据分析服务

包含 CDC consumer、analytics/mastery/warning service、grpc server、repository、ClickHouse DDL 等

packages/shared-proto/proto/analytics.proto

@@ -2,24 +2,113 @@ syntax = "proto3";
 
 package next_edu_cloud.analytics.v1;
 
+// AnalyticsService 数据分析服务契约（D6 智能洞察领域）.
+// P4 启用 gRPC server 端口 50055，HTTP 3006 保留作 Gateway 直连降级.
+// 所有 RPC 返回 ActionState 信封（success/data/error/details.degraded）.
 service AnalyticsService {
+  // 班级成绩分析（平均分/及格率/参考人数）.
   rpc GetClassPerformance(GetClassPerformanceRequest) returns (ClassPerformance);
+  // 学生薄弱知识点（mastery_level < 0.6）.
   rpc GetStudentWeakness(GetStudentWeaknessRequest) returns (StudentWeakness);
+  // 学习趋势（历史成绩曲线）.
   rpc GetLearningTrend(GetLearningTrendRequest) returns (LearningTrend);
+  // 教师仪表盘聚合（班级概览 + 待办 + 预警）.
+  rpc GetTeacherDashboard(GetTeacherDashboardRequest) returns (TeacherDashboard);
+  // 学生仪表盘（个人学情 + 排名 + 薄弱点）.
+  rpc GetStudentDashboard(GetStudentDashboardRequest) returns (StudentDashboard);
+  // 家长仪表盘（孩子学情概览）.
+  rpc GetParentDashboard(GetParentDashboardRequest) returns (ParentDashboard);
+  // 管理员仪表盘（全校统计 + AI 用量）.
+  rpc GetAdminDashboard(GetAdminDashboardRequest) returns (AdminDashboard);
+  // 预警列表查询（按班级/严重度/时间过滤）.
+  rpc GetWarnings(GetWarningsRequest) returns (WarningList);
+  // 手动触发预警（管理员/教师主动标记关注）.
+  rpc TriggerWarning(TriggerWarningRequest) returns (TriggerWarningResponse);
+  // 班级掌握度分布（mastered/progressing/weak 三档）.
+  rpc GetMasteryDistribution(GetMasteryDistributionRequest) returns (MasteryDistribution);
+  // 学生知识点掌握度明细.
+  rpc GetStudentMastery(GetStudentMasteryRequest) returns (StudentMastery);
+  // 订阅掌握度更新（server-streaming，P5+ AI 个性化推荐实时推送通道）.
+  rpc SubscribeMasteryUpdate(SubscribeMasteryUpdateRequest) returns (stream MasteryUpdateEvent);
 }
 
+// ===== 请求消息 =====
+
 message GetClassPerformanceRequest {
   string class_id = 1;
   string subject_id = 2;
-  int64 start_date = 3;
+  int64 start_date = 3; // Unix timestamp（秒）
   int64 end_date = 4;
 }
 
+message GetStudentWeaknessRequest {
+  string student_id = 1;
+  string subject_id = 2;
+}
+
+message GetLearningTrendRequest {
+  string student_id = 1;
+  int64 start_date = 2;
+  int64 end_date = 3;
+  string subject_id = 4;
+}
+
+message GetTeacherDashboardRequest {
+  string user_id = 1;
+  string class_id = 2; // 可选，不传则返回教师全部班级
+}
+
+message GetStudentDashboardRequest {
+  string user_id = 1;
+}
+
+message GetParentDashboardRequest {
+  string user_id = 1;
+  string student_id = 2; // 家长查看指定孩子
+}
+
+message GetAdminDashboardRequest {
+  string user_id = 1;
+  string scope = 2; // ALL / SCHOOL / DISTRICT
+  string scope_id = 3; // 具体范围 ID
+}
+
+message GetWarningsRequest {
+  string class_id = 1;
+  string severity = 2; // INFO / WARN / CRITICAL
+  int64 since = 3; // Unix timestamp（秒）
+}
+
+message TriggerWarningRequest {
+  string target_id = 1; // 学生 ID
+  string warning_type = 2; // LOW_MASTERY / SCORE_DROP / ABSENT_FREQUENT
+  string severity = 3; // INFO / WARN / CRITICAL
+}
+
+message GetMasteryDistributionRequest {
+  string class_id = 1;
+  string subject_id = 2;
+  string knowledge_point_id = 3; // 可选
+}
+
+message GetStudentMasteryRequest {
+  string student_id = 1;
+  string subject_id = 2; // 可选
+}
+
+message SubscribeMasteryUpdateRequest {
+  string student_id = 1; // 可选，订阅指定学生
+  string class_id = 2; // 可选，订阅指定班级全部学生
+}
+
+// ===== 响应消息 =====
+
 message ClassPerformance {
   string class_id = 1;
   double average_score = 2;
   double pass_rate = 3;
-  repeated StudentScore scores = 4;
+  int32 total_students = 4;
+  repeated StudentScore scores = 5;
 }
 
 message StudentScore {
@@ -28,11 +117,6 @@ message StudentScore {
   string grade = 3;
 }
 
-message GetStudentWeaknessRequest {
-  string student_id = 1;
-  string subject_id = 2;
-}
-
 message StudentWeakness {
   string student_id = 1;
   repeated WeakPoint weak_points = 2;
@@ -42,12 +126,7 @@ message WeakPoint {
   string knowledge_point_id = 1;
   string title = 2;
   double mastery = 3;
-}
-
-message GetLearningTrendRequest {
-  string student_id = 1;
-  int64 start_date = 2;
-  int64 end_date = 3;
+  int32 error_count = 4;
 }
 
 message LearningTrend {
@@ -59,3 +138,125 @@ message TrendPoint {
   int64 date = 1;
   double score = 2;
 }
+
+message TeacherDashboard {
+  string user_id = 1;
+  int32 total_classes = 2;
+  int32 total_students = 3;
+  double class_avg_score = 4;
+  int32 pending_homework_count = 5;
+  repeated ClassSummary classes = 6;
+  repeated StudentSummary top_students = 7;
+  repeated WarningInfo recent_warnings = 8;
+}
+
+message ClassSummary {
+  string class_id = 1;
+  string class_name = 2;
+  int32 student_count = 3;
+  double average_score = 4;
+}
+
+message StudentSummary {
+  string student_id = 1;
+  string student_name = 2;
+  double score = 3;
+  int32 rank_in_class = 4;
+}
+
+message StudentDashboard {
+  string user_id = 1;
+  double avg_score = 2;
+  int32 class_rank = 3;
+  int32 total_students = 4;
+  repeated WeakPoint weak_points = 5;
+  repeated TrendPoint recent_trends = 6;
+  int32 pending_homework = 7;
+}
+
+message ParentDashboard {
+  string user_id = 1;
+  string student_id = 2;
+  double child_avg_score = 3;
+  int32 child_class_rank = 4;
+  int32 total_class_students = 5;
+  repeated WeakPoint child_weak_points = 6;
+  repeated WarningInfo child_warnings = 7;
+}
+
+message AdminDashboard {
+  string user_id = 1;
+  int32 total_teachers = 2;
+  int32 total_students = 3;
+  int32 total_classes = 4;
+  double school_avg_score = 5;
+  repeated WarningInfo recent_warnings = 6;
+  AIUsageSummary ai_usage = 7;
+}
+
+message AIUsageSummary {
+  int64 total_requests = 1;
+  int64 total_tokens = 2;
+  int64 total_cost_cents = 3;
+  repeated AIUsageByProvider by_provider = 4;
+}
+
+message AIUsageByProvider {
+  string provider = 1;
+  int64 request_count = 2;
+  int64 total_tokens = 3;
+  int64 cost_cents = 4;
+}
+
+message WarningList {
+  repeated WarningInfo warnings = 1;
+  int32 total = 2;
+}
+
+message WarningInfo {
+  string warning_id = 1;
+  string warning_type = 2; // LOW_MASTERY / CRITICAL_LOW / SCORE_DROP / ABSENT_FREQUENT / TREND_DECLINE
+  string target_id = 3; // 学生 ID
+  string target_name = 4;
+  double threshold = 5;
+  double current_value = 6;
+  string severity = 7; // INFO / WARN / CRITICAL
+  int64 occurred_at = 8; // Unix timestamp（秒）
+}
+
+message TriggerWarningResponse {
+  string warning_id = 1;
+  bool triggered = 2;
+}
+
+message MasteryDistribution {
+  string class_id = 1;
+  int32 mastered_count = 2; // mastery >= 0.8
+  int32 progressing_count = 3; // 0.4 <= mastery < 0.8
+  int32 weak_count = 4; // mastery < 0.4
+  int32 total_students = 5;
+}
+
+message StudentMastery {
+  string student_id = 1;
+  repeated KnowledgePointMastery knowledge_points = 2;
+  double overall_mastery = 3;
+}
+
+message KnowledgePointMastery {
+  string knowledge_point_id = 1;
+  string title = 2;
+  string subject_id = 3;
+  double mastery_level = 4; // 0.0-1.0
+  string mastery_label = 5; // mastered / progressing / weak
+  int64 calculated_at = 6; // Unix timestamp（秒）
+}
+
+message MasteryUpdateEvent {
+  string event_id = 1;
+  string student_id = 2;
+  string knowledge_point_id = 3;
+  double mastery_level = 4;
+  double previous_level = 5;
+  int64 calculated_at = 6; // Unix timestamp（秒）
+}