Skip to content

Latest commit

 

History

History
519 lines (477 loc) · 34.1 KB

CLAUDE.md

File metadata and controls

519 lines (477 loc) · 34.1 KB

Datan

Site de décryptage des votes de l'Assemblée nationale française. Ce dépôt est Datan, et sert https://datan.fr/ depuis la bascule du 16 novembre 2026. Il a pris la suite d'une application CodeIgniter 3, qui reste la référence fonctionnelle — quand une question se pose sur un comportement, la réponse est dans son code, pas dans une intuition. Ce code est l'étiquette Git legacy-codeigniter (git show legacy-codeigniter:application/…), et dort encore sur le serveur sous ~/public_html, avec sa base.

Toute page portée devait être visuellement identique au site d'origine et aussi rapide : ce sont les deux exigences sous lesquelles ce code a été écrit, et elles valent pour ce qui reste à porter. Le site d'origine n'étant plus en ligne, la comparaison se fait désormais à son code, pas à une page.

Identique ne veut pas dire miroir : parité sur ce qui est un choix, correction sur ce qui est un défaut. Un tri, une formulation, un seuil se reproduisent tels quels, même s'ils surprennent. Une coquille, un accord manqué, un lien vide, une ancre sans son décalage se corrigent — et le commentaire dit pourquoi, sinon le prochain lecteur croira à une erreur de portage.

TODO.md tient l'état du reste à faire, défauts ouverts compris — et rien d'autre. DIFFERENCES.md liste les écarts voulus avec le site d'origine : les lire avant de « corriger » une différence, et y consigner toute nouvelle.

Ce qui fait la valeur du site

Le décryptage des votes : une couche éditoriale écrite par la rédaction par-dessus les scrutins bruts (entités Decryptage, Categorie, Lecture). Elle n'est pas dérivée de l'open data et ne peut pas être régénérée — les décryptages déjà produits sont à préserver comme des données de production.

Conventions

  • Français partout : noms de commandes, de méthodes privées, de variables locales, commentaires, messages console. Les noms d'entités et de colonnes suivent le vocabulaire de l'Assemblée (scrutin, organe, mandat).

  • Pas d'ORM sur les pages de lecture. Les contrôleurs interrogent DBAL et rendent des tableaux associatifs. Aux volumes en jeu (1,2 M de votes), hydrater des entités coûte plusieurs ordres de grandeur. L'ORM sert au schéma et aux écritures unitaires.

  • Cache HTTP sur toute page publique : setPublic() + setSharedMaxAge(). Le reverse proxy intégré est branché dans public/index.php hors debug. Une page en cache doit sortir en ~20 ms. Deux sortes de pages, deux magasins (App\Http\MagasinDouble) :

    • vivante, un jour (RechauffeurCache::DUREE_PAGES) : la fraîcheur vient des purges, pas de l'expiration — après le sync quotidien, et après toute écriture d'un contenu publié (décryptage, explication, article), qui appelle RechauffeurCache::apresPublication(). Une nouvelle écriture éditoriale visible sur le site doit l'appeler aussi, sinon elle n'apparaît que le lendemain ;
    • figée, sans expiration (DUREE_FIGEE) : élections, communes, départements, parrainages, listes et groupes des législatures closes, anciens députés. Son magasin survit aux purges ordinaires ; il n'est vidé que lorsque App\Http\EmpreinteFigee — l'empreinte de tout ce que ces pages lisent — a changé à la fin d'un sync, ou par purger(tout: true).

    app:cache:rechauffer remet ensuite en cache les ~2 500 pages les plus lues ; --tout vide aussi les figées, à passer après une écriture à la main qui réécrit le passé sans purger elle-même. Un déploiement repart de deux magasins vides.

  • Ne poser DUREE_FIGEE que si tout ce que la page affiche est dans le périmètre d'EmpreinteFigee : ni scrutin, statistique ou classement de la législature en cours, ni rien qui dépende du jour du rendu (CURDATE(), date()), et toute écriture de la rédaction qui la touche passe apresPublication(tout: true). Une page figée à tort reste fausse sans une erreur jusqu'au déploiement suivant. Et ce qui a l'air figé ne l'est pas toujours : la page d'un scrutin de 2013 porte le carrousel des derniers décryptages, la page d'une élection de 2022 affiche le groupe d'aujourd'hui du candidat, les statistiques d'un groupe dissous se comparent à son héritier de la législature en cours. Lire le contrôleur et ses gabarits avant de figer ; une table nouvelle lue par une page figée entre dans l'empreinte. Celle-ci écarte l'âge et la commission d'un député, qui bougent presque chaque jour : une page qui les affiche ne se fige pas.

  • Une écriture répétée purge ses seules adresses. Relire cent résumés d'amendements ou renseigner cent fiches de réseaux sociaux viderait cent fois le site : ces deux écrans appellent RechauffeurCache::purgerAdresses(). C'est l'exception — partout ailleurs on purge tout, parce qu'énumérer les pages où paraît un décryptage est un contrat qu'on finit par oublier.

  • Une page n'annonce aucune durée au navigateur : sa copie ne se purge pas, et la navbar change à la connexion. Elle porte un ETag (App\Http\EmpreintePage) et se revalide en 304.

  • Un fichier de public/assets/ est immuable un an, parce qu'asset() ajoute à son adresse le condensat de son contenu (?v=…, App\Asset\VersionParContenu). Toujours passer par asset() ; un fichier cité en dur — l'url() d'une feuille de style — n'a pas de version et ne change donc pas de contenu sans changer de nom.

  • CSS et JS du site s'écrivent dans assets/ (styles/main.scss, scripts/), servis par AssetMapper sous /build/ ; public/assets/ ne porte que du tiers ou du binaire, sous des adresses figées. Compilation, CSS critique, pièges : README, « CSS et JavaScript ». Un changement de mise en page en haut de l'accueil, d'une ville ou d'un groupe appelle npm run critique.

  • Commentaires : expliquer pourquoi, pas quoi. Les pièges métier de ce domaine sont nombreux et non devinables — ce sont eux qu'il faut consigner.

  • Une entité #[ApiResource] s'expose en écriture par défaut. Sans operations:, API Platform ajoute POST, PATCH et DELETE, et n'exige aucune authentification. Notre API est publique en lecture seule : toute nouvelle entité exposée déclare operations: [new Get(), new GetCollection()]. Les écritures passent par l'espace de rédaction, le tableau de bord des députés ou les commandes d'import — jamais par /api.

