# KPI Health Check (Panel) — Plan global

## 1) Contexte & objectif

En NPO, on reçoit des plaintes client (site(s) impacté(s)). L’objectif est de pouvoir, en quelques minutes, vérifier si les KPI radio sont:

- Dégradés récemment
- Dégradés depuis longtemps (persistants)
- En voie de résolution / résolus

Le but est d’avoir une application Panel simple à utiliser, mais “expert-friendly”, qui standardise l’analyse et produit un rapport exportable.

## 2) Entrées & formats de données

### 2.1 Fichiers

- Rapports KPI par technologie: 2G / 3G / LTE
- Format: `.csv` ou `.zip` contenant un (ou plusieurs) `.csv`
- Séparateur: `;` (latin1) comme dans les apps existantes

### 2.2 Colonnes clés attendues

- Date: `PERIOD_START_TIME` (parfois date seule ou date+heure)
- Identifiant NE/site/cell (variable selon RAT)
  - 2G: `BCF name` / `DN`
  - 3G: `WBTS name` / `DN`
  - LTE: `LNBTS name` / `DN`

### 2.3 KPI (liste fournie)

- Les colonnes KPI sont nombreuses et hétérogènes.
- Il faut distinguer:
  - KPI “taux” (availability, success rate, CSSR, etc.) => agrégation moyenne
  - KPI “compteurs/volumes/traffic” => agrégation somme

## 3) Sorties attendues

### 3.1 Résultats UI

- Tableau “Health Summary” par site:
  - Nombre de KPI dégradés (par RAT)
  - Nombre de KPI persistants
  - Top KPI les plus critiques
- Drill-down par site:
  - Courbes temporelles
  - Jours dégradés
  - Comparaison baseline vs récent

### 3.2 Export

- Export Excel d’un rapport complet:
  - Résumé datasets
  - Règles KPI (seuils/direction)
  - Résumé site
  - Détails par KPI/site
  - Série journalière (optionnel / selon volume)

## 4) Modèle de détection (logique “expert”)

### 4.1 Normalisation

- Parsing date en `datetime`
- Construction `date_only`
- Extraction d’un `site_code` (ou code site) depuis le nom (pattern numérique / split comme dans l’app trafic)
- Enrichissement via `physical_db` (City, Latitude/Longitude) comme dans `trafic_analysis_panel.py`

### 4.2 Règles KPI (paramétrables)

Chaque KPI doit avoir:

- `direction`:
  - `higher_is_better` (availability, success rate, CSSR, throughput, traffic)
  - `lower_is_better` (drop rate, blocking, congestion, loss, discard, RTWP, PRB usage)
- `sla` (optionnel): seuil absolu
- `agg`: `mean` ou `sum`

### 4.3 Fenêtres temporelles

Paramètres globaux:

- Baseline window (ex: 30 jours)
- Recent window (ex: 7 jours)
- Min consecutive bad days (ex: 3 jours) => persistant

### 4.4 Critères de dégradation

Pour un couple (site, KPI, RAT):

- **Dégradation relative** vs baseline
  - ex: variation > X% dans le “mauvais sens”
- **Dégradation absolue** vs SLA
  - ex: availability < 98% ou drop > 2%

### 4.5 Classification (états)

- `OK`: pas de dégradation
- `DEGRADED`: dégradé récemment
- `PERSISTENT_DEGRADED`: dégradé récemment + streak >= N jours
- `RESOLVED` (V2): dégradé avant mais OK sur les derniers jours
- `NO_DATA`: pas de points exploitables

## 5) UX / écrans (Panel)

### 5.0 Mode multipage (Portal)

L’app cible est un **portal Panel multipage** qui regroupe plusieurs pages (apps) sur un seul serveur Panel.

Pages initiales:

- Global Traffic Analysis (page existante: `panel_app/trafic_analysis_panel.py`)
- KPI Health Check (nouvelle page: `panel_app/kpi_health_check_panel.py`)

Navigation:

- menu latéral (sélecteur de page)
- la sidebar et le contenu principal changent selon la page sélectionnée

### 5.1 Sidebar (configuration)

- Upload 2G/3G/LTE
- Période d’analyse optionnelle
- Paramètres: baseline/recent/threshold/persistance
- Boutons:
  - Charger & construire les règles
  - Lancer le health check
  - Export Excel

