feat(contracts): documenter le contexte des records (#85)

[citarf]

Résumé

• déclare les quatre compteurs du jour du record dans les contrats ODCS v2, ic et StatIC ;
• conserve tnn_min_statut et txx_max_statut hors ODCS : ils sont calculés par le serving ;
• fournit le prérequis contractuel de la PR chom-poc-data associée.

Vérifications

• datacontract lint des trois contrats ;
• python3 -m pytest tools/tests/ -v — 121 passed ;
• python3 tools/build_rgpd_register.py --check.

Liée à https://github.com/infoclimat-labs/chom-poc-data/issues/85.

[citarf]

Revue indépendante Opus 5 — VERDICT : APPROUVÉ

Revue en lecture seule au SHA c2baedb7a933ff82989e35581d748dff930ed5e0, dans un checkout neuf (gh repo clone + pull/26/head), indépendamment de la PR consommatrice chom-poc-data#165. Aucun fichier modifié, aucune fusion, aucun déploiement.

Ce qui est vérifié

1. Les quatre compteurs sont de vraies colonnes ODCS dans les trois contrats records. Chargement YAML des trois fichiers et énumération de l'objet records :

Contrat	objet	physicalName	colonnes après le lot
gold-climato-v2.odcs.yaml	records	gold_v2.records	17 (13 + 4)
gold-ic.odcs.yaml	records	gold_ic.records	17 (13 + 4)
gold-statIC.odcs.yaml	records	gold_statIC.records	16 (12 + 4)

Les quatre — txx_max_n_obs, tnn_min_n_obs, txx_max_n_obs_rejetees, tnn_min_n_obs_rejetees — sont déclarées en physicalType: BIGINT dans l'objet records et nulle part ailleurs. Aucun autre objet n'est touché.

2. Les deux statuts restent hors ODCS. grep -n statut contracts/*.odcs.yaml : zéro occurrence de tnn_min_statut / txx_max_statut. C'est la moitié qui compte de la décision de #85 (2026-08-11) — les déclarer ici ferait échouer le build côté serving (garde openapi.ts:283), et j'ai vérifié que c'est bien le cas : en injectant tnn_min_statut dans gold-ic.odcs.yaml, la suite du portail casse avec

Error: openapi: /ic/records.tnn_min_statut est une colonne du contrat ODCS —
       à décrire là-bas, pas dans COLONNES_SERVING

3. Les noms et les types correspondent au noyau qui produit la table. scripts/gold_records_sql.py:99-102 (dépôt chom-poc-data) :

CAST(b.txx_jour['n'] AS BIGINT) AS txx_max_n_obs,
CAST(b.tnn_jour['n'] AS BIGINT) AS tnn_min_n_obs,
CAST(b.txx_jour['r'] AS BIGINT) AS txx_max_n_obs_rejetees,
CAST(b.tnn_jour['r'] AS BIGINT) AS tnn_min_n_obs_rejetees

Mêmes noms, même ordre, même type. BIGINT est donc exact, pas approché.

4. Les noms correspondent à ce que la production sert réellement. Sondage lecture seule de l'API publique : /ic/records?station=07156 sert 19 clés, dont les quatre compteurs, à l'orthographe près. Le contrat rattrape la production, il ne l'anticipe pas.

5. La description dit vrai. Le seuil annoncé — « au moins 8 observations retenues (n_obs - n_obs_rejetees) » — est exactement scripts/cadence_extremes.py (SEUIL_QUOTIDIEN = 8, retenues = n_obs - (n_obs_rejetees or 0)). Contre-vérifié sur données servies : 192 extrêmes de 8 stations, zéro divergence entre le statut servi et la règle recalculée à la main.

Validations rejouées indépendamment

Contrôle	Résultat
python3 -m pytest tools/tests/ -q	121 passed
python3 tools/build_rgpd_register.py --check	Registre cohérent (10 traitements)
CI GitHub (lint ODCS, tests outillage, registre RGPD)	3/3 vertes
Suite chom-poc-data compilée contre CES contrats	131 passed (voir #165)
Dérive de doc dans catalog/, inventory/, lineage/	aucune — les mentions records y visent le legacy dataclimat/MariaDB

Findings

Bloquants — aucun.
Importants — aucun.

Mineur (1) — la description des compteurs cite des colonnes que la famille records ne porte pas. Les quatre descriptions renvoient à « n_obs - n_obs_rejetees », or /v2|/ic|/statIC/records n'exposent ni n_obs ni n_obs_rejetees : les compteurs y sont préfixés. Vérifié : 'n_obs' in props == False sur les trois routes. Un intégrateur qui lit la description sur la route cherchera une colonne absente. Le sens reste devinable, et le même mot-à-mot vaut pour la description du statut côté #165 — c'est cohérent, simplement imprécis. Non bloquant : à corriger à la prochaine passe sur ces descriptions, pas maintenant. Un contrat republié pour une reformulation coûte plus qu'il ne rapporte.

Ordre de fusion

Cette PR passe en premier. La CI vitest de #165 fait un actions/checkout de AssociationInfoclimat/data-platform sans ref — donc main — et pointe CHOM_CONTRACTS_DIR dessus. Tant que ces quatre colonnes ne sont pas sur main, #165 reste rouge, et c'est le comportement voulu : le garde refuse de masquer une divergence contrat/production.

Après fusion ici : relancer la CI de #165, la vérifier verte, puis fusionner #165. Aucune fusion avec CI rouge.

_{Revue indépendante, lecture seule. Aucun fichier modifié, aucune fusion, aucun déploiement. Le compte gh étant l'auteur de la PR, --approve est refusé par GitHub : le verdict APPROUVÉ est porté par écrit ci-dessus.}