/*
 * A /felfedezes oldal tervezett statisztikai végpontjai: mit vár a frontend, mit jelentenek a mezők.
 * A példaértékek a mostani statikus fájlokból valók (2026 október), hogy látszódjon a formátum.
 *
 * Állapot: a getOverview és a getCreators elkészült (GET /api/auth/statControl/...), a getWorks és a
 * getPrograms még tervezett.
 *
 * Jelenleg ezeket a számokat a scripts/azopus-szamokban/ szkriptjei és a docs/azopus-szamokban/sql/
 * lekérdezései állítják elő: ott olvashatók a pontos számítási szabályok és szűrések.
 *
 * Általános szabályok:
 *  - Csak publikált rekordok számítanak.
 *  - Elég naponta újraszámolni, a frontend is egy napig cache-eli a választ.
 *  - A `label` értékek a felületen megjelenő magyar szövegek. Ahol a kód konkrét címkére keres,
 *    ott azt a mező megjegyzése jelzi: ezeket pontosan így kell visszaadni.
 *
 * Nincs itt, mert már élő a meglévő API-ból: az Időgép (culturalEntityControl/getList),
 * a születésnapok (personControl/getBirthdayInfo) és a művészeti ágak képei.
 *
 * Nincs itt, mert egyelőre statikus marad: a címek színei és motívumai, a mester–tanítvány párok,
 * az évfolyamtársak, a Kossuth-lépcső, a kiemelt videók, a YouTube-csatorna számai.
 */

/** Egy név és a hozzá tartozó darabszám. Példa: { label: 'Képzőművészet', value: 11542 } */
export type Ranked = { label: string; value: number };

/** Egy alkotó kártyája egy számmal. */
export type CreatorCount = {
  /** Az alkotó nyilvános azonosítója. Példa: 'AL0000037' */
  id: string;
  /** Példa: 'Berecz András' */
  name: string;
  /** Példa: 'mesemondó, énekes' */
  profession: string | null;
  /** A profilkép azonosítója. Példa: 36199 */
  image: number | null;
  /** A halál dátuma, élő alkotónál null. Példa: '2011-09-27' */
  died: string | null;
  /** A kártyán látható szám, itt a programok száma. Példa: 54 */
  value: number;
};

/**
 * GET statControl/getOverview
 * Az oldal eleje, a „Miből mennyi?” és az „Idő és tér” blokkok.
 */
export type OverviewStatistics = {
  /** Mikor készültek az adatok; ebből lesz a „2026 októberéig” felirat. Példa: '2026-10-30' */
  generatedAt: string;
  totals: {
    /** Az összes publikált alkotás. Példa: 46259 */
    creations: number;
    /** Az összes alkotó. Példa: 524 */
    creators: number;
    /** A művészeti ágak száma. Példa: 10 */
    branches: number;
    /** A települések száma, ahol alkotás született. Példa: 1943 */
    places: number;
    /** Az életesemények száma. Példa: 19279 */
    lifeEvents: number;
    /** Az intézmények száma. Példa: 4096 */
    institutions: number;
    /** A programnaptár programjainak száma. Példa: 1789 */
    programs: number;
  };
  /** Alkotások áganként, csökkenő sorrendben. Példa: [{ label: 'Képzőművészet', value: 11542 }] */
  creationsByBranch: Ranked[];
  /** Alkotók áganként, csökkenő sorrendben. Példa: [{ label: 'Képzőművészet', value: 93 }] */
  creatorsByBranch: Ranked[];
  /**
   * Hány alkotónak hány alkotása van az adatbázisban (a személy `contentCount` mezője alapján). A
   * sávok ebben a sorrendben: '< 25', '25–49', '50–100', '> 100'. A kód az utolsó sávra támaszkodik.
   * Példa: [{ label: '< 25', value: 97 }, { label: '> 100', value: 155 }]
   */
  workBuckets: Ranked[];
  /** Az évtizedek kezdőévei, növekvő sorrendben. Példa: [1920, 1930, 1940, ..., 2020] */
  decades: number[];
  /**
   * Alkotások áganként és évtizedenként. A `counts` a `decades` sorrendjét követi, a sorok pedig
   * a `creationsByBranch` sorrendjét. Példa: { branch: 'Képzőművészet', counts: [1, 19, 58, ...] }
   */
  decadeMatrix: { branch: string; counts: number[] }[];
  /** A helyhez kötött alkotások Budapestre eső aránya, 0–1. Példa: 0.3756 */
  budapestShare: number;
  /** Az alkotások helyei a pontokból kirajzolódó térképhez, [hosszúság, szélesség]. Példa: [[19.04, 47.49]] */
  points: [number, number][];
};

