Note de réalignement — Starlink Priority, côté application mobile

Cette note corrige trois malentendus du briefing d’origine et dit ce que l’application doit changer. Le contrat détaillé reste CONTRAT-API-STARLINK-PRIORITY.

1. Ce qui a changé, en trois phrases

Tout écran qui affiche un montant Starlink doit porter la mention facture_par: "STARLINK". Sans elle, le gérant croit qu’il paie chez nous.

2. Le parc a DEUX populations — c’est le point le plus important

Certains gérants vendent via notre RADIUS : leurs ventes arrivent dans nos registres. D’autres font tourner Mikhmon en local sur le routeur : leurs ventes n’arrivent jamais chez nous.

[!WARNING] Le backend ne peut pas deviner ce qu’un gérant Mikhmon a encaissé. Sans vous, son bilan l’affiche comme déficitaire alors qu’il gagne sa vie.

L’application, elle, sait lire Mikhmon sur le routeur. C’est à elle de combler le trou.

Comment le backend le signale

GET /starlink/priority/{nasId}/rentabilite → objet recettes :

connu: false ne veut pas dire zéro. Quand il vaut false, bilan.benefice_xof, bilan.recettes_xof et bilan.rentable valent null : n’affichez ni « 0 F », ni « non rentable », mais recettes.avertissement.

Ce que l’application doit remonter

PUT /api/v1/radius/starlink/priority/{nasId}/recettes
{ "recettes_xof": 61000, "source": "MIKHMON_LOCAL" }

• source vaut MIKHMON_LOCAL quand le montant est lu sur le routeur, SAISIE_MANUELLE quand le gérant l’a tapé. Ne mettez pas MIKHMON_LOCAL sur un chiffre saisi à la main : plus tard, personne ne saura si un montant a été mesuré ou estimé.
• Le montant est rattaché au cycle en cours par le serveur. Celui du mois dernier ne resservira pas — il afficherait un bénéfice qui n’existe plus.
• Remontez-le une fois par jour, et au moins la veille du renouvellement : c’est la dernière occasion d’avoir un bilan de cycle juste.

La fenêtre à utiliser pour interroger Mikhmon

N’utilisez pas le mois calendaire. Prenez cycle.debut et cycle.renouvellement rendus par GET /starlink/priority/{nasId} : le cycle Starlink démarre au jour de facturation du client (le 9, le 17…), pas le 1er, et il est calculé dans le fuseau du routeur. Un total calculé sur le mois calendaire ne correspondra à rien.

recettes_xof = somme des ventes Mikhmon entre cycle.debut (inclus) et cycle.renouvellement (exclu)

Ne les additionnez pas

Les recettes déclarées remplacent les recettes enregistrées, elles ne s’y ajoutent pas. Un gérant en mode mixte verrait sinon ses ventes RADIUS comptées deux fois. Règle de la maison : on n’additionne jamais deux registres.

3. La page « rentabilité » — ce qui doit y figurer

"bilan": {
  "cout_xof": 24400, "recettes_xof": 61000, "benefice_xof": 36600,
  "marge_pct": 60, "rentable": true,
  "cout_par_go": 488, "recette_par_go": 1220
}

• benefice_xof peut être négatif — affichez-le tel quel. Un tableau de bord qui ne sait dire que de bonnes nouvelles ne convainc personne, et le gérant qui perd de l’argent est justement celui qui a besoin de le savoir.
• cout_par_go est le chiffre qui fait changer de forfait. 1 To payé pour 200 Go consommés, c’est 545 F le gigaoctet au lieu de 109. Mettez-le en évidence : la jauge de quota ne dit pas ça.
• marge_pct est calculée sur les recettes, pas sur le coût. Ne la recalculez pas.

4. Rappels de fin de cycle — ce que l’app doit faire du push

Deux notifications de type STARLINK_CYCLE arrivent : à J-3 avant la fin du cycle, et au renouvellement.

Un appui doit ouvrir l’écran de mise à jour du forfait, pas la page d’accueil. C’est l’action qu’on demande au gérant : son abonnement a peut-être changé, et nous ne pouvons pas le savoir.

Affichez la règle de reconduction tacite sur cet écran : sans mise à jour de votre part, le cycle repart à l’identique. Le silence est une réponse — encore faut-il qu’il le sache.

5. Trois nombres, trois natures — à ne jamais confondre à l’écran

consommation.source vaut toujours MESURE_JSERVICES. Nous ne lisons pas le compte Starlink : nous comptons ce qui passe par le routeur, Starlink compte ce qui passe par la parabole — donc aussi ce qui la partage sans passer par nous. consommation.ecart_gb expose la différence dès que le gérant saisit son relevé.

6. Récapitulatif des appels

7. À cocher avant publication

• [ ] Aucun montant Starlink affiché sans « facturé par Starlink ».
• [ ] Aucun prix codé en dur : tout vient de /grille.
• [ ] connu: false n’affiche ni « 0 F » ni « non rentable ».
• [ ] Les recettes Mikhmon sont calculées sur cycle.debut → cycle.renouvellement, pas sur le mois calendaire.
• [ ] source: "MIKHMON_LOCAL" seulement quand le montant est lu, jamais quand il est saisi.
• [ ] Les recettes déclarées ne sont jamais additionnées aux recettes enregistrées.
• [ ] benefice_xof négatif est affiché.
• [ ] Le push de fin de cycle ouvre l’écran de mise à jour du forfait.
• [ ] La règle de reconduction tacite est écrite à l’écran.
• [ ] La jauge de consommation porte « estimation », pas « consommation Starlink ».