UC-10 — Consultation des statistiques

Acteur : Admin / Superviseur / Gestionnaire But : Consulter les indicateurs et statistiques de l'organisation

Trigger

Un utilisateur ouvre le tableau de bord.

Préconditions

• Permission analytics.read

Endpoints

Tableau de bord organisation

GET /api/v1/admin/org/stats/dashboard

Statistiques détaillées (période requise from/to)

GET /api/v1/admin/org/stats/revenue-by-type?from=2025-06-01T00:00:00&to=2025-06-30T23:59:59
GET /api/v1/admin/org/stats/top-products?from=...&to=...
GET /api/v1/admin/org/stats/sites-revenue?from=...&to=...
GET /api/v1/admin/org/stats/hourly?from=...&to=...
GET /api/v1/admin/org/stats/holders?from=...&to=...
GET /api/v1/admin/org/stats/recharges?from=...&to=...
GET /api/v1/admin/org/stats/sales?from=...&to=...
GET /api/v1/admin/org/stats/balances?from=...&to=...
GET /api/v1/admin/org/stats/reservations?from=...&to=...
GET /api/v1/admin/org/stats/stock?from=...&to=...      (permission stock.read)

Analytics avec comparaison de périodes

GET /api/v1/admin/org/analytics/overview?from=...&to=...&compare_from=...&compare_to=...
GET /api/v1/admin/org/analytics/growth?from=...&to=...
...

Stats basiques et export

GET /api/v1/stats/daily?from=2025-06-01&to=2025-06-30
GET /api/v1/stats/export?from=2025-06-01&to=2025-06-30

Endpoints inexistants

Il n'existe pas de /stats/dashboard, /stats/transactions ni /stats/balance. Les stats d'organisation sont sous /admin/org/stats/*; les stats globales sous /admin/system/stats/* (permission stats.exhaustive.read).

Flow

sequenceDiagram
    participant Admin
    participant Dashboard
    participant API
    participant DB

    Admin->>Dashboard: Ouvrir le tableau de bord
    Dashboard->>API: GET /admin/org/stats/dashboard
    API->>DB: Agrégations (cartes, transactions du jour, stock…)
    API-->>Dashboard: {cards, transactions_today, products, holders…}
    Dashboard->>Admin: Afficher les KPIs

    Admin->>Dashboard: "Revenus du mois"
    Dashboard->>API: GET /admin/org/stats/revenue-by-type?from=...&to=...
    API->>DB: SELECT ... GROUP BY type
    API-->>Dashboard: {data: [{type, count, total_cents}]}

Exemple de réponse (dashboard)

{
  "cards": { "total": 1250, "active": 1100, "unassigned": 100, "deactivated": 40, "lost": 10 },
  "transactions_today": {
    "count": 320,
    "amount_cents": 850000,
    "amount_formatted": "850 000 FCFA",
    "by_type": [],
    "currency": "XOF"
  },
  "products": { "total": 42, "low_stock": 3 },
  "sites_count": 2,
  "pending_reservations": 5,
  "holders": { "total": 1200, "new_this_month": 45 },
  "active_operators_today": 8,
  "currency": "XOF"
}

Permissions

Permission	Description
analytics.read	Stats et analytics d'organisation
stats.exhaustive.read	Stats système cross-organisation

Erreurs

error_code	Description
Validation	from/to manquants sur endpoints à période
Forbidden	Permission insuffisante

Voir Statistiques et Analytics.