DESCRIPTION COMPLETE DU DASHBOARD SAHAM
========================================

Document généré à partir du code source actuel du projet.
Périmètre : Vue globale, Objectifs, Détails quotidien, Détails hebdomadaire,
Statistiques et écran de contrôle AppsFlyer.


1. VUE D'ENSEMBLE TECHNIQUE
---------------------------

Le dashboard est un tableau de bord d'acquisition payante et d'onboarding bancaire.
Il consolide :
- les dépenses, impressions et clics Meta Ads et Google Ads ;
- les installs et métriques AppsFlyer ;
- les événements d'onboarding GA4 ;
- les onboardings attribués à Meta/Google ;
- les campagnes et leur performance ;
- les comptes CDC et états de dossiers provenant d'un snapshot CRM CSV local.

Client interrogé : client_id = 10.
Devise d'affichage : MAD.
Conversion métier annoncée dans l'interface : 11 MAD par euro.
Début minimum du projet : 2026-07-01.
La date maximale normale est hier. L'écran AppsFlyer s'arrête à J-2.
Période par défaut : les 7 derniers jours complets jusqu'à hier.
Période précédente : fenêtre immédiatement antérieure, de même longueur.
Les pages sont dynamiques et protégées par authentification.
Les appels API sont mis en cache côté serveur pendant 300 secondes.
En cas d'échec d'une API, la page continue avec une structure vide pour les autres blocs.


2. APIS ET SOURCES UTILISEES
----------------------------

Toutes les API distantes utilisent POST, API_BASE_URL, un Bearer token et un X token.

2.1 /api/meta-ads-data/getAppsFlyerDailyFunnel
Payload : client_id, since, until, previous_since, previous_until.
Rôle : socle journalier du dashboard.
Champs principaux : date, meta_spend, google_spend, total_spend,
total_paid_impressions, total_paid_clicks, meta_clicks, google_clicks,
installs Android/iOS/total, onboarding start, onboarding success, cdc_accounts,
source_status, total agrégé et données de période précédente.
Utilisé par : dépenses, funnel paid media, ratios, coûts, charts quotidiens,
répartition plateformes, contrôles et objectifs mensuels de dépense.

2.2 /api/meta-ads-data/getActiveCampaigns
Payload : client_id et périodes courante/précédente.
Retour : meta_active_campaigns, google_active_campaigns, total_active_campaigns.
Utilisé par : carte Campagnes actives et bandeau de contrôle.

2.3 /api/meta-ads-data/getOnboardingSuccessMetaGoogle
Payload : client_id et périodes courante/précédente.
Retour : campagnes Meta et Google, dépenses MAD, réussites, coût/réussite,
statut de rapprochement AppsFlyer et informations de complétude.
Utilisé par : coût par onboarding par campagne, partage du budget et table campagne.
Règle : AppsFlyer est utilisé au niveau campagne uniquement si toutes les campagnes
avec dépense sont correctement rapprochées et possèdent une valeur AppsFlyer.
Sinon les conversions natives Meta/Google sont conservées pour toutes les campagnes.

2.4 /api/google-analytics/getAllTrackedEventsdaily
Payload adapté : client_id, start_date, end_date, previous_start_date,
previous_end_date.
Retour : jours > streams > événements avec event_name et active_users.
Utilisé par : chart Distribution des événements.

2.5 /api/google-analytics/getAllTrackedEvents
Payload adapté identique au précédent.
Retour : événements agrégés courant/précédent, variation et events_by_stream.
Utilisé par : funnel onboarding 23 événements et répartition Desktop/Mobile.

2.6 /api/meta-ads-data/getAppsFlyerCampaignPerformance
Payload : client_id, since, until.
Retour flexible : campaigns/data ou groupes meta_ads/google_ads.
Utilisé par : grande table AppsFlyer Campaign Performance.

2.7 /api/appsflyer/getAppsFlyerDailyStats
Payload : client_id, since, until.
Retour quotidien et total : installs Android, iOS et total, ainsi que métriques
d'onboarding AppsFlyer.
Utilisé dans Détails quotidien. Les installs sont ensuite remplacées par GA4 si
getGa4DailyOnboarding fournit la même date, car GA4 est fusionné en dernier.

2.8 /api/google-analytics/getGa4DailyOnboarding
Payload : client_id, since, until.
Retour : install Android/iOS/total, onboarding_start Android/iOS/total et
contract_signed Android/iOS/total.
Mapping interne : contract_signed devient onboarding_success.
Utilisé par : charts et cartes de la vue Détails.

