florian/maj-docs

florian commented

2026-09-08 14:40:42 +00:00

Member

Ce que ça change

Passe de vérification de bout en bout sur la documentation : chaque affirmation vérifiable a été confrontée au dépôt, au serveur ou aux deux. Trente-neuf fichiers, que des documents — treize fiches ADR, la documentation d'API, les manuels d'exploitation, le glossaire et les plans.

Rien n'a été réécrit pour la forme. Les corrections portent sur des écarts entre ce qui est écrit et ce qui tourne.

Closes #

Preuve

Les constats sont datés du 08/09 et relevés sur ml-stagiaire-02. Les plus structurants :

# La chaîne complète tourne, l'ADR 0003 et les manuels ETL le disaient « partiel »
$ sudo tail -1 /var/log/enervision/gold.log
2026-09-08 08:27:02 INFO etl.gold.chargement 2026-09-08 chargé :
  3360 lignes de mesure, 7 lignes de qualité, 957 alertes

# Le conteneur d'archive Azure n'existe pas — l'ADR 0012 et le plan le disaient créé
$ az storage container metadata show --account-name stenervisiong2tfstate -n archive
ERROR: The specified container does not exist. ErrorCode:ContainerNotFound
$ terraform.tfstate (série 3) : une seule entrée, data azurerm_resource_group.projet

# Le codes de sortie du collecteur étaient inversés dans son manuel
$ grep -n "return 0" services/collector/collector/current.py
151:    return 0 if releves and all(r.ecrit for r in releves) else 1
# « all » et non « any » : le manuel annonçait 0 = « au moins un objet écrit »

# Le volume de la zone bronze est le double de l'extrapolation du plan de migration
$ du -shc bronze/.../dt=2026-09-07   →  104 Mio  (le plan annonçait ~50 Mio/jour)

# postgres-exporter n'écoute pas là où sa composition le règle
$ ss -lntp | grep 9187         →  LISTEN *:9187
$ docker inspect ev-postgres-exporter | grep LISTEN
                               →  PG_EXPORTER_WEB_LISTEN_ADDRESS=127.0.0.1:9187

Relecture

Un pair a relu et laissé un commentaire, même court
Ses remarques sont traitées, ou une réponse explique pourquoi elles ne le sont pas

Ce qui suit le code

docs/runbooks/ mis à jour, un geste d'exploitation a changé
docs/adr/ complété, une décision structurante a été prise

Où regarder en priorité

Trois écarts sont documentés sans être corrigés. Ils demandent un arbitrage, pas une relecture de style :

L'ENF-02 n'est pas tenue. dashboard/autorisation.py rend tous les sites sans lire ops.acces_site : tout compte authentifié voit les sept, et le 404 des routes /v1 ne se déclenche que sur un site inconnu. La table est vide et rien ne l'écrit — ni route d'administration, ni amorce — donc la brancher telle quelle viderait le tableau de bord. Aucun ticket ne porte ce raccordement. Écrit dans docs/api/decisions.md, authentification.md et l'ADR 0002.
infra/ansible/restore.yml échouera à sa dernière tâche. Elle teste pg_isready contre la chaîne anglaise accepting connections, or le serveur répond « acceptation des connexions ». failed_when est donc vrai à tous les coups : le playbook rougit après avoir restauré les bases. Jamais rencontré parce que l'exercice du #41 n'a pas été joué et que la chaîne ne valide que la syntaxe. Le correctif tient en une ligne, il est décrit dans docs/runbooks/reprise.md. Volontairement hors de cette demande : c'est du code, il mérite son ticket.
Le port 80 est ouvert au pare-feu sans service derrière. Le rôle base l'ouvre pour « la redirection ACME et vers 443 », mais le Caddyfile porte auto_https disable_redirects et rien n'écoute. Il n'est pas non plus au plan d'adressage du §8 d'EXIGENCES-collectives.md, qui pose pourtant qu'un port se déclare avant d'être exposé. Trois sources, trois versions. Constat dans docs/FORGE.md §2.

Deux relectures ciblées seraient utiles :

