/**
 * GVMC Open Data Portal - Complete Shared API Contracts Specification (v1.0)
 * Single source of truth for REST API types used by React Web & React Native Mobile apps.
 */

export type UserRole = 
  | 'CITIZEN' 
  | 'STUDENT'
  | 'RESEARCHER' 
  | 'STARTUP' 
  | 'FIELD_OFFICER' 
  | 'SUPERVISOR' 
  | 'COMMISSIONER' 
  | 'ADMIN';

export type DatasetCategory = 
  | 'WATER_SUPPLY' 
  | 'WASTE_MANAGEMENT' 
  | 'TRANSPORT' 
  | 'PUBLIC_HEALTH' 
  | 'URBAN_PLANNING' 
  | 'PROPERTY_TAX' 
  | 'ENVIRONMENT';

export type DatasetStatus = 
  | 'DRAFT' 
  | 'UNDER_REVIEW' 
  | 'APPROVED' 
  | 'PUBLISHED' 
  | 'ARCHIVED';

export type AccessLevel = 'PUBLIC' | 'RESEARCHER_ONLY' | 'RESTRICTED';

export interface WardBoundaryFeature {
  type: 'Feature';
  geometry: any;
  properties: {
    ward_number: number;
    ward_name: string;
    zone_name: string;
    area_sq_km: number;
    population_est: number;
  };
}

export interface HeatmapPoint {
  lat: number;
  lng: number;
  intensity: number;
}

export interface AnalyticsOverview {
  total_datasets: number;
  total_api_calls: number;
  active_citizens: number;
  ward_health_index: number;
}

export interface Token {
  access_token: string;
  token_type: string;
}

export interface UserOut {
  id: string;
  email: string;
  full_name: string;
  role: UserRole;
  organization?: string;
  is_active?: boolean;
  is_verified?: boolean;
}

// Unified Response Wrappers
export interface APIResponse<T> {
  success: boolean;
  message: string;
  data?: T;
  errors?: ErrorDetail[];
}

export interface PaginationMeta {
  total_items: number;
  page: number;
  page_size: number;
  total_pages: number;
  has_next: boolean;
  has_prev: boolean;
}

export interface PaginatedResponse<T> {
  success: boolean;
  message: string;
  data: T[];
  pagination: PaginationMeta;
  errors?: ErrorDetail[];
}

export interface ErrorDetail {
  code?: string;
  message: string;
  field?: string;
}

// Authentication & Identity Contracts
export interface LoginRequest {
  email: string;
  password?: string;
}

export interface AuthTokens {
  access_token: string;
  refresh_token: string;
  token_type: 'bearer';
  expires_in: number;
}

export interface UserDTO {
  id: string;
  email: string;
  full_name: string;
  role: UserRole;
  organization?: string;
  phone_number?: string;
  avatar_url?: string;
  created_at: string;
}

export interface AuthResponse {
  user: UserDTO;
  tokens: AuthTokens;
}

// Data Catalog & Governance Contracts
export interface DatasetOut {
  id: string;
  title: string;
  description: string;
  category: DatasetCategory;
  department: string;
  status: DatasetStatus;
  access_level: AccessLevel;
  tags: string[];
  current_version: string;
  current_version_id?: string;
  total_downloads: number;
  view_count: number;
  overall_quality_score: number;
  overall_trust_score: number;
  created_at: string;
  updated_at: string;
}

// Citizen Module Contracts
export type CivicIssueCategory = 
  | 'SOLID_WASTE'
  | 'ILLEGAL_DUMPING'
  | 'ROAD_DAMAGE'
  | 'WATER_LEAKAGE'
  | 'DRAINAGE_OVERFLOW'
  | 'BROKEN_STREET_LIGHT'
  | 'PUBLIC_TOILET_ISSUE'
  | 'PARK_MAINTENANCE'
  | 'ENCROACHMENT'
  | 'OTHER';

export type IssueStatus = 
  | 'SUBMITTED'
  | 'ASSIGNED'
  | 'IN_PROGRESS'
  | 'RESOLVED'
  | 'VERIFIED'
  | 'CLOSED'
  | 'REJECTED';

export type IssuePriority = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';

export interface CivicIssueCreateIn {
  category: CivicIssueCategory;
  description: string;
  latitude: number;
  longitude: number;
  area: string;
  landmark?: string;
  captured_images?: string[];
  priority?: IssuePriority;
}

