/**
 * TypeScript type definitions for SchoolCompare API
 * Generated from backend/models.py and backend/schemas.py
 */

// ============================================================================
// School Types
// ============================================================================

export interface School {
  id?: number;
  urn: number;
  school_name: string;
  local_authority: string | null;
  local_authority_code: number | null;
  school_type: string | null;
  school_type_code: string | null;
  religious_denomination: string | null;
  age_range: string | null;

  // Address
  address1: string | null;
  address2: string | null;
  town: string | null;
  postcode: string | null;
  address?: string; // Computed full address

  // Geocoding
  latitude: number | null;
  longitude: number | null;

  // School context
  total_pupils?: number | null;

  // Latest year metrics (for search/list views)
  rwm_expected_pct?: number | null;
  reading_expected_pct?: number | null;
  writing_expected_pct?: number | null;
  maths_expected_pct?: number | null;
  reading_progress?: number | null;
  writing_progress?: number | null;
  maths_progress?: number | null;

  // Trend indicators (for list views)
  prev_rwm_expected_pct?: number | null;
  trend?: 'up' | 'down' | 'stable';

  // Location search fields
  distance?: number | null;

  // GIAS enrichment fields
  website?: string | null;
  headteacher_name?: string | null;
  capacity?: number | null;
  trust_name?: string | null;
  gender?: string | null;

  // Ofsted (for list view — summary only)
  ofsted_grade?: 1 | 2 | 3 | 4 | null;
  ofsted_date?: string | null;
}

// ============================================================================
// Supplementary Data Types (populated by Kestra data integrator)
// ============================================================================

export interface OfstedInspection {
  framework: 'OEIF' | 'ReportCard' | null;
  inspection_date: string | null;
  inspection_type: string | null;
  // OEIF fields (old framework, pre-Nov 2025)
  overall_effectiveness: 1 | 2 | 3 | 4 | null;
  quality_of_education: number | null;
  behaviour_attitudes: number | null;
  personal_development: number | null;
  leadership_management: number | null;
  early_years_provision: number | null;
  previous_overall: number | null;
  // Report Card fields (new framework, from Nov 2025)
  // 1=Exceptional 2=Strong 3=Expected standard 4=Needs attention 5=Urgent improvement
  rc_safeguarding_met: boolean | null;
  rc_inclusion: number | null;
  rc_curriculum_teaching: number | null;
  rc_achievement: number | null;
  rc_attendance_behaviour: number | null;
  rc_personal_development: number | null;
  rc_leadership_governance: number | null;
  rc_early_years: number | null;
  rc_sixth_form: number | null;
}

export interface OfstedParentView {
  survey_date: string | null;
  total_responses: number | null;
  q_happy_pct: number | null;
  q_safe_pct: number | null;
  q_behaviour_pct: number | null;
  q_bullying_pct: number | null;
  q_communication_pct: number | null;
  q_progress_pct: number | null;
  q_teaching_pct: number | null;
  q_information_pct: number | null;
  q_curriculum_pct: number | null;
  q_future_pct: number | null;
  q_leadership_pct: number | null;
  q_wellbeing_pct: number | null;
  q_recommend_pct: number | null;
  q_sen_pct: number | null;
}

export interface SchoolCensus {
  year: number;
  class_size_avg: number | null;
  ethnicity_white_pct: number | null;
  ethnicity_asian_pct: number | null;
  ethnicity_black_pct: number | null;
  ethnicity_mixed_pct: number | null;
  ethnicity_other_pct: number | null;
}

export interface SchoolAdmissions {
  year: number;
  published_admission_number: number | null;
  total_applications: number | null;
  first_preference_offers_pct: number | null;
  oversubscribed: boolean | null;
}

export interface SenDetail {
  year: number;
  primary_need_speech_pct: number | null;
  primary_need_autism_pct: number | null;
  primary_need_mld_pct: number | null;
  primary_need_spld_pct: number | null;
  primary_need_semh_pct: number | null;
  primary_need_physical_pct: number | null;
  primary_need_other_pct: number | null;
}

export interface Phonics {
  year: number;
  year1_phonics_pct: number | null;
  year2_phonics_pct: number | null;
}

export interface SchoolDeprivation {
  lsoa_code: string | null;
  idaci_score: number | null;
  idaci_decile: number | null;
}

export interface SchoolFinance {
  year: number;
  per_pupil_spend: number | null;
  staff_cost_pct: number | null;
  teacher_cost_pct: number | null;
  support_staff_cost_pct: number | null;
  premises_cost_pct: number | null;
}

// ============================================================================
// School Result Types
// ============================================================================

export interface SchoolResult {
  id?: number;
  school_id: number;
  year: number;

  // Pupil numbers
  total_pupils: number | null;
  eligible_pupils: number | null;

  // Core KS2 metrics - Expected Standard
  rwm_expected_pct: number | null;
  reading_expected_pct: number | null;
  writing_expected_pct: number | null;
  maths_expected_pct: number | null;
  gps_expected_pct: number | null;
  science_expected_pct: number | null;

  // Higher Standard
  rwm_high_pct: number | null;
  reading_high_pct: number | null;
  writing_high_pct: number | null;
  maths_high_pct: number | null;
  gps_high_pct: number | null;