docs/adr/0006 — j'ai corrigé la borne du report d'imputation. Le manuel disait « ≤ 10 minutes » de trou ; le code borne sur l'âge de la valeur, si bien qu'une coupure de six heures voit ses dix premières minutes reportées. Le test test_une_coupure_de_six_heures_ne_s_invente_pas_meme_sur_un_site_stable fixe ce comportement. Olivier ou Justine pour confirmer que c'est bien l'intention.
docs/runbooks/etl.md — la fusion a gardé la cadence au quart d'heure du #205, mais le serveur tourne encore à l'heure (0 / 17 / 27). J'ai posé la réserve ; un --tags app alignerait les deux.

Enfin, docs/GLOSSAIRE.md : current_a est servie par la source et gardée en bronze, mais GRANDEURS n'en compte que six et l'abandonne à l'entrée de la zone argent. C'est peut-être délibéré — l'intensité se déduit de la tension et du facteur de puissance — mais ce n'est écrit nulle part.

## Ce que ça change Passe de vérification de bout en bout sur la documentation : chaque affirmation vérifiable a été confrontée au dépôt, au serveur ou aux deux. Trente-neuf fichiers, **que des documents** — treize fiches ADR, la documentation d'API, les manuels d'exploitation, le glossaire et les plans. Rien n'a été réécrit pour la forme. Les corrections portent sur des écarts entre ce qui est écrit et ce qui tourne. Closes # ## Preuve Les constats sont datés du 08/09 et relevés sur `ml-stagiaire-02`. Les plus structurants : ``` # La chaîne complète tourne, l'ADR 0003 et les manuels ETL le disaient « partiel » $ sudo tail -1 /var/log/enervision/gold.log 2026-09-08 08:27:02 INFO etl.gold.chargement 2026-09-08 chargé : 3360 lignes de mesure, 7 lignes de qualité, 957 alertes # Le conteneur d'archive Azure n'existe pas — l'ADR 0012 et le plan le disaient créé $ az storage container metadata show --account-name stenervisiong2tfstate -n archive ERROR: The specified container does not exist. ErrorCode:ContainerNotFound $ terraform.tfstate (série 3) : une seule entrée, data azurerm_resource_group.projet # Le codes de sortie du collecteur étaient inversés dans son manuel $ grep -n "return 0" services/collector/collector/current.py 151: return 0 if releves and all(r.ecrit for r in releves) else 1 # « all » et non « any » : le manuel annonçait 0 = « au moins un objet écrit » # Le volume de la zone bronze est le double de l'extrapolation du plan de migration $ du -shc bronze/.../dt=2026-09-07 → 104 Mio (le plan annonçait ~50 Mio/jour) # postgres-exporter n'écoute pas là où sa composition le règle $ ss -lntp | grep 9187 → LISTEN *:9187 $ docker inspect ev-postgres-exporter | grep LISTEN → PG_EXPORTER_WEB_LISTEN_ADDRESS=127.0.0.1:9187 ``` ## Relecture - [ ] Un pair a relu et laissé un commentaire, même court - [ ] Ses remarques sont traitées, ou une réponse explique pourquoi elles ne le sont pas ## Ce qui suit le code  - [x] `docs/runbooks/` mis à jour, un geste d'exploitation a changé - [x] `docs/adr/` complété, une décision structurante a été prise ## Où regarder en priorité **Trois écarts sont documentés sans être corrigés.** Ils demandent un arbitrage, pas une relecture de style : 1. **L'ENF-02 n'est pas tenue.** `dashboard/autorisation.py` rend tous les sites sans lire `ops.acces_site` : tout compte authentifié voit les sept, et le `404` des routes `/v1` ne se déclenche que sur un site inconnu. La table est vide et **rien ne l'écrit** — ni route d'administration, ni amorce — donc la brancher telle quelle viderait le tableau de bord. Aucun ticket ne porte ce raccordement. Écrit dans `docs/api/decisions.md`, `authentification.md` et l'ADR 0002. 2. **`infra/ansible/restore.yml` échouera à sa dernière tâche.** Elle teste `pg_isready` contre la chaîne anglaise `accepting connections`, or le serveur répond « acceptation des connexions ». `failed_when` est donc vrai à tous les coups : **le playbook rougit après avoir restauré les bases**. Jamais rencontré parce que l'exercice du #41 n'a pas été joué et que la chaîne ne valide que la syntaxe. Le correctif tient en une ligne, il est décrit dans `docs/runbooks/reprise.md`. **Volontairement hors de cette demande** : c'est du code, il mérite son ticket. 3. **Le port 80 est ouvert au pare-feu sans service derrière.** Le rôle `base` l'ouvre pour « la redirection ACME et vers 443 », mais le `Caddyfile` porte `auto_https disable_redirects` et rien n'écoute. Il n'est pas non plus au plan d'adressage du §8 d'`EXIGENCES-collectives.md`, qui pose pourtant qu'un port se déclare avant d'être exposé. Trois sources, trois versions. Constat dans `docs/FORGE.md` §2. **Deux relectures ciblées seraient utiles :** - `docs/adr/0006` — j'ai corrigé la borne du report d'imputation. Le manuel disait « ≤ 10 minutes » de trou ; le code borne sur **l'âge de la valeur**, si bien qu'une coupure de six heures voit ses dix premières minutes reportées. Le test `test_une_coupure_de_six_heures_ne_s_invente_pas_meme_sur_un_site_stable` fixe ce comportement. **Olivier ou Justine** pour confirmer que c'est bien l'intention. - `docs/runbooks/etl.md` — la fusion a gardé la cadence au quart d'heure du #205, mais le serveur tourne encore à l'heure (`0` / `17` / `27`). J'ai posé la réserve ; **un `--tags app` alignerait les deux**. Enfin, `docs/GLOSSAIRE.md` : `current_a` est servie par la source et gardée en bronze, mais `GRANDEURS` n'en compte que six et l'abandonne à l'entrée de la zone argent. C'est peut-être délibéré — l'intensité se déduit de la tension et du facteur de puissance — mais ce n'est écrit nulle part.