2.9 /api/meta-ads-data/getMetaOnboardingDaily
2.10 /api/google-ads/getGoogleAdsOnboardingDaily
Payload : client_id, since, until.
Retour pour chaque plateforme : installs, onboarding_start, onboarding_success,
totaux et jours.
Utilisé par : cartes Global Overview, ratios globaux, funnel paid media et donuts.
Les valeurs Meta + Google ne sont fusionnées que si les deux plateformes sont
présentes pour le total ou la journée concernée.

2.11 /api/meta-ads-data/getMetaOnboardingMonthly
2.12 /api/google-ads/getGoogleAdsOnboardingMonthly
Payload : client_id, since=2026-07-01, until=date du jour.
Retour mensuel : installs, starts et successes.
Utilisé par : charts mensuels Onboarding Success et coût/Onboarding Success.

2.13 Source CRM locale
Fichier : src/data/mensuel-projete/funnel snapshot.csv.
Clé unique : device_id. Date utilisée exclusivement : jour.
La colonne jour_selection est volontairement ignorée.
En cas de doublon, la ligne la plus récente gagne ; à date égale, l'état le plus
avancé gagne selon : FINALISE > SIGNE_PROVISIONING > ESCALATED_CRC >
ABANDON_SIGNATURE > ABANDON_PARCOURS > EN_COURS > ABANDON_AMONT.
Utilisé par : CDC, coût/CDC, objectifs mensuels et entonnoir CRM.


3. FILTRE, PERIODES ET REGLES COMMUNES
-------------------------------------

- Format date accepté : YYYY-MM-DD.
- Les dates avant 2026-07-01 sont ramenées au 2026-07-01.
- Une date de fin future est ramenée à hier.
- Si since > until, since devient until.
- La période précédente a normalement la même durée que la période courante.
- Fenêtre hebdomadaire : 7 jours terminant à until.
- Donnée partielle : fenêtre incomplète ou source_status différent de complete.
- Valeur manquante ou dénominateur nul : affichage N/A ou tiret, jamais division par zéro.
- Variation : (valeur courante - valeur précédente) / valeur précédente * 100.
- Pour les volumes, une hausse est positive. Pour les coûts, une baisse est positive.
- Les derniers 7 jours de conversion sont signalés comme incomplets.


4. VUE GLOBALE - 10 CARTES PRINCIPALES
--------------------------------------

Un filtre permet Meta + Google, Meta seulement ou Google seulement.

4.1 Campagnes actives
Métrique : nombre actif total ou par plateforme.
API : getActiveCampaigns ; fallback possible sur le total du funnel.
Comparaison : même métrique sur période précédente si disponible.

4.2 Dépense publicitaire
Métrique : total_spend, meta_spend ou google_spend selon le filtre.
API : getAppsFlyerDailyFunnel.
Fallback : somme des lignes quotidiennes si le total agrégé manque.
Unité : MAD.

4.3 Installs
Métrique : installs de la ou des plateformes payantes.
API : getMetaOnboardingDaily + getGoogleAdsOnboardingDaily.
Formule tous : installs Meta + installs Google.

4.4 Coût / install (CPI)
APIs : funnel de dépense + onboarding daily Meta/Google.
Formule : dépense filtrée / installs filtrés.

4.5 Démarrages onboarding
APIs : onboarding daily Meta/Google.
Métrique : onboarding_start Meta, Google ou somme des deux.

4.6 Coût / démarrage
Formule : dépense filtrée / démarrages filtrés.

4.7 Onboardings réussis
APIs : onboarding daily Meta/Google.
Métrique : onboarding_success Meta, Google ou somme des deux.

4.8 Coût / réussite
Formule : dépense filtrée / réussites filtrées.

4.9 CDC
Source : CSV CRM local.
Métrique : dossiers uniques FINALISE et isCDC=TRUE dans la période.
Attention : cette carte n'est pas ventilée par plateforme même si le filtre change.

4.10 Coût / CDC
Formule : dépense filtrée / nombre CDC CRM.


5. VUE GLOBALE - CHARTS, TABLES ET FUNNELS
------------------------------------------

5.1 Distribution des événements
Type : courbes multiples sélectionnables.
API : getAllTrackedEventsdaily.
X : date ; Y : active_users.
Pour un événement et une date, addition de active_users dans tous les streams.
Les événements sont classés par total décroissant ; top 3 sélectionné par défaut.
Les points sont masqués si la période dépasse 31 jours.

