{
    "ok": true,
    "generated_at": "2026-07-07T22:10:10+00:00",
    "summary": "Regles d aggregation KPI pour comparer les territoires vin/oenotourisme sans melanger mailles, temporalites, denominateurs ou niveaux de preuve.",
    "territory_level_count": 5,
    "rule_count": 5,
    "recipe_count": 4,
    "territory_levels": [
        {
            "key": "commune",
            "label": "Commune",
            "join_keys": [
                "insee_code",
                "postal_code_fallback"
            ],
            "best_for": "Cartes, preuves locales, capacite Insee, surfaces bio, BAN.",
            "risk": "Petits volumes, secret statistique, faux sentiment de precision.",
            "copy_rule": "Afficher comme maille fine ; ne pas extrapoler a une appellation sans mapping explicite."
        },
        {
            "key": "appellation",
            "label": "Appellation",
            "join_keys": [
                "inao_product_id",
                "appellation_name",
                "insee_code_bridge"
            ],
            "best_for": "Preuves vin, score reference, SIQO, eAmbrosia, recit viticole.",
            "risk": "Perimetres reglementaires et communes non equivalentes aux flux touristiques.",
            "copy_rule": "Toujours citer la preuve INAO/eAmbrosia et expliquer le bridge commune."
        },
        {
            "key": "destination",
            "label": "Destination oenotouristique",
            "join_keys": [
                "destination_label",
                "vignobles_decouvertes_area",
                "commune_set"
            ],
            "best_for": "Deck partenaire, oenotourisme, offre + demande, labels et experience visiteur.",
            "risk": "Perimetre marketing variable et non toujours administratif.",
            "copy_rule": "Publier la liste des communes ou le perimetre source de la destination."
        },
        {
            "key": "epci_department_region",
            "label": "EPCI / departement / region",
            "join_keys": [
                "epci_code",
                "department_code",
                "region_code"
            ],
            "best_for": "Benchmarks, Insee, Agreste, Agence Bio, donnees a maille large.",
            "risk": "Dilution des signaux vin dans un territoire touristique large.",
            "copy_rule": "Preciser que le niveau administratif contextualise le territoire viticole."
        },
        {
            "key": "custom_territory",
            "label": "Territoire custom",
            "join_keys": [
                "territory_id",
                "commune_set",
                "source_contract"
            ],
            "best_for": "Clients, destinations non standard, zones commerciales, data room.",
            "risk": "Comparaisons impossibles si le perimetre n est pas versionne.",
            "copy_rule": "Versionner le territoire, ses communes, la date et le responsable de validation."
        }
    ],
    "rules": [
        {
            "key": "same_denominator",
            "label": "Denominateur constant",
            "rule": "Comparer des taux seulement si le denominateur est identique ou explicitement normalise.",
            "applies_to": [
                "wine_offer_density",
                "organic_operator_density",
                "geocoded_rate",
                "quality_reception_signal"
            ],
            "copy_caveat": "Taux normalise sur le meme perimetre et la meme famille de sources."
        },
        {
            "key": "source_granularity_guard",
            "label": "Granularite source",
            "rule": "Ne pas descendre une source region/departement au niveau commune sans l afficher comme contexte.",
            "applies_to": [
                "tourism_demand_signal",
                "bulk_price_context",
                "production_context",
                "land_value_context"
            ],
            "copy_caveat": "Contexte a maille large, non attribuable directement au territoire fin."
        },
        {
            "key": "privacy_first",
            "label": "Agregat avant nominatif",
            "rule": "Pour Sirene, HVE, Agence Bio et listings etablissements, publier d abord des agregats puis relire le nominatif.",
            "applies_to": [
                "wine_business_density_score",
                "organic_wine_sustainability_score",
                "map_publication_readiness"
            ],
            "copy_caveat": "Les listings nominatifs restent internes tant que RGPD/metier/source gate ne sont pas passes."
        },
        {
            "key": "time_window_alignment",
            "label": "Fenetre temporelle alignee",
            "rule": "Comparer des territoires sur la meme periode ou afficher les millesimes distincts.",
            "applies_to": [
                "tourism_demand_signal",
                "surface_bio_total_ha",
                "hve_wine_related_density",
                "supply_market_context_score"
            ],
            "copy_caveat": "Les millesimes source peuvent differer ; lire comme tendance ou contexte si non alignes."
        },
        {
            "key": "pipeline_cap",
            "label": "Plafond pipeline",
            "rule": "Un score dont un composant cle reste metadata_only ou non normalise ne doit pas etre presente comme live.",
            "applies_to": [
                "territory_reference_score",
                "oenotourism_readiness_score",
                "organic_wine_sustainability_score"
            ],
            "copy_caveat": "Score partiel : composants prets visibles, reste en pipeline."
        }
    ],
    "recipes": [
        {
            "key": "sum_when_volume",
            "label": "Sommer les volumes",
            "metrics": [
                "operator_count",
                "offer_count",
                "surface_bio_total_ha",
                "bed_capacity"
            ],
            "method": "Somme apres dedoublonnage des cles source au niveau territorial choisi.",
            "avoid": "Ne pas sommer des taux, scores ou indices deja normalises."
        },
        {
            "key": "weighted_average",
            "label": "Moyenne ponderee",
            "metrics": [
                "occupancy_rate",
                "quality_score",
                "address_score"
            ],
            "method": "Ponderer par volume pertinent : capacite, nombre d etablissements, surface ou observations.",
            "avoid": "Ne pas ponderer par une source sans lien avec le KPI."
        },
        {
            "key": "max_for_gate",
            "label": "Max pour gate bloquant",
            "metrics": [
                "publication_blocker",
                "privacy_risk",
                "source_gap"
            ],
            "method": "Un seul blocage fort peut bloquer la publication externe du territoire.",
            "avoid": "Ne pas moyenner un risque de publication."
        },
        {
            "key": "confidence_minimum",
            "label": "Minimum de confiance",
            "metrics": [
                "source_fidelity",
                "map_readiness",
                "citation_quality"
            ],
            "method": "Le score final ne depasse pas le composant de confiance le plus faible si celui-ci est critique.",
            "avoid": "Ne pas masquer une source faible par un score visuel eleve."
        }
    ],
    "copy_markdown": "# Reference KPI Aggregation Rules\n\nRegles d aggregation KPI pour comparer les territoires vin/oenotourisme sans melanger mailles, temporalites, denominateurs ou niveaux de preuve.\n\n## Mailles territoire\n\n### Commune\n- Cles : insee_code, postal_code_fallback\n- Usage : Cartes, preuves locales, capacite Insee, surfaces bio, BAN.\n- Risque : Petits volumes, secret statistique, faux sentiment de precision.\n- Regle copy : Afficher comme maille fine ; ne pas extrapoler a une appellation sans mapping explicite.\n\n### Appellation\n- Cles : inao_product_id, appellation_name, insee_code_bridge\n- Usage : Preuves vin, score reference, SIQO, eAmbrosia, recit viticole.\n- Risque : Perimetres reglementaires et communes non equivalentes aux flux touristiques.\n- Regle copy : Toujours citer la preuve INAO/eAmbrosia et expliquer le bridge commune.\n\n### Destination oenotouristique\n- Cles : destination_label, vignobles_decouvertes_area, commune_set\n- Usage : Deck partenaire, oenotourisme, offre + demande, labels et experience visiteur.\n- Risque : Perimetre marketing variable et non toujours administratif.\n- Regle copy : Publier la liste des communes ou le perimetre source de la destination.\n\n### EPCI / departement / region\n- Cles : epci_code, department_code, region_code\n- Usage : Benchmarks, Insee, Agreste, Agence Bio, donnees a maille large.\n- Risque : Dilution des signaux vin dans un territoire touristique large.\n- Regle copy : Preciser que le niveau administratif contextualise le territoire viticole.\n\n### Territoire custom\n- Cles : territory_id, commune_set, source_contract\n- Usage : Clients, destinations non standard, zones commerciales, data room.\n- Risque : Comparaisons impossibles si le perimetre n est pas versionne.\n- Regle copy : Versionner le territoire, ses communes, la date et le responsable de validation.\n\n## Regles\n\n### Denominateur constant\n- Cle : `same_denominator`\n- Regle : Comparer des taux seulement si le denominateur est identique ou explicitement normalise.\n- KPI : wine_offer_density, organic_operator_density, geocoded_rate, quality_reception_signal\n- Caveat : Taux normalise sur le meme perimetre et la meme famille de sources.\n\n### Granularite source\n- Cle : `source_granularity_guard`\n- Regle : Ne pas descendre une source region/departement au niveau commune sans l afficher comme contexte.\n- KPI : tourism_demand_signal, bulk_price_context, production_context, land_value_context\n- Caveat : Contexte a maille large, non attribuable directement au territoire fin.\n\n### Agregat avant nominatif\n- Cle : `privacy_first`\n- Regle : Pour Sirene, HVE, Agence Bio et listings etablissements, publier d abord des agregats puis relire le nominatif.\n- KPI : wine_business_density_score, organic_wine_sustainability_score, map_publication_readiness\n- Caveat : Les listings nominatifs restent internes tant que RGPD/metier/source gate ne sont pas passes.\n\n### Fenetre temporelle alignee\n- Cle : `time_window_alignment`\n- Regle : Comparer des territoires sur la meme periode ou afficher les millesimes distincts.\n- KPI : tourism_demand_signal, surface_bio_total_ha, hve_wine_related_density, supply_market_context_score\n- Caveat : Les millesimes source peuvent differer ; lire comme tendance ou contexte si non alignes.\n\n### Plafond pipeline\n- Cle : `pipeline_cap`\n- Regle : Un score dont un composant cle reste metadata_only ou non normalise ne doit pas etre presente comme live.\n- KPI : territory_reference_score, oenotourism_readiness_score, organic_wine_sustainability_score\n- Caveat : Score partiel : composants prets visibles, reste en pipeline.\n\n## Recettes aggregation\n\n### Sommer les volumes\n- Methode : Somme apres dedoublonnage des cles source au niveau territorial choisi.\n- Metriques : operator_count, offer_count, surface_bio_total_ha, bed_capacity\n- Eviter : Ne pas sommer des taux, scores ou indices deja normalises.\n\n### Moyenne ponderee\n- Methode : Ponderer par volume pertinent : capacite, nombre d etablissements, surface ou observations.\n- Metriques : occupancy_rate, quality_score, address_score\n- Eviter : Ne pas ponderer par une source sans lien avec le KPI.\n\n### Max pour gate bloquant\n- Methode : Un seul blocage fort peut bloquer la publication externe du territoire.\n- Metriques : publication_blocker, privacy_risk, source_gap\n- Eviter : Ne pas moyenner un risque de publication.\n\n### Minimum de confiance\n- Methode : Le score final ne depasse pas le composant de confiance le plus faible si celui-ci est critique.\n- Metriques : source_fidelity, map_readiness, citation_quality\n- Eviter : Ne pas masquer une source faible par un score visuel eleve.\n"
}