  // Progress Scores
  reading_progress: number | null;
  writing_progress: number | null;
  maths_progress: number | null;

  // Average Scores
  reading_avg_score: number | null;
  maths_avg_score: number | null;
  gps_avg_score: number | null;

  // School Context
  disadvantaged_pct: number | null;
  eal_pct: number | null;
  sen_support_pct: number | null;
  sen_ehcp_pct: number | null;
  stability_pct: number | null;

  // Pupil Absence from Tests
  reading_absence_pct: number | null;
  gps_absence_pct: number | null;
  maths_absence_pct: number | null;
  writing_absence_pct: number | null;
  science_absence_pct: number | null;

  // Gender Breakdown
  rwm_expected_boys_pct: number | null;
  rwm_expected_girls_pct: number | null;
  rwm_high_boys_pct: number | null;
  rwm_high_girls_pct: number | null;

  // Disadvantaged Performance
  rwm_expected_disadvantaged_pct: number | null;
  rwm_expected_non_disadvantaged_pct: number | null;
  disadvantaged_gap: number | null;

  // 3-Year Averages
  rwm_expected_3yr_pct: number | null;
  reading_avg_3yr: number | null;
  maths_avg_3yr: number | null;
}

// ============================================================================
// API Response Types
// ============================================================================

export interface AbsenceData {
  overall_absence_rate: number | null;
  persistent_absence_rate: number | null;
}

export interface PaginationInfo {
  page: number;
  page_size: number;
  total: number;
  total_pages: number;
}

export interface SchoolsResponse {
  schools: School[];
  page: number;
  page_size: number;
  total: number;
  total_pages: number;
  search_mode?: 'name' | 'location';
  location_info?: {
    postcode: string;
    radius: number;
    coordinates: [number, number];
  };
}

export interface SchoolDetailsResponse {
  school_info: School;
  yearly_data: SchoolResult[];
  absence_data: AbsenceData | null;
  // Supplementary data (null until Kestra populates)
  ofsted: OfstedInspection | null;
  parent_view: OfstedParentView | null;
  census: SchoolCensus | null;
  admissions: SchoolAdmissions | null;
  sen_detail: SenDetail | null;
  phonics: Phonics | null;
  deprivation: SchoolDeprivation | null;
  finance: SchoolFinance | null;
}

export interface ComparisonData {
  school_info: School;
  yearly_data: SchoolResult[];
}

export interface ComparisonResponse {
  comparison: Record<string, ComparisonData>;
}

export interface RankingItem {
  urn: number;
  school_name: string;
  local_authority: string;
  school_type?: string;
  value: number;
  rank?: number;
}

// Alias for backwards compatibility
export type RankingEntry = RankingItem;

export interface RankingsResponse {
  rankings: RankingItem[];
  metric: string;
  year?: number;
  local_authority?: string;
}

export interface Filters {
  local_authorities: string[];
  school_types: string[];
  years: number[];
}

// Backend returns filters directly, not wrapped
export type FiltersResponse = Filters;

export interface MetricDefinition {
  key: string;
  label: string;
  description: string;
  category: 'expected' | 'higher' | 'progress' | 'average' | 'context' | 'absence' | 'gender' | 'disadvantaged' | '3yr';
  format: 'percentage' | 'score' | 'progress';
  hasNationalAverage?: boolean;
}

// Backend returns metrics as an array, not an object
export interface MetricsResponse {
  metrics: MetricDefinition[];
}

export interface DataInfoResponse {
  total_schools: number;
  years_available: number[];
  latest_year: number;
  total_records: number;
}

// ============================================================================
// API Request Parameter Types
// ============================================================================

export interface SchoolSearchParams {
  search?: string;
  local_authority?: string;
  school_type?: string;
  postcode?: string;
  radius?: number;
  page?: number;
  page_size?: number;
}

export interface RankingsParams {
  metric: string;
  year?: number;
  local_authority?: string;
  limit?: number;
}

export interface ComparisonParams {
  urns: string | number[];
}

// ============================================================================
// UI State Types
// ============================================================================

export interface ComparisonState {
  selectedSchools: School[];
  selectedMetric: string;
}

export interface SearchState {
  mode: 'name' | 'location';
  query: string;
  filters: {
    local_authority: string;
    school_type: string;
  };
  postcode?: string;
  radius?: number;
  resultsView: 'list' | 'map';
}

export interface MapState {
  center: [number, number];
  zoom: number;
  bounds?: [[number, number], [number, number]];
}

// ============================================================================
// Chart Data Types
// ============================================================================

export interface ChartDataset {
  label: string;
  data: (number | null)[];
  borderColor: string;
  backgroundColor: string;
}

export interface ChartData {
  labels: (string | number)[];
  datasets: ChartDataset[];
}

// ============================================================================
// Error Types
// ============================================================================

export interface APIError {
  detail: string;
  status?: number;
}

// ============================================================================
// Utility Types
// ============================================================================

export type MetricKey = keyof Omit<SchoolResult, 'id' | 'school_id' | 'year'>;

export type SortDirection = 'asc' | 'desc';

export interface SortConfig {
  key: string;
  direction: SortDirection;
}