export interface CivicIssueTimelineEntry {
  status: IssueStatus;
  notes?: string;
  changed_by_name: string;
  timestamp: string;
}

export interface CivicIssueOut {
  id: string;
  issue_code: string;
  citizen_user_id: string;
  category: CivicIssueCategory;
  category_label: string;
  description: string;
  latitude: number;
  longitude: number;
  area: string;
  ward_number: number;
  current_status: IssueStatus;
  priority: IssuePriority;
  captured_images: string[];
  assigned_officer_name?: string;
  assigned_department?: string;
  estimated_resolution_hours: number;
  created_at: string;
  updated_at: string;
  resolved_at?: string;
  citizen_rating?: number;
  citizen_feedback?: string;
  timeline: CivicIssueTimelineEntry[];
}

export interface CivicIssueFeedbackIn {
  rating: number;
  feedback?: string;
}

export interface AnnouncementOut {
  id: string;
  announcement_code: string;
  title: string;
  description: string;
  category: string;
  priority: 'NORMAL' | 'HIGH' | 'EMERGENCY' | 'URGENT';
  target_audience: 'ALL' | 'SELECTED_WARDS';
  target_wards: number[];
  target_regions?: string[];
  image_url?: string;
  voice_note_url?: string;
  created_by_name: string;
  created_at: string;
  is_read: boolean;
}

export interface CitizenProfileOut {
  id: string;
  user_id: string;
  full_name: string;
  email: string;
  phone_number?: string;
  address?: string;
  state: string;
  city: string;
  area: string;
  ward_number: number;
  dataset_interests: string[];
  saved_datasets: string[];
  favorite_reports: string[];
  notification_preferences: {
    email_alerts: boolean;
    sms_alerts: boolean;
    announcement_notifications: boolean;
    issue_status_updates: boolean;
  };
}

export interface CitizenProfileUpdateIn {
  full_name?: string;
  phone_number?: string;
  address?: string;
  state?: string;
  city?: string;
  area?: string;
  ward_number?: number;
  dataset_interests?: string[];
  notification_preferences?: {
    email_alerts?: boolean;
    sms_alerts?: boolean;
    announcement_notifications?: boolean;
    issue_status_updates?: boolean;
  };
}

export interface CityInsightCard {
  id: string;
  title: string;
  category: string;
  metric_value: string;
  status_label: string;
  status_color: 'green' | 'amber' | 'red' | 'blue';
  description: string;
  ward_number: number;
  area_name: string;
  last_updated: string;
}

export interface CityInsightsOut {
  city_health_score: number;
  ward_number: number;
  area_name: string;
  active_road_repairs_count: number;
  water_supply_ph_level: number;
  waste_collection_efficiency_pct: number;
  active_civic_reports_count: number;
  insight_cards: CityInsightCard[];
  recent_civic_activities: {
    title: string;
    ward_name: string;
    timestamp: string;
    status: string;
  }[];
}

// Student Module Contracts
export type AcademicDomain = 
  | 'COMPUTER_SCIENCE'
  | 'ARTIFICIAL_INTELLIGENCE'
  | 'MACHINE_LEARNING'
  | 'DATA_SCIENCE'
  | 'CIVIL_ENGINEERING'
  | 'MECHANICAL_ENGINEERING'
  | 'ELECTRICAL_ENGINEERING'
  | 'ELECTRONICS'
  | 'ENVIRONMENTAL_ENGINEERING'
  | 'GIS'
  | 'URBAN_PLANNING'
  | 'ARCHITECTURE'
  | 'BUSINESS_ANALYTICS'
  | 'ECONOMICS'
  | 'PUBLIC_POLICY'
  | 'OTHER';

export type ProjectStatus = 
  | 'DRAFT'
  | 'SUBMITTED'
  | 'UNDER_REVIEW'
  | 'APPROVED'
  | 'REJECTED'
  | 'FEATURED';

export interface StudentProfileOut {
  id: string;
  user_id: string;
  full_name: string;
  email: string;
  college: string;
  course: string;
  current_year: number;
  academic_domain: AcademicDomain;
  student_id_code?: string;
  graduation_year: number;
  purpose: string;
  areas_of_interest: string[];
  student_id_card_url?: string;
  notification_preferences: Record<string, boolean>;
}