Routage et adresses

  • Les URL du legacy sont un contrat. Elles sont indexées depuis des années ; Datan vit de son référencement. Une adresse ne change pas — et si notre donnée produit une autre forme, on redirige en 301 vers celle du site plutôt que de rendre un 404 (DepartementController::versLAdresseCanonique()).
  • Rien ne garantit l'ordre entre deux contrôleurs. Les routes viennent d'attributs, chargées fichier par fichier : une route large en attrape une précise déclarée ailleurs. Deux parades selon le cas — une contrainte d'exclusion (DepartementController::SLUG écarte legislature- et inactifs), ou priority: quand l'adresse précise appartient à un autre contrôleur (/statistiques/aide face à /statistiques/{page}, qui accepte [a-z\-]+ et l'avalerait). Le legacy règle les mêmes collisions par l'ordre de routes.php : sa lecture dit lesquelles existent.
  • Un sitemap n'annonce que ce qui répond 200. Promettre des 404 coûte plus que de se taire. Chaque liste de SitemapController reprend donc le critère de sélection de la page correspondante — et se vérifie en interrogeant réellement chaque adresse, pas en relisant la requête.
  • Deux jeux de slugs de département coexistent. depute.dpt_slug est fabriqué (nom + code) ; departement.slug vient de la table tenue à la main du legacy, et c'est lui l'adresse de datan.fr — francais-de-letranger, pas francais-etablis-hors-de-france-099. Cinq diffèrent. Bâtir un lien depuis dpt_slug sans vérifier expose à servir une adresse que la route refuse.

Imports

  • Toujours APP_ENV=prod. En dev, le logger Doctrine conserve chaque requête en mémoire et fait échouer tout import volumineux. La variable d'environnement seule ne suffit pas pour un serveur de test : il faut un .env.local temporaire, à supprimer ensuite.
  • Upsert par lots (INSERT … ON DUPLICATE KEY UPDATE), maps de correspondance via fetchAllKeyValue, lecture en flux.
  • Un upsert ne doit jamais écraser avec du vide. L'open data publie irrégulièrement : une colonne absente d'une moisson ne veut pas dire que l'information est fausse. Utiliser $misAJourSiRenseigne d' ImportTricoteusesCommand, qui traduit en COALESCE(VALUES(c), c). Exception : ce qu'on sait faux se purge avant d'apparier, sans quoi la garde protège l'erreur pour toujours.
  • Ne jamais lancer cache:clear pendant une synchronisation. Vider var/cache/prod sous une commande en cours la fait échouer sans message exploitable — code 1 muet, ou Failed opening required …Service.php. Le symptôme ne ressemble en rien à sa cause.
  • Lier un false PHP, c'est lier une chaîne vide. Le pilote mysqli ne connaît pas le booléen : MariaDB refuse alors la valeur dans une colonne entière (« Incorrect integer value: '' »). Passer des 0/1, et garder le null quand l'absence de valeur a un sens — un candidat dont on ignore encore s'il est élu n'est pas un candidat battu.
  • Compter les lignes écartées, et dire pourquoi. Un import qui lit trois millions de lignes et en écrit moins doit rendre l'écart à l'unité : sans ce bilan, une règle fausse ressemble en tout point à une source incomplète.
  • Un delta n'est consommé qu'une fois acquitté. .datan-acquitte désigne, dans chaque clone, le dernier commit importé par une chaîne app:sync:quotidien entièrement réussie ; le delta se calcule depuis lui, pas depuis la moisson précédente. Auparavant chaque moisson réécrivait .datan-modifies : le 29/10/2026 l'import a été tué après la moisson, celle du 30 a remplacé le delta, et les scrutins 9156 à 9200 ont disparu sans une erreur. Toute commande qui lit le delta doit donc être une étape de la chaîne. app:import:scrutins se contrôle en plus lui-même : un scrutin du dépôt absent de la base est rattrapé, ou fait échouer la commande.
  • Jamais SET unique_checks = 0 avant un upsert. InnoDB ne vérifie alors plus l'index unique, et l'ON DUPLICATE KEY UPDATE insère des doublons au lieu de mettre à jour (91 doublons pour 186 votes relus, à l'essai).
  • L'open data réécrit le passé. Sept scrutins de la 15e législature ont perdu leur bloc MODEM à la source (234 votes, que seule la base de production d'origine détient encore). app:import:scrutins signale « Source incomplète » quand les blocs de groupe totalisent moins de voix que la synthèse.
  • L'hébergement coupe ce qui dure. Sur o2switch, wait_timeout vaut 260 s : une étape qui lit des milliers de fichiers sans requête perd sa connexion (« MySQL server has gone away »). Et vers 6 h, la remise en place de la configuration PHP par CloudLinux coïncide avec des SIGHUP : rien ne se planifie entre 6 h et 6 h 10, et la chaîne ignore ce signal.

Source des données : les Tricoteuses

Les Tricoteuses n'ont pas d'API HTTP : elles publient des dépôts Git de fichiers JSON remoissonnés chaque nuit depuis l'open data de l'Assemblée, sous https://git.tricoteuses.fr/assemblee — et non plus git.en-root.org, abandonné à l'été 2026 sans avertissement dans les dépôts de données : il répond toujours, figé au 22 juillet, et un sync qui le lit réussit chaque soir sans rien apporter (Catalogue). Git est l'interface : il donne le transfert incrémental et la liste exacte des fichiers modifiés.

php bin/console app:sync:quotidien          # moisson + imports (~50 s à vide)
php bin/console app:sync:quotidien --tout   # reconstruction complète
php bin/console app:tricoteuses:sync --liste

Dépôts déclarés dans App\Tricoteuses\Catalogue, clonés dans var/tricoteuses/. Le moissonneur y dépose un fichier .datan-modifies que les imports consomment pour ne traiter que le delta, calculé depuis le dernier acquittement (cf. « Imports »). Planification Windows : bin\planifier-sync.ps1.

Tout ne vient pas des Tricoteuses. Restent à la charge de Datan : le lien scrutin → dossier et scrutin → amendement (l'Assemblée ne le publie que depuis 2026, et sur 75 % des scrutins seulement — le legacy le scrape sur assemblee-nationale.fr/dyn/), le détourage des photos, les parrainages et les réseaux sociaux des députés.

Seconde source : la base de production

Ce que l'open data ne publie pas vit dans la base de l'application d'origine, qui n'est pas joignable depuis un poste de développement. On passe donc par des exports TSV, et chaque export a sa requête dans bin/recuperation/legacy/<nom>.sql, qui produit <nom>.tsv — source unique, les docblocks y renvoient : sans cela, l'import n'est plus rejouable dès que le fichier est perdu. Socle commun : ImportLegacyCommand (lecture en flux, upsert par lots, COALESCE, bilan consigné).

Trois outils, à lancer sur le serveur :

bin/recuperation/exporter-legacy.sh                # tous les TSV, depuis la base d'origine
php bin/console app:recuperation:legacy --dossier=… # rejoue toute la récupération, dans l'ordre
bin/recuperation/exporter-hors-sync.sh             # ce que le sync ne remplit pas, depuis NOTRE base

app:recuperation:legacy vérifie ses préalables (--verifier), rend un bilan par fichier qui doit tomber juste, et se ferme par --clore le jour de la bascule : après quoi elle refuse de tourner, sans option pour passer outre. exporter-hors-sync.sh tient sa liste dans hors-sync.conf ; l'objectif qu'il doit tenir : base vide + migrations + app:sync:quotidien --tout + cet export = base équivalente à la production. Sur le serveur, les identifiants de la base d'origine viennent des variables DATABASE_* de ~/.bashrc, pas de ~/.my.cnf.

Les commandes une à une :

php bin/console app:import:communes             # départements, communes, voisinages
php bin/console app:import:elections            # catalogue des scrutins, candidatures
php bin/console app:import:resultats-electoraux # 3,1 M de résultats par commune (105 s)
php bin/console app:import:utilisateurs         # comptes de connexion, tous types (mot de passe repris)
php bin/console app:import:decryptages          # décryptages, catégories, lectures, auteurs
php bin/console app:import:explications         # explications de vote des députés
php bin/console app:import:articles             # blog (rubriques + articles)
php bin/console app:import:campagnes            # campagnes de dons
php bin/console app:import:amendements-clos     # exposés et auteurs des amendements des 15e-16e
php bin/console app:import:exposes              # résumés d'exposé des motifs de la 16e
php bin/console app:import:resumes-amendements  # résumés IA et mots-clés déjà produits
php bin/console app:import:municipales          # municipales 2026 (fichiers du ministère, ~3 min)
php bin/console app:import:noms-communes        # « d'Hirson », « du Havre » (CSV data.gouv)

Aucune n'est dans app:sync:quotidien et aucune n'a à y entrer : un scrutin passé ne change plus, une commune non plus. On les lance sciemment.

  • Le contenu éditorial de la production se préserve, il ne se régénère pas. Comptes, explications de vote, blog, FAQ, quiz, décryptages : rien de tout cela n'est dans l'open data. Ce sont des données de production, à récupérer telles quelles. Le mot de passe d'un compte se reprend sans le réinitialiser — le legacy hache en password_hash(PASSWORD_DEFAULT), du bcrypt que le vérifieur auto de Symfony relit et ré-encode tout seul.
  • Tous les comptes se reprennent, lecteurs compris. Un compte sans type, de type inconnu, ou « mp » sans député chez nous devient ROLE_LECTEUR : il se connecte et gère son compte, sans accès à la rédaction ni à l'espace député. utilisateur.id_origine garde l'identifiant d'origine ; c'est par lui que les décryptages retrouvent leur auteur et la newsletter son abonné.
  • Les amendements des législatures closes ne sont dans aucun dépôt. Exposé des motifs et auteur des 5 705 amendements votés en 15e et 16e ne viennent que de la base d'origine (app:import:amendements-clos).
  • Un import de récupération réaligne sur la production. Il est fait pour le chargement initial ; une fois l'application devenue la source (un rédacteur qui publie, un député qui écrit), le rejouer écraserait les écritures locales. À ne pas glisser dans une tâche planifiée.
  • Le backup public datan.fr/assets/dataset_backup est réduit et anonymisé : un seul compte, users_mp vide, decryptage.created_by non résolvable. Les commandes de récupération s'y vérifient mais se rejouent contre la vraie base des comptes au déploiement.
  • Résoudre le scrutin d'une explication par le décryptage, pas par le numéro. Un vote du Congrès porte le numéro sentinelle -1 dans explications_mp ; chercher scrutin.numero = -1 ne trouve rien et perd les explications (les 5 de l'IVG en L16). La table decryptage porte le même -1 et le bon scrutin_id : passer par elle.

Les municipales 2026 sont portées depuis le 2026-11-16, et ne viennent pas de la base de production : app:import:municipales lit directement les fichiers du ministère de l'Intérieur (MUN2026/), comme le font les scripts d'origine, et app:import:noms-communes le CSV de data.gouv. Aucune des deux n'entre dans le sync : les résultats sont définitifs depuis mai 2026.

Ce qui est délibérément laissé de côté : les tables elect_bv_* (grain bureau de vote). Vides au portage, elles portent aujourd'hui 9 millions de lignes pour 17 scrutins de 2017 à 2024, mais le site d'origine ne les lit que pour le bloc « Législatives 2024 » de la page d'une commune, que nous servons à l'identique depuis resultat_legislative (vérifié sur Faux et sur Toulouse, découpée en cinq circonscriptions). Leur source est publique (data.gouv.fr, « Données des élections agrégées ») : si un jour une page en a besoin, c'est elle qu'on importera, pas la base.

Pièges métier à ne pas réinventer

  • depute.groupe_id et depute.parti_id ne portent que l'appartenance courante — un rattachement encore ouvert, jamais le dernier connu. Un ancien député n'a donc ni groupe ni parti. Pour un groupe à une législature passée, ou pour la composition au moment d'un scrutin, passer par fonction_groupe, mandat ou vote_groupe. Recalculer une ventilation depuis vote + groupe_id donne des totaux faux.
  • Rattachement d'un député à un groupe : le plus récent — encore ouvert d'abord, puis date de fin la plus tardive (daily.php:914). Pas le plus long.
  • fonction_groupe.nomin_principale ne dit pas à quel groupe on appartient. L'Assemblée met ce drapeau à 0 sur le mandat de simple membre d'un député tant qu'il préside son groupe — sur toute la durée du mandat, rétroactivement — et le remet à 1 quand la présidence finit. Les « onze doubles rattachements ouverts » de la 17e sont les onze présidents : un mandat de membre et un de président, dans le même groupe. Filtrer sur ce drapeau à une date donnée fait donc disparaître un président de tous ses votes antérieurs à sa présidence (Sébastien Chenu : 1 814 votes sans groupe, et une loyauté de 100 % sur 14 votes). Pour l'appartenance à une date — groupe au jour d'un scrutin, loyauté, effectifs —, filtrer les qualités membre, apparenté et non-inscrit (GroupeAuScrutin::APPARTENANCE), comme daily.php:2147, et compter les députés en DISTINCT. Une fonction se superpose à l'appartenance, elle ne la remplace pas.
  • Composition d'un groupe dissous : celle du jour de sa disparition (date_fin du groupe, BETWEEN sur les bornes du rattachement). Les apparentés (code_qualite = 'Membre apparenté') comptent dans l'effectif mais s'affichent à part.
  • Proximité entre deux groupes : part des scrutins où tous deux ont voté pour, ou tous deux contre (daily.php:2176). Deux abstentions ne valent pas accord, et il n'y a pas d'accord partiel — c'est 0 ou 1. Contre-intuitif, mais c'est le chiffre affiché depuis toujours.
  • Une coalition est l'ensemble des groupes ayant pris la même position majoritaire sur un scrutin, « pour » ou « contre » — l'abstention n'en forme pas une, et les non-inscrits en sont exclus : ils ne constituent pas un groupe. Le partage en blocs politiques qui commente ces coalitions (App\Groupe\BlocPolitique) est une lecture éditoriale, valable pour la seule 17e législature, et LIOT n'y appartient à aucun bloc.
  • La 17e législature n'a aucun groupe « Majoritaire ». Depuis la dissolution de 2024, l'Assemblée ne déclare plus de positionPolitique sur ses groupes : tout bloc qui compare à la majorité présidentielle doit disparaître au lieu de se rabattre sur un groupe choisi au jugé.
  • Commission d'un député : celle de son mandat COMPER encore ouvert — à préséance minimale s'il en a plusieurs, le minimum pris sur les seuls mandats ouverts —, affichée par le libelleAbrege de l'organe (« Lois »). C'est la règle du site d'origine. La commission la plus fréquentée de la législature, retenue un temps pour ignorer les remplacements de quelques jours, retardait d'autant tout vrai changement : 67 députés sur 574 s'écartaient du site, dont 38 installés depuis plus d'un mois dans leur nouvelle commission. Elle ne sert plus qu'à un ancien député, qui n'a pas de mandat ouvert.
  • Participation d'un député : votes exprimés sur les scrutins solennels (code_type_vote = 'SPS') rapportés à tous les solennels tenus pendant sa période d'activité. Ne compter que les scrutins où il a une ligne vote donne faussement 100 %.
  • Un non-votant n'est pas un votant qui s'abstient. Dans la ventilation d'un scrutin, nonVotants — présidence de séance, membres du Gouvernement, qui n'ont pas le droit de voter — désigne un ensemble disjoint des pours, contres et abstentions : le decompteNominatif les liste à part. Les nonVotantsVolontaires, eux, sont bien inclus dans les abstentions. D'où la participation d'un groupe : (pours + contres + abstentions) / (membres − nonVotants) — on les retire du dénominateur, faute d'avoir pu voter, et jamais du numérateur, où ils n'ont jamais été comptés. Le legacy se trompe de côté sur sa seule page de vote et affiche des participations trop basses, voire nulles ; cf. App\Groupe\ParticipationGroupe.
  • date_fin d'un député n'est pas fiable pour savoir s'il siège : se fonder sur l'existence d'un mandat sans date de fin.
  • Les votes nominatifs couvrent les législatures 14 à 17 (2,46 M lignes) depuis l'import des dépôts Scrutins_XIV/XV/XVI_nettoye — clos, déclarés quotidien: false dans le Catalogue, importés une fois pour toutes par app:import:scrutins --depot=scrutins-xiv --tout et jamais par le sync. Toute statistique qui compte des votes DOIT filtrer la législature : un réélu porte les lignes de quatre législatures. Et après un tel import, les calculs se rejouent par législature : app:calcul:statistiques-deputes --legislature=N, qui ne réécrit que la sienne — les lignes des législatures closes survivent au recalcul quotidien de la courante.
  • dec est un mot réservé MariaDB : ne pas s'en servir comme alias.
  • Un vote du Congrès porte le même numéro qu'un scrutin de l'Assemblée. Le scrutin n° 1 de la 16e législature existe deux fois ; seul le préfixe d'uid (VTANR / VTCGR) les distingue. Le Congrès vit sous vote_c<n>, et decryptage.vote_numero le note négatif. D'où la fonction Twig lien_vote(legislature, numero) : appeler path('vote_individual') sur un numéro venant de la base lève une 500 dès qu'il est négatif.
  • L'article d'un département est une donnée, pas une règle. departement.libelle_de vaut « du », « de la », « des », « de l' » — et porte son espace final quand il en faut un, le libellé se concaténant directement au nom. 86 des 107 en ont un : les rogner casse la moitié des titres. Ni cet article ni la liste des communes ne sont dans l'open data ; ils viennent de la base de production (app:import:communes).
  • La Corse n'a pas la même casse d'une colonne à l'autre. commune.code_insee l'écrit en minuscules — 2a004 pour Ajaccio — quand departement.code écrit 2A. Or les collations de MariaDB ignorent la casse : une jointure, un WHERE, un LIKE retrouvent toujours leur ligne, et rien ne se voit. Ce qui s'y casse les dents est en dehors de la base — un isset() en PHP, une route qui exige [a-z0-9\-]+. Comparer à l'identique fait disparaître les 360 communes corses en silence, et la perte ne se constate qu'en comptant. Indexer les référentiels en minuscules et rendre l'orthographe de la base ; pour seulement voir le problème depuis SQL, il faut un REGEXP BINARY.
  • Le « département » 099 n'est pas de l'outre-mer : ce sont les Français établis hors de France, et leur code fait six caractères — 099069 désigne Dubaï. Les règles taillées pour l'outre-mer, appliquées à lui, font atterrir des pays entiers sur des communes de l'Ariège (099 + 233 → 09233).
  • Le code INSEE d'une commune d'outre-mer ne s'écrit pas partout pareil. Les fichiers du ministère répètent le troisième chiffre du département dans le premier du code de commune, et les deux tables ne renseignent pas le même : la présidentielle écrit Mayotte 976 + 503, les européennes 976 + 603, pour la même commune 97603. Ne jamais recomposer un code par une règle de découpage seule : essayer les écritures possibles et laisser le référentiel arbitrer, sans jamais inventer un code. Reste un cas insoluble à la source, Saint-Barthélemy et Saint-Martin, qu'elle range indifféremment sous 977 et 978.
  • Un slug dérivé d'un libellé n'est pas unique. Deux organes peuvent porter le même nom : « Affaires économiques » existe en PO277060 (clos en 2009) et PO419610 (en activité), idem pour les affaires culturelles. Avec un index unique sur le slug, l'ON DUPLICATE KEY UPDATE d'un import écrase silencieusement la ligne homonyme — l'organe perdu disparaît de la table de correspondance, et tous ses mandats sont rejetés sans la moindre erreur (3 362 sur 25 118 la première fois). Traiter les organes en activité d'abord, pour qu'ils gardent l'adresse simple, et suffixer le doublon.
  • Un sigle de groupe n'est pas unique dans une législature. En novembre 2026, l'Assemblée a rendu le sigle « UDR » au successeur de l'UDR dissous : la 17e a deux groupes de ce sigle. Retrouver un groupe par son uid ; l'adresse simple va au groupe en activité, l'homonyme prend sigle-uid (/groupes/legislature-17/udr-po847173, cf. App\Groupe\AdresseGroupe) ; un sigle abandonné redirige en 301 (GroupeController::SIGLES_ABANDONNES). Tout lien qui peut désigner un groupe disparu passe par |adresse_groupe(id).
  • Un député peut porter deux mandats dans une même législature. Un ministre qui revient siéger reçoit un second mandat avec la même dateDebut ; seule la prise de fonction les distingue (141 cas, dont 29 en 17e). La clé de mandat est l'uid de l'Assemblée — l'ancienne clé (député, législature, début) écrasait le premier. Une page qui ne veut qu'un mandat par législature prend le plus récent, et l'on compte des législatures distinctes, pas des mandats ; une jointure sur mandat pèse ces députés double, préférer EXISTS.
  • Le code de commune du ministère de l'Intérieur est CodCirElec : le code INSEE, Corse en capitales (2A004). Paris, Lyon et Marseille n'ont aux municipales qu'un scrutin à l'échelle de la ville, sous le code de la commune. Quatre communes de Nouvelle-Calédonie n'ont pas de numéro de panneau : se rabattre sur NumListe, sans quoi leurs listes s'écrasent l'une l'autre.
  • L'ordre des députés candidats d'une commune est l'ordre physique de la table d'origine (elect_deputes_candidats, MyISAM) : son export se fait sans ORDER BY, et candidature.ordre_saisie en garde le rang.
  • Résumés d'amendements par IA : un seul prompt, celui de la rédaction (App\Ia\Amendement\PromptResumeAmendement), envoyé par lots à l'API d'Anthropic (IA_MODELE_RESUMES, distinct d'IA_MODELE). Rien n'écrase un résumé existant, et rien de généré ne s'affiche au public avant d'avoir été relu (resume_relu, posé dans /admin/amendements) — le site d'origine publie sans relecture, nous non. Un mot-clé se rattache toujours par son slug normalisé (NormaliseurTag) ; un alias pointe un tag canonique, et amendement_tag ne porte que des canoniques. La table d'origine amendements_ia n'a pas de clé unique : on en garde une ligne par amendement, la plus récente qui a un résumé.