### 5.2 Main

- Datasets summary
- KPI Rules table (editable)
- Site Summary table
- Drill-down:
  - Sélection site
  - Sélection RAT
  - Sélection KPI
  - Courbe KPI
  - Table KPI/site (statuts)

## 6) Architecture code & organisation

### 6.1 Modules

Objectif: **app modulaire**, pas un fichier monolithique.

- `panel_app/kpi_health_check_panel.py`
  - UI Panel (widgets, layout)
  - branchement des callbacks
  - aucune logique “métier” lourde
- `panel_app/panel_portal.py`
  - page d’accueil + navigation multipage
  - import des pages et affichage via `get_page_components()`
- `process_kpi/kpi_health_check/io.py`
  - lecture ZIP/CSV
  - support ZIP multi-CSV (V2)
- `process_kpi/kpi_health_check/normalization.py`
  - détection colonne date / parsing
  - extraction `site_code` depuis BCF/WBTS/LNBTS/DN
  - agrégation journalière (mean vs sum)
  - enrichissement `physical_db` (City/Lat/Lon)
- `process_kpi/kpi_health_check/rules.py`
  - génération des règles KPI (direction, SLA, agg)
  - validation / normalisation des règles
- `process_kpi/kpi_health_check/engine.py`
  - calcul baseline vs récent
  - classification (OK / DEGRADED / PERSISTENT_DEGRADED / RESOLVED)
  - construction tables output
- `process_kpi/kpi_health_check/multi_rat.py`
  - synthèse cross-RAT par site
  - “top anomalies” multi-RAT
- `process_kpi/kpi_health_check/export.py`
  - build Excel bytes (réutilise `panel_app/convert_to_excel_panel.py`)

### 6.2 Fonctions clés

- Lecture ZIP/CSV
- Détection colonnes date & ID
- Construction dataset journalier
- Génération règles KPI
- Évaluation health check
- Export Excel

### 6.3 Règle `site_code` + enrichissement physical DB (comme l’app trafic)

- **Extraction code site**
  - stratégie principale: logique proche de `trafic_analysis_panel.py` (split / préfixe numérique du nom)
  - fallback: regex sur séquence de chiffres dans le nom
- **Enrichissement**
  - charger `physical_db/physical_database.csv` via `get_physical_db()`
  - construire `code` depuis `Code_Sector` (`split('_')[0]`) puis cast int
  - jointure sur le code pour récupérer `City`, `Longitude`, `Latitude`

## 7) Roadmap / itérations

### V1 (MVP)

- [DONE] Upload 2G/3G/LTE (multi-RAT)
- [DONE] Détection KPI numériques
- [DONE] Règles KPI éditables
- [DONE] Détection DEGRADED / PERSISTENT_DEGRADED / OK
- [DONE] Drill-down simple + export

### V2 (expert)

- [DONE] RESOLVED (dégradé puis OK)
- [DONE] Support ZIP multi-CSV
- [N/A] Support “cell-level” vs “site-level” (switch) (KPI confirmés par site)
- [DONE] Score de criticité (pondération trafic OK avec conversion 2G MB -> GB; pas de données population/criticité client)
- [DONE] Table “Top anomalies” multi-RAT (cross-RAT)
- [DONE] Visualisations avancées (heatmap par jour, histogrammes, etc.)

### V3 (industrialisation)

- [DONE] Presets de règles (JSON local) + sauvegarde/chargement dans l'UI
- [TODO] Gestion profils / sauvegarde de configuration
- [TODO] Import automatique de “liste des sites plaintes”
- [N/A] Génération PDF (optionnel) et pack de preuves

## 8) Points ouverts à confirmer

- [DONE] Les KPI sont par site
- [DONE] Les ZIP contiennent-ils parfois plusieurs CSV ? (support multi-CSV implémenté)
- [PARTIAL] Format exact de `PERIOD_START_TIME` sur tous les rapports ? (parsing renforcé, à valider sur tes fichiers)
- [TODO] Extraction du code site: règle unique ou dépend du naming ?

## 9) Critères de réussite

- Charger un rapport KPI et obtenir un top sites dégradés en < 1 minute
- Pouvoir isoler rapidement: depuis quand, sur quels KPI, et si c’est persistant
- Export Excel exploitable pour partage interne