5.2 Paid Media Acquisition Funnel
Type : table funnel comparative.
API principale : getAppsFlyerDailyFunnel, enrichie par onboarding daily Meta/Google.
Etapes : Dépense > Impressions > Clics > Installs > Démarrages > Réussites.
Clics : total_paid_clicks, sinon meta_clicks + google_clicks.
Conversion vers étape suivante : valeur étape suivante / valeur étape courante * 100.
Particularité : aucune conversion n'est calculée depuis Dépense vers Impressions.
Chaque ligne affiche valeur courante, précédente et variation.

5.3 Cost Efficiency Metrics
Sources : funnel enrichi + CDC CRM.
CPM = dépense / impressions * 1 000.
CPC = dépense / clics.
CPI = dépense / installs.
Coût/démarrage = dépense / onboarding starts.
Coût/réussite = dépense / onboarding successes.
Coût/CDC = dépense / CDC.
La baisse d'un coût est colorée positivement.

5.4 Install vers démarrage
Type : courbe quotidienne.
Sources : dépenses/funnel enrichi par onboarding Meta+Google.
Formule jour : onboarding_start / installs * 100.

5.5 Démarrage vers réussite
Type : courbe quotidienne.
Formule jour : onboarding_success / onboarding_start * 100.

5.6 Cost Evolution (Daily)
Type : courbes quotidiennes.
Coût/réussite = total_spend / onboarding_success.
Coût/CDC = total_spend / cdc_accounts.
La courbe CDC est totalement masquée si aucune journée ne contient cdc_accounts.
Dans ce cas, un message explique que l'API doit fournir ce champ quotidien.

5.7 AppsFlyer Campaign Performance
Type : table par campagne.
API : getAppsFlyerCampaignPerformance.
Colonnes de base : campagne, plateforme, statut.
Colonnes métriques affichées seulement si au moins une ligne a une valeur non nulle :
dépense, impressions, installs, CPI, démarrages, coût/démarrage, réussites,
coût/réussite, install>demarrage et demarrage>reussite.
Formules : CPI=dépense/installs ; coût start=dépense/starts ; coût success=
dépense/successes ; taux install>start=starts/installs*100 ; taux start>success=
successes/starts*100.
Le composant accepte plusieurs noms de champs alternatifs pour tolérer les formats API.

5.8 Onboarding funnel 23 events
Type : funnel/barres comparant période courante et précédente.
API : getAllTrackedEvents.
Filtre : tous, iOS ou Android via events_by_stream.
Evénements, dans l'ordre : first_open, onboarding_start, otp_requested_phone,
otp_verified_phone, otp_requested_email, otp_verified_email, document_scan,
personal_data_confirmation, face_verification_begin, address_confirmation,
job_selection, monthly_revenue_selection, fund_origin_selection,
international_operations, fatca_status_declared, card_begin, see_cards,
confirm_card, card_reception, card_agency_confirmation, card_signed,
card_confirmation, contract_signed.
Perte entre étapes : (étape courante - étape précédente) / étape précédente * 100.
Hauteur visuelle normalisée sur le maximum courant/précédent.

5.9 SEO Device Traffic
Type : deux donuts, période courante et précédente.
API : getAllTrackedEvents.
Evénement recherché : session_start dans les streams desktop et mobile.
Valeur : active_users courant/précédent.

5.10 Coût par onboarding réussi, par campagne
Type : barres horizontales triées par coût croissant.
API : getOnboardingSuccessMetaGoogle.
Formule : spend_mad / onboarding_success.
Couleurs : vert <= 1 500 MAD ; orange entre 1 500 et moins de 5 000 ; rouge >= 5 000.
Les campagnes sans réussite, donc sans CPA calculable, sont exclues du chart.

5.11 Dépenses par plateforme
Type : donut Google Ads / Meta Ads.
Source : totals google_spend et meta_spend du funnel.

5.12 Démarrages onboarding par plateforme
Type : donut Google Ads / Meta Ads.
Source : getGoogleAdsOnboardingDaily + getMetaOnboardingDaily.

5.13 Réussites onboarding par plateforme
Type : donut Google Ads / Meta Ads.
Source : mêmes APIs ; métrique onboarding_success.


6. MODE DETAILS - BANDEAU DE CONTROLE
-------------------------------------

6.1 Pacing du jour
Formule : dépense du jour until / (budget mensuel planifié / jours du mois) * 100.
OK entre 60 % et 115 %, warning sinon.

6.2 Coût / onboarding
Fenêtre 7 jours. Formule : dépense 7 j / réussites 7 j.
OK <= 1 500 ; warning > 1 500 ; danger > 3 000 MAD.

6.3 Onboardings 7 j
Somme onboarding_success_active_users sur 7 jours.

6.4 Install > démarrage
Formule : somme starts 7 j / somme installs 7 j * 100.
Danger sous 10 %, OK sinon.