Environnement

Base MariaDB 11.4.13, la version de la production, sur 127.0.0.1:3307 (datan / datan / datan_symfony, utf8mb4_unicode_ci). Elle s'installe sans sudo par bin/mariadb-locale.sh installer, tourne en unité systemd utilisateur (mariadb-datan.service) et se pilote par le même script : etat, console, admin, dump, demarrer. Ni mariadb ni docker ne sont dans le PATH : passer par le script ou par php bin/console dbal:run-sql. Le serverVersion du DSN doit dire 11.4.13-MariaDB, sinon Doctrine génère des diffs de schéma fantômes.

Aucun autre moteur en local. Un MySQL 8 a servi quelques semaines : il a laissé partir vers la production du SQL que MariaDB n'avait jamais exécuté, il tournait en mode non strict, et sa collation par défaut n'existe pas chez MariaDB. La chaîne de qualité rejoue de toute façon les migrations sur une MariaDB 11.4 vierge avant chaque déploiement.

Une table créée sans COLLATE ne prend pas la collation de la base. Avec le seul DEFAULT CHARACTER SET utf8mb4, MariaDB 11.4 lui donne utf8mb4_general_ci ; doctrine:schema:validate ne voit pas l'écart, et la première comparaison de texte avec une colonne unicode_ci lève « Illegal mix of collations ». Dans une migration, toujours DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci.

