Edu/packages/shared-proto/proto/analytics.proto

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; // 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;
  int32 total_students = 4;
  repeated StudentScore scores = 5;
}

message StudentScore {
  string student_id = 1;
  double score = 2;
  string grade = 3;
}

message StudentWeakness {
  string student_id = 1;
  repeated WeakPoint weak_points = 2;
}

message WeakPoint {
  string knowledge_point_id = 1;
  string title = 2;
  double mastery = 3;
  int32 error_count = 4;
}

message LearningTrend {
  string student_id = 1;
  repeated TrendPoint points = 2;
}

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（秒）
}