Stats2 — Guide développeurs

But : collecte Deciplus → SQLite (staging + marts) + pages de debug. Cette page est vivante (à mettre à jour au fil de l’eau).

Principes de synchronisation

• Incrémental partout : on ne persiste que les enregistrements nouveaux ou modifiés.
• Chaque item est stocké en staging avec un payload_hash (SHA1 du JSON brut).
• Si le hash est identique à celui déjà en base, l’item est skippé (pas d’UPDATE, pas de write inutile).
• Si une date de mise à jour est fournie par l’API, elle est stockée dans source_updated_at (utile pour audit/debug).
• Les watermarks (s2_wm::...) restent en place quand l’API supporte des paramètres « changed since ».

Architecture

• stats2/api.php : API interne (ETL + endpoints de debug).
• stats2/lib/deciplus.php : client HTTP Deciplus (auth/token + GET) avec cache token.
• stats2/lib/http.php : wrapper cURL (timeouts 15s connect / 45s total).
• stats2/lib/db.php : init SQLite + migrations.
• stats/sql/003_extra_endpoints.sql : tables planning (activities/resources/schedules/lessons).
• stats/sql/004_incremental.sql : colonnes payload_hash / source_updated_at (incremental).

Règles métier

Règles appliquées dans stats2/dashboard2.php (KPIs, transformation, croissance, export).

Catégorisation membre

• Un membre est dans la population analysée si son payload contient category = "Client" (détection tolérante sur plusieurs clés).

Produits spéciaux

Produit	Rôle	Impact KPIs
15 — Séance d'essai EMS	Essai gratuit	Exclu des actifs payants, exclu des gains. Sert au KPI essais et à la perte fin d’essai (si essai seul et plus rien derrière).
99 — Abonnement Cadres et Direction hôtels	Gratuit	Exclu des actifs payants, exclu des gains et croissance. KPI volume séparé.
96 — 1 coaching EMS (40€)	Séance unitaire	Exclu des actifs payants, exclu des gains, exclu de la croissance et exclu de la conversion essai. KPI volume possible (audit).

Définitions KPI (pilotage)

• Actif payant à date : membre “Client” avec ≥1 contrat actif dont le produit n’est pas dans {15, 99, 96}.
• Prospect : membre avec essai 15 actif et sans contrat payant actif (ni 99, ni 96) — utilisé pour debug, mais non compté dans les actifs payants.
• Gain (payants) : membre dont la première date de début d’un contrat “payant” (produit hors {15,99,96}) est dans l’intervalle.
• Perte (total) = Perte payants + Perte fin d’essai :
• Perte payants : payant actif au début → plus payant actif à la fin.
• Perte fin d’essai : essai 15 “seul” au début → plus aucun contrat actif à la fin.
• Churn : calculé sur la base payante uniquement : perte_payants / base_payants_début.
• Base fin de mois (courbe) : nombre de payants actifs au dernier jour du mois.

Transformation des essais par vendeur

• On attribue 1 essai par membre : le premier essai (id 15) du membre dans la période.
• Non transformé si aucun contrat payant (hors {15,99,96}) ne démarre après l’essai.
• Transformé si le premier contrat payant (hors {15,99,96}) démarre dans les 30 jours suivant cet essai.
• Le vendeur provient du champ sold_by_user_id du contrat essai, résolu via stg_users (first_name/last_name).

Moteurs de croissance (zones)

• La zone (salle) est la zone_id du membre (stg_members.zone_id).
• Gain zone : gains payants des membres de la zone.
• Perte zone : pertes payants des membres de la zone.
• Net zone = gain − perte.

Indicateurs par membre (audit actifs payants)

• Endpoint : dashboard2.php?op=members_indicators (JSON) ou &as=csv (export CSV).
• Champs : first_free_start (15/99), first_paid_start (hors {15,99,96}), last_paid_end, active_paid_at.

Procédure ETL

GET stats2/api.php?op=bootstrap
GET stats2/api.php?op=run
GET stats2/api.php?op=reset

Note : items_ingested = nb d’items réellement écrits (nouveaux/modifiés), items_fetched = nb reçus depuis Deciplus.

Endpoints internes (stats2/api.php)

• ?op=status
• ?op=bootstrap / ?op=reset / ?op=run
• ?op=tables / ?op=rows / ?op=payload
• ?op=ops_kpi / ?op=planning_kpi / ?op=pilotage / ?op=series

Sources Deciplus (GET)

• /zones, /users, /products, /members, /contracts
• /visits (scope requis), /payment-schedules (scope requis)
• /activities, /resources, /schedules (peut être absent), /lessons-calendar

TODO

• Confirmer les paramètres « changed since » / « lastUpdateDateFrom » sur tous les endpoints (pour réduire encore le volume fetch).
• Identifier l’endpoint planning exact si /schedules est absent (404).
• Scopes manquants à activer selon besoins : payment-schedules:read, visits:read, activities:read, resources:read, lessons-calendar:read.