La base locale n'est pas forcément complète. Au 2026-11-16 elle ne porte que la 17e législature, sans décryptages, comptes ni résultats électoraux par commune : compter les lignes avant de conclure d'une page vide à un défaut de code. La base de l'application d'origine, elle, n'est joignable que sur le serveur (cf. « Seconde source »).

Une variable d'environnement se déclare à deux endroits : sa valeur de repli dans config/services.yaml (env(NOM): …), son mode d'emploi dans .env.dist. Symfony ne lit .env.dist qu'en l'absence de .env : sur un poste où un .env traînait, CORS_ALLOW_ORIGIN et MATOMO_URL, définies là seulement, faisaient tomber toutes les pages en 500. Et .env.dev, suivi par Git, passe après .env.local et l'emporte sur lui : n'y mettre aucune valeur propre à un service réel — l'adresse de Matomo y a figuré un jour, et chaque poste de développement chargeait le suivi d'audience de la production. Un réglage pour le seul développement va dans .env.dev.local.

Vérifier .env.local avant de conclure quoi que ce soit d'un 404. Ce fichier va et vient ; quand il pose APP_ENV=prod, une route neuve répond 404 tant que var/cache/prod n'a pas été reconstruit, et le conteneur compilé fait foi contre le code. Le signe distinctif est la page d'erreur : celle de production (« Oops! An Error Occurred ») et non celle de débogage. Remède : rm -rf var/cache/prod && php bin/console cache:warmup. Le fichier appartient à l'utilisateur — ne pas le supprimer sans le lui dire ; en revanche, un .env.local créé pour un essai se supprime toujours.