6.5 Campagnes actives
API getActiveCampaigns. Détail Google/Meta.
Danger si le résumé du funnel signale une campagne active à zéro dépense.


7. DETAILS QUOTIDIEN - CARTES ET CHARTS
---------------------------------------

Fusion des sources : funnel > AppsFlyer Daily Stats > GA4 Daily Onboarding.
Pour les installs/onboarding d'une même date, GA4 est la dernière source appliquée.

Cartes :
- Dépense J-1 : total_spend à until ; variation vs jour précédent.
- Installs J-1 : total et détail Android/iOS.
- Démarrages J-1 : onboarding_start.
- Réussites J-1 : onboarding_success, signalé incomplet.
- Dépense 7 j : somme total_spend.
- Coût/réussite : dépense 7 j / réussite 7 j ; cible 750, warning au-dessus,
  danger au-dessus de 3 000.

Charts :
7.1 Dépense quotidienne : barres empilées Google + Meta ; ligne rythme cible =
budget mensuel / nombre de jours du mois.
7.2 Répartition du jour : donut Google/Meta sur le dernier jour disponible.
7.3 Evolution installs et onboarding : 3 courbes installs, start, success.
7.4 Onboardings réussis/jour : barres + moyenne mobile 7 j ; derniers 7 jours
affichés comme fenêtre incomplète.
7.5 Coût par onboarding réussi : coût glissant = somme dépense fenêtre 7 j /
somme réussites fenêtre 7 j ; lignes cible 750 et arbitrage 3 000 MAD.
7.6 Installs par système : barres empilées Android/iOS.
7.7 Install > démarrage : starts/installs*100 par jour.
7.8 Démarrage > réussite : success/starts*100 par jour.


8. DETAILS HEBDOMADAIRE - CARTES ET CHARTS
------------------------------------------

Fenêtre : 7 jours terminant à until.

Cartes :
- Dépense semaine = somme total_spend.
- Onboardings réussis = somme onboarding_success.
- Coût/onboarding = dépense/réussites ; OK <=1 500, warning >1 500,
  danger >3 000.
- Budget sous la cible = part de dépense des campagnes dont CPA <=1 500.
- Part iOS volume = installs iOS / (iOS + Android) * 100.
- Part iOS réussites = success iOS / (iOS + Android) * 100.

Charts :
8.1 Coût par onboarding/campagne : même logique que 5.10.
8.2 Où va le budget : donut sous cible, au-dessus, non rapproché.
Sous cible : CPA <= 1 500. Non rapproché : campagne sans réussite/CPA.
Chaque part = dépense catégorie / dépense totale * 100.
8.3 Android contre iOS : barres 100 % comparant part des installs et part des
réussites sur 7 jours.
8.4 Détail par campagne : table triée par CPA croissant. Colonnes campagne,
dépense, réussites, coût, cible tenue/dépassée. Statut orange entre 1 500 et
moins de 5 000, rouge à partir de 5 000.


9. MODE OBJECTIFS - CARTES MENSUELLES
-------------------------------------

Horizon : juillet à décembre 2026.
Objectifs CDC : Juil 1 200 ; Août 1 300 ; Sept 1 300 ; Oct 3 300 ;
Nov 3 400 ; Déc 3 600.
Budgets MAD : Juil 2 100 000 ; Août 2 000 000 ; Sept 2 000 000 ;
Oct 4 600 000 ; Nov 4 800 000 ; Déc 5 000 000.

9.1 Comptes CDC
CRM : dossiers FINALISE et isCDC=TRUE dans la période.
Progression = CDC réels / objectif du mois * 100.

9.2 Comptes finalisés
CRM : dossiers uniques au statut FINALISE.
Objectif attendu = objectif CDC / 50 %.

9.3 Ratio CDC réel
Formule : CDC finalisés / tous comptes finalisés * 100.
Hypothèse plan : 50 %.

9.4 CPA par compte CDC
Formule : dépense période / comptes CDC.
Cible affichée : 1 450-1 500 MAD ; OK <=1 500.

9.5 Budget consommé
Formule : dépense période / budget planifié du mois * 100.

9.6 Dossiers uniques
Nombre de device_id uniques du snapshot CRM filtré.


10. MODE OBJECTIFS - CHARTS MENSUELS
------------------------------------

10.1 Comptes CDC contre objectif du plan
Barres par mois : CDC FINALISE/isCDC TRUE vs objectifs CDC ci-dessus.

10.2 Ratio de comptes CDC
Barres : CDC finalisés / finalisés * 100. Ligne cible : 50 %.