/**
 * GET statControl/getCreators
 * „Az alkotók”, a „Pályák és díjak” és a „Mesterek és kapcsolatok” blokkok számai.
 */
export type CreatorStatistics = {
  /** Példa: '2026-10-30' */
  generatedAt: string;
  /** Alkotók születési évtized szerint. Példa: [{ decade: 1930, alive: 23, deceased: 79 }] */
  birthDecades: { decade: number; alive: number; deceased: number }[];
  /** A mai határokon túl születettek aránya, 0–1. Példa: 0.2309 */
  bornAbroadShare: number;
  /**
   * Alkotók születési ország szerint, csökkenő sorrendben. A kód a 'Magyarország' és a 'Szerbia'
   * címkére keres. Példa: [{ label: 'Magyarország', value: 403 }, { label: 'Románia', value: 75 }]
   */
  countries: Ranked[];
  /** Alkotók születési vármegye szerint. Példa: [{ label: 'Budapest', value: 208 }] */
  counties: Ranked[];
  /** Születési helyek a térképhez, a településen született alkotókkal. */
  birthPlaces: {
    /** Példa: 'Budapest' */
    city: string;
    /** Példa: 'Magyarország' */
    country: string;
    /** Példa: 19.083 */
    lng: number;
    /** Példa: 47.567 */
    lat: number;
    /** Példa: [{ id: 'AL0000002', name: 'Ács Margit', profession: 'író' }] */
    people: { id: string; name: string; profession: string | null }[];
  }[];
  /** Az életkori sávok alsó határai, ötévenként. Példa: [15, 20, 25, ..., 95] */
  ageBins: number[];
  /** Alkotások az alkotó akkori életkora szerint, áganként; a `counts` az `ageBins` sorrendjét követi. */
  ageAtCreation: {
    /** Az ág kisbetűvel, mondatba illesztve jelenik meg. Példa: 'filmművészet' */
    branch: string;
    /** Példa: [19, 167, 369, 432, 486, ...] */
    counts: number[];
    /** Az ág életkorral számolható alkotásai. Példa: 3647 */
    total: number;
    /** A legtöbb alkotást adó sáv alsó határa. Példa: 35 */
    peak: number;
  }[];
  /** A 80 év felett született alkotások aránya, 0–1. Példa: 0.0309 */
  oldCreationShare: number;
  /** A legidősebb korukban is alkotók, életkor szerint csökkenően. Példa: [{ name: 'Dávid Katalin', age: 96 }] */
  oldestWorkers: { name: string; age: number }[];
  /**
   * A pálya mérföldkövei, medián életkorral. A kód az 'Első ösztöndíj' és az 'Első díj' címkére keres.
   * Példa: [{ label: 'Első díj', median: 43, count: 461 }]
   */
  careerMilestones: { label: string; median: number; count: number }[];
  /**
   * Az állami díjak első elnyerésekor betöltött életkorok, a kiválasztott díjlistán (33 díj); csak
   * a legalább 9 ismert életkorral szereplő díjak kerülnek ide.
   * Példa: { award: 'Nemzet Művésze', ages: [66, 66, 67, ...], median: 76 }
   */
  ageAtAward: { award: string; ages: number[]; median: number }[];
  /** Évszámmal rögzített díjak évtizedenként. Példa: [{ label: '2010', value: 1335 }] */
  awardsByDecade: Ranked[];
  /** A leggyakoribb díjak, csökkenő sorrendben. Példa: [{ label: 'Kossuth-díj', value: 215 }] */
  topAwards: Ranked[];
  /** Az iskolák, ahol a legtöbb alkotó tanult. Példa: [{ label: 'Liszt Ferenc Zeneművészeti Főiskola', value: 65 }] */
  schools: Ranked[];
};

/**
 * GET statControl/getWorks
 * „A művek közelről” blokk és a videók számai.
 */
