/**
 * 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;

  // 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';
}

// ============================================================================
// 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;
}

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;
}
