# Prompt de régénération — Shaka Crew Ce document décrit entièrement une application web communautaire pour windsurfers. Il est autonome : il ne suppose aucun accès au code d'origine. Un assistant de code doit pouvoir reconstruire, à partir de lui seul, une application fonctionnellement équivalente, avec la pile technique de son choix, sauf mention contraire en section 6. Toute l'interface est en **français**, sur un ton familier (tutoiement). Les textes cités entre guillemets sont ceux de l'application d'origine. On peut les reformuler s'ils gardent le même sens, sauf ceux qu'un critère d'acceptation vérifie. --- ## 1. INTENTION **Shaka Crew** est une application web installable (PWA), utilisable sur smartphone et sur ordinateur. Elle permet à une communauté de windsurfers de savoir **qui navigue où en ce moment**, avec les **conditions observées sur place** (taille de voile, vent estimé, direction, vagues). Elle sert aussi à annoncer les **sessions prévues** dans les 14 jours à venir et à **organiser le covoiturage** vers les spots. Elle s'adresse à un groupe de pratiquants qui se connaissent ou se cooptent, en France et dans les pays voisins. Le premier jeu de données compte 454 spots. Elle répond à un problème simple : les mesures des balises ne disent ni si quelqu'un est déjà à l'eau, ni avec quelle voile, ni l'état réel du plan d'eau. Les groupes de messagerie mélangent tout et ne gèrent ni les places en voiture, ni la vie privée. Elle remplace l'abonnement payant aux services de spots et de vent communautaires, du type Winds-Up premium, **pour la partie « observations des riders »**. Elle ne fournit pas de mesures de vent instrumentées (voir « Points à confirmer »). Elle remplace aussi les groupes WhatsApp et les tableurs de covoiturage. --- ## 2. PÉRIMÈTRE FONCTIONNEL Chaque fonctionnalité est décrite du point de vue de l'utilisateur : *ce qu'il fait → ce que le système répond*. Les seuils exacts sont dans la section 4. ### 2.1 Compte et connexion 1. **Créer un compte par e-mail.** L'utilisateur saisit un prénom ou pseudo, un e-mail et un mot de passe d'au moins 8 caractères, puis passe la vérification anti-robot si elle est activée. → Le système affiche « Vérifie ta boîte mail » et envoie un lien d'activation valable 48 h. La réponse est **toujours la même**, que l'adresse soit libre ou déjà prise : un compte existant n'est jamais modifié et son titulaire reçoit un e-mail adapté. 2. **Activer son compte.** L'utilisateur clique sur le lien reçu. → Son adresse est confirmée et il arrive sur l'écran de connexion avec le message « Adresse confirmée, bienvenue ! ». **Le clic ne connecte pas** : il faut ensuite saisir son mot de passe. Un lien expiré ou déjà utilisé affiche « Ce lien a expiré ou a déjà servi… ». 3. **Se connecter par e-mail et mot de passe.** → Le système ouvre une session sur l'appareil. Il passe d'abord par l'étape du second facteur si celui-ci est activé (point 6). Si l'adresse n'a pas été vérifiée, il refuse et renvoie automatiquement un lien d'activation. 4. **Se connecter avec Google** (bouton visible seulement si le serveur est configuré pour). → Le compte est créé à la première connexion, déjà vérifié, ou rattaché à un compte existant qui a la même adresse. 5. **Mot de passe oublié.** L'utilisateur saisit son e-mail. → Le système répond toujours « Si un compte existe pour cette adresse, un email vient de partir », avec un lien valable 2 h. Quand l'utilisateur choisit un nouveau mot de passe par ce lien, **tous ses appareils sont déconnectés**, il reçoit un e-mail d'alerte, puis il est connecté (en passant par le second facteur s'il est actif). 6. **Double authentification (TOTP).** Dans « Moi », l'utilisateur active la double authentification : il scanne un QR code avec une application d'authentification, puis saisit un premier code. → Le système affiche une seule fois 10 codes de secours, déconnecte tous ses autres appareils et lui envoie un e-mail. Ensuite, chaque connexion demande un code à 6 chiffres ou un code de secours. Il peut désactiver le second facteur en saisissant un code valide. Le second facteur est **obligatoire pour accéder à l'administration**. 7. **Appareils connectés.** L'utilisateur voit la liste de ses sessions ouvertes : navigateur et système déduits de l'agent utilisateur, dernière activité, date de connexion, et l'appareil actuel signalé. Il peut déconnecter un appareil précis ou « Déconnecter les autres appareils ». 8. **Se déconnecter.** → Les notifications de cet appareil sont désactivées, la session est fermée et l'utilisateur revient à l'écran de connexion. 9. **Inscription sur invitation** (mode optionnel du serveur). Sans lien d'invitation d'un membre, l'écran d'inscription affiche « Sur invitation » et explique qu'il faut demander le lien d'un membre. La connexion Google refuse elle aussi de créer un compte sans invitation valide. ### 2.2 Carte des spots 10. **Voir la carte.** À l'ouverture, la carte est cadrée sur la **zone par défaut** de l'utilisateur, ou sur la France métropolitaine s'il n'en a pas choisi. Elle affiche tous les spots : - les spots calmes : petit point neutre ; les **favoris** de l'utilisateur sont un peu plus gros et cerclés de la couleur principale ; - les spots où **des riders sont sur l'eau** : pastille **orange** qui pulse, avec le nombre de riders ; - les spots avec une **session prévue** dans les 7 jours : épingle **cyan** ; - au-dessus des spots, les **avatars des membres que l'utilisateur suit** : anneau orange plein s'ils sont sur l'eau, contour cyan pointillé s'ils ont une session prévue dans les 7 jours. Les « stars » sont plus grandes, avec un halo doré et un badge ★. On montre au plus 3 avatars, puis « +N ». Une étiquette « sur l'eau » ou « prévu » répète l'état en texte. La carte se met à jour toute seule chaque minute. 11. **Chercher un spot.** Une barre de recherche flotte au-dessus de la carte. Elle ignore les accents et cherche dans le nom et la région. Sans saisie, elle propose les favoris et les spots actifs. → Au plus 8 résultats, favoris d'abord puis par nombre de riders. Le clavier permet de naviguer (flèches, Entrée, Échap). 12. **Ouvrir la fiche d'un spot** (clic sur la carte ou dans la recherche). → La carte se centre sur le spot et un panneau s'ouvre. C'est une feuille repliable en bas de l'écran sur téléphone et une carte latérale sur ordinateur. Le panneau contient : région et nom, bouton favori (étoile), boutons **« J'y suis »** et **« J'y vais »**, puis les rubriques « Vents favorables », « Accès » et « Infos utiles » quand elles sont renseignées. Viennent ensuite la liste « Sur l'eau » (riders actifs avec leurs conditions et leur commentaire), « Dernières 24 h » (check-ins terminés) et « Sessions prévues ». Un administrateur voit en plus un lien « Modifier la fiche ». 13. **Mettre un spot en favori.** L'utilisateur touche l'étoile. → Un message confirme : « Ajouté à tes favoris : tu seras prévenu quand ça navigue ici ». L'utilisateur reçoit ensuite une notification quand quelqu'un navigue sur ce spot. 14. **Accueil de la carte** (panneau quand aucun spot n'est choisi). Il affiche : - « En direct » et le nombre de riders sur l'eau, ou « Calme plat pour l'instant » s'il n'y en a aucun ; - le check-in en cours de l'utilisateur, avec le bouton « Je sors de l'eau » ; - les raccourcis « J'y suis » et « Sessions » ; - une invitation à activer les notifications, que l'on peut fermer ; - « Mes amis » (où ils sont ou vont, avec une légende) ; - « Spots actifs » : les cartes des spots où l'on navigue, avec les dernières conditions et les avatars. 15. **Mode nuit.** L'utilisateur choisit le thème Auto, Clair ou Sombre. En thème sombre, le fond de carte est assombri mais les marqueurs gardent leurs vraies couleurs. ### 2.3 « J'y suis » : signaler qu'on est sur l'eau 16. **Trouver son spot par géolocalisation.** L'utilisateur touche « J'y suis » sur l'accueil. → L'application demande sa position et affiche « Localisation en cours… ». Elle montre ensuite les **8 spots les plus proches** avec leur distance (en mètres sous 1 km, sinon en km avec une décimale) et le nombre de riders déjà présents. Si la position est refusée ou indisponible, elle affiche « Impossible de te localiser » et invite à choisir le spot sur la carte. 17. **Faire un check-in.** L'utilisateur indique, **tous les champs étant facultatifs** : - la taille de voile en m² : réglage par pas de 0,1 et raccourcis 3,3 / 3,7 / 4 / 4,2 / 4,5 / 4,7 / 5 / 5,3 / 5,5 / 5,8 / 6 / 6,3 / 6,6 / 7 / 7,5 / 7,8 / 8,5 / 9,5 ; - le vent estimé en nœuds : curseur de 0 à 50, avec l'option « Je ne sais pas » ; - la direction d'où vient le vent : rose des vents à 8 directions N, NE, E, SE, S, SO, O, NO ; - les vagues : Plat, Clapot, < 1 m, 1 à 2 m, > 2 m ; - un commentaire (500 caractères) ; - le choix « Publier aussi sur le groupe Telegram », si ce groupe existe et que la visibilité de l'utilisateur est « Tous ». → Le système répond « Bonne session ! La communauté est prévenue. », ouvre la fiche du spot et notifie les personnes concernées (section 4.9). Faire un check-in **termine automatiquement** le check-in précédent : on n'est qu'à un seul endroit à la fois. 18. **Sortir de l'eau.** L'utilisateur touche « Je sors de l'eau ». → Son check-in se termine et le message « À la prochaine ! » s'affiche. Sans cette action, un check-in est considéré comme actif pendant **4 h**. ### 2.4 « J'y vais » : sessions prévues et covoiturage 19. **Annoncer une session.** Depuis la fiche d'un spot, l'utilisateur choisit : - un jour : 7 jours proposés en raccourcis, ou n'importe quelle date entre aujourd'hui et J+14 ; - un créneau : Matin, Après-midi ou Journée ; - un mode de covoiturage : **Pas besoin**, **Je conduis** (nombre de places de 1 à 8, 2 par défaut, lieu et heure de départ) ou **Je cherche** (lieu de départ) ; - un commentaire (300 caractères) ; - le choix de publier sur Telegram. → « Session enregistrée ». Si l'utilisateur a déjà une session **sur ce spot ce jour-là**, elle est modifiée au lieu d'être dupliquée. Le formulaire se préremplit avec la session existante de l'utilisateur sur ce spot. 20. **Voir les sessions prévues.** L'onglet « Sessions » liste les sessions des 14 prochains jours, groupées par jour (« Aujourd'hui », « Demain », puis le jour en toutes lettres). Trois filtres : Toutes / Covoiturage / Les miennes (celles que j'organise ou où j'ai réservé une place). 21. **Réserver une place.** Sur une session « Je conduis » qui a des places libres, l'utilisateur touche « Réserver une place ». → « Place réservée, le conducteur est prévenu ». Le conducteur reçoit une notification et un e-mail qui contient le téléphone du passager. Le passager voit alors le téléphone du conducteur. Les places sont dessinées sous forme de points, avec « N places libres » ou « Complet ». 22. **Libérer sa place.** → « Place libérée ». Le conducteur est prévenu par notification et par e-mail. 23. **Proposer d'emmener quelqu'un.** Sur une session « Je cherche » d'un autre membre, l'utilisateur touche « Proposer de l'emmener ». → La personne reçoit par e-mail et notification le prénom, le téléphone (s'il est renseigné) et l'e-mail du conducteur. Le téléphone de la personne qui cherche reste privé. Une seule proposition par conducteur et par demande. 24. **Modifier ou supprimer sa session.** La suppression demande confirmation. Si des passagers avaient réservé, ils sont prévenus de l'annulation du covoiturage, par e-mail et notification. Il en va de même si le conducteur passe sa session en « Pas besoin » ou « Je cherche ». ### 2.5 Groupe (amis) 25. **Voir tous les membres.** L'onglet « Groupe » a deux vues : « Mes amis » (les membres que je suis ou à qui j'ai demandé de suivre, ceux qui demandent à me suivre, ceux que j'ai bloqués) et « Tous les membres ». Une recherche sans accents filtre par prénom. Chaque membre affiche son avatar, son état (« Sur l'eau à X · il y a… », « X, demain », « Pas de session en vue » ou « Demande envoyée, en attente ») et la mention « te suit » le cas échéant. Un compteur rouge indique les demandes de suivi en attente. 26. **Suivre un membre ou le mettre en « Star ».** Un sélecteur à trois positions : Non suivi / Suivi / ★ Star. → Si la personne valide ses abonnés, la demande reste en attente (« Demande envoyée à X »). Sinon, le suivi est immédiat. Dans les deux cas la personne reçoit une notification. Une fois le suivi accepté, l'utilisateur est notifié des check-ins et des nouvelles sessions de ce membre, et le voit sur la carte. Les stars ressortent davantage, sur la carte comme dans les notifications (préfixe ★). 27. **Accepter ou refuser une demande de suivi.** 28. **Retirer un abonné.** 29. **Bloquer un membre**, avec confirmation. → Les abonnements dans les deux sens sont supprimés. Aucun des deux ne voit plus les sessions de l'autre ni ne peut suivre l'autre. La personne bloquée n'est pas informée. On peut débloquer. 30. **Signaler un membre aux administrateurs** : texte libre de 5 à 1 000 caractères. → « Signalement transmis aux administrateurs ». Les administrateurs reçoivent une notification. ### 2.6 Historique 31. **Mes sessions.** L'utilisateur voit ses statistiques globales (nombre de sessions, de spots différents, d'heures sur l'eau), puis ses check-ins du plus récent au plus ancien, groupés par mois. Chaque session affiche le spot, la date, les heures de début et de fin (« ~ » devant une fin estimée), la durée, les conditions, le commentaire, et **les membres présents sur le même spot au même moment** (ou « Session en solo »). La liste se charge par pages avec « Voir les sessions plus anciennes ». ### 2.7 Profil (« Moi ») 32. **Inviter des amis.** La page affiche le lien personnel d'invitation, un QR code à faire scanner sur la plage, et les boutons Partager (partage natif), WhatsApp, SMS et Copier. On peut aussi saisir l'e-mail d'un ami pour qu'il reçoive une invitation, avec vérification anti-robot. 33. **Profil.** Photo (choisie dans la galerie, recadrée en carré et réduite dans le navigateur, supprimable), prénom ou pseudo, téléphone (« Visible seulement par les personnes avec qui tu fais un covoiturage »). L'e-mail est affiché en lecture seule. 34. **Ma zone.** L'utilisateur cadre une mini-carte puis touche « Enregistrer cette zone ». → La carte principale s'ouvrira sur cette zone. Le bouton « France entière » réinitialise. 35. **Confidentialité.** - « Qui voit mes sessions ? » : Tous / Abonnés / Personne (mode fantôme) ; - « Valider mes nouveaux abonnés » : activé par défaut ; - « Telegram : publier par défaut » : précoche la case Telegram à chaque publication. Ce réglage n'apparaît que si le groupe Telegram est configuré. 36. **Notifications.** Un interrupteur active les notifications sur cet appareil, avec un bouton « Envoyer un test ». Sur iPhone, il faut d'abord ajouter l'application à l'écran d'accueil, et l'écran l'explique. 37. **Application.** Bouton « Installer Shaka Crew » quand le navigateur le permet, mode d'emploi pour iPhone sinon, ou « L'application est installée sur cet appareil ». 38. **Apparence** : thème Auto, Clair ou Sombre. 39. **Mes données.** - « Télécharger mes données » : un fichier JSON avec tout ce qui concerne l'utilisateur ; - « Supprimer mon compte » : un e-mail de confirmation part, avec un lien valable 2 h. La page ouverte par ce lien demande une dernière confirmation, puis efface tout définitivement. 40. **Version** de l'application, affichée en bas de la page. ### 2.8 Administration (rôle administrateur, second facteur obligatoire) 41. **Comptes.** Liste de tous les comptes, avec une recherche. Pour chacun : avatar, nom, e-mail, téléphone, badges (Google, Mot de passe, Email non vérifié, Bloqué), date d'inscription, date du dernier check-in, qui l'a invité et combien de personnes il a invitées. Actions possibles : changer le rôle (Membre / Admin), marquer l'adresse comme vérifiée, bloquer le compte, supprimer le compte (avec confirmation). L'administrateur ne peut ni se retirer ses propres droits, ni se bloquer, ni se supprimer. 42. **Spots.** Liste filtrable et bouton « Nouveau spot ». Une fiche d'édition contient : nom, région (avec suggestions tirées des régions existantes), position (clic sur une carte ou repère que l'on déplace, plus la saisie de la latitude et de la longitude), vents favorables, accès, infos utiles. On peut supprimer un spot, avec confirmation. Ses check-ins, sessions et favoris disparaissent avec lui. 43. **Signalements.** Les signalements à traiter (personne signalée, raison, auteur) sont listés en premier, puis les 50 derniers traités. Action : « Marquer comme traité ». Pour sanctionner, l'administrateur bloque le compte depuis l'onglet Comptes. 44. **Telegram.** Le bot est-il configuré ? Si non, la page explique les 3 étapes. Si oui, elle propose « Détecter mes groupes » (groupes où le bot a été ajouté récemment), le choix du groupe, « Envoyer un test », et deux interrupteurs pour les types de publication (« Quelqu'un est sur l'eau », « Nouvelles sessions prévues »). 45. **Journal.** Les actions d'administration et les événements de sécurité, du plus récent au plus ancien, chargés par pages de 100. Les événements sensibles sont en rouge. Chaque ligne affiche l'auteur (ou « système »), l'adresse IP et la date. ### 2.9 Pages publiques et application installable 46. **Confidentialité.** Page publique qui dit ce qui est conservé, qui voit quoi, combien de temps (positions 12 mois, invitations 30 jours), les services tiers utilisés et les droits de l'utilisateur. 47. **Application installable.** Elle a un nom, des icônes (dont une version adaptative), un écran de démarrage (écran de marque affiché tant que l'on ne sait pas si l'utilisateur est connecté, jamais plus de 8 s, et images de démarrage iOS) et deux raccourcis d'application (« Je suis sur l'eau », « Sessions prévues »). Elle fonctionne en orientation portrait. Les tuiles de carte récemment vues restent disponibles sans réseau sur la plage. 48. **Notifications système.** Un clic sur une notification ouvre l'application à la bonne page : la fiche du spot, les sessions, le groupe ou l'administration. --- ## 3. MODÈLE DE DONNÉES Les types sont logiques. « Texte » désigne une chaîne de caractères. Les dates sont des horodatages en UTC, sauf le **jour** d'une session, qui est une date calendaire sans heure. Sauf mention contraire, chaque entité a un identifiant entier auto-incrémenté. ### 3.1 Énumérations | Nom | Valeurs | |---|---| | Rôle | `USER`, `ADMIN` | | Usage d'un jeton | `VERIFY` (activation), `RESET` (mot de passe), `DELETE_ACCOUNT` (suppression), `MFA` (étape du second facteur en cours) | | Visibilité des positions | `EVERYONE`, `FOLLOWERS`, `NOBODY` | | Niveau de suivi | `FOLLOW`, `STAR` | | Statut de suivi | `PENDING`, `ACCEPTED` | | Direction du vent | `N`, `NE`, `E`, `SE`, `S`, `SO`, `O`, `NO` (direction **d'où vient** le vent, en notation française) | | Vagues | `FLAT` (plat), `CHOP` (clapot), `UNDER_1M` (< 1 m), `M1_2` (1 à 2 m), `OVER_2M` (> 2 m) | | Créneau | `MATIN`, `APREM`, `JOURNEE` | ### 3.2 Membre (User) | Champ | Type | Obligatoire | Défaut | Contraintes | |---|---|---|---|---| | id | entier | oui | auto | clé | | email | texte | oui | | **unique**, stocké en minuscules et sans espaces autour, 200 caractères max | | name | texte | oui | | 1 à 60 caractères après nettoyage | | phone | texte | oui | `""` | 30 caractères max | | passwordHash | texte | non | null | null = pas de mot de passe (compte Google seul, ou admin en attente d'activation) | | googleSub | texte | non | null | **unique** (identifiant Google) | | emailVerified | booléen | oui | false | | | role | Rôle | oui | `USER` | | | disabled | booléen | oui | false | compte bloqué par un administrateur | | inviteCode | texte | oui | aléatoire | **unique**, environ 8 caractères sûrs pour une URL, généré à la création | | invitedById | référence Membre | non | null | si le parrain est supprimé, la valeur devient null | | createdAt | date | oui | maintenant | | | avatarVersion | entier | oui | 0 | 0 = pas de photo ; augmente de 1 à chaque nouvelle photo | | homeSouth, homeWest, homeNorth, homeEast | décimaux | non | null | zone par défaut ; les 4 sont renseignés ensemble ou pas du tout | | shareTelegram | booléen | oui | **false** | réglage par défaut du consentement Telegram | | locationVisibility | Visibilité | oui | `EVERYONE` | | | followApproval | booléen | oui | **true** | les nouveaux abonnés doivent être acceptés | | totpSecret | texte | non | null | secret du second facteur (base32) | | totpEnabledAt | date | non | null | non null = second facteur actif | | totpLastStep | entier | non | null | dernier pas de temps de 30 s accepté (anti-rejeu) | | totpRecovery | liste de textes | oui | vide | empreintes des codes de secours **non utilisés** | ### 3.3 Session de connexion (Session) | Champ | Type | Contraintes | |---|---|---| | token | texte | **clé primaire** : empreinte cryptographique (SHA-256) du jeton secret envoyé au navigateur. Le jeton en clair n'est jamais stocké. | | id | entier | **unique**, auto-incrémenté : identifiant public, utilisé pour la liste des appareils | | userId | référence Membre | obligatoire, **indexé**, suppression en cascade | | expiresAt | date | obligatoire, échéance glissante (section 4.2) | | createdAt | date | défaut : maintenant | | lastSeenAt | date | défaut : maintenant | | userAgent | texte | défaut `""`, tronqué à 300 caractères | ### 3.4 Jeton envoyé par e-mail ou d'étape (EmailToken) | Champ | Type | Contraintes | |---|---|---| | token | texte | **clé primaire** : empreinte du jeton secret | | userId | référence Membre | obligatoire, suppression en cascade | | purpose | Usage | obligatoire | | expiresAt | date | obligatoire | Index sur (userId, purpose). Un membre a **au plus un jeton actif par usage** : en émettre un nouveau supprime les précédents du même usage. ### 3.5 Spot | Champ | Type | Obligatoire | Défaut | Contraintes | |---|---|---|---|---| | id | entier | oui | auto | | | name | texte | oui | | 1 à 120 caractères | | lat | décimal | oui | | −90 à 90 | | lon | décimal | oui | | −180 à 180 | | region | texte | oui | `"Autre"` | 60 caractères max ; une région vide devient « Autre » | | winds | texte | oui | `""` | 500 caractères max, retours à la ligne permis | | access | texte | oui | `""` | 2 000 caractères max | | notes | texte | oui | `""` | 4 000 caractères max | Le nom n'est pas unique. ### 3.6 Check-in (présence sur l'eau) | Champ | Type | Obligatoire | Défaut | Contraintes | |---|---|---|---|---| | id | entier | oui | auto | | | userId | Membre | oui | | cascade | | spotId | Spot | oui | | cascade | | createdAt | date | oui | maintenant | début de la session | | endedAt | date | non | null | null = pas terminé explicitement | | windKts | entier | non | | 0 à 80 | | windDir | Direction | non | | | | waves | Vagues | non | | | | sailSize | décimal | non | | 1 à 15 | | comment | texte | oui | `""` | 500 caractères max, retours à la ligne permis | Index : (spotId, createdAt), (userId, endedAt), (createdAt). ### 3.7 Session prévue (Plan) | Champ | Type | Obligatoire | Défaut | Contraintes | |---|---|---|---|---| | id | entier | oui | auto | | | userId | Membre | oui | | cascade | | spotId | Spot | oui | | cascade | | day | **date calendaire** | oui | | | | slot | Créneau | oui | `JOURNEE` | | | comment | texte | oui | `""` | 300 caractères max | | seats | entier | oui | 0 | 0 = ne propose pas de places ; 1 à 8 en mode « Je conduis » | | departure | texte | oui | `""` | 80 caractères max | | departureTime | texte | oui | `""` | vide ou `HH:MM` sur 24 h | | needsRide | booléen | oui | false | mode « Je cherche » | **Unique** sur (userId, spotId, day). Index sur (day, spotId). Les trois modes sont exclusifs : `seats > 0` (je conduis), `needsRide` (je cherche), ou ni l'un ni l'autre. ### 3.8 Réservation de place (Booking) | Champ | Type | Contraintes | |---|---|---| | planId | Plan | cascade | | userId | Membre | cascade | | createdAt | date | défaut : maintenant ; sert à trier les passagers | Clé primaire **composite** (planId, userId) : une seule place par passager et par trajet. ### 3.9 Invitation envoyée par e-mail (InviteSent) id, userId (cascade), email (texte), createdAt. Index sur (userId, createdAt). ### 3.10 Favori userId (cascade), spotId (cascade), lastNotifiedAt (date, nullable : dernière notification « ça navigue » reçue pour ce spot). Clé primaire (userId, spotId). Index sur spotId. ### 3.11 Avatar userId (**clé primaire**, cascade), data (octets de l'image), mime (texte), updatedAt (mise à jour automatique). Les avatars sont stockés à part, pour qu'aucune requête sur les membres ou les sessions ne charge les images. ### 3.12 Suivi (Follow) followerId (cascade), followeeId (cascade), level (Niveau, obligatoire), status (Statut, défaut `ACCEPTED`), createdAt. Clé primaire (followerId, followeeId). Index sur followeeId. ### 3.13 Blocage (Block) blockerId (cascade), blockedId (cascade), createdAt. Clé primaire (blockerId, blockedId). Index sur blockedId. ### 3.14 Signalement (Report) id, reporterId (cascade), reportedId (cascade), reason (texte de 5 à 1 000 caractères), createdAt, resolvedAt (date, nullable). Index sur resolvedAt. ### 3.15 Réglage (Setting) key (texte, clé primaire), value (document JSON), updatedAt. Une seule clé sert aujourd'hui : `telegram`, qui vaut `{ chatId: texte|null, chatTitle: texte|null, events: { checkins: booléen, plans: booléen } }`. Défauts : pas de groupe, les deux types d'événements activés. ### 3.16 Abonnement aux notifications (PushSubscription) id, userId (cascade, indexé), endpoint (texte, **unique**), p256dh (texte), auth (texte), createdAt. ### 3.17 Compteur anti-abus (RateLimit) | Champ | Type | Rôle | |---|---|---| | key | texte, clé primaire | nom du compteur (par exemple « échecs de connexion pour telle adresse ») | | hits | entier | nombre d'occurrences dans la fenêtre courante | | expiresAt | date, indexé | fin de la fenêtre courante | | blockedUntil | date, nullable | blocage actif jusqu'à cette date | Ces compteurs doivent être **persistants et partagés** entre instances du serveur (section 6). ### 3.18 Journal de sécurité (AuditLog) id, createdAt (indexé), actorId (Membre, nullable, mis à null si le membre est supprimé), action (texte), target (texte, défaut `""`), ip (texte, défaut `""`), meta (JSON, nullable). ### 3.19 Données initiales - **Liste des spots** : 454 spots importés une seule fois, avec pour chacun un identifiant, un nom, une latitude, une longitude et une région. Régions présentes : Espagne (88), Méditerranée (82), Italie (71), Bretagne (54), Manche (50), France intérieure (42), Charente & Vendée (26), Aquitaine (20), Outre-mer (14), Autre (3), Thaïlande (2), Belgique (2). **Ce fichier n'est pas reproduit ici.** Il faut le fournir à part, sous la forme d'un tableau JSON `[{id, name, lat, lon, region}]`. L'import se fait seulement si la table des spots est vide, en gardant les identifiants. Le compteur d'identifiants doit ensuite repartir au-delà du plus grand identifiant importé. - **Administrateur de départ** : voir 4.12. ### 3.20 Suppressions en cascade Supprimer un membre efface tout ce qui lui appartient : sessions, jetons, check-ins, sessions prévues (et les réservations des autres sur celles-ci), ses réservations, invitations, favoris, avatar, suivis dans les deux sens, blocages dans les deux sens, signalements faits et reçus, et abonnements aux notifications. Les filleuls perdent leur lien de parrainage. Les entrées du journal perdent leur auteur. Supprimer un spot efface ses check-ins, ses sessions prévues (et leurs réservations) et ses favoris. --- ## 4. RÈGLES MÉTIER ### 4.1 Constantes du domaine | Constante | Valeur | |---|---| | Durée pendant laquelle un check-in non terminé compte comme « sur l'eau » | 4 h | | Horizon des sessions prévues | aujourd'hui → J+14 inclus | | Horizon des sessions affichées sur la carte, dans les états des amis et sur la carte des amis | aujourd'hui → J+7 inclus | | Fenêtre des « Dernières 24 h » sur une fiche spot | 24 h, au plus 50 check-ins | | Fuseau horaire de calcul des jours | celui de la communauté, configurable, par défaut `Europe/Paris` | | Taille d'une page d'historique | 30 check-ins | | Taille d'une page du journal | 100 entrées | **Jours calendaires.** « Aujourd'hui » et « J+N » se calculent côté serveur dans le fuseau de la communauté. Une session dont le jour est passé n'apparaît plus et ne peut plus être réservée. ### 4.2 Sessions de connexion - Le jeton de session est un secret aléatoire d'au moins 256 bits. Il est placé dans un cookie **httpOnly**, `SameSite=Lax`, `Path=/`. En HTTPS, le cookie est aussi `Secure` et son nom porte le préfixe `__Host-` (`__Host-sid`). En HTTP (développement), il s'appelle `sid`. La base ne stocke que l'empreinte du jeton. - **Expiration glissante** : une session meurt après 30 jours sans activité, et dans tous les cas 180 jours après la connexion. La date de dernière activité et l'échéance sont réécrites **au plus une fois par heure** et par session. Le cookie lui-même dure 180 jours. - La session d'un compte bloqué est ignorée : le visiteur est traité comme non connecté. - Les sessions expirées et les jetons expirés sont purgés périodiquement (4.14). - Toutes les sessions d'un membre sont fermées quand il réinitialise son mot de passe, et quand un administrateur bloque son compte (ses abonnements aux notifications sont aussi supprimés). Quand le membre active le second facteur ou utilise « Déconnecter les autres appareils », toutes ses sessions sont fermées sauf la session courante. ### 4.3 Inscription et vérification de l'e-mail - E-mail : nettoyé (espaces retirés, minuscules), format valide, 200 caractères max. Nom : caractères de contrôle remplacés par des espaces, espaces de bord retirés, puis 1 à 60 caractères. Mot de passe : 8 à 200 caractères. - **Plafond d'e-mails de compte par adresse** : au plus 3 e-mails par adresse destinataire et par 24 h, tous types confondus (activation, renvoi, mot de passe, suppression, invitation). Au-delà, l'inscription répond 429 « Trop d'e-mails envoyés à cette adresse, réessaie dans X h. ». - **Mode d'inscription** : - **ouvert** (par défaut) : tout le monde peut s'inscrire ; - **sur invitation** : il faut un code d'invitation appartenant à un membre **actif et vérifié**. Sinon : 403 « L'inscription se fait sur invitation : demande le lien d'invitation d'un membre. ». - **Aucune énumération de comptes** : l'inscription répond toujours `{ok: true}` (hors erreurs de validation, plafonds et anti-robot). - Adresse libre : le compte est créé non vérifié, avec un mot de passe haché, puis le lien d'activation (48 h) est envoyé. - Adresse prise par un compte non vérifié : seul un nouveau lien d'activation est envoyé ; **le compte n'est pas modifié** (ni le nom, ni le mot de passe). - Adresse prise par un compte vérifié : un e-mail « Tu as déjà un compte » est envoyé, avec des liens vers la connexion et vers le mot de passe oublié. - Adresse prise par un compte bloqué : rien n'est envoyé. - Le temps de réponse doit être comparable dans tous les cas : on calcule un hachage factice quand le compte existe. - **Parrainage** : si un code d'invitation valide accompagne l'inscription (dans les deux modes), le nouveau compte est rattaché à son parrain. Quand le filleul devient vérifié (activation de l'e-mail, ou création par Google), le parrain reçoit la notification « Ton invitation a marché ». - **Lien d'activation** : à usage unique, valable 48 h. Il passe le compte en vérifié **sans ouvrir de session**, puis redirige vers `/login?verified=1`, ou vers `/login?err=lien` si le lien est invalide, expiré ou déjà utilisé. ### 4.4 Connexion par mot de passe Ordre des contrôles : 1. **Verrou du compte** : si l'adresse est verrouillée, la réponse est 429 « Compte temporairement verrouillé après plusieurs mots de passe erronés, réessaie dans X min. ». C'est vrai **même avec le bon mot de passe**. 2. **Vérification du mot de passe**, en temps constant. Pour une adresse inconnue ou un compte sans mot de passe, on vérifie contre un hachage factice, pour que le temps de réponse soit le même. 3. Mot de passe faux : le compteur d'échecs de cette adresse augmente (fenêtre de 15 min) et la réponse est 401 « Email ou mot de passe incorrect ». Au **5ᵉ échec en 15 min**, l'adresse est verrouillée. Le verrou dure 15 min au premier verrouillage, 1 h au deuxième et 6 h à partir du troisième dans les 24 h. À chaque verrouillage, le compteur d'échecs repart à zéro, l'événement « compte verrouillé » est journalisé, et le titulaire (s'il existe et n'est pas bloqué) reçoit un e-mail d'alerte avec la durée du verrou et un lien pour changer de mot de passe. Le verrou porte sur l'adresse, **quelle que soit l'IP** de l'attaquant. 4. Mot de passe juste : le compteur d'échecs repart à zéro. 5. Compte bloqué : 403 « Compte désactivé ». 6. Adresse non vérifiée : 403 « Email non vérifié : on vient de te renvoyer le lien d'activation. ». Le lien n'est réellement renvoyé qu'au plus une fois toutes les 10 min, et dans la limite du plafond par adresse. 7. Si le hachage stocké utilise des paramètres plus faibles que ceux en vigueur, il est recalculé avec le mot de passe saisi. 8. Si le second facteur est actif : la réponse est `{mfa: true}`, sans session, et un **ticket d'étape** valable 10 min est déposé dans un cookie httpOnly dédié (`__Host-mfa` en HTTPS). Sinon, la session est ouverte et la réponse est `{user}`. **Hachage des mots de passe** : algorithme de dérivation lent et gourmand en mémoire, avec un sel aléatoire par mot de passe. Les paramètres de coût sont stockés avec le hachage, pour pouvoir les relever plus tard et mettre à niveau les anciens hachages à la connexion suivante. ### 4.5 Second facteur (TOTP) - Norme TOTP (RFC 6238) : HMAC-SHA1, 6 chiffres, pas de 30 s, compatible avec toutes les applications d'authentification. Secret de 160 bits encodé en base32. - **Mise en place** : refusée par un 409 si le second facteur est déjà actif. Sinon, un nouveau secret est généré, enregistré (il n'est pas encore actif) et renvoyé avec l'URI `otpauth://totp/Shaka%20Crew:?secret=…&issuer=Shaka%20Crew&algorithm=SHA1&digits=6&period=30`. L'interface l'affiche en QR code et en clé lisible, par groupes de 4 caractères. - **Activation** : le premier code doit être valide. Sinon, 400 « Code incorrect : vérifie l'heure de ton téléphone et réessaie ». Une fois le code accepté : - le second facteur devient actif et le pas de temps du code est mémorisé ; - **10 codes de secours** sont générés, au format `xxxx-xxxx` (caractères base32 en minuscules), affichés une seule fois et stockés sous forme d'empreintes ; - toutes les autres sessions sont fermées ; - l'activation est journalisée et un e-mail d'information est envoyé. - **Vérification d'un code** : on accepte le pas de temps courant, le précédent et le suivant, pour tolérer une dérive d'horloge. Un pas inférieur ou égal au dernier pas accepté est **refusé** : un code ne sert jamais deux fois. Le code peut contenir des espaces, qui sont ignorés. - **Code de secours** : on le normalise (minuscules, caractères hors alphabet base32 retirés, tiret replacé après le 4ᵉ caractère), puis on le compare aux empreintes. Un code de secours utilisé est retiré de la liste, et l'usage est journalisé avec le nombre de codes restants. - **Étape de connexion** : le ticket doit exister, avoir l'usage `MFA` et ne pas être expiré, sur un compte non bloqué dont le second facteur est actif. Sinon : 401 « Session de connexion expirée : saisis à nouveau ton mot de passe. ». Un code faux répond 401 « Code incorrect ». Au **5ᵉ code faux en 15 min**, le ticket est détruit (401 « Trop de codes erronés : saisis à nouveau ton mot de passe. ») et l'événement est journalisé. En cas de succès, le ticket est consommé, le compteur d'échecs repart à zéro, une session est ouverte et le cookie du ticket est effacé. - **Désactivation** : il faut un code TOTP valide ou un code de secours. Sinon, 400 « Code incorrect ». Si le second facteur n'est pas actif : 400. La désactivation efface le secret, la date d'activation, le dernier pas et les codes de secours. Elle est journalisée et un e-mail d'alerte est envoyé. - La réinitialisation du mot de passe et la connexion Google **ne contournent jamais** le second facteur. ### 4.6 Mot de passe oublié, réinitialisation, suppression de compte - **Mot de passe oublié** : la réponse est toujours `{ok: true}`. Aucun e-mail ne part si l'adresse est inconnue, si le compte est bloqué ou si le plafond de l'adresse est atteint. Sinon, un lien `/reset/` valable **2 h** est envoyé. - **Réinitialisation** : le jeton est à usage unique. Jeton invalide : 400 « Lien expiré ou invalide ». Une réinitialisation réussie : - change le mot de passe ; - **marque l'adresse comme vérifiée**, puisque le membre a prouvé qu'il la possède ; - ferme toutes les sessions ; - lève le verrou de connexion ; - est journalisée ; - envoie l'e-mail « Ton mot de passe Shaka Crew a été changé ». Le membre est ensuite connecté, ou passe par l'étape du second facteur. - **Demande de suppression** (membre connecté) : elle respecte le plafond d'e-mails par adresse (429 sinon). Un lien `/delete-account/` valable **2 h** est envoyé. Réponse : 202. - **Confirmation de suppression** : jeton à usage unique (400 s'il est invalide). Si le membre est **le dernier administrateur actif**, la suppression est refusée : 409 « Tu es le dernier administrateur : nomme un autre admin avant de supprimer ton compte. ». Sinon, le compte et toutes ses données sont supprimés en cascade, l'événement est journalisé et le cookie de session est effacé. Réponse : 204. ### 4.7 Connexion Google (OAuth, flux « code d'autorisation ») - Si Google n'est pas configuré sur le serveur, le bouton est masqué et la route redirige vers `/login?err=google`. - **Démarrage** : un « state » aléatoire et le code d'invitation éventuel (tronqué à 40 caractères) sont placés dans un cookie httpOnly valable 10 min. L'utilisateur est redirigé vers Google, avec les portées `openid email profile` et le choix de compte forcé. - **Retour** : le cookie est effacé. Le « state » doit être identique à celui du cookie et un code doit être présent, sinon redirection vers `/login?err=google`. Le serveur échange le code contre un jeton d'identité, directement auprès de Google. Il exige une audience égale à l'identifiant de l'application, `email_verified` vrai et un e-mail présent. L'adresse est mise en minuscules. - **Résolution du compte** : 1. on cherche d'abord par identifiant Google, puis par e-mail ; 2. si on trouve un compte par l'e-mail sans identifiant Google, on le **rattache** : l'identifiant Google est enregistré et l'adresse est marquée vérifiée. Si ce compte n'était **pas vérifié**, son mot de passe est **effacé**, car celui qui l'a choisi n'a jamais prouvé qu'il possédait l'adresse ; 3. si aucun compte n'existe, on contrôle le droit à l'inscription (mode invitation : sinon `/login?err=invite`), puis on crée le compte vérifié, avec le nom fourni par Google tronqué à 60 caractères (ou la partie de l'adresse avant l'@). Le parrain est notifié s'il y en a un. - Compte bloqué : redirection vers `/login?err=disabled`. Second facteur actif : ticket d'étape et redirection vers `/login?mfa=1`. Sinon : session ouverte et redirection vers `/`. ### 4.8 Visibilité des positions, suivis, blocages (règle centrale de vie privée) **Qui peut voir les check-ins et les sessions prévues d'un membre ?** Les règles suivantes s'appliquent **partout** : carte, compteurs, fiche spot, liste des sessions, état des amis, historique des compagnons, réservation, proposition de trajet. - lui-même ; - si sa visibilité est `EVERYONE` : tout membre actif, **sauf** si l'un des deux a bloqué l'autre ; - si elle est `FOLLOWERS` : seulement ses abonnés **acceptés**, et aucun blocage entre eux ; - si elle est `NOBODY` : personne d'autre que lui ; - un compte bloqué par un administrateur n'est jamais visible. **Qui peut être notifié de la position d'un membre ?** On applique les mêmes règles en partant de l'auteur : personne si `NOBODY`, ses abonnés acceptés si `FOLLOWERS`, tous les membres actifs non bloqués (dans un sens ou dans l'autre) si `EVERYONE`. Jamais l'auteur lui-même, jamais un compte bloqué. **Suivre** : - Interdit de se suivre soi-même (400). La cible doit être active et vérifiée (404 « Membre introuvable »). Un blocage dans un sens ou dans l'autre interdit le suivi (403 « Action impossible avec ce membre »). - Si un suivi existe déjà, seul le niveau change : son statut est conservé. - Un nouveau suivi est `PENDING` si la cible valide ses abonnés, `ACCEPTED` sinon. La cible reçoit la notification « Demande de suivi » ou « Nouvel abonné ». La réponse indique le statut obtenu. - Ne plus suivre, retirer un abonné, débloquer : ces actions sont **idempotentes** et ne renvoient jamais d'erreur si rien n'existe. - Accepter ou refuser une demande : 404 si elle n'existe pas. Refuser supprime la demande. **Bloquer** : interdit sur soi-même (400), la cible doit exister (404). Le blocage est créé s'il n'existe pas, et **les suivis dans les deux sens sont supprimés**, dans la même transaction. La personne bloquée n'est pas prévenue. **Signaler** : interdit sur soi-même (400), la cible doit exister (404). Tous les administrateurs actifs reçoivent la notification « Nouveau signalement ». **Liste « Tous les membres »** : - tous les membres actifs et vérifiés, sauf moi et sauf ceux **qui m'ont bloqué**. Ceux que j'ai bloqués y figurent, marqués « bloqué » et sans état. La liste est plafonnée à 1 000 membres ; - pour chacun, on donne : mon niveau et le statut de mon suivi, le statut de son suivi envers moi, si je l'ai bloqué, et son **état**. L'état est son check-in actif s'il y en a un, sinon sa première session prévue entre aujourd'hui et J+7, sinon rien. Il n'est calculé que si j'ai le droit de voir ses positions ; - ordre : stars acceptées, puis suivis acceptés, puis suivis en attente, puis non suivis, puis bloqués. À l'intérieur de chaque groupe, ordre alphabétique en français. **Carte des amis** : seulement les membres que je suis avec un statut **accepté** et qui sont actifs, avec leur état (règle ci-dessus), regroupés par spot. Chaque ami porte son niveau (`FOLLOW` ou `STAR`) et son statut (`live` ou `planned`, avec le jour pour une session prévue). ### 4.9 Check-ins et notifications associées - Le spot doit exister (404 « Spot introuvable »). - Créer un check-in **termine tous les check-ins encore ouverts** du membre et crée le nouveau, dans une même transaction. - « Sortir de l'eau » termine tous les check-ins ouverts du membre. L'action est idempotente. - **Actif** = non terminé **et** commencé il y a moins de 4 h. - La **fin effective** d'un check-in non terminé est le plus tôt de ces deux moments : début + 4 h, ou maintenant. Dans l'historique, une telle fin est marquée « estimée ». - **Résumé des conditions** utilisé dans les notifications, par exemple « 18 nds NO · voile 5.3 m² · vagues clapot ». Il ne contient que les éléments renseignés. - **Notifications d'un check-in** : elles partent en tâche de fond. Leur échec n'affecte jamais l'action du membre. - **Abonnés acceptés** qui ont le droit de voir les positions : titre « ★ X est sur l'eau » pour les stars, « X est sur l'eau » pour les simples suivis ; corps « à · » ; ouverture sur la fiche du spot. Un même abonné est notifié **au plus une fois toutes les 2 h pour un même ami**. - **Membres qui ont ce spot en favori**, hors auteur et hors abonnés déjà notifiés, qui ont le droit de voir les positions et n'ont pas été notifiés pour ce spot depuis 3 h : titre « Ça navigue à », corps « X est sur l'eau · ». Leur date de dernière notification pour ce spot est mise à jour. - **Plafond social** : au plus 30 notifications « sociales » (amis et favoris) par destinataire et par 24 h. Les notifications de covoiturage ne sont pas plafonnées. - **Groupe Telegram** : un message part seulement si toutes ces conditions sont réunies : - l'auteur y consent pour **cette** publication. Par défaut, on reprend son réglage « publier par défaut » ; l'interface envoie toujours un choix explicite ; - sa visibilité est `EVERYONE` ; - aucun message de check-in n'est parti pour ce spot depuis 2 h ; - le bot est configuré, un groupe est choisi et le type « check-ins » est activé. Le message contient : « 🤙 X est sur l'eau à spot », le résumé, et un lien vers la fiche. - **Débit** : au plus 6 check-ins par heure et par membre. ### 4.10 Sessions prévues et covoiturage - **Création ou modification** : - le jour doit être au format `AAAA-MM-JJ`, entre aujourd'hui et J+14. Sinon : 400 « Choisis une date entre aujourd'hui et J+14 » ; - le spot doit exister (404) ; - mode `offer` : nombre de places obligatoire, de 1 à 8 (400 « Indique le nombre de places proposées ») ; l'heure de départ est `HH:MM` ou vide ; - mode `need` : places à 0, l'heure de départ est vidée, le lieu de départ est conservé ; - mode `none` : places à 0, le lieu et l'heure de départ sont vidés ; - le créneau vaut « Journée » par défaut. - Il y a une seule session par (membre, spot, jour) : renvoyer le formulaire **met à jour** la session. - **Si la session ne propose plus de places** (places = 0 après enregistrement), toutes ses réservations sont supprimées et chaque passager reçoit un e-mail et une notification « Covoiturage annulé ». Une suppression de session fait de même. - **Annonce d'une nouvelle session** : elle a lieu **une seule fois par (auteur, spot, jour)**, pendant 15 jours. Supprimer puis recréer la session, ou la modifier, ne renvoie pas l'annonce. Destinataires : les abonnés acceptés qui ont le droit de voir les positions, avec le titre « ★ X prévoit une session » ou « X prévoit une session », et un corps du type « , · ». Le plafond social s'applique. Côté Telegram, mêmes conditions de consentement et de visibilité que pour les check-ins, et le type « sessions » doit être activé ; il n'y a pas de délai minimum par spot. Message : « 📅 X va à spot » et « 🚗 ». - **Liste des sessions** (onglet Sessions et fiche spot) : de aujourd'hui à J+14, en respectant la visibilité, triées par jour, puis par nom de spot, puis par identifiant. Pour chaque session : `mine` (c'est la mienne), `booked` (j'y ai une place), `taken` (nombre de places prises). - **Téléphone du conducteur** : seulement pour lui-même et pour ses passagers. - **Liste des passagers** (nom, avatar) : seulement pour le conducteur et pour les passagers. Le **téléphone d'un passager** n'est visible que par le conducteur et par ce passager. Les autres membres ne voient que le nombre de places prises. - **Réserver une place** : - la session doit être visible pour le demandeur (sinon 404 « Trajet introuvable »), et son jour ne doit pas être passé (404) ; - réserver sa propre session est interdit (400 « C'est ton propre trajet ») ; - si le demandeur a déjà réservé : succès sans effet et sans notification ; - si les places prises sont supérieures ou égales aux places proposées : 409 « Plus de place disponible ». C'est aussi le cas d'une session sans places ; - **le contrôle et l'insertion se font sous un verrou exclusif sur la session**, pour qu'aucune surréservation ne soit possible en cas de demandes simultanées ; - en cas de succès, le conducteur reçoit un e-mail (avec le téléphone du passager s'il est renseigné) et la notification « Nouvelle réservation ». - **Libérer une place** : idempotent. Si une place a vraiment été libérée, le conducteur reçoit un e-mail et la notification « Place libérée ». - **Proposer d'emmener** : - la session doit chercher une place, être visible, et son jour ne doit pas être passé (sinon 404 « Demande introuvable ») ; - interdit sur sa propre demande (400) ; - une seule proposition par (conducteur, demande) sur 30 jours (sinon 409 « Tu as déjà proposé de l'emmener ») ; - la personne qui cherche reçoit un e-mail avec le nom, le téléphone (s'il existe) et l'e-mail du conducteur, et la notification « On peut t'emmener ! ». - **Supprimer une session** : seulement la sienne (404 « Session introuvable » sinon). Les passagers sont prévenus, puis la session est supprimée. ### 4.11 Spots et favoris - **Liste des spots** (tous les membres connectés) : identifiant, nom, latitude, longitude, région, nombre de riders actifs visibles, nombre de sessions visibles entre aujourd'hui et J+7, et drapeau favori. Ordre alphabétique. - **Fiche d'un spot** : le spot complet, le drapeau favori, les check-ins visibles des dernières 24 h (50 au plus, du plus récent au plus ancien, chacun marqué actif ou non), et les sessions prévues de ce spot (règles de 4.10). Spot inexistant : 404. - **Favori** : ajouter et retirer sont deux actions idempotentes. - **Gestion des spots** (administrateur) : créer, modifier (tous les champs sont renvoyés à chaque fois : nom, latitude et longitude obligatoires) et supprimer (avec cascade). ### 4.12 Administrateur de départ (au démarrage, de façon idempotente) Le serveur lit une adresse d'administrateur, un nom (par défaut « Admin ») et, en option, un mot de passe hérité d'une ancienne configuration. - Pas d'adresse configurée : on ne fait rien. - Mot de passe hérité configuré, mais de moins de 12 caractères : **le démarrage échoue** avec une erreur explicite. - Un compte **vérifié** existe à cette adresse : on s'assure seulement qu'il est administrateur et non bloqué. - Un compte **non vérifié** existe : on ne le promeut **jamais** tel quel, car n'importe qui peut s'inscrire avec n'importe quelle adresse. On supprime ses sessions, ses jetons et ses abonnements aux notifications, puis : - **avec** le mot de passe hérité : on fixe ce mot de passe, on supprime le lien Google, on marque le compte vérifié, administrateur et actif, et on journalise « compte admin récupéré au démarrage » ; - **sans** mot de passe hérité : si le compte avait un mot de passe ou un lien Google, on efface les deux et on journalise la récupération ; dans tous les cas, on le passe administrateur et actif. - Aucun compte n'existe : on le crée administrateur, avec le mot de passe hérité (le compte est alors vérifié) ou **sans mot de passe**. - **Sans mot de passe hérité** : si aucun lien de réinitialisation valide n'est déjà en attente, on envoie à l'adresse un **lien d'activation à usage unique valable 48 h** (« Choisir mon mot de passe »), et on journalise l'envoi. Ce lien suit le même parcours que la réinitialisation, et son usage marque le compte vérifié. ### 4.13 Administration - Toute route d'administration exige d'être connecté (401 « Connexion requise »), d'avoir le rôle administrateur (403 « Réservé aux administrateurs ») **et** d'avoir activé le second facteur (403 « Active la double authentification (onglet Moi) pour accéder à l'administration. »). - **Modifier un compte** : rôle, adresse vérifiée, compte bloqué. Un administrateur ne peut ni se rétrograder ni se bloquer lui-même (400 « Tu ne peux pas retirer tes propres droits »). Bloquer un compte ferme toutes ses sessions et supprime tous ses abonnements aux notifications. - **Supprimer un compte** : impossible sur soi-même (400). Cascade complète. - **Signalements** : « traiter » enregistre la date de traitement. Un signalement inconnu renvoie 404. - **Telegram** : détecter les groupes (groupes non privés où le bot a reçu un événement récent ; la plateforme ne garde ces événements qu'environ 24 h), enregistrer le groupe choisi et les types d'événements, envoyer un message de test (« 🤙 **Shaka Crew** est bien connecté à ce groupe. Bon vent ! »). Si le bot n'est pas configuré ou si Telegram refuse : 502, avec le message d'erreur de Telegram. Débit : 20 actions par heure. - **Journal automatique** : **chaque écriture réussie** sur une route d'administration est journalisée, avec la méthode et le chemin, l'auteur, l'identifiant ciblé, l'IP et le corps de la requête. Dans ce corps, toute clé dont le nom contient `token`, `password`, `secret`, `code` ou `captcha` est remplacée par `***`. - **Événements de sécurité journalisés** : compte verrouillé, mot de passe réinitialisé, compte supprimé par son titulaire, second facteur activé, désactivé, en échec (5 codes faux), code de secours utilisé, « autres appareils déconnectés », compte admin récupéré au démarrage, lien d'activation admin envoyé. - Une écriture dans le journal **ne fait jamais échouer** l'action qu'elle enregistre. ### 4.14 Rétention et maintenance Une tâche tourne au démarrage puis toutes les 6 h (pas en environnement de test). Elle supprime : - les sessions et les jetons expirés ; - les compteurs anti-abus expirés qui ne sont pas en cours de blocage ; - les check-ins plus anciens que la durée de rétention (365 jours par défaut, configurable) ; - les invitations envoyées depuis plus de 30 jours ; - les signalements traités depuis plus d'un an ; - les entrées du journal de plus d'un an. Un échec est consigné dans les logs sans arrêter le serveur. ### 4.15 Invitations par e-mail - Réservées aux comptes créés il y a **plus de 24 h**. Sinon : 403 « Les invitations par e-mail sont possibles 24 h après ton inscription. En attendant, partage ton lien ! ». - Vérification anti-robot (si elle est activée). - **10 invitations par membre et par 24 h** (429). - **La même adresse au plus une fois par 7 jours**, tous parrains confondus (409 « Cette personne a déjà reçu une invitation cette semaine »). - Plafond quotidien de l'adresse destinataire (409 « Cette adresse a reçu trop d'e-mails aujourd'hui »). - L'e-mail contient le lien `/?invite=`. L'envoi est enregistré. - **Côté client** : un paramètre `?invite=` présent à l'arrivée est mémorisé localement puis retiré de l'URL. Il survit ainsi à l'inscription et à l'aller-retour Google. Un visiteur non connecté qui a un code est dirigé vers l'inscription, sinon vers la connexion. ### 4.16 Avatars - L'image est envoyée encodée en base64 (avec ou sans préfixe `data:`), 420 000 caractères au plus. Le navigateur la recadre au centre en carré de 256 px, au format WebP ou JPEG. - **Contrôles du serveur** : - 300 Ko au plus une fois décodée ; - format reconnu par ses **octets de signature** (JPEG, PNG ou WebP seulement ; le type déclaré n'est pas pris en compte) ; - 4 096 px au plus en largeur comme en hauteur ; - refus des « bombes de décompression ». - L'image est **ré-encodée** côté serveur en WebP 256 × 256 (recadrage), orientée selon son EXIF, puis **toutes les métadonnées sont supprimées** (EXIF, GPS). Une image refusée renvoie 400 « Image invalide : photo JPEG, PNG ou WebP de 300 Ko et 4096 px maximum ». - Chaque nouvelle photo augmente le numéro de version de 1. Supprimer la photo remet la version à 0. - L'image n'est servie **qu'aux membres connectés**. Son URL contient la version (`?v=N`), ce qui permet une mise en cache privée d'un an, marquée immuable. Pas de photo : 404. Côté client, on affiche alors les initiales (deux lettres au plus). ### 4.17 Notifications push - Norme Web Push avec clés VAPID. Sans clés configurées, le push est désactivé, avec un avertissement dans les logs, et la clé publique renvoyée vaut null. - **Liste blanche des services de push** : l'adresse d'abonnement doit être en HTTPS, sans port ni identifiants, sur `fcm.googleapis.com`, `updates.push.services.mozilla.com`, `web.push.apple.com`, un sous-domaine de `push.apple.com` ou un sous-domaine de `notify.windows.com`. Sinon : 400 « Service de notification non reconnu ». Cette règle empêche le serveur d'envoyer des requêtes vers des hôtes arbitraires. Au démarrage, et au moment d'un envoi, les abonnements hors liste blanche sont supprimés. - Enregistrer un abonnement le crée, ou le met à jour s'il existe déjà, avec la même adresse. Il est alors rattaché au membre courant. - Contenu envoyé : `{title, body, url, tag}`, valable 1 h. Les notifications qui portent le même `tag` se remplacent sur l'appareil. - Si le service répond 404 ou 410, l'abonnement est supprimé. Les autres erreurs sont consignées dans les logs. - Les comptes bloqués ne reçoivent **jamais** de notification. - Icônes de notification : l'icône de l'application et un badge monochrome. ### 4.18 Telegram - La publication passe par un bot, dans un **groupe existant** dont l'administrateur de la communauté est responsable. - Toute erreur de publication est consignée dans les logs et n'affecte jamais l'action du membre. - Le texte est en HTML, avec échappement de toutes les données saisies par les membres et sans aperçu de lien. ### 4.19 E-mails - Envoi par une API transactionnelle (section 6). Tous les e-mails partagent une même mise en page : en-tête « Shaka Crew », bouton d'action, pied de page « La communauté qui dit où ça navigue. ». - **Toutes les données saisies par les membres sont échappées** avant d'être insérées dans le HTML. - **Plafond global** : au plus `MAIL_HOURLY_LIMIT` e-mails par heure (300 par défaut). Au-delà, l'envoi est refusé avec 503 « Trop d'e-mails envoyés en ce moment, réessaie dans une heure. ». - Si le service d'envoi échoue : 502 « L'envoi de l'email a échoué, réessaie plus tard. ». Pour les e-mails d'information (alertes de sécurité, covoiturage), l'échec est seulement consigné dans les logs. - **Sans clé d'API** (développement) : les e-mails ne partent pas. Leur texte, liens compris, est écrit dans les logs. ### 4.20 Anti-robot Une vérification de type Cloudflare Turnstile protège l'inscription, le mot de passe oublié et les invitations par e-mail. Elle est désactivée si les clés ne sont pas configurées. Si elle est activée et que le jeton manque : 400 « Vérification anti-robot manquante, réessaie. ». Si le jeton est rejeté ou que le service est injoignable : 400 « Vérification anti-robot échouée, réessaie. ». Un jeton ne sert qu'une fois : l'interface renouvelle le défi après chaque tentative. ### 4.21 Limites de débit Compteurs à fenêtre fixe, persistants. On compte **par membre** quand il est connecté, **par IP** sinon. L'IP du client n'est lue dans l'en-tête de transfert du proxy que si ce proxy fait partie des proxys de confiance configurés. Un dépassement répond 429 avec un message lisible : « Trop de requêtes, réessaie dans N min. » (ou « N h » au-delà de 90 min). | Portée | Limite | |---|---| | Filet global (toutes routes) | 300 requêtes / min | | Inscription | 5 / h | | Vérification d'e-mail | 30 / h | | Connexion, étape du second facteur | 20 / 15 min chacune | | Mot de passe oublié | 5 / h | | Réinitialisation | 10 / h | | Confirmation de suppression | 10 / h | | Démarrage et retour Google | 30 / h chacun | | Profil, zone (enregistrer ou effacer) | 30 / h | | Avatar (envoyer ou supprimer) | 10 / h | | Invitations par e-mail | 10 / 24 h | | Export des données | 5 / h | | Demande de suppression | 3 / h | | Mise en place du TOTP | 10 / h | | Activation et désactivation du TOTP | 10 / 15 min | | Check-in | 6 / h | | Créer, supprimer une session ; réserver, libérer une place | 20 / h chacune | | Proposer d'emmener | 10 / h | | Suivre ou ne plus suivre | 60 / h | | Bloquer ou débloquer | 30 / h | | Signaler | 5 / 24 h | | S'abonner aux notifications | 10 / h | | Notification de test | 5 / h | | Actions Telegram (admin) | 20 / h | | Santé, images d'avatar | aucune limite | Une variable d'environnement permet de désactiver ces limites pour les tests. ### 4.22 Protection des requêtes - Taille maximale d'un corps de requête : **16 Ko**, sauf pour l'envoi d'avatar (**512 Ko**). - **Défense anti-CSRF** : en plus de `SameSite=Lax`, toute requête `POST` vers l'API dont le type de contenu n'est pas `application/json` est refusée avec 415 et `{statusCode: 415, message: "JSON requis"}`. Le serveur n'accorde jamais de pré-vérification CORS cross-origin. - Validation : les champs inconnus sont **supprimés en silence**. Les chaînes sont nettoyées : caractères de contrôle remplacés par des espaces (retours à la ligne conservés pour les textes multilignes), espaces de bord retirés. En cas d'erreur, la réponse est un 400 qui porte **un seul message lisible**, celui de la première contrainte violée, ou « Données invalides ». - Erreurs de base de données présentées à l'utilisateur : élément introuvable → 404 « Introuvable » ; doublon → 409 « Cet élément existe déjà » ; référence invalide (par exemple un favori sur un spot inexistant) → 400 « Référence invalide ». Toute autre erreur → 500 « Erreur serveur », avec le détail dans les logs. - Format d'erreur : JSON `{statusCode, message}`, où `message` est une chaîne. - En-têtes de sécurité : - politique de sécurité de contenu stricte : tout en `self`, plus le service anti-robot (scripts et cadres), les tuiles de carte (images et connexions), les images `data:` et `blob:`, les styles en ligne autorisés et l'envoi de formulaire vers Google ; - interdiction d'être affiché dans un cadre ; - `Referrer-Policy: strict-origin-when-cross-origin` ; - HSTS et passage forcé en HTTPS quand l'URL publique est en HTTPS ; - en-tête de version du serveur supprimé. ### 4.23 Export des données (portabilité) L'export est un fichier téléchargé (`shaka-crew-.json`) qui contient : - la date de l'export ; - le profil : champs publics de l'utilisateur, date de création, adresse vérifiée ou non, compte Google lié ou non ; - l'avatar, sous forme d'URL `data:` ; - tous les check-ins (avec le nom du spot), les sessions prévues, les réservations (jour et spot), les suivis donnés et reçus (avec les noms), les favoris, les blocages, les signalements faits (raison, date, nom de la personne signalée) et les invitations envoyées (e-mail, date) ; - les appareils de notification, réduits au **nom d'hôte** du service et à la date d'abonnement. ### 4.24 Profil - La modification du profil renvoie le prénom (obligatoire) et, en option, le téléphone (une absence vaut chaîne vide), le consentement Telegram par défaut, la visibilité et la validation des abonnés. L'interface renvoie toujours le prénom et le téléphone actuels, même quand elle ne change qu'un réglage de confidentialité. - **Zone par défaut** : quatre bornes, avec latitudes entre −90 et 90 et longitudes entre −180 et 180. Le sud doit être strictement inférieur au nord, sinon 400 « Zone invalide ». L'interface ramène les bornes de la carte dans ces intervalles avant l'envoi. - **Représentation publique du membre courant** : id, email, name, phone, role, inviteCode, avatarVersion, shareTelegram, locationVisibility, followApproval, mfaEnabled (booléen), home (`{south, west, north, east}` ou null). Elle ne contient **jamais** l'empreinte du mot de passe, ni le secret ou les codes du second facteur. --- ## 5. INTERFACES ### 5.1 Principes d'interface - **Mise en page responsive.** Sur téléphone, une barre d'onglets en bas de l'écran : Carte, Sessions, Groupe, Admin (administrateurs seulement), Moi. Sur ordinateur, ces onglets forment un rail vertical à gauche, avec le logo. Chaque icône est accompagnée de son libellé. Les zones de sécurité des écrans à encoche sont respectées. - **Code couleur** : orange pour « sur l'eau » (en direct), cyan ou bleu pour « prévu », couleur principale cyan, or ou ambre pour les stars. La couleur n'est **jamais** le seul signal : un texte l'accompagne toujours. Thèmes clair et sombre. Le fond de carte sombre est obtenu par un filtre sur les tuiles seulement. - **Squelettes de chargement** sur chaque écran qui attend des données. Retour par messages brefs (« toasts ») pour chaque action. Confirmation obligatoire pour toute action destructrice. - **Accessibilité** : libellés pour les lecteurs d'écran sur les boutons qui n'ont qu'une icône, sélecteurs exclusifs exposés comme groupes de choix, navigation au clavier dans la recherche, zones tactiles d'au moins 40 px environ. - **Rafraîchissement** : la liste des spots, les riders en direct, la liste des membres et la carte des amis se rechargent toutes les 60 s. Toute action qui change « qui est où » ou « qui va où » rafraîchit la carte, le direct, les fiches, les sessions, le groupe et l'historique. Les données sont considérées fraîches 20 s et rechargées au retour sur l'onglet du navigateur. - **Gestion des erreurs côté client** : - une réponse 401 sur n'importe quel appel efface l'utilisateur en mémoire et renvoie vers la connexion ; - les erreurs 4xx ne sont jamais retentées ; les autres le sont jusqu'à 2 fois ; - réseau absent : « Tu es hors ligne. » ; - serveur injoignable : « Serveur injoignable, réessaie dans un instant. » ; - sinon on affiche le message renvoyé par le serveur. - **Écran de démarrage** : écran de marque en HTML, affiché au moins 0,7 s et au plus 8 s, retiré dès que l'on sait si l'utilisateur est connecté. On évite ainsi un flash de l'écran de connexion. ### 5.2 Écrans et parcours | Chemin | Accès | Contenu | |---|---|---| | `/login` | visiteurs seulement (un membre connecté est redirigé vers `/`) | Titre « Bon retour ! », bouton Google (s'il est configuré), e-mail, mot de passe avec bouton afficher/masquer, lien « Oublié ? », lien « Rejoindre la crew ». Bandeaux selon l'URL : `?verified=1` (succès), `?err=lien`, `?err=google`, `?err=disabled`, `?err=invite` (messages en 2.1). `?mfa=1` affiche l'**étape du second facteur** : code à 6 chiffres ou, en basculant, code de secours, avec un lien « Annuler ». | | `/signup` | visiteurs | Bouton Google, prénom, e-mail, mot de passe (« 8 caractères minimum »), vérification anti-robot, mention de consentement avec un lien vers la page de confidentialité. Après envoi : « Vérifie ta boîte mail » avec l'adresse. En mode invitation sans code : écran « Sur invitation ». Avec un code : sous-titre « Tu as été invité, bienvenue à bord ! ». | | `/forgot` | visiteurs | E-mail et anti-robot, puis message neutre. | | `/reset/:token` | tous | Nouveau mot de passe, puis connexion (ou étape du second facteur). Erreur affichée sous le champ. | | `/delete-account/:token` | tous | Avertissement et « Supprimer définitivement », puis « Compte supprimé ». Le lien « Annuler et garder mon compte » ramène à l'accueil. | | `/privacy` | tous | Notice de confidentialité. Le lien de retour mène à « Moi » pour un membre connecté, à la connexion sinon. | | `/` | membres | Carte plein écran, recherche flottante, panneau d'accueil (2.2, point 14). États vides : « Calme plat pour l'instant » et « Personne n'a signalé être sur l'eau — Tu y vas ? Dis-le aux autres en un tap. ». Badge « Chargement des spots… » pendant le premier chargement. | | `/near` | membres | Géolocalisation et 8 spots proches. Clic sur un spot → `/spot/:id/checkin`. | | `/spot/:id` | membres | Fiche spot dans le panneau (2.2, point 12). Spot inconnu : « Spot introuvable » avec un retour à la carte. États vides : « Personne en ce moment. » et « Aucune session prévue. Lance la première ! ». | | `/spot/:id/checkin` | membres | Formulaire de check-in. Bouton « Je suis sur l'eau ». Après succès → fiche du spot. | | `/spot/:id/plan` | membres | Formulaire de session. Titre « J'y vais », ou « Modifier ma session à » si l'utilisateur en a déjà une. Après succès → fiche du spot. | | `/sessions` | membres | Sessions prévues, filtres, groupement par jour. État vide : « Rien de prévu pour l'instant ». | | `/group` | membres | Onglets « Mes amis » et « Tous les membres », recherche, lignes de membres (2.5). États vides : « Tu ne suis encore personne » (avec un lien vers Tous les membres) et « Aucun membre trouvé ». | | `/history` | membres | Statistiques et sessions par mois. État vide : « Pas encore de session ». | | `/me` | membres | Cartes : Inviter des amis, lien vers Mes sessions, Profil, Sécurité (ancre `#securite`, défilement automatique), Ma zone, Confidentialité, Notifications, Application, Apparence, Mes données. Puis « Se déconnecter » et la version. | | `/admin` | administrateurs | Onglets Comptes, Spots, Signalements, Telegram, Journal. Sans second facteur : écran « Double authentification requise » avec un lien vers `/me#securite`. Un non-administrateur est redirigé vers `/`. | | `/admin/spots`, `/admin/spots/new`, `/admin/spots/:id` | administrateurs | Liste et éditeur de spot. | | `/admin/reports`, `/admin/telegram`, `/admin/audit` | administrateurs | Voir 2.8. | | toute autre URL | | Redirection vers `/`. | Un visiteur non connecté qui ouvre une page réservée aux membres est redirigé vers `/signup` s'il a un code d'invitation mémorisé, vers `/login` sinon. **Panneau cartographique.** Sur téléphone, c'est une feuille en bas de l'écran, haute de 56 % de l'écran au plus, avec une poignée pour la replier. Sur ordinateur, c'est une carte fixe de 400 px à droite. Quand un spot est sélectionné, la carte le centre (zoom 11 au minimum) en tenant compte de la place prise par le panneau. Le panneau revient en haut et se déplie à chaque changement de page. ### 5.3 Application installable et hors-ligne - **Manifeste** : nom et nom court « Shaka Crew », démarrage sur `/`, affichage autonome (`standalone`), orientation portrait, couleurs de fond et de thème `#050d18`. La couleur de thème suit le mode clair (`#eef6fb`) ou sombre. - **Raccourcis** : « Je suis sur l'eau » → `/near` ; « Sessions prévues » → `/sessions`. - **Service worker** : - la coquille de l'application est mise en cache et remplacée à chaque déploiement (mise à jour automatique et immédiate) ; - toute navigation qui n'est pas vers l'API est servie par la page d'accueil de l'application ; - **les tuiles de carte sont servies depuis le cache en priorité** (au plus 1 500 tuiles, 30 jours) ; - **les réponses de l'API ne sont jamais mises en cache** ; - à la réception d'une notification push, il l'affiche ; - au clic sur une notification, il réutilise une fenêtre de l'application déjà ouverte, la met au premier plan et la dirige vers l'URL de la notification, ou bien ouvre une nouvelle fenêtre. - **Mise en cache HTTP** : pas de cache pour le service worker, les pages HTML et le manifeste ; cache public d'un an, immuable, pour les fichiers statiques dont le nom contient une empreinte. - **Invitation à activer les notifications** : affichée sur l'accueil seulement si le navigateur gère le push, que la permission n'a pas été refusée, qu'il n'existe pas déjà d'abonnement, que l'invitation n'a pas été fermée, et (sur iOS) que l'application est installée. La permission n'est **jamais** demandée sans un geste explicite de l'utilisateur. ### 5.4 API HTTP Toutes les routes sont préfixées par `/api`. Les échanges se font en JSON. Sauf mention « public », une route exige une session valide (401 `{"statusCode":401,"message":"Connexion requise"}` sinon). Les codes de succès indiqués sont ceux de l'application d'origine. Le client ne distingue que succès et échec, mais les critères d'acceptation de la section 7 s'appuient sur ces codes. #### Santé et configuration | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/health` (public, sans limite) | | 200 `{status: "ok"}` après une vraie requête en base ; erreur si la base ne répond pas | | GET | `/auth/config` (public) | | 200 `{google: bool, registrationMode: "open"\|"invite", turnstileSiteKey: string\|null, telegram: bool}`. `telegram` est vrai si le bot est configuré **et** qu'un groupe est choisi. | #### Authentification (public) | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | POST | `/auth/signup` | `{email, name, password, invite?, captcha?}` | 201 `{ok: true}` · 400 validation ou anti-robot · 403 mode invitation · 429 plafond · 502/503 e-mail | | GET | `/auth/verify?token=` | | 302 vers `/login?verified=1` ou `/login?err=lien` | | POST | `/auth/login` | `{email, password}` | 200 `{user}` + cookie de session, **ou** 200 `{mfa: true}` + cookie de ticket · 401 identifiants · 403 compte bloqué ou non vérifié · 429 verrou ou débit | | POST | `/auth/mfa` | `{code}` (6 à 20 caractères) | 200 `{user}` + cookie de session · 401 ticket expiré, code faux, trop d'échecs | | POST | `/auth/logout` | `{}` | 200 `{ok: true}` ; cookie effacé | | POST | `/auth/forgot` | `{email, captcha?}` | 200 `{ok: true}` (toujours) · 400 anti-robot | | POST | `/auth/reset` | `{token, password}` | 200 `{user}` ou `{mfa: true}` · 400 « Lien expiré ou invalide » | | POST | `/auth/delete-account` | `{token}` | 204, cookie effacé · 400 jeton invalide · 409 dernier administrateur | | GET | `/auth/google?invite=` | | 302 vers Google (ou `/login?err=google` si Google n'est pas configuré) | | GET | `/auth/google/callback?code=&state=` | | 302 vers `/`, `/login?mfa=1`, `/login?err=google`, `/login?err=invite` ou `/login?err=disabled` | #### Membre courant | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/me` (public) | | 200 `{user: Me \| null}` | | PATCH | `/me` | `{name, phone?, shareTelegram?, locationVisibility?, followApproval?}` | 200 `{user}` | | PUT | `/me/home` | `{south, west, north, east}` | 200 `{user}` · 400 « Zone invalide » | | DELETE | `/me/home` | | 200 `{user}` (home = null) | | PUT | `/me/avatar` | `{data: base64}` | 200 `{user}` · 400 image invalide | | DELETE | `/me/avatar` | | 200 `{user}` (avatarVersion = 0) | | GET | `/users/:id/avatar` (sans limite) | | 200 image (`Content-Type` selon l'image, `Cache-Control: private, max-age=31536000, immutable`) · 404 | | POST | `/me/invites` | `{email, captcha?}` | 201 `{ok: true}` · 400 · 403 compte trop récent · 409 adresse déjà invitée ou plafond de l'adresse · 429 | | GET | `/me/export` | | 200 fichier JSON en pièce jointe (`Content-Disposition: attachment; filename="shaka-crew-.json"`) | | POST | `/me/deletion` | `{}` | 202 `{ok: true}` · 429 | | GET | `/me/security` | | 200 `{totpEnabled, recoveryCodesLeft, required (= est administrateur), sessions: [{id, userAgent, createdAt, lastSeenAt, current}]}`. Sessions non expirées, de la plus récemment active à la plus ancienne. | | POST | `/me/totp/setup` | `{}` | 201 `{secret, uri}` · 409 déjà actif | | POST | `/me/totp/enable` | `{code}` | 201 `{recoveryCodes: string[10]}` · 400 code faux · 409 déjà actif | | POST | `/me/totp/disable` | `{code}` | 204 · 400 | | DELETE | `/me/sessions/:id` | | 204 · 404 « Appareil introuvable » (un appareil d'un autre membre compte comme introuvable) | | DELETE | `/me/sessions` | | 204 (toutes les sessions sauf la courante) | #### Spots | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/spots` | | 200 `[{id, name, lat, lon, region, riders, plans, favorite}]` | | GET | `/spots/:id` | | 200 `{spot: Spot, favorite, recent: [Checkin + {userName, userAvatar, active}], plans: [Plan]}` · 404 | | PUT | `/spots/:id/favorite` | | 204 · 400 si le spot n'existe pas | | DELETE | `/spots/:id/favorite` | | 204 | | POST | `/admin/spots` | `{name, lat, lon, region?, winds?, access?, notes?}` | 201 `Spot` | | PATCH | `/admin/spots/:id` | même forme | 200 `Spot` · 404 | | DELETE | `/admin/spots/:id` | | 204 · 404 | Les paramètres `:id` doivent être des entiers. Sinon : 400. #### Check-ins | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/checkins/live` | | 200 `[{id, userId, spotId, createdAt, endedAt, windKts, windDir, waves, sailSize, comment, spotName, userName, userAvatar}]`, du plus récent au plus ancien | | POST | `/checkins` | `{spotId, windKts?, windDir?, waves?, sailSize?, comment?, telegram?}` | 201 `{id}` · 404 spot · 429 | | POST | `/checkins/end` | `{}` | 204 | | GET | `/checkins/history?before=` | | 200 `{stats: {sessions, spots, hours}, items: [{id, spotId, spotName, region, start, end, estimatedEnd, windKts, windDir, waves, sailSize, comment, companions: [{id, name, avatarVersion}]}], nextCursor: id \| null}` | `stats` porte sur **tous** les check-ins du membre (heures arrondies à l'entier). `nextCursor` n'est renseigné que si la page est pleine (30 éléments). Un **compagnon** est un membre dont un check-in sur le même spot **chevauche** le mien, c'est-à-dire qu'il commence avant ma fin effective et se termine après mon début. On ne retient que les membres dont je peux voir les positions, et chaque compagnon n'apparaît qu'une fois. #### Sessions prévues | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/plans` | | 200 `[Plan]` | | POST | `/plans` | `{spotId, day: "AAAA-MM-JJ", slot?, ride: "none"\|"offer"\|"need", seats? (exigé si offer, 1–8), departure?, departureTime?, comment?, telegram?}` | 201 `{id}` · 400 · 404 | | DELETE | `/plans/:id` | | 204 · 404 | | POST | `/plans/:id/booking` | `{}` | 204 · 400 propre trajet · 404 · 409 complet | | DELETE | `/plans/:id/booking` | | 204 | | POST | `/plans/:id/ride-offer` | `{}` | 204 · 400 · 404 · 409 déjà proposé | Forme d'un `Plan` : `{id, spotId, spotName, day, slot, comment, seats, taken, departure, departureTime, needsRide, mine, booked, user: {id, name, avatarVersion, phone}, passengers: [{id, name, avatarVersion, phone}]}`. Les champs `phone` et `passengers` sont masqués selon 4.10 : chaîne vide ou liste vide. #### Groupe | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/friends/people` | | 200 `[{id, name, avatarVersion, level, followStatus, followsMe, blocked, status: null \| {kind: "live", spotId, spotName, since} \| {kind: "planned", spotId, spotName, day}}]` | | GET | `/friends/map` | | 200 `[{spotId, spotName, lat, lon, friends: [{id, name, avatarVersion, level, status: "live"\|"planned", day?}]}]` | | PUT | `/friends/:id` | `{level: "FOLLOW"\|"STAR"}` | 200 `{status: "PENDING"\|"ACCEPTED"}` · 400 · 403 · 404 | | DELETE | `/friends/:id` | | 204 | | POST | `/friends/requests/:id/accept` | `{}` | 204 · 404 | | POST | `/friends/requests/:id/decline` | `{}` | 204 · 404 | | DELETE | `/friends/followers/:id` | | 204 | | PUT | `/friends/:id/block` | | 204 · 400 · 404 | | DELETE | `/friends/:id/block` | | 204 | | POST | `/friends/:id/report` | `{reason}` (5 à 1 000 caractères) | 204 · 400 · 404 | #### Notifications push | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/push/key` | | 200 `{publicKey: string \| null}` | | POST | `/push/subscriptions` | `{endpoint, keys: {p256dh, auth}}` (clés de 200 caractères max) | 204 · 400 service non reconnu | | DELETE | `/push/subscriptions` | `{endpoint}` | 204 | | POST | `/push/test` | `{}` | 204 ; notification « Les notifications fonctionnent. Bon vent ! » | #### Administration (rôle administrateur et second facteur actif) | Verbe | Chemin | Requête | Réponse | |---|---|---|---| | GET | `/admin/users` | | 200 `[{id, email, name, avatarVersion, phone, role, disabled, emailVerified, createdAt, google, hasPassword, invitedByName, invitedCount, lastCheckin}]`, du plus récent au plus ancien | | PATCH | `/admin/users/:id` | `{role?, disabled?, emailVerified?}` | 200 `{ok: true}` · 400 action sur soi-même · 404 | | DELETE | `/admin/users/:id` | | 204 · 400 sur soi-même · 404 | | GET | `/admin/reports` | | 200 `[{id, reason, createdAt, resolvedAt, reporter: {id, name, email}, reported: {id, name, email, disabled}}]` : ouverts d'abord, puis les 50 derniers traités | | POST | `/admin/reports/:id/resolve` | `{}` | 204 · 404 | | GET | `/admin/telegram` | | 200 `{configured, bot: nom du bot \| null, settings: {chatId, chatTitle, events: {checkins, plans}}}` | | POST | `/admin/telegram/detect` | `{}` | 200 `[{id, title, type}]` · 502 | | PUT | `/admin/telegram` | `{chatId? (entier signé, 20 chiffres max), chatTitle?, events: {checkins, plans}}` | 200 les réglages enregistrés | | POST | `/admin/telegram/test` | `{}` | 204 (rien n'est envoyé si aucun groupe n'est choisi) · 502 | | GET | `/admin/audit?before=` | | 200 `[{id, createdAt, action, target, ip, meta, actor: {id, name, email} \| null}]` : 100 entrées au plus, par identifiant décroissant | --- ## 6. CONTRAINTES TECHNIQUES ### 6.1 Contraintes réelles (le comportement en dépend) | Contrainte | Raison | |---|---| | **HTTPS en production** | Le push web, l'installation de l'application et le préfixe de cookie `__Host-` l'exigent. Sur iPhone, le push ne fonctionne que si l'application est installée sur l'écran d'accueil (iOS 16.4 et suivants). | | **API et application servies sur la même origine** | La protection anti-CSRF repose sur des cookies `SameSite=Lax`, sur l'exigence de JSON pour les `POST` et sur l'absence de CORS. La politique de contenu est en `self`. Le service worker ne doit pas mettre l'API en cache. | | **Base relationnelle transactionnelle avec verrou de ligne et insertion atomique « créer ou incrémenter »** | Il faut des réservations sans surréservation (verrou exclusif sur la session) et des compteurs anti-abus atomiques. Il faut aussi des dates calendaires, des listes de textes (ou une table annexe pour les codes de secours) et du JSON (réglages, journal). PostgreSQL (17 à l'origine) remplit tout cela. Un équivalent convient s'il offre ces garanties. | | **Compteurs anti-abus persistants et partagés** | Les verrous de compte, les plafonds d'e-mails et les délais de notification doivent survivre aux redémarrages et être communs à toutes les instances. Un cache en mémoire ne suffit pas. Ils peuvent vivre dans la base, ou dans un magasin clé-valeur persistant. | | **Fuseau de la communauté** pour les jours | « Aujourd'hui » et J+14 doivent être identiques pour tous les membres, quel que soit l'appareil. | | **Proxy inverse en frontal** | L'application tourne derrière un nginx en conteneur. L'IP réelle du client (utilisée par les limites de débit) n'est lue dans l'en-tête de transfert que si le proxy figure dans la liste des proxys de confiance. | | **Déploiement en conteneur, chaîne CI/CD GitLab** | Exigence de l'auteur. Une seule image contient l'API et l'application. Au démarrage, le conteneur applique les migrations, puis l'amorçage idempotent (spots et administrateur), puis lance le serveur. Il expose une sonde de santé. La base n'est pas joignable depuis le réseau du proxy. | | **Envoi d'e-mails par Brevo** | L'auteur a un compte Brevo. L'API transactionnelle est appelée avec une clé et un expéditeur validé. | | **Connexion Google** (OAuth web) | Exigée par l'auteur. L'URI de redirection est `/api/auth/google/callback`. | | **Web Push avec clés VAPID** | Ce sont des clés **stables** : les changer invalide tous les abonnements des appareils. | | **Bot Telegram** vers un groupe existant | Demandé par l'auteur. | | **Pas de données de vent temps réel de Winds-Up** | Les conditions d'utilisation de ce service interdisent la rediffusion. Seule la liste des spots a été importée, une fois. | | **Échec au démarrage si la configuration est invalide** | Voir la liste ci-dessous. | ### 6.2 Variables d'environnement | Variable | Obligatoire | Rôle et validation | |---|---|---| | `DATABASE_URL` | **oui** | Connexion à la base. Le démarrage échoue si elle manque. | | `PUBLIC_URL` | non (défaut `http://localhost:3000`) | URL publique, sans barre finale. Elle doit commencer par `http://` ou `https://`. Elle sert aux liens des e-mails, au retour Google et aux liens d'invitation. En `https`, elle active les cookies sécurisés et HSTS. | | `PORT` | non (3000) | Port d'écoute. | | `TZ` | non (`Europe/Paris`) | Fuseau de la communauté. | | `TRUST_PROXY` | non | Proxys de confiance (adresses IP ou plages CIDR seulement, pas de noms de machine). Par défaut : boucle locale, adresses lien-local et réseaux privés. Recommandé : le sous-réseau du réseau Docker du proxy. | | `REGISTRATION_MODE` | non (`open`) | `open` ou `invite`. Toute autre valeur fait échouer le démarrage. | | `TURNSTILE_SITE_KEY` / `TURNSTILE_SECRET_KEY` | non | Les deux ou aucune, sinon le démarrage échoue. | | `CHECKIN_RETENTION_DAYS` | non (365) | Nombre positif. | | `MAIL_HOURLY_LIMIT` | non (300) | Nombre positif. | | `BREVO_API_KEY` | non | Sans elle, les e-mails sont seulement écrits dans les logs. | | `MAIL_FROM` | si `BREVO_API_KEY` | Adresse de l'expéditeur. | | `MAIL_FROM_NAME` | non (« Shaka Crew ») | Nom de l'expéditeur. | | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | non | Sans elles, le bouton Google est masqué. | | `TELEGRAM_BOT_TOKEN` | non | Jeton du bot. | | `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` | non, mais les deux ou aucune | Sinon le démarrage échoue. Sans elles, le push est désactivé. | | `VAPID_SUBJECT` | non | Contact VAPID, par défaut `mailto:`. | | `ADMIN_EMAIL`, `ADMIN_NAME`, `ADMIN_PASSWORD` | non | Administrateur de départ (4.12). Il vaut mieux laisser `ADMIN_PASSWORD` vide (12 caractères minimum s'il est rempli). | | `THROTTLE_DISABLED` | non | `1` désactive les limites de débit (tests). | | `LOG_FORMAT` | non | `json` force des logs d'une ligne JSON par entrée, comme c'est déjà le cas en production. | | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `HOST_PORT`, `PROXY_NETWORK` | déploiement | Paramètres de l'orchestration des conteneurs. | | `BACKUP_DIR`, `BACKUP_KEEP_DAYS`, `BACKUP_PASSPHRASE_FILE`, `BACKUP_REMOTE` | non | Sauvegarde quotidienne de la base : export compressé, chiffré si une phrase secrète est fournie, rétention de 30 jours par défaut, copie hors du serveur en option. | ### 6.3 Intégrations externes - **Brevo** : API d'envoi d'e-mails transactionnels. - **Google** : points d'autorisation et d'échange de jeton OAuth 2.0 / OpenID Connect. - **Cloudflare Turnstile** : script du widget côté client, vérification du jeton côté serveur (avec l'IP du client). - **Telegram Bot API** : nom du bot, mises à jour récentes, envoi de messages HTML. - **Services de push des navigateurs** (Google, Mozilla, Apple, Microsoft). - **Tuiles OpenStreetMap** standard, sans clé, à usage raisonnable. Les changer pour un fournisseur commercial impose d'adapter la politique de contenu et le cache du service worker. ### 6.4 Choix d'opportunité du premier auteur (librement remplaçables) Pour l'API : TypeScript avec un cadriciel modulaire et injection de dépendances. Pour l'accès aux données : un ORM avec migrations. Pour l'interface : React avec un outil de construction moderne, des composants accessibles prêts à l'emploi, une bibliothèque de cartes en tuiles et une bibliothèque de cache de requêtes. Les polices d'affichage et de texte, la palette exacte, les icônes et la génération du logo (des mains « shaka » au-dessus d'une houle) relèvent du même registre. Le nommage `__Host-sid`, `__Host-mfa`, `__Host-gstate` est un détail, mais **le préfixe `__Host-` lui-même est une exigence**. Le numéro de version (`-`, ou « dev » en local) est injecté à la construction. ### 6.5 Reprendre une base de données existante (facultatif) Une régénération qui doit reprendre la base de production doit relire ses formats : - **Mots de passe** : `scrypt$N,r,p$$`. Les paramètres actuels sont N = 32768, r = 8, p = 3, pour une clé de 64 octets. Les hachages anciens au format `scrypt$$` utilisent N = 16384, r = 8, p = 1. Ils doivent être reconnus, puis recalculés avec les paramètres actuels à la connexion suivante. - **Jetons de session, jetons d'e-mail, tickets d'étape, codes de secours** : stockés sous forme d'empreinte SHA-256 en hexadécimal. Les codes de secours sont hachés une fois normalisés au format `xxxx-xxxx`. - **Secret TOTP** : base32 standard, sans remplissage. - **Jours des sessions** : dates sans heure. Les autres horodatages sont en UTC. --- ## 7. CRITÈRES D'ACCEPTATION Chaque assertion doit pouvoir se vérifier isolément. Les tests de bout en bout sont lancés sur une base **jetable** : créée, migrée et amorcée pour chaque exécution, puis supprimée. Sauf mention contraire, les limites de débit sont désactivées. L'URL publique est en HTTP, sauf pour les tests de cookies. Les e-mails sont capturés. ### 7.1 Amorçage et santé 1. Sur une base vide, l'amorçage importe exactement le nombre de spots du fichier fourni (454). Un deuxième lancement n'en ajoute aucun. Un spot créé ensuite reçoit un identifiant supérieur au plus grand identifiant importé. 2. `GET /api/health` répond 200 `{"status":"ok"}` sans session. 3. Avec `ADMIN_EMAIL` renseigné et `ADMIN_PASSWORD` vide, le compte administrateur est créé **sans mot de passe** et un e-mail contenant `/reset/` part vers cette adresse. Utiliser ce lien fixe le mot de passe, marque l'adresse comme vérifiée et ouvre une session. Un deuxième amorçage ne renvoie pas de lien tant que le premier est valide. 4. Si un compte **non vérifié** avec mot de passe existe déjà à l'adresse `ADMIN_EMAIL` avant l'amorçage, il n'est pas promu tel quel : ses sessions sont révoquées, son mot de passe est effacé (ou remplacé par `ADMIN_PASSWORD`), et l'ancien mot de passe ne permet plus de se connecter. 5. Un `ADMIN_PASSWORD` de moins de 12 caractères fait échouer l'amorçage. 6. Le serveur refuse de démarrer : sans `DATABASE_URL` ; avec un `REGISTRATION_MODE` différent de `open` et `invite` ; avec une seule des deux clés VAPID ; avec une seule des deux clés Turnstile ; avec `BREVO_API_KEY` mais sans `MAIL_FROM`. ### 7.2 Inscription, vérification, connexion 7. Une inscription avec une adresse libre répond 201 `{ok:true}` et envoie un lien `/api/auth/verify?token=…`. Avant le clic, `POST /auth/login` répond 403. 8. Une inscription avec une adresse **déjà vérifiée** répond aussi `{ok:true}`. Elle ne change ni le nom ni le mot de passe du compte existant, qui reçoit un e-mail « déjà un compte ». Une inscription avec une adresse **non vérifiée** ne change pas le mot de passe enregistré. 9. Ouvrir le lien de vérification renvoie un 302 vers `/login?verified=1` **sans** cookie de session. Le réutiliser renvoie vers `/login?err=lien`. 10. Une connexion valide répond 200 `{user}` et dépose un cookie httpOnly. Ce `user` ne contient ni empreinte de mot de passe ni secret TOTP. 11. Un `POST` vers l'API avec un type de contenu autre que JSON répond 415 « JSON requis ». Un corps de plus de 16 Ko répond 413. Un avatar de 400 Ko en base64 est accepté par la limite de taille. 12. Une erreur de validation répond 400 avec un `message` **chaîne** (par exemple « Email invalide »). Un champ inconnu est ignoré en silence. 13. Un mot de passe de 7 caractères est refusé : « Mot de passe : 8 caractères minimum ». 14. Après 5 mauvais mots de passe sur une même adresse, la 6ᵉ tentative, **même avec le bon mot de passe et depuis une autre IP**, répond 429, et le titulaire reçoit un e-mail d'alerte. Une réinitialisation du mot de passe lève le verrou. 15. Après 3 e-mails de compte vers une même adresse dans la journée, une nouvelle inscription vers cette adresse répond 429. Une demande de mot de passe oublié répond 200 sans envoyer d'e-mail. 16. En mode `invite`, une inscription sans code valide répond 403. Elle réussit avec le code d'invitation d'un membre actif et vérifié, et le nouveau compte est rattaché à ce parrain. 17. En HTTPS, le cookie de session s'appelle `__Host-sid` et porte `Secure`, `HttpOnly`, `Path=/` et `SameSite=Lax`, sans attribut `Domain`. En HTTP, il s'appelle `sid`. 18. Une réinitialisation de mot de passe ferme toutes les sessions existantes du membre : un ancien cookie reçoit 401 sur une route protégée. 19. Un hachage de mot de passe aux paramètres anciens est remplacé par un hachage aux paramètres actuels après une connexion réussie. ### 7.3 Second facteur et appareils 20. `POST /me/totp/setup` renvoie un secret et une URI `otpauth://`. Un code calculé avec ce secret, transmis à `/me/totp/enable`, renvoie 10 codes de secours et ferme les autres sessions du membre. 21. Une fois le second facteur actif, `POST /auth/login` répond `{mfa:true}` sans cookie de session. `POST /auth/mfa` avec un code valide ouvre la session. **Le même code, rejoué, est refusé.** 22. Un code de secours permet une connexion **une seule fois**. Ensuite, `recoveryCodesLeft` vaut 9. 23. Au 5ᵉ code faux, le ticket est annulé : même un code valide répond alors 401 jusqu'à une nouvelle saisie du mot de passe. 24. Un administrateur sans second facteur reçoit 403 sur toute route `/api/admin/*`. Avec le second facteur actif, il reçoit 200. 25. `GET /me/security` liste les sessions, la courante marquée `current: true`. `DELETE /me/sessions/:id` ferme l'appareil visé. `DELETE /me/sessions` ferme tous les appareils sauf le courant. L'identifiant de session d'un autre membre répond 404. 26. Une session inactive depuis plus de 30 jours, ou ouverte depuis plus de 180 jours, est refusée (401). ### 7.4 Spots, check-ins, carte 27. `GET /spots` renvoie tous les spots, avec `riders`, `plans` et `favorite`. Après un check-in d'un membre visible, `riders` vaut 1 pour ce spot et le spot apparaît dans `GET /checkins/live`. 28. Un deuxième check-in du même membre sur un autre spot termine le premier : un seul check-in actif par membre. 29. `POST /checkins/end` termine le check-in. Un check-in non terminé n'est plus compté comme actif au bout de 4 h. 30. Un check-in avec `windKts` à 81 ou `sailSize` à 16 répond 400. Un check-in sans aucune condition est accepté. 31. Un check-in sur un spot inexistant répond 404. 32. Le membre qui a le spot en favori reçoit une notification « Ça navigue à ». Un deuxième check-in dans les 3 h ne lui en envoie pas une autre. 33. Un abonné accepté reçoit « X est sur l'eau », ou « ★ X est sur l'eau » s'il a mis X en star. Un deuxième check-in de X dans les 2 h ne lui en envoie pas d'autre. 34. Un administrateur crée, modifie et supprime un spot. Supprimer un spot supprime ses check-ins, ses sessions et ses favoris. Un non-administrateur reçoit 403 sur ces routes. ### 7.5 Sessions prévues et covoiturage 35. Une session au jour J+15, ou à une date passée, répond 400. Une session au jour J+14 est acceptée. 36. Renvoyer une session pour le même spot et le même jour met à jour la session existante : `GET /plans` ne montre qu'une seule session. 37. `ride: "offer"` sans `seats` répond 400. 38. Pour une session à 1 place, deux réservations **simultanées** par deux membres donnent exactement un 204 et un 409. 39. Réserver sa propre session répond 400. Réserver une deuxième fois la même session répond 204 sans créer de deuxième réservation. 40. Le conducteur reçoit un e-mail et une notification à chaque réservation et à chaque libération. 41. Le téléphone du conducteur et la liste des passagers sont vides pour un membre tiers. Ils sont visibles pour un passager. Le téléphone d'un passager n'est visible que par le conducteur et par ce passager. 42. Le téléphone d'un membre qui « cherche une place » n'apparaît **jamais** dans `GET /plans` pour les autres membres. `POST /plans/:id/ride-offer` envoie à ce membre le nom, le téléphone et l'e-mail du conducteur. Une deuxième proposition du même conducteur répond 409. 43. Supprimer une session réservée, ou la repasser en `ride: "none"`, supprime les réservations et prévient chaque passager par e-mail et par notification. 44. L'annonce d'une nouvelle session n'est envoyée aux abonnés qu'une fois par (auteur, spot, jour), même après une suppression suivie d'une recréation. ### 7.6 Vie privée, suivis, blocages, signalements 45. Avec la visibilité `NOBODY`, les check-ins et sessions d'un membre n'apparaissent pour **aucun autre membre** : ni dans le direct, ni dans les compteurs de `/spots`, ni sur la fiche spot, ni dans `/plans`, ni dans l'état de `/friends/people`. Ils ne déclenchent aucune notification. 46. Avec la visibilité `FOLLOWERS`, seul un abonné **accepté** voit les positions. Un abonné en attente ne les voit pas. 47. Suivre un membre qui valide ses abonnés renvoie `{status:"PENDING"}`. Tant que la demande n'est pas acceptée, le suiveur ne reçoit aucune notification de check-in. Après acceptation, il en reçoit. 48. Bloquer un membre supprime les suivis dans les deux sens. Le membre bloqué ne voit plus les positions de celui qui l'a bloqué, ne le voit plus dans `/friends/people`, ne peut plus le suivre (403) et ne peut plus réserver ses trajets (404). 49. Un signalement de 4 caractères répond 400. Un signalement valide apparaît dans `/admin/reports` et notifie les administrateurs. 50. Un nouveau compte a `shareTelegram = false`. Aucun message Telegram ne part pour un check-in sans consentement explicite, ni pour un membre dont la visibilité n'est pas `EVERYONE`. 51. Avec consentement et visibilité `EVERYONE`, un message Telegram part pour le premier check-in sur un spot. Aucun ne part pour un deuxième check-in sur le même spot dans les 2 h. ### 7.7 Compte, données, avatars, invitations 52. `PUT /me/avatar` avec un PNG valide renvoie `avatarVersion` augmenté de 1. L'image servie est un WebP de 256 × 256 **sans métadonnées EXIF ni GPS**. Un fichier texte renommé en image, une image de plus de 4 096 px de côté ou un fichier de plus de 300 Ko répond 400. 53. `GET /users/:id/avatar` sans session répond 401. 54. `PUT /me/home` avec `south >= north` répond 400. Une zone valide est renvoyée dans `user.home`. 55. `GET /me/export` renvoie un fichier en pièce jointe qui contient au moins le profil, les check-ins, les sessions, les réservations, les suivis, les favoris et les blocages. 56. `POST /me/deletion` répond 202 et envoie un lien `/delete-account/`. `POST /auth/delete-account` avec ce jeton répond 204 et supprime le compte et toutes ses données. Le même jeton, réutilisé, répond 400. 57. Le dernier administrateur actif ne peut pas supprimer son compte (409). 58. Une invitation par e-mail envoyée depuis un compte créé il y a moins de 24 h répond 403. Une deuxième invitation vers la même adresse dans la semaine répond 409. 59. Le parrain reçoit la notification « Ton invitation a marché » quand son filleul active son compte. ### 7.8 Administration et journal 60. Un administrateur qui tente de se rétrograder ou de se bloquer reçoit 400. Bloquer un autre compte ferme ses sessions (son cookie reçoit 401) et supprime ses abonnements aux notifications : il ne reçoit plus aucune notification. 61. Chaque écriture d'administration crée une entrée de journal. Un mot de passe ou un code présent dans le corps y apparaît sous la forme `***`. 62. Les verrouillages de compte, les réinitialisations, l'activation et la désactivation du second facteur, et l'usage d'un code de secours apparaissent dans le journal. ### 7.9 Notifications push 63. Un abonnement dont l'adresse n'est pas un service de push reconnu (par exemple `https://127.0.0.1/…` ou `http://fcm.googleapis.com/…`) répond 400. 64. Un abonnement auquel le service de push répond 410 est supprimé. ### 7.10 Limites de débit (limites activées) 65. Le 7ᵉ check-in dans l'heure répond 429, avec un message de la forme « Trop de requêtes, réessaie dans N min. ». 66. La 6ᵉ inscription dans l'heure depuis une même IP répond 429. 67. Deux instances du serveur branchées sur la même base partagent les compteurs : le verrou de compte posé par l'une est appliqué par l'autre. ### 7.11 Interface 68. Sur un écran de 375 px de large, la carte occupe tout l'écran, le panneau est une feuille repliable en bas et la barre d'onglets est en bas. Sur un écran de 1 280 px, le panneau est à droite et la navigation est un rail vertical à gauche. 69. Chaque écran qui charge des données affiche un squelette, puis le contenu ou un état vide explicite (libellés de 5.2). 70. La recherche « almanarre » (sans accent ni majuscule) trouve « Almanarre - Salin des Pesquiers ». 71. Un membre connecté qui ouvre `/login` est redirigé vers `/`. Un visiteur qui ouvre `/sessions` est redirigé vers `/login`. Avec `?invite=CODE` dans l'URL d'arrivée, il est redirigé vers `/signup` et le code disparaît de l'URL. 72. L'application passe l'audit d'installabilité PWA d'un navigateur Chromium : manifeste, service worker, icônes 192 et 512 px (dont une icône adaptative) et deux raccourcis. 73. Hors ligne, l'application déjà visitée s'ouvre et affiche les tuiles de carte vues récemment. Un appel à l'API affiche « Tu es hors ligne. ». 74. Un clic sur une notification « Nouvelle réservation » ouvre `/sessions` dans la fenêtre de l'application si elle est déjà ouverte. 75. Le thème Sombre assombrit le fond de carte sans changer la couleur orange des spots actifs. Le choix du thème est conservé après rechargement. --- ## Points à confirmer par l'auteur Le code ne permet pas de trancher les points suivants. Une régénération doit reproduire le comportement constaté, sauf avis contraire de l'auteur. 1. **Vent temps réel.** Le cahier des charges demandait le vent temps réel des balises Winds-Up. Le service n'a pas été branché parce que ses conditions d'utilisation l'interdisent. Les observations des riders suffisent-elles, ou faut-il une source de vent sous licence ouverte (par exemple un modèle météo public) ? 2. **Logiciel payant remplacé.** Le code ne le dit pas. L'hypothèse retenue en section 1 (abonnement premium d'un service de spots et de vent, plus les groupes de messagerie) est à valider. 3. **Baisse du nombre de places sous le nombre de réservations.** Un conducteur qui passe de 3 à 1 place alors que 3 passagers ont réservé les garde tous, et l'interface affiche « Complet ». Seul le passage à 0 place annule les réservations. Faut-il refuser ce changement, ou retirer les derniers inscrits ? 4. **Protection du dernier administrateur.** La suppression par le membre lui-même vérifie qu'il n'est pas le dernier administrateur actif. Depuis l'administration en revanche, un administrateur peut rétrograder, bloquer ou supprimer **un autre** administrateur, même le dernier autre. Est-ce voulu ? 5. **Zone par défaut et antiméridien.** Seul « sud < nord » est contrôlé. Une zone avec ouest > est est acceptée. Faut-il gérer les zones qui traversent l'antiméridien, ou les refuser ? 6. **Bornes de saisie.** L'interface limite le vent à 50 nœuds et propose des voiles de 3,3 à 9,5 m². Le serveur accepte jusqu'à 80 nœuds et des voiles de 1 à 15 m². Lesquelles sont les vraies bornes métier ? 7. **Fuseau horaire.** Le serveur calcule les jours dans le fuseau de la communauté (Paris). L'interface affiche « Aujourd'hui » et « Demain » et propose les dates selon l'heure de l'appareil. Pour un membre en Outre-mer ou en Thaïlande (spots présents dans les données), les deux peuvent diverger. Faut-il un fuseau par spot ? 8. **Plusieurs sessions le même jour.** L'unicité porte sur (membre, spot, jour). Un membre peut donc annoncer deux spots le même jour, avec deux covoiturages. Est-ce voulu ? 9. **Parrainage en mode ouvert.** Le code d'invitation d'un membre bloqué ou non vérifié rattache quand même le filleul à ce parrain. Seul le mode invitation exige un parrain actif et vérifié. 10. **Annonces Telegram des sessions.** Il n'y a aucun délai minimum par spot, contrairement aux check-ins (2 h). Il n'y a que la déduplication par auteur, spot et jour. 11. **Plafond de la liste des membres.** Elle est limitée à 1 000 membres, sans pagination. Est-ce suffisant pour la taille visée de la communauté ? 12. **Réception des signalements.** Il est possible de signaler un compte déjà bloqué, et le signalement n'a pas de catégorie. Faut-il des motifs prédéfinis ? 13. **Validation des abonnés activée par défaut** (`followApproval = true`) et visibilité « Tous » par défaut. Ces deux défauts sont-ils le bon compromis entre partage et protection contre le pistage ? 14. **Administrateur et vérification de l'adresse.** Un administrateur peut marquer manuellement une adresse comme vérifiée. Dans quel cas d'usage, et faut-il le journaliser à part ? Aujourd'hui, seul le journal automatique des écritures d'administration le garde. 15. **Durée de rétention.** L'historique de positions est effacé au bout de 365 jours par défaut, et la notice de confidentialité annonce « 12 mois ». Si l'exploitant change `CHECKIN_RETENTION_DAYS`, la notice n'est pas mise à jour automatiquement. Faut-il l'alimenter par la configuration ? 16. **Nom de domaine.** Le fichier d'exemple de configuration contient `shaka-craw.librehub.store`, alors que le nom de l'application est « crew ». C'est un paramètre de déploiement (`PUBLIC_URL`). Le domaine réel est à confirmer. 17. **Spots importés.** La liste de 454 spots vient d'un export unique de Winds-Up. Le droit de réutiliser cette base (droit des producteurs de bases de données) reste à confirmer, ou la liste doit être reconstituée à partir d'une source ouverte.