# Audit AMCO / Keros — Synthèse

## Note méthodologique

Au moment de cet audit, aucun document fonctionnel, cahier des charges, screenshot, export UI ou spec API n'était présent dans le workspace `[IA-2026-04] Keros`. Cet audit s'appuie donc sur :

- le contexte projet TEEO / AMCO / Keros / Data & IA décrit dans `CLAUDE.md` (source primaire) ;
- des inférences raisonnables sur les plateformes industrielles de supervision énergie/eau ;
- les références historiques mentionnées (Keros AI) traitées comme contexte de continuité.

Pour chaque affirmation, le niveau de confiance est indiqué :

- `Observé (CLAUDE.md)` : information explicitement présente dans le contexte projet ;
- `Inféré` : déduction raisonnable à partir du contexte ;
- `À confirmer` : hypothèse qui demande validation par TEEO avant action structurante.

> **Action recommandée avant la suite du programme design** : déposer dans le workspace les screenshots AMCO existants, un export du sitemap actuel, un extrait de l'OpenAPI et 1-2 cahiers des charges récents. Cela permettra de transformer la majorité des `Inféré` en `Observé`.

---

## 1. Qu'est-ce qu'AMCO ?

`Observé (CLAUDE.md)` AMCO est la **plateforme métier principale** de TEEO. Elle est qualifiée d'historique, orientée exploitation et supervision dans le domaine **énergie/eau**.

`Inféré` AMCO est une application web multi-tenant qui sert de portail central pour :

- visualiser et exploiter des **mesures et indicateurs** physiques (consommations, débits, températures, pressions, niveaux) ;
- piloter un parc de **compteurs** (intelligents et/ou télérelevés) regroupés en **secteurs** ;
- détecter, qualifier et commenter des **anomalies** sur les séries temporelles ;
- restituer des indicateurs via tableaux, graphiques et exports ;
- administrer le contexte utilisateur, les droits, les périmètres clients.

`À confirmer` Le périmètre exact (industriels, collectivités, distributeurs, gestionnaires de réseaux, syndicats des eaux, bailleurs) n'est pas figé dans les sources disponibles.

## 2. Ce que couvre la plateforme

`Inféré` Modules fonctionnels probables :

- **Supervision temps quasi-réel** : vue d'ensemble par site, secteur ou flotte de compteurs.
- **Catalogue compteurs** : inventaire, identifiants, métadonnées, état, périmètre tenant.
- **Mesures** : visualisation des séries (pas 10 min / horaire / jour), agrégations, comparaisons.
- **Anomalies** : détection, listing, requalification, suivi du cycle de vie.
- **Commentaires / annotations** : trace métier sur les compteurs, secteurs et anomalies.
- **Indicateurs / KPI** : agrégats énergétiques ou hydrauliques sur des périodes paramétrables.
- **Exports** : CSV / Excel, voire PDF pour les rapports périodiques.
- **Administration** : utilisateurs, droits, périmètres, paramètres techniques.
- **Santé technique** : statut API, ingestion, qualité des données.

`Inféré` Modules transverses :

- authentification / SSO (probablement JWT ou Keycloak côté cible) ;
- gestion multi-tenant filtrée systématiquement côté backend (cf. règles CLAUDE.md) ;
- notifications / alertes.

## 3. Utilisateurs cibles

`Inféré` Personas types :

| Persona | Besoin principal | Posture face à l'outil |
|---|---|---|
| Exploitant / agent terrain | Comprendre vite un compteur, suivre des relèves, repérer une anomalie locale | Pragmatique, peu de temps, mobile et desktop |
| Technicien réseau / énergie | Diagnostiquer une dérive, requalifier une anomalie | Métier expert sur un domaine restreint |
| Responsable énergie / eau | Suivi des indicateurs, reporting, arbitrages | Vue agrégée, mensuel/hebdomadaire, exports |
| Analyste data / qualité | Explorer les données, valider les modèles | Densité d'information assumée, multi-écrans |
| Administrateur tenant | Gérer comptes, périmètres, intégrations | Usage ponctuel, sensibilité aux droits |

`À confirmer` Présence d'utilisateurs externes (clients finaux de TEEO ayant accès à un portail restreint).

## 4. Écrans et patterns identifiés (hypothèses)

`Inféré` Sur la base d'un historique de plateforme métier énergie/eau, on peut s'attendre à :

- une **AppShell** classique : barre de navigation haute, navigation secondaire à gauche, contenu principal, breadcrumb ;
- des **pages de listing** denses (compteurs, secteurs, anomalies) avec filtres, recherche, tri et pagination ;
- des **pages de synthèse** par compteur ou par secteur avec onglets (mesures, anomalies, commentaires, informations techniques) ;
- des **graphiques temporels** (courbes, histogrammes, parfois combinés) ;
- des **panneaux latéraux** pour le détail d'une anomalie ou un commentaire ;
- des **formulaires** d'administration et de qualification d'anomalie ;
- des **exports** sous forme de boutons d'action dans l'en-tête des listings.

