/**
 * v2-P2-7: 诊断模块监控埋点接口。
 *
 * 这是一个预留的扩展点，用于追踪诊断模块的关键操作。
 * 默认实现为 no-op（不发送任何事件），生产环境可通过
 * DiagnosticMonitorProvider 注入真实实现（如发送到 Sentry、PostHog、
 * Mixpanel、自建埋点系统等）。
 *
 * 设计原则：
 * - 接口与实现解耦：组件依赖接口，不依赖具体埋点 SDK。
 * - 不阻塞主流程：埋点失败不应影响业务操作。
 * - 客户端与服务端均可使用：事件类型设计为通用，避免环境耦合。
 *
 * 用法：
 * ```tsx
 * <DiagnosticMonitorProvider monitor={postHogDiagnosticMonitor}>
 *   <DiagnosticServiceProvider service={defaultDiagnosticService}>
 *     <ReportList />
 *   </DiagnosticServiceProvider>
 * </DiagnosticMonitorProvider>
 * ```
 */

/** 诊断模块可追踪的事件名称 */
export type DiagnosticEventName =
  | "report_generated"
  | "report_published"
  | "report_deleted"
  | "report_exported"
  | "class_kp_filtered"

/** 诊断报告类型（用于事件属性） */
export type DiagnosticReportType = "individual" | "class" | "grade"

/** 事件属性（按事件名称区分的可选字段） */
export interface DiagnosticEventProperties {
  /** 报告类型（report_generated 事件必填） */
  reportType?: DiagnosticReportType
  /** 报告 ID（publish/delete/export 事件必填） */
  reportId?: string
  /** 学生 ID（individual 报告） */
  studentId?: string
  /** 班级 ID（class 报告或 class_kp_filtered 事件） */
  classId?: string
  /** 年级 ID（grade 报告） */
  gradeId?: string
  /** 知识点 ID（class_kp_filtered 事件） */
  knowledgePointId?: string
  /** 报告周期（report_generated 事件，格式 YYYY-MM） */
  period?: string
  /** 掌握度阈值（class_kp_filtered 事件） */
  threshold?: number
  /** 操作是否成功（便于计算转化率） */
  success?: boolean
  /** 错误信息（失败时记录，便于排查） */
  error?: string
  /** 操作耗时（毫秒，便于性能监控） */
  durationMs?: number
  /** 触发操作的用户 ID */
  userId?: string
}

/**
 * 诊断模块监控接口。
 *
 * 所有方法均为 async（即使 no-op 也返回 Promise），
 * 以便真实实现可异步发送事件而不阻塞调用方。
 */
export interface DiagnosticMonitor {
  /**
   * 追踪诊断模块事件。
   *
   * @param eventName 事件名称
   * @param properties 事件属性（可选）
   */
  track(
    eventName: DiagnosticEventName,
    properties?: DiagnosticEventProperties,
  ): Promise<void>
}

/**
 * 默认 no-op 实现：不发送任何事件，仅静默返回。
 *
 * 在未注入真实监控实现时使用，确保业务流程不受影响。
 */
export const noopDiagnosticMonitor: DiagnosticMonitor = {
  async track(): Promise<void> {
    // no-op: 默认不发送任何事件
  },
}
