Edu/apps/teacher-portal/src/lib/graphql-p4.ts

/**
 * GraphQL P4 扩展 Query - 知识图谱 + 学情分析
 *
 * 维护者：ai13（teacher-portal）
 * 关联：graphql.ts P2/P3 扩展、workline.md §3 P4 交付物
 *
 * schema 尚未在 ARB-001 P2 第一版中定义，开发期通过 MSW 拦截返回 mock 响应；
 * 上游就绪后由 ai03 在 teacher-bff.graphql 扩展，届时合并本文件到 graphql.ts。
 *
 * 查询范围（P4）：
 * - KnowledgeGraph：班级/科目知识点图谱（节点 + 前置依赖边）
 * - ClassAnalytics：班级学情分析（均分/及格率/趋势/Top 学生/弱项）
 * - StudentAnalytics：单生学情分析（趋势/弱项/强项/掌握度）
 */

import { gql } from "urql";

// ============ Types（对齐 P4 schema 设计） ============

/** 知识图谱节点（知识点） */
export interface KnowledgeNode {
  id: string;
  name: string;
  subject: string;
  description: string | null;
  masteryLevel: number; // 0-100
}

/** 知识图谱边（前置依赖关系） */
export interface KnowledgeEdge {
  from: string;
  to: string;
  type: "PREREQUISITE" | "RELATED";
}

/** 知识图谱完整结构 */
export interface KnowledgeGraphData {
  nodes: KnowledgeNode[];
  edges: KnowledgeEdge[];
}

/** 单生学情分析 */
export interface StudentAnalytics {
  studentId: string;
  studentName: string;
  avgScore: number;
  trend: number[]; // 最近 5 次成绩趋势
  weakPoints: string[]; // 弱项知识点名称
  strongPoints: string[];
  masteryRate: number; // 掌握度 0-100
}

/** 班级学情分析 */
export interface ClassAnalytics {
  classId: string;
  className: string;
  avgScore: number;
  passRate: number;
  avgTrend: number[];
  topStudents: StudentAnalytics[];
  weakPoints: string[];
}

// ============ P4 Query ============

/** 知识图谱查询（按班级 + 科目过滤） */
export const KnowledgeGraphQuery = gql`
  query KnowledgeGraph($classId: ID, $subject: String) {
    knowledgeGraph(classId: $classId, subject: $subject) {
      nodes {
        id
        name
        subject
        description
        masteryLevel
      }
      edges {
        from
        to
        type
      }
    }
  }
`;

/** 班级学情分析查询 */
export const ClassAnalyticsQuery = gql`
  query ClassAnalytics($classId: ID!) {
    classAnalytics(classId: $classId) {
      classId
      className
      avgScore
      passRate
      avgTrend
      topStudents {
        studentId
        studentName
        avgScore
        trend
        weakPoints
        strongPoints
        masteryRate
      }
      weakPoints
    }
  }
`;

/** 单生学情分析查询 */
export const StudentAnalyticsQuery = gql`
  query StudentAnalytics($studentId: ID!) {
    studentAnalytics(studentId: $studentId) {
      studentId
      studentName
      avgScore
      trend
      weakPoints
      strongPoints
      masteryRate
    }
  }
`;