florian added the

Kind/Documentation

label

2026-09-08 14:40:42 +00:00

florian self-assigned this

2026-09-08 14:40:42 +00:00

florian added 4 commits

2026-09-08 14:40:43 +00:00

docs : aligne les fiches ADR, la documentation d'API et les manuels sur le code a1741453af

Passe de vérification de bout en bout : chaque affirmation vérifiable a été
confrontée au dépôt, au serveur ou aux deux. Les corrections portent sur des
écarts entre ce qui est écrit et ce qui tourne, pas sur la forme.

Principaux écarts fermés :

- ADR 0001 : l'exception PostgreSQL était levée depuis le 02/09, la
  composition est par pile, les secrets sont en 0640 et non 0600
- ADR 0002 : SameSite réel (Lax sur ev_access, Strict sur ev_refresh),
  condition de bascule Keycloak échue et non remplie
- ADR 0005 et CONVENTIONS : endpoint=alerts manquait, hour= absent des clés
  /readings, la zone or écrit table=mesure et non mesure_horaire
- ADR 0006 : le report se borne sur l'âge de la valeur, pas sur la longueur
  du trou ; l'imputation ne touche que les deux grandeurs décisionnelles
- ADR 0012 et plan de migration : le conteneur d'archive est déclaré mais
  jamais appliqué — l'état distant ne porte que la source de données
- docs/api : les dix routes /v1 n'étaient documentées nulle part, le
  filtrage par site est inerte, le tableau de bord sert des fixtures
- runbooks : codes de sortie du collecteur inversés (all et non any),
  chemins Ruff incomplets, zones sensibles de la CI fausses

Un bug corrigé au passage : restore.yml testait la sortie de pg_isready
contre une chaîne anglaise alors que le serveur répond en français. La
tâche échouait donc après avoir restauré les bases. Le verdict passe au
code de sortie.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9QRxZiZ6TZzSAmtTsg6Sw

Merge branch 'develop' into florian/maj-docs f72b399650

# Conflicts:
#	docs/runbooks/README.md
#	docs/runbooks/deploiement.md
#	docs/runbooks/etl.md

adr 0013 : la fiche ne se contredit plus après la livraison du #37 a8d82fad55

Trois constats écrits ce matin sont périmés depuis la fusion de develop :

- « Le #37 n'est pas commencé » : le paquet services/inference/inference/
  existe, prevoir.sh tourne sous cron à la minute 35, public.prevision porte
  21 lignes dont la dernière pour 14 h 00 UTC, et fixtures.py n'invente plus
  de prévision. Le document affirmait le contraire deux sections avant
  « Ce que le #37 a tranché ».
