from __future__ import annotations

from typing import Any


def sources_catalog() -> list[dict[str, Any]]:
    """Catalog of public sources prepared for the prototype.

    The application uses this catalog both for documentation and for the
    /api/open-data/sources endpoint. It is deliberately explicit about the
    recommended strategy: live calls only for light referentials, cache for
    statistics and large files.
    """

    return [
        {
            "id": "api_geo",
            "label": "API Geo - decoupage administratif",
            "scope": "Communes, EPCI, departements, regions",
            "use_for": ["territoires", "communes_aula", "rattachement_commune_epci"],
            "strategy": "live_or_cache",
            "cache_file": "data/cache/aula_scope.json",
            "base_url": "https://geo.api.gouv.fr",
            "needs_token": False,
            "status": "implemented",
        },
        {
            "id": "conso_enaf",
            "label": "Consommation ENAF 2009-2024 - Portail national artificialisation / data.gouv",
            "scope": "Commune, carreau 1 km, pas annuel",
            "use_for": ["consommation_fonciere", "zan", "trajectoire"],
            "strategy": "metadata_api_then_cached_file",
            "cache_file": "data/cache/conso_enaf_metadata.json",
            "dataset_slug": "consommation-despaces-naturels-agricoles-et-forestiers-du-1er-janvier-2009-au-1er-janvier-2024",
            "needs_token": False,
            "status": "implemented_metadata_ready",
        },
        {
            "id": "sitadel",
            "label": "SDES Sitadel - autorisations d'urbanisme",
            "scope": "Logements, locaux, permis, declarations, depuis 2013",
            "use_for": ["logements_autorises", "logements_commences", "dynamique_construction"],
            "strategy": "dido_api_or_cached_exports",
            "cache_file": "data/cache/sitadel_metadata.json",
            "needs_token": False,
            "status": "connector_skeleton",
            "note": "Configurer les identifiants Dido ou les URLs de fichiers dans .env apres choix des tables.",
        },
        {
            "id": "insee",
            "label": "INSEE API Melodi / donnees locales",
            "scope": "Population, ages, menages, naissances, revenus selon cubes disponibles",
            "use_for": ["population", "menages", "classes_age", "naissances", "revenus"],
            "strategy": "api_with_cache",
            "cache_file": "data/cache/insee_metadata.json",
            "needs_token": True,
            "status": "connector_skeleton",
            "note": "Les API INSEE demandent une souscription selon le service. Le code prepare la couche cache et normalisation.",
        },
        {
            "id": "georisques",
            "label": "Georisques - API risques",
            "scope": "Risques naturels et technologiques, documents par commune selon endpoints",
            "use_for": ["risques", "ppri", "contraintes"],
            "strategy": "api_with_cache_then_local_spatial_crossing",
            "cache_file": "data/cache/georisques_metadata.json",
            "needs_token": False,
            "status": "connector_skeleton",
            "note": "Les metadonnees peuvent venir de l'API ; les croisements batiments/PPR restent a faire dans PostGIS.",
        },
        {
            "id": "depp",
            "label": "DEPP / data.gouv - effectifs scolaires",
            "scope": "Ecoles, niveaux, classes, annees scolaires",
            "use_for": ["socio_demo_optionnel", "observatoire_ecoles"],
            "strategy": "data_gouv_metadata_then_cached_file",
            "cache_file": "data/cache/depp_metadata.json",
            "needs_token": False,
            "status": "catalog_only",
        },
    ]