/**
 * v2-P1-4: 诊断模块数据服务接口。
 *
 * 通过 TypeScript 接口抽象所有客户端可调用的诊断操作，
 * 使组件依赖接口而非具体 Server Action 实现，便于测试与替换。
 *
 * 默认实现绑定现有 Server Actions；测试时可注入 mock 实现。
 */

import type { ActionState } from "@/shared/types/action-state"

/** 按知识点筛选学生返回项 */
export interface KnowledgePointStudent {
  studentId: string
  studentName: string
  masteryLevel: number
  totalQuestions: number
  correctQuestions: number
  lastAssessedAt: string | null
  needsAttention: boolean
}

/** 导出结果 */
export interface ExportResult {
  buffer: string
  filename: string
}

/**
 * 诊断模块客户端服务接口。
 * 所有客户端组件通过 useDiagnosticService() 获取实现，不直接 import actions。
 */
export interface DiagnosticService {
  /** 生成学生个人诊断报告 */
  generateStudentReport(studentId: string, period: string): Promise<ActionState<string>>

  /** 生成班级诊断报告 */
  generateClassReport(classId: string, period: string): Promise<ActionState<string>>

  /** 生成年级诊断报告 */
  generateGradeReport(gradeId: string, period: string): Promise<ActionState<string>>

  /** 发布诊断报告 */
  publishReport(id: string): Promise<ActionState<null>>

  /** 删除诊断报告 */
  deleteReport(id: string): Promise<ActionState<null>>

  /** 导出诊断报告为 Excel（返回 base64 buffer + 文件名） */
  exportReport(reportId: string): Promise<ActionState<ExportResult>>

  /** 按知识点筛选班级学生掌握度 */
  getClassStudentsByKp(
    classId: string,
    knowledgePointId: string,
    threshold?: number,
  ): Promise<ActionState<KnowledgePointStudent[]>>
}