10.3 Entonnoir des dossiers
Snapshot CRM complet et dédupliqué.
Etapes : Abandon amont ; En cours (inclut ESCALATED_CRC) ; Abandon parcours ;
Abandon signature ; Provisioning (SIGNE_PROVISIONING) ; Finalisé.

10.4 Coût par CDC par mois
Formule : dépense mensuelle / CDC mensuels. Ligne cible : 1 500 MAD.

10.5 Onboarding Success contre objectif du plan
Réel : onboarding_success mensuel Meta + Google.
Objectif : 2 * objectif CDC, cohérent avec une hypothèse CDC de 50 %.

10.6 Coût par Onboarding Success par mois
Formule : dépense mensuelle / successes Meta+Google.
Ligne cible : 750 MAD.

10.7 Budget consommé contre plan
Barres : budget planifié vs somme réelle total_spend par mois.


11. PAGE STATISTIQUES
---------------------

La page /statistiques recrée volontairement ses propres appels et ne réutilise
pas les données déjà chargées par la page d'accueil. Elle affiche la partie
analytique de la Vue globale : 10 cartes, distribution événements, paid funnel,
cost efficiency, deux taux de conversion, cost evolution, table campagnes,
funnel 23 événements, device traffic, CPA campagne et trois donuts plateforme.
Les formules et APIs sont identiques aux sections 4 et 5.


12. PAGE DE CONTROLE APPSFLYER
------------------------------

Route : /appsflyer. Période maximale J-2.
Source : base locale via loadAppsFlyerMediaReport, tables production/staging,
état du cron, historique et journal d'erreurs.

Cartes : état cron, jours couverts, prochaine période, anomalies détectées.
Anomalies = dates manquantes + jours avec métriques manquantes + erreurs.
Table quotidienne : installs, starts, successes, install>start, start>success,
install>success. Chaque taux = destination/source*100.
Autres blocs : dates manquantes, qualité métriques, dernières exécutions,
dernières erreurs et état d'arrêt de synchronisation.


13. SEUILS ET OBJECTIFS RECAPITULATIFS
--------------------------------------

- Cible coût/onboarding quotidienne : 750 MAD.
- Cible CPA campagne/hebdomadaire : 1 500 MAD.
- Seuil critique/arbitrage : 3 000 MAD.
- Couleur campagne rouge : CPA >= 5 000 MAD.
- Seuil install>start : 10 %.
- Pacing acceptable : 60 % à 115 % du rythme quotidien planifié.
- Hypothèse ratio CDC : 50 %.
- Cible coût CDC : 1 450 à 1 500 MAD selon la carte ; ligne chart 1 500.
- Fenêtre de prudence conversion : 7 derniers jours.


14. CHAMPS DE DONNEES PRINCIPAUX
--------------------------------

Media : date, meta_spend, google_spend, total_spend,
total_paid_impressions, total_paid_clicks, meta_clicks, google_clicks.
Acquisition : appsflyer_installs_android, appsflyer_installs_ios,
appsflyer_installs_total.
Onboarding : onboarding_start_active_users et déclinaisons OS,
onboarding_success_active_users et déclinaisons OS.
Campagne : campaign_id, campaign_name, platform, status, spend_mad,
impressions, installs, onboarding_start, onboarding_success.
CRM : jour, device_id, current_step, journey_status, isCDC.
GA4 événements : event_name, active_users, current_value, previous_value,
variation_percent, stream_name.


15. POINTS D'ATTENTION FONCTIONNELS
-----------------------------------

- Plusieurs sources mesurent des notions proches. La vue globale utilise les
  endpoints d'onboarding payant Meta/Google pour installs/starts/successes,
  tandis que la vue Détails enrichit avec AppsFlyer puis GA4.
- Les coûts viennent toujours de la dépense publicitaire du funnel.
- Une absence de donnée n'est pas transformée en performance nulle lorsqu'elle
  peut être identifiée : le dashboard préfère N/A.
- Les conversions par campagne peuvent être natives Meta/Google si le
  rapprochement AppsFlyer n'est pas complet.
- Les données CDC quotidiennes ne sont pas actuellement garanties ; la courbe
  coût/CDC peut donc être absente même si la carte CDC CRM existe.
- La carte CDC globale est issue du CRM et n'est pas attribuée à Meta/Google.
- Les objectifs et budgets mensuels sont codés explicitement pour juillet à
  décembre 2026 ; hors de cet horizon, les objectifs mensuels peuvent être nuls.
- Le chart Distribution additionne un même événement sur tous les streams ; le
  funnel onboarding permet au contraire de filtrer un stream iOS/Android.


FIN DU DOCUMENT
===============