documentations/kpi_health_check_improvement_roadmap.md

# KPI Health Check (Panel) — Plan d’amélioration (Roadmap)

## 0) Objectif

Consolider l’app **KPI Health Check** pour une utilisation “NPO / exploitation” plus fluide et plus actionnable.

Axes demandés:

- **[A] Exploitation / priorisation** (alert pack, ops queue, snapshot/delta, RCA hints)
- **[B] Visualisation** (map des sites, corrélation KPI)

Décision prise:

- **“Complaint sites only” = UI + export Excel (les deux)**

Non-scope:

- Génération PDF / evidence pack (optionnel, non prioritaire).

## 0.1) Principes (invariants)

- **Compatibilité**: ne pas casser l’existant (tables, drill-down, export principal).
- **Performance**: éviter les recalculs inutiles (réutiliser caches/versions déjà en place dans l’UI).
- **Robustesse données**: gérer proprement `NO_DATA`, colonnes manquantes, coordonnées absentes.
- **Export Excel**: garder des noms d’onglets **stables** (important pour les utilisateurs qui automatisent).

---

## 1) État actuel (déjà en place)

### 1.1 Flux de l’app

- Upload KPI **2G/3G/LTE** (CSV/ZIP)
- Normalisation `date_only`, `site_code`, enrichissement éventuel `City/Lat/Lon`
- Construction + édition des **rules** (`direction`, `sla`)
- Health-check: `OK / DEGRADED / PERSISTENT_DEGRADED / RESOLVED / NO_DATA`
- Synthèses:
  - `Site_Summary`
  - `MultiRAT_Summary` (score criticité)
  - `Top_Anomalies` (score anomaly)
- Drill-down: trend + heatmap + histogram
- Export Excel (Datasets / KPI Rules / Summary / Status / MultiRAT / Top)
- Gestion: presets + profiles
- Filtre existant: checkbox **Only complaint sites** (filtre les tables multi-rat / top anomalies)

### 1.2 Fichiers “source of truth”

- UI:
  - `panel_app/kpi_health_check_panel.py`
- Export:
  - `process_kpi/kpi_health_check/export.py`
- Calculs:
  - `process_kpi/kpi_health_check/engine.py`
  - `process_kpi/kpi_health_check/multi_rat.py`

---

## 2) Roadmap (ordre recommandé)

### Phase 1 — Complaint sites only (UI + Export) (priorité haute)

#### 2.1 UI: onglet dédié “Complaint sites only”

But: ne plus dépendre d’un filtre à cocher; fournir un écran prêt à l’emploi.

Contenu onglet:

- `MultiRAT Summary (Complaint)`
- `Top Anomalies (Complaint)`
- Optionnel: un petit “mini résumé” (counts)

Spécifications:

- Les tables doivent être **toujours** filtrées sur `is_complaint_site == True`.
- Les interactions existantes restent:
  - double-click (ou click) pour appliquer le drill-down (`_handle_double_click` + `_apply_drilldown_selection`).

Implémentation (point d’intégration):

- Créer 2 nouveaux `Tabulator` dans `kpi_health_check_panel.py`, alimentés par une fonction de refresh dédiée.
- Réutiliser la logique existante de flag `is_complaint_site` déjà posée dans `_apply_complaint_flags()`.

Critères d’acceptation:

- Après `Run health check`, l’onglet affiche uniquement les complaint sites.
- Les filtres “city / min score / top RAT / status” ne doivent pas casser l’onglet.
- Si la liste plaintes est vide/non trouvée, l’onglet reste vide (ou affiche un message) **sans erreur**.

#### 2.2 Export Excel: feuilles “Complaint sites only”

But: avoir un export directement partageable “ops / plaintes”.

Feuilles proposées:

- `Complaint_MultiRAT`
- `Complaint_Top_Anomalies`

Option bonus (si utile):

- `Complaint_Ops_Queue` (par site) = tri par criticité pondérée trafic si dispo.

Implémentation (point d’intégration):

- Étendre `process_kpi/kpi_health_check/export.py`:
  - soit en ajoutant de nouveaux paramètres optionnels,
  - soit en ajoutant des dfs supplémentaires en fin de liste (compatibilité).
- Dans `kpi_health_check_panel.py`, construire les df “complaint only” à partir de `current_multirat_df` / `current_top_anomalies_df` ou des raw (selon besoin) et les fournir à l’export.

Critères d’acceptation:

- L’export contient les 2 feuilles complaint.
- Les feuilles complaint restent vides si aucune liste plaintes n’est chargée et aucun fichier `data/complaint_sites.*` n’est trouvé.
- Les noms d’onglets restent < 31 caractères et sans caractères invalides (contrainte Excel).

---

### Phase 2 — Ops Queue + Alert Pack (priorité haute)

#### 2.3 “Ops Queue” (table unique priorisée)

But: une table de travail qui regroupe le besoin exploitation:

- 1 ligne par site
- priorité = criticité (pondérée trafic si dispo)
- infos clés: `impacted_rats`, `persistent_kpis_total`, `degraded_kpis_total`, `resolved_kpis_total`, `is_complaint_site`, trafic

Implémentation:

- Construire `ops_queue_df` à partir de `current_multirat_raw` (qui contient déjà scores + flags).
- Ajouter un onglet UI “Ops Queue” + une feuille Excel.

#### 2.4 “Alert Pack” export court

But: un export “prêt à envoyer” (résumé + ops queue + top anomalies) sans l’exhaustivité.

- Nouveau bouton export, ou une option dans l’export existant.

---

### Phase 3 — Snapshot + Delta (priorité haute)

#### 2.5 Snapshot de run

But: figer un run (résultats + paramètres + rules) pour audit et comparaison.

Format recommandé:

- `json` (simple) ou `parquet` (plus robuste pour gros volumes). Pour MVP: JSON.

Contenu snapshot (proposition):

- `snapshot_version`: int
- `created_at`: ISO datetime
- `profile_config`: dict (baseline/recent/thr/min streak + filtres)
- `rules_df`: list[dict] (records)
- `multirat_df`: list[dict]
- `top_anomalies_df`: list[dict]

UI:

- `FileDownload` “Save snapshot”
- `FileInput` “Load snapshot”

#### 2.6 Delta entre runs

But: sortir les variations entre snapshot chargé et run courant:

- `New degraded`
- `Still degraded`
- `Resolved`
- `Severity up / down`

Sorties:

- onglet UI “Delta”
- feuille Excel “Delta”

---

### Phase 4 — Visualisation (Map + Corrélation) (priorité moyenne)

#### 2.7 Map des sites dégradés

But: voir des clusters (zone / ville) et naviguer vers le drill-down.

Pré-requis:

- `Latitude` / `Longitude` disponibles (normalisation ou physical db).

Affichage:

- Plotly `scatter_mapbox` (style `open-street-map`) ou `scatter_geo`
- Couleur = status (ou degraded/persistent)
- Taille = criticité (weighted si dispo)

Interaction:

- click point => sélection site dans drill-down

#### 2.8 KPI Correlation Explorer

But: RCA rapide sur un site/RAT.

- Matrice corrélation des KPI sélectionnés (Pearson/Spearman)
- fenêtre: `recent` / `baseline` / `full filtered range`
- sortie: heatmap Plotly (`px.imshow`)

---

## 3) RCA Hints (bonus mais très utile)

Objectif: rendre `Top_Anomalies` plus actionnable.

Ajouts colonnes:

- `delta_pct`
- `sla_breached`
- `reason` (texte)
- `data_quality_flag`

Ces colonnes peuvent être calculées:

- lors de la génération de `Top_Anomalies` (dans `multi_rat.py`),
- ou côté Panel lors du refresh (plus rapide à itérer).

---

## 4) Découpage technique (recommandé)

Pour éviter d’alourdir `kpi_health_check_panel.py`:

- `process_kpi/kpi_health_check/snapshot.py`
  - save/load snapshot + validation version
  - compute delta

- `process_kpi/kpi_health_check/ops_queue.py`
  - build ops queue df

- `panel_app/kpi_health_check_maps.py`
  - build map figure

- `process_kpi/kpi_health_check/correlation.py`
  - build correlation matrix

---

## 4.1) Qualité des données & garde-fous (à intégrer dès Sprint 1)

- **Validation d’inputs**:
  - dataset vide / pas de `date_only` / pas de `site_code`
  - aucun point dans la `analysis_range`
- **Validation complaint list**:
  - parsing robuste (csv/txt/xlsx déjà prévu)
  - normalisation des codes site (cast int + extraction regex si besoin)
- **Fail-safe**: si `is_complaint_site` n’existe pas, ne pas crasher (considérer `False`).

## 4.2) Performance / mémoire (à surveiller)

- Limiter le volume affiché dans les tables (ex: top N) quand nécessaire.
- Éviter les copies inutiles de DataFrames lors des refresh.
- Garder les calculs lourds dans `process_kpi/*` et l’UI comme orchestration.

## 4.3) Tests rapides (smoke tests) / DoD

Minimum avant de considérer une phase “done”:

- Charger un petit sample 2G/3G/LTE et exécuter `Load` + `Run` sans erreur.
- Vérifier:
  - export Excel principal
  - export complaint
  - double-click tables => drill-down
  - aucun crash si complaint list absente

---

## 5) Critères de réussite globaux

- **Exploitation**: obtenir une liste priorisée + top anomalies complaint en < 1 minute.
- **Partage**: export Excel avec onglets complaint + delta.
- **Visualisation**: map cliquable et corrélation sur drill-down.

---

## 6) Plan de livraison (sprints)

- Sprint 1: Complaint UI tab + Export complaint sheets
- Sprint 2: Ops Queue + Alert Pack
- Sprint 3: Snapshot + Delta
- Sprint 4: Map + Correlation explorer
- Sprint 5 (option): RCA hints (reason/tags)

---

## 7) Risques & mitigations

- **Volumes importants** (beaucoup de sites/KPI/jours):
  - mitigation: top-N dans certaines vues + pagination Tabulator + éviter les figures avec trop de traces.
- **Coordonnées manquantes** (pas de Lat/Lon):
  - mitigation: la map doit être optionnelle et afficher un message clair si données insuffisantes.
- **Excel / automatisation utilisateur** (noms d’onglets attendus):
  - mitigation: ajouter les nouveaux onglets sans renommer les existants.