Notifications SMS (Passerelle légère)

Statut : proposition d’architecture — non implémenté. Aucun code n’existe encore dans apps/api pour ce module ; ce document sert de base de conception avant développement.

1. Contexte et Exigence

L’application doit pouvoir notifier ses utilisateurs par SMS (ex : confirmation de commande, compte bloqué par un administrateur, code de vérification) en utilisant une technologie de communication légère, avec deux contraintes :

Pas d’API SMS commerciale (Twilio, Vonage, etc.) — ces services sont payants à l’envoi, nécessitent un compte externe et une dépendance à un tiers.
Utilisation d’une passerelle SMS (SMS gateway) auto-hébergée à la place.

2. Options envisagées

Option	Principe	Avantages	Inconvénients
1. Téléphone Android en passerelle (retenue)	Un smartphone Android + SIM active fait tourner une app open-source qui expose une API HTTP locale ; le backend l’appelle pour déclencher l’envoi.	Zéro matériel à acheter (réutilise un vieux téléphone), gratuit, mise en place en ~15 min, aucune dépendance externe en mode local.	Le téléphone doit rester allumé et connecté en permanence ; pas la solution “bas niveau” d’un vrai modem GSM.
2. Modem GSM USB + Gammu	Un dongle GSM USB + SIM, piloté par `gammu-smsd` (service Windows natif) en AT commands.	Passerelle SMS au sens propre (couche matérielle/protocole GSM directe), pertinent si l’exigence vise la compréhension télécom.	Matériel à acheter (~15-30€), configuration plus longue, envoi plus lent.
3. playSMS	Plateforme web PHP+MySQL au-dessus de Kannel/d’un modem, avec sa propre API HTTP.	Interface d’administration des envois toute faite.	Overkill pour de simples notifications ponctuelles ; Kannel est pénible à faire tourner nativement sous Windows.

3. Solution retenue : téléphone Android en passerelle locale

Outil open-source : SMS Gateway for Android (projet capcom6). L’app installée sur un smartphone dédié (avec carte SIM active) expose un serveur HTTP local sur le réseau Wi-Fi/LAN, protégé par Basic Auth.

Pourquoi ce choix plutôt que le mode “relais cloud”

L’app propose aussi un mode relais cloud (le téléphone se connecte à un serveur public sms-gate.app, appelé à la place du téléphone directement). Ce mode réintroduit une dépendance à un service tiers — non retenu ici tant que le backend et le téléphone tournent sur le même réseau local de développement.

4. Intégration prévue côté `apps/api`

Le modèle User (apps/api/prisma/schema.prisma) possède déjà un champ phone obligatoire, renseigné à l’inscription — aucune migration nécessaire pour savoir à qui envoyer un SMS.
Ajout d’un nouveau module SmsModule / SmsService encapsulant l’appel HTTP vers la passerelle :
- Variables d’environnement à prévoir : SMS_GATEWAY_URL, SMS_GATEWAY_USERNAME, SMS_GATEWAY_PASSWORD.
- Méthode sendSms(phoneNumber: string, message: string) faisant un POST /message vers la passerelle.
Points d’appel envisagés (en complément des toasts sonner déjà en place côté front, qui ne couvrent que l’UI in-app) :
- Confirmation de commande (OrdersService/PaymentsService).
- Blocage d’un compte par un administrateur (UsersService.update → isActive: false).
- Décision de validation d’un compte vendeur (SellersService.validate → vendorStatus: APPROVED/REJECTED) — aujourd’hui notifiée uniquement par SSE (vendor.status.decided), donc uniquement si le vendeur est connecté au moment de la décision ; un SMS couvrirait le cas où il ne l’est pas. Voir Validation des comptes vendeur.

5. Mise en place pratique (matériel de test)

Installer l’APK “SMS Gateway for Android” sur un smartphone disposant d’une carte SIM active avec forfait SMS.
Dans l’app : activer le mode Local Server, définir un couple username/mot de passe.
Désactiver l’optimisation de batterie pour l’app (sinon Android tue le service en arrière-plan).
Relever l’IP locale du téléphone affichée dans l’app — il doit être sur le même réseau Wi-Fi que la machine faisant tourner apps/api.
Configurer les variables d’environnement du SmsService avec cette IP et les identifiants.

6. Limites à documenter

Contrainte réseau : la passerelle doit être joignable en HTTP depuis apps/api. En dev local, aucun souci ; en cas de déploiement cloud de l’API, il faudrait soit exposer le téléphone publiquement (tunnel, IP fixe), soit basculer vers le mode relais cloud de l’app.
Fiabilité “grand public” : un smartphone n’est pas conçu comme serveur 24/7 (redémarrages, coupures réseau, épuisement du quota SMS du forfait). Acceptable pour un contexte labo/démo, à réévaluer pour une vraie mise en production.
Coût réel : gratuit si réutilisation de matériel déjà possédé ; chaque SMS envoyé consomme le forfait/crédit de la carte SIM comme un SMS humain classique.