export type WorkStatistics = {
  /** Példa: '2026-10-30' */
  generatedAt: string;
  sizes: {
    /** Az ismert méretű művek száma. Példa: 5355 */
    count: number;
    /** A szélesség mediánja, cm. Példa: 64 */
    medianWidth: number;
    /** A magasság mediánja, cm. Példa: 60 */
    medianHeight: number;
    /** Tájolás szerinti megoszlás. Példa: [{ label: 'fekvő', value: 2657 }, { label: 'álló', value: 2139 }] */
    orientation: Ranked[];
    /** A legnagyobb művek, cm-ben. Példa: [{ title: 'Okos táj', width: 1680, height: 570 }] */
    largest: { title: string; width: number; height: number }[];
  };
  architecture: {
    /**
     * Megvalósult és tervben maradt épületek funkció szerint. A kód a 'középület' és a 'lakóépület'
     * címkére keres. Példa: [{ label: 'középület', built: 1335, planned: 1058 }]
     */
    byFunction: { label: string; built: number; planned: number }[];
    /** Ugyanez évtizedenként. Példa: [{ label: '1950', built: 64, planned: 38 }] */
    byDecade: { label: string; built: number; planned: number }[];
  };
  /** A legtöbbször megformált szerepek. Példa: [{ label: 'Tosca', value: 34 }] */
  playedRoles: Ranked[];
  /** A legtöbbször színre vitt művek. Példa: [{ label: 'Tosca', value: 59, branch: 'Színházművészet' }] */
  stagedWorks: (Ranked & { branch: string })[];
  videos: {
    /** Az összes videó. Példa: 1359 */
    total: number;
    /** Videók típus szerint. A kód az 'alkotásvideó' címkére keres. Példa: [{ label: 'alkotásvideó', value: 496 }] */
    types: Ranked[];
    /** A „Hogyan készült?” beszélgetések száma. Példa: 449 */
    conversations: number;
    /** A beszélgetésekben szereplő alkotások száma. Példa: 464 */
    creations: number;
    /** A beszélgetésekben szereplő alkotók száma. Példa: 36 */
    creators: number;
    /** A felvételek havonta, időrendben; az első és utolsó hónap kerül a szövegbe. Példa: [{ month: '2024-01', value: 2 }] */
    recordingsByMonth: { month: string; value: number }[];
  };
};

/**
 * GET statControl/getPrograms
 * A „Ma” blokk. Program: publikált kulturális entitás, amely nem alkotáshoz és nem eseményhez tartozik.
 * Ezek a számok avulnak a leggyorsabban, ezért ezt a végpontot lenne érdemes elsőként elkészíteni.
 */
export type ProgramStatistics = {
  /** Példa: '2026-10-30' */
  generatedAt: string;
  /** Az összes program. Példa: 1789 */
  total: number;
  /** A programnaptár első hónapja. Példa: '2025-07' */
  firstMonth: string;
  /** Programok havonta, időrendben. Példa: [{ month: '2025-07', value: 65 }] */
  calendar: { month: string; value: number }[];
  /** Programok a hét napjai szerint, hétfőtől vasárnapig. Példa: [{ label: 'hétfő', value: 126 }] */
  weekdays: Ranked[];
  /** A kezdési órák, a `grid` oszlopai. Példa: [9, 10, 11, ..., 22] */
  hours: number[];
  /**
   * Programok napok és kezdési órák szerint; a `counts` az `hours` sorrendjét követi.
   * Példa: [{ label: 'hétfő', counts: [2, 2, 5, 0, 2, 3, 3, 4, 15, 36, 46, 3, 1, 1] }]
   */
  grid: { label: string; counts: number[] }[];
  creators: {
    /** Az élő alkotók száma. Példa: 334 */
    alive: number;
    /** Az élő alkotók közül hánynak volt legalább egy programja. Példa: 281 */
    aliveWithProgram: number;
    /** A legtöbb programban szereplő élő alkotók, csökkenő sorrendben, legalább 10 fő. */
    top: CreatorCount[];
  };
  legacy: {
    /** Hány elhunyt alkotóhoz kötődik program. Példa: 73 */
    creators: number;
    /** Hány program kötődik elhunyt alkotóhoz. Példa: 230 */
    programs: number;
    /** A legtöbb programhoz kötődő elhunyt alkotók, csökkenő sorrendben, legalább 10 fő. */
    top: CreatorCount[];
  };
};

