# Reference KPI Aggregation Rules

Regles d aggregation KPI pour comparer les territoires vin/oenotourisme sans melanger mailles, temporalites, denominateurs ou niveaux de preuve.

## Mailles territoire

### Commune
- Cles : insee_code, postal_code_fallback
- Usage : Cartes, preuves locales, capacite Insee, surfaces bio, BAN.
- Risque : Petits volumes, secret statistique, faux sentiment de precision.
- Regle copy : Afficher comme maille fine ; ne pas extrapoler a une appellation sans mapping explicite.

### Appellation
- Cles : inao_product_id, appellation_name, insee_code_bridge
- Usage : Preuves vin, score reference, SIQO, eAmbrosia, recit viticole.
- Risque : Perimetres reglementaires et communes non equivalentes aux flux touristiques.
- Regle copy : Toujours citer la preuve INAO/eAmbrosia et expliquer le bridge commune.

### Destination oenotouristique
- Cles : destination_label, vignobles_decouvertes_area, commune_set
- Usage : Deck partenaire, oenotourisme, offre + demande, labels et experience visiteur.
- Risque : Perimetre marketing variable et non toujours administratif.
- Regle copy : Publier la liste des communes ou le perimetre source de la destination.

### EPCI / departement / region
- Cles : epci_code, department_code, region_code
- Usage : Benchmarks, Insee, Agreste, Agence Bio, donnees a maille large.
- Risque : Dilution des signaux vin dans un territoire touristique large.
- Regle copy : Preciser que le niveau administratif contextualise le territoire viticole.

### Territoire custom
- Cles : territory_id, commune_set, source_contract
- Usage : Clients, destinations non standard, zones commerciales, data room.
- Risque : Comparaisons impossibles si le perimetre n est pas versionne.
- Regle copy : Versionner le territoire, ses communes, la date et le responsable de validation.

## Regles

### Denominateur constant
- Cle : `same_denominator`
- Regle : Comparer des taux seulement si le denominateur est identique ou explicitement normalise.
- KPI : wine_offer_density, organic_operator_density, geocoded_rate, quality_reception_signal
- Caveat : Taux normalise sur le meme perimetre et la meme famille de sources.

### Granularite source
- Cle : `source_granularity_guard`
- Regle : Ne pas descendre une source region/departement au niveau commune sans l afficher comme contexte.
- KPI : tourism_demand_signal, bulk_price_context, production_context, land_value_context
- Caveat : Contexte a maille large, non attribuable directement au territoire fin.

### Agregat avant nominatif
- Cle : `privacy_first`
- Regle : Pour Sirene, HVE, Agence Bio et listings etablissements, publier d abord des agregats puis relire le nominatif.
- KPI : wine_business_density_score, organic_wine_sustainability_score, map_publication_readiness
- Caveat : Les listings nominatifs restent internes tant que RGPD/metier/source gate ne sont pas passes.

### Fenetre temporelle alignee
- Cle : `time_window_alignment`
- Regle : Comparer des territoires sur la meme periode ou afficher les millesimes distincts.
- KPI : tourism_demand_signal, surface_bio_total_ha, hve_wine_related_density, supply_market_context_score
- Caveat : Les millesimes source peuvent differer ; lire comme tendance ou contexte si non alignes.

### Plafond pipeline
- Cle : `pipeline_cap`
- Regle : Un score dont un composant cle reste metadata_only ou non normalise ne doit pas etre presente comme live.
- KPI : territory_reference_score, oenotourism_readiness_score, organic_wine_sustainability_score
- Caveat : Score partiel : composants prets visibles, reste en pipeline.

## Recettes aggregation

### Sommer les volumes
- Methode : Somme apres dedoublonnage des cles source au niveau territorial choisi.
- Metriques : operator_count, offer_count, surface_bio_total_ha, bed_capacity
- Eviter : Ne pas sommer des taux, scores ou indices deja normalises.

### Moyenne ponderee
- Methode : Ponderer par volume pertinent : capacite, nombre d etablissements, surface ou observations.
- Metriques : occupancy_rate, quality_score, address_score
- Eviter : Ne pas ponderer par une source sans lien avec le KPI.

### Max pour gate bloquant
- Methode : Un seul blocage fort peut bloquer la publication externe du territoire.
- Metriques : publication_blocker, privacy_risk, source_gap
- Eviter : Ne pas moyenner un risque de publication.

### Minimum de confiance
- Methode : Le score final ne depasse pas le composant de confiance le plus faible si celui-ci est critique.
- Metriques : source_fidelity, map_readiness, citation_quality
- Eviter : Ne pas masquer une source faible par un score visuel eleve.