export interface StudentProfileUpdateIn {
  college?: string;
  course?: string;
  current_year?: number;
  academic_domain?: AcademicDomain;
  student_id_code?: string;
  graduation_year?: number;
  purpose?: string;
  areas_of_interest?: string[];
  student_id_card_url?: string;
  notification_preferences?: Record<string, boolean>;
}

export interface ProblemStatementOut {
  id: string;
  problem_code: string;
  title: string;
  description: string;
  department: string;
  difficulty: 'BEGINNER' | 'INTERMEDIATE' | 'ADVANCED' | 'EXPERT';
  related_datasets: string[];
  related_gis_layers: string[];
  target_domains: string[];
  status: string;
  is_featured: boolean;
  created_at: string;
}

export interface ProjectAttachmentOut {
  id: string;
  file_name: string;
  file_url: string;
  file_size: number;
  mime_type: string;
}

export interface StudentProjectCreateIn {
  title: string;
  description: string;
  academic_domain?: AcademicDomain;
  selected_datasets?: string[];
  problem_statement_id?: string;
  github_link?: string;
  presentation_url?: string;
  demo_url?: string;
  submit_immediately?: boolean;
}

export interface StudentProjectUpdateIn {
  title?: string;
  description?: string;
  academic_domain?: AcademicDomain;
  selected_datasets?: string[];
  github_link?: string;
  presentation_url?: string;
  demo_url?: string;
}

export interface StudentProjectOut {
  id: string;
  project_code: string;
  user_id: string;
  title: string;
  description: string;
  academic_domain: AcademicDomain;
  selected_datasets: string[];
  problem_statement_id?: string;
  github_link?: string;
  presentation_url?: string;
  demo_url?: string;
  current_status: ProjectStatus;
  admin_feedback?: string;
  review_notes?: string;
  review_date?: string;
  is_featured: boolean;
  created_at: string;
  updated_at: string;
  attachments?: ProjectAttachmentOut[];
}

export interface StudentBookmarkOut {
  id: string;
  dataset_id: string;
  dataset_title: string;
  dataset_category: string;
  note?: string;
  created_at: string;
}

export interface StudentBookmarkCreateIn {
  dataset_id: string;
  dataset_title: string;
  dataset_category: string;
  note?: string;
}

export interface ResearchLibraryItemOut {
  id: string;
  item_code: string;
  title: string;
  authors: string;
  publication_type: string;
  publication_date: string;
  summary: string;
  document_url: string;
  related_categories: string[];
  download_count: number;
}

export interface RecommendedDataset {
  dataset_id: string;
  title: string;
  category: string;
  department: string;
  relevance_score: number;
  reason: string;
}

export interface RecommendationOut {
  academic_domain: AcademicDomain;
  recommended_datasets: RecommendedDataset[];
  recommended_departments: string[];
  recommended_categories: string[];
}

export interface StudentDashboardOut {
  profile: StudentProfileOut;
  total_projects: number;
  submitted_projects: number;
  approved_projects: number;
  bookmarked_count: number;
  total_downloads: number;
  recent_projects: StudentProjectOut[];
  recent_bookmarks: StudentBookmarkOut[];
  recent_downloads: any[];
  recommendations: RecommendationOut;
  curated_problems: ProblemStatementOut[];
  recent_activities: any[];
}

/** Researcher Module Types & DTOs */
export type StudyStatus = 'DRAFT' | 'ACTIVE' | 'SUBMITTED' | 'PUBLISHED' | 'ARCHIVED';
export type DataRequestStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'EXPIRED';
export type PublicationStatus = 'DRAFT' | 'SUBMITTED' | 'PUBLISHED' | 'ARCHIVED';

