/**
 * ExamServicePort — exams 模块对内的服务端口接口（P2-4 骨架）
 *
 * 目的：
 * - 通过 TypeScript 接口抽象 exams 模块内部组件对数据/动作的依赖
 * - 使用 React Context 注入具体实现，便于单元测试时替换为 mock
 * - 为未来不同角色（teacher/admin/parent/student）通过不同 Provider 实现隔离
 *
 * 与 `@/shared/services/exam-homework-port.ts` 的区别：
 * - shared 层的 ExamHomeworkServicePort 是面向 **跨模块调用方**（app 层 / 其他 modules）
 *   的契约，在 instrumentation.ts 启动时以单例方式注册
 * - 本文件定义的 ExamServicePort 是面向 **模块内部组件** 的契约，
 *   通过 React Context 注入，可在不同角色页面提供差异化实现
 *
 * 当前阶段（P2-4）：
 * - 仅落地接口与 Context 骨架
 * - 不强制改造现有组件（exam-rich-form.tsx 等仍直接调用 Server Actions）
 * - P2-6+ 重构时再将组件改为通过 useExamService() 获取服务
 *
 * 使用示例（未来落地后）：
 * ```tsx
 * // app/(dashboard)/teacher/exams/layout.tsx
 * import { ExamServiceProvider, TeacherExamService } from "@/modules/exams/services"
 * export default function Layout({ children }) {
 *   return <ExamServiceProvider service={new TeacherExamService()}>{children}</ExamServiceProvider>
 * }
 *
 * // components/exam-rich-form.tsx（未来重构后）
 * const service = useExamService()
 * const result = await service.createExamFromRichEditor(formData)
 * ```
 */

import type { ActionState } from "@/shared/types/action-state"
import type { DataScope } from "@/shared/types/permissions"
import type { Exam } from "../types"
import type { ExamAnalyticsSummary } from "../stats-service"
import type { GetExamsParams } from "../data-access"

/**
 * 试卷详情：扩展 Exam，包含组卷结构与题目列表
 */
export interface ExamDetail extends Exam {
  structure: unknown
  questions: Array<{
    id: string
    score: number
    order: number
  }>
}

/**
 * 创建试卷输入
 */
export interface ExamCreateInput {
  title: string
  subjectId: string
  gradeId: string
  difficulty: number
  totalScore: number
  durationMin: number
  scheduledAt?: string | null
  examModeConfig?: {
    examMode: "homework" | "timed" | "proctored"
    durationMinutes: number | null
    shuffleQuestions: boolean
    allowLateStart: boolean
    lateStartGraceMinutes: number
    antiCheatEnabled: boolean
  }
}

/**
 * 更新试卷输入
 */
export interface ExamUpdateInput extends Partial<ExamCreateInput> {
  examId: string
}

/**
 * exams 模块服务端口契约。
 *
 * 所有方法返回 Promise，签名尽量与现有 Server Actions 保持一致，
 * 但将 prevState / FormData 等表单协议参数剥离，便于客户端组合调用。
 *
 * 注意：
 * - 此接口仅描述"做什么"，不规定"如何鉴权"——鉴权应在具体实现中完成
 * - 每个方法都应返回 ActionState，便于调用方统一处理成功/失败
 */
export interface ExamServicePort {
  /** 列出考试（带数据范围与筛选） */
  listExams(params: GetExamsParams & { scope: DataScope }): Promise<Exam[]>
  /** 获取考试详情（含结构/题目） */
  getExam(id: string, scope?: DataScope): Promise<ExamDetail | null>
  /** 创建考试草稿 */
  createExam(input: ExamCreateInput, formData: FormData): Promise<ActionState<string>>
  /** AI 生成考试 */
  createAiExam(input: ExamCreateInput & { prompt: string }, formData: FormData): Promise<ActionState<string>>
  /** 从富文本编辑器创建考试 */
  createExamFromRichEditor(formData: FormData): Promise<ActionState<string>>
  /** 更新考试 */
  updateExam(input: ExamUpdateInput, formData: FormData): Promise<ActionState<string>>
  /** 从富文本编辑器更新考试 */
  updateExamFromRichEditor(formData: FormData): Promise<ActionState<string>>
  /** 删除考试 */
  deleteExam(id: string): Promise<ActionState<string>>
  /** 复制考试 */
  duplicateExam(id: string): Promise<ActionState<string>>
  /** AI 自动标记 */
  autoMarkExam(formData: FormData): Promise<ActionState<{ title: string; doc: unknown }>>
  /** 获取考试预览 */
  getExamPreview(examId: string): Promise<ActionState<{ structure: unknown; questions: Array<{ id: string }> }>>
  /** 获取考试分析数据 */
  getAnalytics(examId: string): Promise<ExamAnalyticsSummary | null>
  /** 获取可用科目列表 */
  getSubjects(): Promise<ActionState<Array<{ id: string; name: string }>>>
  /** 获取可用年级列表 */
  getGrades(): Promise<ActionState<Array<{ id: string; name: string }>>>
}

/**
 * 默认实现标记：未注入 Provider 时调用会抛错。
 * 仅用于类型推断与测试场景的兜底，生产环境必须通过 ExamServiceProvider 注入。
 */
export const EXAM_SERVICE_NOT_REGISTERED = Symbol("EXAM_SERVICE_NOT_REGISTERED")
