france-data-mcp: Skill for Claude Code

Ingestion (crons GitHub Actions)

Déplacé verbatim depuis CLAUDE.md le 2026-09-06 (budget). Source de vérité pour ce périmètre ; CLAUDE.md ne garde que les règles de tête.

3 sources : FINESS (flux ANS JSON.gz quotidien, cron le 1er et le 15, ~105K), Ameli (hebdo, ~466K), RPPS (mensuel, ~2.28M). Pattern : download → SHA256 short-circuit si identique → COPY staging → validate → atomic swap → canary → ingest_log.

FINESS vient de l'ANS depuis 2026-09-05, plus du CSV DREES (flux arrêté le 2026-07-20 ; le cron a court-circuité en same_checksum/success quatre mois sans signal — d'où last_data_change_at/data_age_days dans data_freshness). Source de vérité : docs/plans/finess-migration-ans.md. Les trois pièges qui ont failli passer en silence, tous testés sur fixtures réelles (finess-ans-parse.test.ts) : (1) adresse géographique = usageAdresse "03", JAMAIS adresse[0] (2 294 EGE ont l'accueil devant) ; (2) deux paires de coordonnées dont le système WGS84/Lambert 93 s'inverse d'un enregistrement à l'autre → resolveCoordinates détecte par plage de valeurs ; (3) seulement 74,9 % des EGE ont des coordonnées → repli previous_ingest (point de la prod par num_finess, tracé raw.geom_source), JAMAIS de centroïde commune dans finess.geom (le RPPS le recopierait en finess_join = tier précis). Parsing en flux obligatoire (715 Mo > limite de chaîne V8). Un débordement de colonne = null compté, jamais tronqué (un téléphone à deux numéros a fait échouer le premier dry-run ; parité DDL↔COLUMN_RULES testée). Les seuils qui décident du swap vivent dans finess-validate.ts (pur, testé sur les chiffres mesurés) — ne pas les réinliner dans main(). FINESS_DRY_RUN=1 = pipeline complet sans swap, staging conservée ; FORCE_REINGEST=1 bypass le checksum.

Service client typage : pour toute RPC ajoutée par migration récente, utiliser getUntypedServiceClient(source) (sinon tsc -p tsconfig.api.json échoue, types Supabase pas regénérés).

Canal d'apply des migrations en prod (V0.20+, débloqué) : MCP Supabase mcp__supabase_france_data__apply_migration({name, query}) — Claude apply directement depuis la session, sans intervention humaine, avec tracking propre dans supabase_migrations.schema_migrations. Workflow validé V0.20 : list_migrations (état) → execute_sql pg_proc (idempotence) → apply_migration({name: snake_case, query: SQL complet}) → execute_sql (tests fonctionnels : signature + appels réels + edge cases) → push code + tag. Le canal CLI supabase db push reste cassé (pattern CLI exige YYYYMMDDHHMMSS_ sans T, le repo a 52 migrations format T) — le MCP contourne en passant directement la chaîne SQL. L'auto-apply via GitHub Actions reste parqué (mémoire migration-autoapply-deferred partiellement obsolète — MCP en supersede pour les sessions Claude). Fallback dashboard SQL editor manuel (https://supabase.com/dashboard/project/_/sql/new) toujours valide si le MCP Supabase est down/non configuré. Le retry défensif PGRST204_RECOVERABLE_FIELDS protège la fenêtre transitoire push code ↔ apply migration (cf. ci-dessous).

Marqueur forced dans ingest_log (V0.12.2) : un run déclenché via FORCE_REINGEST=1 (workflow_dispatch) est marqué forced=true par shortCircuitIfSameChecksum(..., force=true) (chokepoint unique). Audit : SELECT * FROM ingest_log WHERE forced=true. Distingue un run ops manuel d'un cron normal — sinon perdu en audit quand checksums identiques.

Convention PGRST204_RECOVERABLE_FIELDS (V0.12.2) : writeIngestLog retry défensif si PGRST204 sur un champ optionnel récent (fenêtre transitoire push code ↔ apply migration). Tout nouvel ajout de champ optionnel dans IngestLogEntry DOIT être listé dans PGRST204_RECOVERABLE_FIELDS (scripts/ingest/shared.ts) jusqu'à propagation de la migration en prod, puis peut être retiré. Sans cet allow-list, un PGRST204 perdrait silencieusement TOUTE l'entrée ingest_log du run (classe close en V0.12.2). Best-effort doc : appliquer la migration AVANT de déployer le code.