## 5. Rôle de Keros

`Observé (CLAUDE.md)` Keros est la **trajectoire de modernisation** d'AMCO, dans trois dimensions :

- **UX** : clarifier, alléger, harmoniser les écrans existants ;
- **IA** : intégrer des briques (détection d'anomalies, futurs services) ;
- **Architecture** : micro-services, API REST contractualisées, micro-frontends.

`Observé (CLAUDE.md)` Keros n'est pas une refonte radicale d'AMCO. C'est une couche d'évolution progressive : les habitudes utilisateurs et l'architecture en place doivent être respectées.

`Inféré` Concrètement, Keros se traduit pour les utilisateurs par :

- un design system unifié (le présent chantier) ;
- des modules métier modernisés réintégrés dans AMCO en micro-frontend / iFrame ;
- une montée en gamme progressive : la barre de navigation, les filtres et certains écrans clés peuvent être harmonisés avant le reste.

## 6. AMCO Avancé — Module Détection d'anomalies

`Observé (CLAUDE.md)` AMCO Avancé est la **gamme** qui intègre les briques Data & IA, dont la détection d'anomalies est le premier micro-service phare.

`Observé (CLAUDE.md)` La détection d'anomalies réutilise les acquis du projet historique **Keros AI** (modèles de détection d'anomalies sur séries temporelles).

`Inféré` Périmètre fonctionnel cible du module détection d'anomalies :

- ingestion des séries de mesures (depuis AMCO ou via DSS) ;
- exécution de modèles de détection (modèles Keros AI) ;
- restitution sous forme :
  - d'un **dashboard anomalies** (liste filtrée, indicateurs synthétiques) ;
  - d'une **vue détaillée d'anomalie** (graphique + contexte + actions de qualification) ;
  - de **commentaires métier** rattachés à l'anomalie ;
  - d'une **timeline d'événements** sur le compteur ou le secteur ;
- statuts d'anomalie : `nouvelle`, `en cours`, `confirmée`, `requalifiée`, `ignorée`, `résolue` (`À confirmer`) ;
- sévérités : `faible`, `moyenne`, `élevée`, `critique` (`À confirmer`).

`Inféré` Le module est livré comme **micro-service** avec un front dédié, intégré progressivement dans AMCO via micro-frontend ou iFrame. Le filtrage multi-tenant reste backend (voir CLAUDE.md §7.1).

## 7. Contraintes d'intégration progressive

`Observé (CLAUDE.md)` et `Inféré` :

- **Coexistence visuelle obligatoire** avec AMCO actuel pendant toute la phase de transition.
- **Pas de rupture brutale** des habitudes utilisateurs (navigation, filtres, tables, sémantique des statuts).
- **Compatibilité micro-frontend / iFrame** : le front Keros doit s'embarquer dans une frame AMCO sans collisions CSS, sans dépendances lourdes globales et avec un contexte (`tenant_id`, JWT, langue) passé en paramètre.
- **Authentification JWT** centralisée, filtrage multi-tenant côté backend uniquement.
- **API versionnées** (`/api/v1/...`), documentation OpenAPI.
- **Stack front possible** : React/Vite ou Vue. Le design system doit donc rester framework-agnostique au niveau des tokens et des composants HTML/CSS.
- **Industrialisation progressive** : dev / préprod / prod, observabilité (Prometheus / Grafana), conformité RGPD.
- **Simplicité d'exploitation** : équipes TEEO restreintes, donc privilégier composants peu dépendants, build léger, et conventions stables.

## 8. Risques identifiés

| Risque | Impact | Mitigation |
|---|---|---|
| Refonte trop ambitieuse → rejet utilisateur | Élevé | Évolution progressive, conserver patterns AMCO connus, communiquer sur la roadmap |
| Inflation des composants design system | Moyen | Tokens stricts, gouvernance design system, changelog systématique |
| Collisions CSS en iFrame | Moyen | Préfixe `keros-`, `:where()` pour les selectors, scoping strict |
| Multi-tenant cassé côté front | **Critique** | Filtrage backend systématique, jamais côté front uniquement (cf. CLAUDE.md §7.1) |
| Performances sur tableaux denses | Moyen | Pagination, tri côté serveur, virtualisation au besoin |
| Accessibilité dégradée par excès de densité | Moyen | Tokens d'espacement, contrastes WCAG, focus visible, taille minimale des cibles |

## 9. Synthèse exécutive

Keros est une **couche d'évolution progressive** d'AMCO, pas une refonte. Le présent chantier design pose les fondations (audit, artboard, design system HTML, design.md) pour que les développements futurs — à commencer par le micro-service **Détection d'anomalies** d'AMCO Avancé — soient industriels, cohérents et compatibles avec l'existant.

Le rendu visuel cible reste **professionnel, industriel, sobre, dense mais lisible** — pas startup, pas marketing. Les composants livrés doivent être réutilisables, accessibles et neutres vis-à-vis du framework front (React/Vite ou Vue).