Changer la signature d'un constructeur périme le conteneur prod en silence. Le conteneur compilé injecte le nombre d'arguments qu'il connaissait à la compilation : un service ajouté à un contrôleur fait tomber toutes ses pages en 500 (ArgumentCountError) tant que var/cache/prod n'est pas reconstruit — et le symptôme ressemble à un défaut du code fraîchement écrit, pas à un cache. Avec plusieurs agents dans le même arbre, celui qui modifie un constructeur réchauffe le cache lui-même, sitôt le changement posé (jamais pendant un import en cours, cf. plus haut).

APP_ENV=dev php -S … ne suffit pas à sortir de prod. Le runtime Symfony lit $_SERVER['APP_ENV'], et le variables_order=GPCS du php.ini local n'y verse pas l'environnement : le préfixe est ignoré sans un mot et .env.local gagne. Le signe : l'en-tête Age: (HttpCache) au lieu de X-Debug-Token. Remède : php -d variables_order=EGPCS -S ….

Un temps de réponse se mesure depuis le serveur. Depuis un poste, le délai jusqu'au premier octet contient un aller-retour réseau — 300 ms le 16/11/2026, quand une page en cache en coûtait 16 au serveur — et l'on avait conclu d'une page « à 330 ms » que PHP démarrait trop lentement. Mesurer en SSH (curl --resolve datan.fr:443:<IP> sur le serveur lui-même), ou retrancher le temps d'un fichier statique demandé au même instant.

Un banc d'essai à plusieurs php -S fabrique de faux 500. Ces serveurs sont mono-processus : pour interroger beaucoup d'adresses, on en lance plusieurs, et ils partagent alors le même magasin var/cache/prod/http_cache, dont les verrous lâchent sous concurrence. Les anomalies sortent alors par tranches contiguës — signature qu'un vrai défaut n'a pas. Toujours rejouer les adresses signalées une à une sur un seul serveur avant de conclure : 62 sur 26 875 ont ainsi été disculpées d'un coup.