# Phase 1C — Provenance, confiance, conflits et historique

Version : 0.3.0

## Objectif

Cette phase sépare définitivement les **valeurs trouvées par les fournisseurs** des **valeurs canoniques utilisées par Coaster World**.

Un fournisseur, une page web ou plus tard un agent IA peut proposer une valeur. Cette proposition est conservée avec sa provenance et son niveau de confiance, mais elle ne modifie jamais directement la fiche canonique.

Le cycle devient :

`source → observation → comparaison → conflit éventuel → sélection canonique → historique`

## Tables ajoutées

### `data_observations`

Journal des valeurs collectées pour un champ précis d'une entité.

Chaque observation conserve notamment :

- l'entité concernée ;
- le champ (`field_key`) ;
- le provider ;
- la source concrète ;
- la valeur brute ;
- la valeur normalisée ;
- une empreinte SHA-256 de la valeur normalisée ;
- un score de confiance de 0 à 100 ;
- la date déclarée par la source si elle existe ;
- la date de récupération ;
- le statut courant, remplacé ou rejeté ;
- des métadonnées facultatives.

Lorsqu'une même source fournit une nouvelle valeur pour le même champ, son ancienne observation devient `superseded` au lieu d'être supprimée.

### `canonical_values`

Conserve la valeur actuellement retenue par Coaster World et sa provenance de décision.

Une valeur canonique peut :

- provenir d'une observation sélectionnée ;
- être corrigée manuellement ;
- conserver son score de confiance ;
- être marquée comme vérifiée manuellement.

Pour les champs structurés déjà présents dans les tables principales (`opened_year`, `height_m`, etc.), la sélection canonique synchronise également la colonne correspondante afin de conserver des lectures API rapides.

Les champs qui n'existent pas encore comme colonne structurée peuvent quand même être conservés dans `canonical_values`. Leur formalisation complète sera traitée dans la Phase 1D.

### `data_conflicts`

Un conflit apparaît lorsque plusieurs observations **courantes** proposent des valeurs normalisées différentes pour le même champ.

La table conserve :

- l'entité et le champ ;
- le nombre de valeurs différentes ;
- l'état `open` ou `resolved` ;
- l'observation retenue le cas échéant ;
- les dates de détection et résolution ;
- le mode de résolution ;
- un compteur de réouverture.

Un conflit peut se résoudre automatiquement si les sources convergent ensuite vers la même valeur.

Une résolution humaine reste mémorisée tant que l'ensemble des valeurs contradictoires ne change pas. Une nouvelle contradiction peut rouvrir le conflit.

### `canonical_value_history`

Historique immuable des changements de valeur canonique.

Il conserve l'ancienne et la nouvelle valeur, les observations associées, les scores de confiance, le motif du changement et, lorsqu'il existe, l'utilisateur ayant effectué la validation.

## Service `DataReliabilityService`

Le service fournit quatre opérations centrales :

- `recordObservation()` : enregistre une proposition sans toucher à la donnée finale ;
- `promoteObservation()` : sélectionne explicitement une observation comme valeur canonique ;
- `setManualCanonicalValue()` : applique une correction humaine ;
- `rejectObservation()` : rejette une observation qui ne doit plus participer aux comparaisons.

### Règle fondamentale

`recordObservation()` ne modifie jamais les colonnes canoniques d'un parc, coaster, attraction, POI, zone ou organisation.

Une écriture canonique nécessite une action explicite de sélection ou de correction. Plus tard, cette action pourra être déclenchée automatiquement par un moteur de règles uniquement lorsque les conditions de confiance le permettent.

## Score de confiance

Le score est stocké de `0` à `100`.

Cette phase ne décide volontairement pas encore qu'une valeur à 90 est automatiquement meilleure qu'une valeur à 80. Les règles de priorité par type de donnée, fournisseur et contexte seront ajoutées au-dessus de ce socle afin de ne pas cacher des décisions arbitraires dans le schéma.

## Entités couvertes

La provenance et les conflits sont disponibles pour :

- parcs / resorts ;
- zones ;
- attractions ;
- coasters ;
- POI ;
- organisations.

## Hors périmètre de cette phase

- interface web de validation ;
- calcul automatique avancé de confiance ;
- règles de priorité champ par champ ;
- définition dynamique des nouveaux champs ;
- traductions et alias ;
- connecteurs fournisseurs réels ;
- IA ;
- API publique ;
- temps d'attente Live.