/**
 * Phase 3.4: `/api/search/ask` 응답 타입.
 *
 * Backend Pydantic 모델 (`app/api/search.py::AskResponse`) 과 1:1 매칭.
 * 필드 변경 시 양쪽 동시 수정 필수.
 */

export type SynthesisStatus =
  | 'completed'
  | 'timeout'
  | 'skipped'
  | 'no_evidence'
  | 'parse_failed'
  | 'llm_error'
  | 'backend_unavailable';

export type Confidence = 'high' | 'medium' | 'low';

export interface Citation {
  n: number;
  chunk_id: number | null;
  doc_id: number;
  title: string | null;
  section_title: string | null;
  /** LLM이 추출한 50~300자 핵심 span. UI에서 이것만 노출. */
  span_text: string;
  /**
   * 원본 800자 window.
   *
   * ⚠ UI 기본 경로에서 절대 렌더 금지. debug 모드에서 hover tooltip 용도로만
   * 조건부 노출 가능. full_snippet을 보여주면 backend span-precision UX
   * 가치가 사라진다 (plan §Evidence 표시 규칙).
   */
  full_snippet: string;
  relevance: number;
  rerank_score: number;
}

export interface SearchResult {
  id: number;
  title: string | null;
  ai_domain: string | null;
  ai_summary: string | null;
  file_format: string;
  score: number;
  snippet: string | null;
  match_reason: string | null;
  chunk_id: number | null;
  chunk_index: number | null;
  section_title: string | null;
  rerank_score: number | null;
}

export type Completeness = 'full' | 'partial' | 'insufficient';

export interface ConfirmedItem {
  aspect: string;
  text: string;
  citations: number[];
}

export interface AskResponse {
  results: SearchResult[];
  ai_answer: string | null;
  citations: Citation[];
  synthesis_status: SynthesisStatus;
  synthesis_ms: number;
  confidence: Confidence | null;
  refused: boolean;
  no_results_reason: string | null;
  query: string;
  total: number;
  /** Phase 3.5a */
  completeness: Completeness;
  covered_aspects: string[] | null;
  missing_aspects: string[] | null;
  confirmed_items: ConfirmedItem[] | null;
  /**
   * PR-MacBook-RAG-Backend-1: backend dispatcher metadata.
   * backend 미지정 호출은 둘 다 null (기존 호출자 호환). 명시 opt-in 시만 채워짐.
   */
  backend_requested?: string | null;
  backend_used?: string | null;
}