- La fenêtre d'évaluation par défaut n'est plus de trois jours mais de
  quatorze (_JOURS_TEST_DEFAUT), portée par le #36 le 08/09.
- L'état « proposée » était dit deux fois, la seconde plus précisément :
  le paragraphe de clôture porte la condition de levée.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9QRxZiZ6TZzSAmtTsg6Sw

révision : sort restore.yml et autorisation.py du périmètre documentaire

Intégration / Tableau de bord — dépendances, tests et construction (pull_request) Successful in 37s

Details

Intégration / Contrôles statiques du dépôt (pull_request) Successful in 6s

Details

Intégration / Workflows — lint et audit de sécurité (pull_request) Successful in 19s

Details

Intégration / Python — qualité, tests et dépendances (pull_request) Successful in 5m56s

Details

9da8cefe86

Ces deux fichiers sont du code, pas de la documentation. Ils reviennent à
l'identique de develop pour que cette branche ne porte que des documents.

Les deux constats qui avaient motivé les changements restent valables et
sont à traiter dans leur propre ticket :

- infra/ansible/restore.yml teste la sortie de pg_isready contre la chaîne
  anglaise « accepting connections » alors que le serveur répond en
  français, « acceptation des connexions ». La condition failed_when est
  donc vraie à tous les coups : le playbook rougit APRÈS avoir restauré les
  bases. Vérifié le 08/09 sur ml-stagiaire-02. Le correctif tient en une
  ligne — s'appuyer sur le code de sortie de pg_isready, qui vaut 0 quand le
  serveur accepte. Le piège reste documenté dans docs/runbooks/reprise.md.

- dashboard/autorisation.py rend tous les sites sans lire ops.acces_site :
  tout compte authentifié voit les sept, et l'ENF-02 n'est pas tenue. Le
  docstring du module reste celui de develop. L'écart est documenté dans
  docs/api/decisions.md, authentification.md et l'ADR 0002.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D9QRxZiZ6TZzSAmtTsg6Sw

florian requested reviews from lenaic, marvin, gabriel, olivier, justine

2026-09-08 14:40:52 +00:00

justine added 1 commit

2026-09-08 14:48:00 +00:00

Merge branch 'develop' into florian/maj-docs

Intégration / Tableau de bord — dépendances, tests et construction (pull_request) Successful in 44s

Details

Intégration / Contrôles statiques du dépôt (pull_request) Successful in 7s

Details

Intégration / Workflows — lint et audit de sécurité (pull_request) Successful in 18s

Details

Intégration / Python — qualité, tests et dépendances (pull_request) Has been cancelled

Details

e9f7ef0e17

justine added 1 commit

2026-09-08 14:53:55 +00:00

Correction docs

Intégration / Contrôles statiques du dépôt (pull_request) Has been cancelled

Details

Intégration / Python — qualité, tests et dépendances (pull_request) Has been cancelled

Details

Intégration / Workflows — lint et audit de sécurité (pull_request) Has been cancelled

Details

Intégration / Tableau de bord — dépendances, tests et construction (pull_request) Has been cancelled

Details

b0694d7978

gabriel added 1 commit

2026-09-08 16:43:38 +00:00

Merge branch 'develop' into florian/maj-docs

Intégration / Contrôles statiques du dépôt (pull_request) Successful in 8s

Details

Intégration / Workflows — lint et audit de sécurité (pull_request) Successful in 23s

Details

Intégration / Tableau de bord — dépendances, tests et construction (pull_request) Successful in 40s

Details

Intégration / Python — qualité, tests et dépendances (pull_request) Successful in 5m43s

Details

c3de21e41d

Résout le conflit sur docs/api/authentification.md : conserve à la
fois la précision develop sur le 403 (mot de passe actuel incorrect)
et l'ajout florian sur le 404 (site inconnu ou non autorisé).

gabriel merged commit 51bd956167 into develop

2026-09-08 16:51:06 +00:00

gabriel deleted branch florian/maj-docs

2026-09-08 16:51:06 +00:00

gabriel referenced this pull request from a commit

2026-09-08 16:51:07 +00:00

Merge pull request 'florian/maj-docs' (#214) from florian/maj-docs into develop

Rows
Columns

florian/maj-docs #214

Ce que ça change

Preuve

Relecture

Ce qui suit le code

Où regarder en priorité