> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Spécifications d'ingestion — anatomie

> La structure complète d'une spécification d'ingestion : comment un fichier circule dans la détection, l'analyse et la promotion, ainsi que la portée, la priorité et la versioning.

Une **spécification d'ingestion** est le contrat complet qui transforme un fichier entrant en lignes dans le modèle analytique de Solya. Cette référence en documente chaque partie. Pour l'introduction orientée utilisateur, voir le [guide de couche données](/fr/data-layer/ingestion-spec).

## Comment un fichier circule dans une spécification

<Steps>
  <Step title="Détection">
    Solya décide **quelle spécification** s'applique à un fichier entrant, en utilisant les
    [règles de détection](/fr/developers/ingestion-specs/detection) de la spécification.
  </Step>

  <Step title="Analyse">
    Le fichier est lu sous forme tabulaire et ses colonnes sont mappées à des champs typés, en
    utilisant la [configuration d'analyse](/fr/developers/ingestion-specs/parsing).
  </Step>

  <Step title="Promotion">
    Un ou plusieurs [pipelines de promotion](/fr/developers/ingestion-specs/promotion-steps)
    transforment les données analysées et les écrivent dans les tables silver/gold.
  </Step>
</Steps>

```mermaid theme={null}
flowchart TB
  file["Fichier entrant"]
  det["Configuration de<br/>détection<br/>(règles d'appairage)"]
  parse["Configuration<br/>d'analyse<br/>(mapping de champs)"]
  promo["Promotions<br/>(tableau de pipelines)"]
  silver["Tables Silver"]
  gold["Tables Gold"]
  
  file --> det
  det --> parse
  parse --> promo
  promo --> silver
  promo --> gold
```

## Forme de premier niveau

Une spécification est rédigée en JSON (clés en snake\_case). Ses champs :

| Champ             | Requis       | Description                                                                                                       |
| ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------- |
| `spec_id`         | ✓            | Identifiant canonique, stable entre les versions (ex. `polaris_sav`, `ginkoia_tickets`).                          |
| `spec_version`    | ✓            | Numéro de version monotone. Unique par `(spec_id, spec_version)`.                                                 |
| `name`            | –            | Nom d'affichage.                                                                                                  |
| `description`     | –            | À quoi sert la spécification.                                                                                     |
| `pos_system`      | –            | Identifiant du système source (ex. `polaris`, `ginkoia`).                                                         |
| `status`          | ✓            | `DRAFT` · `ACTIVE` · `DEPRECATED` · `ARCHIVED`.                                                                   |
| `scope`           | ✓            | `GLOBAL` (seeds de la plateforme, partagée) ou `ORG` (possédée par l'organisation).                               |
| `organization_id` | conditionnel | Requis pour la portée `ORG` ; null pour `GLOBAL`.                                                                 |
| `is_default`      | ✓            | Indique si c'est la spécification par défaut pour son `pos_system` + `scope`.                                     |
| `priority`        | ✓            | Brise-égalité quand plusieurs spécifications correspondent (plus haut gagne). Par défaut `0`.                     |
| `detection`       | ✓            | La [configuration de détection](/fr/developers/ingestion-specs/detection).                                        |
| `parsing`         | ✓            | La [configuration d'analyse](/fr/developers/ingestion-specs/parsing).                                             |
| `promotions`      | –            | Un tableau de [pipelines de promotion](/fr/developers/ingestion-specs/promotion-steps), un par dataset de sortie. |
| `promotion`       | –            | Forme de promotion unique dépréciée ; utiliser `promotions`.                                                      |
| `tags`            | ✓            | `{ "systems": [...], "formats": [...] }` pour le filtrage UI.                                                     |

```json theme={null}
{
  "spec_id": "ginkoia_tickets",
  "spec_version": 2,
  "name": "Ginkoia — Tickets",
  "pos_system": "ginkoia",
  "status": "ACTIVE",
  "scope": "GLOBAL",
  "is_default": true,
  "priority": 0,
  "detection": { "match_mode": "composite", "rules": [ /* … */ ] },
  "parsing":   { "parser": { /* … */ }, "mapping": { /* … */ } },
  "promotions": [ { /* … */ } ],
  "tags": { "systems": ["ginkoia"], "formats": ["excel"] }
}
```

## Portée : GLOBAL vs ORG

* Les spécifications **GLOBAL** sont fournies par la plateforme et disponibles pour chaque organisation. Elles couvrent les formats POS standards (Polaris, Ginkoia, Kezia, …).
* Les spécifications **ORG** appartiennent à une seule organisation (`organization_id` défini) et ne sont visibles que pour elle.

## Déploiement

L'existence n'est pas la même que l'activation pour une organisation. Une spécification est **déployée** vers une organisation via un enregistrement d'activation (flag `enabled`) — ainsi une organisation peut activer/désactiver les spécifications sans que personne n'édite la spécification elle-même. Dans l'API/DTO cela apparaît comme `isDeployed` sur chaque spécification.

## Priorité et résolution de conflits

Quand plus d'une spécification correspond à un fichier :

1. Les spécifications sont classées par **`priority`** (décroissant).
2. La **`spec_version`** plus récente prend préséance.
3. La **première spécification correspondante** est appliquée.

## Cycle de vie et versioning

```
DRAFT → ACTIVE ⇄ DEPRECATED → ARCHIVED
```

* Un `spec_id` peut avoir **plusieurs versions** ; `(spec_id, spec_version)` est unique.
* Le seeding est **idempotent** (upsert sur cette paire) ; les spécifications GLOBAL supprimées de l'ensemble de seeds sont **archivées**, non supprimées, pour préserver l'historique.

```mermaid theme={null}
stateDiagram-v2
  [*] --> DRAFT
  DRAFT --> ACTIVE
  ACTIVE --> DEPRECATED
  DEPRECATED --> ACTIVE
  DEPRECATED --> ARCHIVED
  ARCHIVED --> [*]
```

<Note>
  Continuez vers les trois éléments constitutifs :
  [Détection](/fr/developers/ingestion-specs/detection),
  [Analyse](/fr/developers/ingestion-specs/parsing), et le
  catalogue [Étapes de promotion](/fr/developers/ingestion-specs/promotion-steps) — puis voir
  les [exemples](/fr/developers/ingestion-specs/examples) complets.
</Note>