export interface ResearcherProfileOut {
  id: string;
  user_id: string;
  full_name: string;
  email: string;
  institution: string;
  designation: string;
  years_of_experience: number;
  orcid_id?: string;
  institution_id_card_url?: string;
  approval_letter_url?: string;
  research_domains: string[];
  research_interests: string[];
  research_purpose?: string;
  expected_duration: string;
  notification_preferences: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface ResearcherProfileUpdateIn {
  institution?: string;
  designation?: string;
  years_of_experience?: number;
  orcid_id?: string;
  institution_id_card_url?: string;
  approval_letter_url?: string;
  research_domains?: string[];
  research_interests?: string[];
  research_purpose?: string;
  expected_duration?: string;
  notification_preferences?: Record<string, any>;
}

export interface ResearchStudyOut {
  id: string;
  study_code: string;
  user_id: string;
  title: string;
  abstract: string;
  objective: string;
  research_domain: string;
  methodology: string;
  datasets_used: string[];
  gis_layers: string[];
  study_area: string;
  ward_coverage: number[];
  expected_outcome?: string;
  current_status: StudyStatus;
  created_at: string;
  updated_at: string;
}

export interface ResearchStudyCreateIn {
  title: string;
  abstract: string;
  objective: string;
  research_domain?: string;
  methodology: string;
  datasets_used?: string[];
  gis_layers?: string[];
  study_area?: string;
  ward_coverage?: number[];
  expected_outcome?: string;
  submit_for_review?: boolean;
}

export interface ResearchStudyUpdateIn {
  title?: string;
  abstract?: string;
  objective?: string;
  research_domain?: string;
  methodology?: string;
  datasets_used?: string[];
  gis_layers?: string[];
  study_area?: string;
  ward_coverage?: number[];
  expected_outcome?: string;
  current_status?: StudyStatus;
}

export interface CollectionDatasetOut {
  id: string;
  collection_id: string;
  dataset_id: string;
  dataset_title: string;
  dataset_category: string;
  version_reference: string;
  notes?: string;
  added_at: string;
}

export interface CollectionDatasetAddIn {
  dataset_id: string;
  dataset_title: string;
  dataset_category: string;
  version_reference?: string;
  notes?: string;
}

export interface ResearchCollectionOut {
  id: string;
  user_id: string;
  name: string;
  description?: string;
  tags: string[];
  is_public: boolean;
  created_at: string;
  updated_at: string;
  datasets: CollectionDatasetOut[];
}

export interface ResearchCollectionCreateIn {
  name: string;
  description?: string;
  tags?: string[];
  is_public?: boolean;
  datasets?: CollectionDatasetAddIn[];
}

export interface ResearchCollectionUpdateIn {
  name?: string;
  description?: string;
  tags?: string[];
  is_public?: boolean;
}

export interface SpatialAnalysisSessionOut {
  id: string;
  user_id: string;
  session_name: string;
  dataset_id: string;
  ward_numbers: number[];
  gis_layers: string[];
  date_start?: string;
  date_end?: string;
  query_config: Record<string, any>;
  results_summary: Record<string, any>;
  created_at: string;
}

export interface SpatialAnalysisSessionCreateIn {
  session_name: string;
  dataset_id: string;
  ward_numbers?: number[];
  gis_layers?: string[];
  date_start?: string;
  date_end?: string;
  query_config?: Record<string, any>;
}

export interface PublicationOut {
  id: string;
  publication_code: string;
  user_id: string;
  study_id?: string;
  title: string;
  abstract: string;
  authors: string;
  institution: string;
  datasets_used: string[];
  publication_date: string;
  document_url: string;
  doi_url?: string;
  current_status: PublicationStatus;
  citation_formatted?: string;
  download_count: number;
  created_at: string;
  updated_at: string;
}

export interface PublicationCreateIn {
  study_id?: string;
  title: string;
  abstract: string;
  authors: string;
  institution: string;
  datasets_used?: string[];
  document_url: string;
  doi_url?: string;
}

export interface PublicationUpdateIn {
  title?: string;
  abstract?: string;
  authors?: string;
  institution?: string;
  datasets_used?: string[];
  document_url?: string;
  doi_url?: string;
  current_status?: PublicationStatus;
}

export interface DataAccessRequestOut {
  id: string;
  request_code: string;
  user_id: string;
  dataset_id: string;
  dataset_title: string;
  research_purpose: string;
  expected_duration: string;
  expected_outcome: string;
  current_status: DataRequestStatus;
  approval_notes?: string;
  expiry_date?: string;
  reviewed_by_user_id?: string;
  created_at: string;
  updated_at: string;
}

export interface DataAccessRequestCreateIn {
  dataset_id: string;
  dataset_title: string;
  research_purpose: string;
  expected_duration: string;
  expected_outcome: string;
}

export interface ResearcherDashboardOut {
  profile: ResearcherProfileOut;
  total_studies: number;
  active_studies: number;
  published_studies: number;
  collections_count: number;
  publications_count: number;
  data_requests_count: number;
  total_downloads: number;
  recent_studies: ResearchStudyOut[];
  recent_collections: ResearchCollectionOut[];
  recent_publications: PublicationOut[];
  data_requests: DataAccessRequestOut[];
  recent_activities: Record<string, any>[];
}

/** Startup Module Types & DTOs */
export type FundingStage = 'BOOTSTRAPPED' | 'PRE_SEED' | 'SEED' | 'SERIES_A' | 'SERIES_B_PLUS' | 'GOVERNMENT_SUPPORTED';
export type AnnualRevenue = 'PRE_REVENUE' | 'LESS_THAN_10L' | 'BETWEEN_10_50L' | 'BETWEEN_50L_1CR' | 'BETWEEN_1_5CR' | 'ABOVE_5CR';
export type StartupStage = 'IDEATION' | 'VALIDATION' | 'EARLY_TRACTION' | 'SCALING' | 'ESTABLISHED';
export type ApplicationStatus = 'DRAFT' | 'SUBMITTED' | 'UNDER_REVIEW' | 'APPROVED' | 'FEATURED' | 'REJECTED';
export type ConfidentialRequestStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'EXPIRED';
export type ApiKeyStatus = 'ACTIVE' | 'REVOKED' | 'EXPIRED';

export interface StartupProfileOut {
  id: string;
  user_id: string;
  founder_name: string;
  official_email: string;
  mobile_number: string;
  startup_name: string;
  startup_stage: StartupStage;
  year_founded: number;
  team_size: number;
  industry: string;
  company_website: string;
  linkedin_url: string;
  registration_number?: string;
  description?: string;
  problem_statement?: string;
  target_sector: string;
  funding_stage: FundingStage;
  annual_revenue: AnnualRevenue;
  primary_technologies: string[];
  municipal_sectors: string[];
  trust_score: number;
  notification_preferences: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface StartupProfileUpdateIn {
  founder_name?: string;
  official_email?: string;
  mobile_number?: string;
  startup_name?: string;
  startup_stage?: StartupStage;
  year_founded?: number;
  team_size?: number;
  industry?: string;
  company_website?: string;
  linkedin_url?: string;
  registration_number?: string;
  description?: string;
  problem_statement?: string;
  target_sector?: string;
  funding_stage?: FundingStage;
  annual_revenue?: AnnualRevenue;
  primary_technologies?: string[];
  municipal_sectors?: string[];
  notification_preferences?: Record<string, any>;
}

export interface ApiKeyOut {
  id: string;
  user_id: string;
  startup_id?: string;
  key_name: string;
  key_prefix: string;
  scopes: string[];
  status: ApiKeyStatus;
  rate_limit_per_minute: number;
  total_requests: number;
  created_at: string;
  last_used_at?: string;
  expires_at?: string;
}

export interface ApiKeyCreateIn {
  key_name: string;
  scopes?: string[];
  rate_limit_per_minute?: number;
  expires_in_days?: number;
}

export interface ApiKeyUpdateIn {
  key_name?: string;
  scopes?: string[];
  status?: ApiKeyStatus;
  rate_limit_per_minute?: number;
}

export interface ApiKeyCreatedOut extends ApiKeyOut {
  raw_secret: string;
}

export interface StartupApplicationOut {
  id: string;
  user_id: string;
  startup_id: string;
  application_name: string;
  description: string;
  target_sector: string;
  website_url?: string;
  demo_url?: string;
  version: string;
  datasets_used: string[];
  api_keys_used: string[];
  current_status: ApplicationStatus;
  administrator_notes?: string;
  created_at: string;
  updated_at: string;
}

export interface StartupApplicationCreateIn {
  application_name: string;
  description: string;
  target_sector?: string;
  website_url?: string;
  demo_url?: string;
  version?: string;
  datasets_used?: string[];
  api_keys_used?: string[];
}

export interface StartupApplicationUpdateIn {
  application_name?: string;
  description?: string;
  target_sector?: string;
  website_url?: string;
  demo_url?: string;
  version?: string;
  datasets_used?: string[];
  api_keys_used?: string[];
  current_status?: ApplicationStatus;
  administrator_notes?: string;
}

export interface ConfidentialDatasetRequestOut {
  id: string;
  request_code: string;
  user_id: string;
  startup_id: string;
  dataset_id: string;
  dataset_title: string;
  reason: string;
  expected_usage: string;
  expected_duration: string;
  business_impact: string;
  portfolio_snapshot: Record<string, any>;
  current_status: ConfidentialRequestStatus;
  approval_notes?: string;
  expiry_date?: string;
  reviewed_by_user_id?: string;
  created_at: string;
  updated_at: string;
}

export interface ConfidentialDatasetRequestCreateIn {
  dataset_id: string;
  dataset_title: string;
  reason: string;
  expected_usage: string;
  expected_duration: string;
  business_impact: string;
}

export interface EndpointDocOut {
  endpoint: string;
  method: string;
  summary: string;
  description: string;
  category: string;
  authentication_required: boolean;
  rate_limit: string;
  sample_request: Record<string, any>;
  sample_response: Record<string, any>;
}

export interface DeveloperDocsOut {
  api_version: string;
  base_url: string;
  authentication_guide: string;
  rate_limiting_rules: string;
  endpoints: EndpointDocOut[];
}

export interface UsageAnalyticsOut {
  total_api_requests: number;
  requests_today: number;
  monthly_requests: number;
  success_rate_percentage: number;
  average_latency_ms: number;
  error_rate_percentage: number;
  bandwidth_used_mb: number;
  top_endpoints: Record<string, any>[];
  most_used_datasets: Record<string, any>[];
  api_key_usage_breakdown: Record<string, any>[];
  daily_request_trends: Record<string, any>[];
}

export interface StartupDashboardOut {
  profile: StartupProfileOut;
  company_summary: Record<string, any>;
  active_api_keys_count: number;
  total_applications_count: number;
  datasets_consumed_count: number;
  monthly_api_requests: number;
  api_success_rate: number;
  recent_applications: StartupApplicationOut[];
  recent_api_keys: ApiKeyOut[];
  confidential_requests: ConfidentialDatasetRequestOut[];
  recent_activities: Record<string, any>[];
}

/** Supervisor & Field Officer Operations Contracts */
export type OperationalTaskStatus = 
  | 'NEW' 
  | 'ASSIGNED' 
  | 'IN_PROGRESS' 
  | 'WAITING_VERIFICATION' 
  | 'RESOLVED' 
  | 'ESCALATED' 
  | 'CLOSED';

export type OperationalTaskPriority = 
  | 'LOW' 
  | 'MEDIUM' 
  | 'HIGH' 
  | 'EMERGENCY';

export interface SupervisorProfileOut {
  id: string;
  user_id: string;
  employee_code: string;
  supervisor_name: string;
  official_email: string;
  mobile_number: string;
  department: string;
  designation: string;
  assigned_wards: number[];
  assigned_officers_count: number;
  trust_score: number;
  notification_preferences: Record<string, boolean>;
  created_at: string;
  updated_at: string;
}

export interface SupervisorProfileUpdateIn {
  mobile_number?: string;
  department?: string;
  designation?: string;
  assigned_wards?: number[];
  notification_preferences?: Record<string, boolean>;
}

export interface FieldOfficerProfileOut {
  id: string;
  user_id: string;
  officer_name: string;
  employee_code: string;
  department: string;
  assigned_supervisor_id: string;
  mobile_number: string;
  assigned_wards: number[];
  current_status: 'AVAILABLE' | 'ON_TASK' | 'OFF_DUTY';
  created_at: string;
  updated_at: string;
}

export interface ComplaintTimelineOut {
  id: string;
  task_id: string;
  action: string;
  status_from?: string;
  status_to?: string;
  performed_by_id: string;
  performed_by_name: string;
  performed_by_role: string;
  notes?: string;
  created_at: string;
}

export interface OperationalTaskOut {
  id: string;
  issue_code: string;
  citizen_id?: string;
  citizen_name: string;
  citizen_phone?: string;
  category: string;
  priority: OperationalTaskPriority;
  ward_number: number;
  area_name: string;
  department: string;
  assigned_officer_id?: string;
  assigned_officer_name?: string;
  assigned_supervisor_id?: string;
  current_status: OperationalTaskStatus;
  deadline_date?: string;
  notes?: string;
  evidence_photos?: string[];
  resolution_notes?: string;
  lat?: number;
  lng?: number;
  timeline: ComplaintTimelineOut[];
  created_at: string;
  updated_at: string;
}

export interface OperationalTaskCreateIn {
  category: string;
  priority?: OperationalTaskPriority;
  ward_number: number;
  area_name: string;
  department: string;
  notes?: string;
  lat?: number;
  lng?: number;
}

export interface OperationalTaskUpdateIn {
  current_status?: OperationalTaskStatus;
  priority?: OperationalTaskPriority;
  notes?: string;
  resolution_notes?: string;
  evidence_photos?: string[];
}

export interface TaskAssignIn {
  assigned_officer_id: string;
  priority?: OperationalTaskPriority;
  deadline_date?: string;
  notes?: string;
}

export interface WardAnnouncementOut {
  id: string;
  supervisor_id: string;
  supervisor_name: string;
  title: string;
  content: string;
  category: 'GENERAL' | 'WATER_SHUTDOWN' | 'SANITATION_DRIVE' | 'EMERGENCY';
  target_wards: number[];
  target_roles: string[];
  created_at: string;
}

export interface WardAnnouncementCreateIn {
  title: string;
  content: string;
  category?: 'GENERAL' | 'WATER_SHUTDOWN' | 'SANITATION_DRIVE' | 'EMERGENCY';
  target_wards: number[];
  target_roles?: string[];
}

export interface SupervisorGisOut {
  ward_boundaries: Record<string, any>[];
  active_complaints: OperationalTaskOut[];
  resolved_complaints: OperationalTaskOut[];
  assigned_officers: FieldOfficerProfileOut[];
  complaint_density_heatmap: Record<string, any>[];
}

export interface SupervisorReportsOut {
  total_complaints_received: number;
  total_complaints_resolved: number;
  total_pending_issues: number;
  average_resolution_time_hours: number;
  officer_performance: Record<string, any>[];
  ward_performance: Record<string, any>[];
  department_performance: Record<string, any>[];
}

export interface SupervisorDashboardOut {
  profile: SupervisorProfileOut;
  active_complaints_count: number;
  pending_complaints_count: number;
  resolved_today_count: number;
  assigned_officers_count: number;
  ward_summary: Record<string, any>[];
  todays_tasks: OperationalTaskOut[];
  recent_activity: ComplaintTimelineOut[];
  emergency_alerts: WardAnnouncementOut[];
}

/** Administrator Platform Governance Contracts */
export type ApprovalRequestType = 
  | 'DATASET_PUBLICATION' 
  | 'RESEARCH_CLEARANCE' 
  | 'STARTUP_CONFIDENTIAL' 
  | 'STUDENT_INNOVATION';

export type ApprovalStatus = 
  | 'PENDING' 
  | 'APPROVED' 
  | 'REJECTED' 
  | 'MORE_INFO_REQUESTED' 
  | 'FORWARDED';

export interface AdminProfileOut {
  id: string;
  user_id: string;
  employee_code: string;
  admin_name: string;
  official_email: string;
  mobile_number: string;
  department: string;
  designation: string;
  trust_score: number;
  notification_preferences: Record<string, boolean>;
  security_settings: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface AdminProfileUpdateIn {
  mobile_number?: string;
  department?: string;
  designation?: string;
  notification_preferences?: Record<string, boolean>;
  security_settings?: Record<string, any>;
}

export interface ApprovalHistoryOut {
  id: string;
  approval_id: string;
  action: string;
  status_from?: string;
  status_to?: string;
  performed_by_id: string;
  performed_by_name: string;
  performed_by_role: string;
  notes?: string;
  created_at: string;
}

export interface ApprovalQueueItemOut {
  id: string;
  request_code: string;
  request_type: ApprovalRequestType;
  submitted_by_id: string;
  submitted_by_name: string;
  submitted_by_role: string;
  department: string;
  priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  title: string;
  description: string;
  supporting_documents: string[];
  current_status: ApprovalStatus;
  administrator_notes?: string;
  reviewed_by_id?: string;
  history: ApprovalHistoryOut[];
  created_at: string;
  updated_at: string;
}

export interface ApprovalQueueItemUpdateIn {
  current_status: ApprovalStatus;
  administrator_notes?: string;
}

export interface PlatformUserOut {
  id: string;
  email: string;
  full_name: string;
  role: string;
  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
  organization?: string;
  department?: string;
  ward_number?: number;
  last_login_at?: string;
  created_at: string;
}

export interface PlatformUserUpdateIn {
  full_name?: string;
  role?: string;
  status?: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
  organization?: string;
  department?: string;
  ward_number?: number;
}

export interface CityAnnouncementOut {
  id: string;
  title: string;
  content: string;
  priority: 'NORMAL' | 'HIGH' | 'URGENT';
  target_roles: string[];
  image_url?: string;
  voice_note_url?: string;
  expiry_date?: string;
  is_active: boolean;
  published_by: string;
  created_at: string;
}

export interface CityAnnouncementCreateIn {
  title: string;
  content: string;
  priority?: 'NORMAL' | 'HIGH' | 'URGENT';
  target_roles?: string[];
  target_regions?: string[];
  image_url?: string;
  voice_note_url?: string;
  expiry_date?: string;
}

export interface PlatformGovernanceOut {
  platform_health_status: string;
  uptime_percentage: number;
  active_api_keys_count: number;
  total_registered_users: number;
  storage_used_gb: number;
  storage_total_gb: number;
  redis_cache_hit_ratio: number;
  security_threats_blocked_today: number;
  persona_counts: {
    citizens: number;
    students: number;
    researchers: number;
    startups: number;
    supervisors: number;
    field_officers: number;
    admins: number;
  };
  ecosystem_metrics: {
    citizen_complaints: number;
    student_projects: number;
    research_studies: number;
    startup_apps: number;
    api_requests_today: number;
  };
  system_config: Record<string, any>;
  recent_audit_events: Record<string, any>[];
}

export interface AdminDashboardOut {
  profile: AdminProfileOut;
  total_users_count: number;
  active_users_count: number;
  pending_approvals_count: number;
  total_datasets_count: number;
  platform_governance: PlatformGovernanceOut;
  recent_approvals: ApprovalQueueItemOut[];
  recent_users: PlatformUserOut[];
  active_announcements: CityAnnouncementOut[];
  platform_activity_stream: Record<string, any>[];
}

/** Commissioner Executive Intelligence Contracts */
export interface CommissionerProfileOut {
  id: string;
  user_id: string;
  employee_code: string;
  commissioner_name: string;
  official_email: string;
  mobile_number: string;
  department: string;
  designation: string;
  executive_preferences: Record<string, any>;
  created_at: string;
  updated_at: string;
}

export interface CommissionerProfileUpdateIn {
  mobile_number?: string;
  executive_preferences?: Record<string, any>;
}

export interface ExecutiveReportOut {
  id: string;
  report_code: string;
  report_title: string;
  report_type: string;
  summary: string;
  metrics: Record<string, any>;
  generated_by: string;
  file_url: string;
  created_at: string;
}

export interface PolicyInsightOut {
  id: string;
  title: string;
  category: string;
  recommendation: string;
  impact_score: number;
  target_department: string;
  created_at: string;
}

export interface DepartmentPerformanceOut {
  department_name: string;
  resolution_rate_percent: number;
  average_resolution_hours: number;
  datasets_contributed: number;
  sla_compliance_percent: number;
  citizen_satisfaction_score: number;
  total_issues_handled: number;
}

export interface CityIntelligenceOut {
  city_health_index: number;
  monthly_complaint_trend: Record<string, any>[];
  dataset_catalog_growth: Record<string, any>[];
  research_publication_growth: Record<string, any>[];
  startup_economic_growth: Record<string, any>[];
  policy_insights: PolicyInsightOut[];
}

export interface CommissionerGisIntelligenceOut {
  ward_rankings: Record<string, any>[];
  spatial_complaint_heatmaps: Record<string, any>[];
  department_layers: Record<string, any>[];
  infrastructure_status: Record<string, any>;
}

export interface CommissionerDashboardOut {
  profile: CommissionerProfileOut;
  city_health_index: number;
  citizen_satisfaction_score: number;
  department_sla_compliance: number;
  active_complaints_count: number;
  resolved_complaints_count: number;
  open_datasets_count: number;
  research_studies_count: number;
  startup_apps_count: number;
  student_projects_count: number;
  api_requests_today: number;
  departments_performance: DepartmentPerformanceOut[];
  top_performing_wards: Record<string, any>[];
  recent_policy_insights: PolicyInsightOut[];
  available_reports: ExecutiveReportOut[];
}