/**
 * TypeScript interfaces for all mock data entities.
 *
 * These types define the shape of every record generated by the mock data
 * layer and consumed by dashboard pages via TanStack Query hooks.
 */

// Re-export UserRole from the canonical source in navigation constants
export type { UserRole } from '@/lib/constants/navigation';

/** A musical composition in the catalogue. */
export interface Work {
  id: string;
  title: string;
  iswc: string;
  genre: string;
  rightsType: 'controlled' | 'uncontrolled';
  writerSplits: Array<{ composerId: string; percentage: number }>;
  createdAt: Date;
  monthlyIncome: Array<{ month: string; amount: number }>;
}

/** A writer or rights-holder associated with one or more Works. */
export interface Composer {
  id: string;
  name: string;
  workCount: number;
  associatedWorkIds: string[];
  monthlyIncome: Array<{ month: string; amount: number }>;
  createdAt: Date;
}

/** A publisher, sub-publisher, administrator, or individual entitled to royalty payments. */
export interface Payee {
  id: string;
  name: string;
  type: 'publisher' | 'sub-publisher' | 'administrator' | 'individual';
  territory: string;
  cumulativeEarnings: number;
}

/** A deal specifying territory, currency, royalty splits, and validity period. */
export interface Contract {
  id: string;
  territory: string;
  currency: string;
  royaltySplit: number;
  startDate: Date;
  endDate: Date;
  status: 'active' | 'inactive';
}

/** A simulated sales or royalty income entry. */
export interface IncomeRecord {
  id: string;
  workId: string;
  amount: number;
  grossAmount: number;
  netAmount: number;
  territory: string;
  mediaType: string;
  source: 'PRO' | 'DSP' | 'sub-publisher';
  date: Date;
}

/** A simulated financial transaction. */
export interface Transaction {
  id: string;
  type: 'royalty' | 'fee' | 'advance' | 'adjustment';
  amount: number;
  currency: string;
  date: Date;
}

/** A simulated cost entry. */
export interface Cost {
  id: string;
  type: 'administration' | 'ownership-purchase' | 'other';
  amount: number;
  currency: string;
  date: Date;
}

/** A simulated publishing statement. */
export interface Statement {
  id: string;
  period: string;
  payeeId: string;
  payeeName: string;
  currency: string;
  status: 'Draft' | 'Final' | 'Published';
  grossAmount: number;
  deductions: number;
  netPayable: number;
}

/** A simulated unmatched or ambiguous sales record. */
export interface SuspenseItem {
  id: string;
  date: Date;
  sourceFile: string;
  matchType: 'unmatched' | 'ambiguous';
  resolutionStatus: 'pending' | 'resolved';
  suggestedWorkId: string | null;
}

/** A simulated activity log entry. */
export interface AuditEvent {
  id: string;
  timestamp: Date;
  entityType: string;
  actionType: 'create' | 'update' | 'delete';
  userName: string;
}

/** A simulated user profile for the demo authentication flow. */
export interface MockUser {
  id: string;
  name: string;
  avatar: string;
  role: 'Super_Admin' | 'Publisher_Admin' | 'Viewer' | 'Client_Portal';
  clientId?: string;
}

// ─── Client Portal Types ─────────────────────────────────────────────────────

/** A quarterly financial period */
export interface PortalPeriod {
  id: string;
  label: string;           // e.g., "enero 2026 - marzo 2026"
  startDate: Date;
  endDate: Date;
  status: 'Activo' | 'Establecido' | 'Pendiente';
  balance: number;         // Saldo actual (CLP)
  advances: number;        // Anticipos (CLP)
  adjustments: number;     // Ajustes (CLP)
  netEarnings: number;     // Ganancias netas (CLP)
}

/** A time-series data point for the financial summary chart */
export interface FinancialTimePoint {
  month: string;           // e.g., "Ene 2025"
  netEarnings: number;     // CLP
  finalBalance: number;    // CLP
}

/** A top song entry for the analytics view */
export interface PortalTopSong {
  id: string;
  title: string;
  composers: string[];
  income: number;          // CLP
  percentage: number;      // 0-100
}

/** An income group category */
export interface PortalIncomeGroup {
  category: string;        // e.g., "Synchronisation", "Digital Mechanical"
  amount: number;          // CLP
  percentage: number;      // 0-100
}

/** An exploitation source entry */
export interface PortalExploitationSource {
  platform: string;        // e.g., "Spotify", "YouTube", "SCD"
  amount: number;          // CLP
  percentage: number;      // 0-100
  trend: number;           // percentage change
}

/** A territory entry */
export interface PortalTerritory {
  country: string;         // e.g., "Chile", "United States"
  amount: number;          // CLP
  percentage: number;      // 0-100
}

/** A downloadable statement entry */
export interface PortalStatement {
  id: string;
  periodLabel: string;     // e.g., "octubre 2025 - diciembre 2025"
  downloadUrl: string;
}

/** A document entry */
export interface PortalDocument {
  id: string;
  name: string;
  type: 'statement' | 'contract' | 'report';
  periodLabel?: string;
  downloadUrl: string;
}

/** A song catalogue entry */
export interface PortalSong {
  id: string;
  title: string;
  composers: string[];
  iswc: string;
  registrationDate: Date;
}

// ─── Analytics Detail Types ──────────────────────────────────────────────────

/** Detail data for a song in the analytics detail view */
export interface PortalSongDetail {
  id: string;
  title: string;
  composers: string[];
  lastPeriodAmount: number;
  currentPeriodAmount: number;
  percentageChange: number;
  topCategory: string;
  topCategoryAmount: number;
  topSource: string;
  topSourceAmount: number;
  topTerritory: string;
  topTerritoryAmount: number;
}

/** Detail data for an income group in the analytics detail view */
export interface PortalIncomeGroupDetail {
  category: string;
  lastPeriodAmount: number;
  currentPeriodAmount: number;
  percentageChange: number;
  subCategories: Array<{
    name: string;
    lastPeriodAmount: number;
    currentPeriodAmount: number;
    percentageChange: number;
  }>;
}

/** Detail data for a territory in the analytics detail view */
export interface PortalTerritoryDetail {
  country: string;
  lastPeriodAmount: number;
  currentPeriodAmount: number;
  percentageChange: number;
}

/** Detail data for an exploitation source in the analytics detail view */
export interface PortalSourceDetail {
  platform: string;
  lastPeriodAmount: number;
  currentPeriodAmount: number;
  percentageChange: number;
  topSong: string;
  topSongAmount: number;
  topCategory: string;
  topCategoryAmount: number;
  topTerritory: string;
  topTerritoryAmount: number;
}