Melvane Review Management

Planifie une visite sur place pour compléter la fiche M.G.B avant qu'un ticket ne soit affecté à un prestataire. Tous les logements sont listés (« Ce qui est déjà enregistré » détaille chaque rubrique et l'équipement pièce par pièce), du plus susceptible d'être incomplet (rouge) au plus complet (vert). Jamais Moret ni Bastille (déjà bien suivis autrement / pas de vraie activité Guesty).

Crée un lien à envoyer à une personne : elle choisit elle-même son prénom, son email et son mot de passe, et n'accède qu'aux rubriques cochées ci-dessous. Le lien ne sert qu'une fois.

Les prestataires assignables aux tickets. Chacun peut avoir un compte "Mes tickets" (lien à usage unique : il choisit son email, son mot de passe et renseigne son téléphone pour recevoir le SMS d'affectation) qui ne montre QUE ses propres tickets et leurs codes d'accès — jamais les rubriques admin.

Fiche de reprise en main : ce qu'il faut savoir pour continuer ce projet sans avoir tout redécouvert. Mise à jour manuelle (pas automatique) — pense à la tenir à jour quand l'architecture change.

Site statique (index.html, un seul fichier, pas de framework) + fonctions serveur Vercel (api/*.js) + base de données Supabase (Postgres/PostgREST + Auth + Storage). Le "pipeline" (pipeline/*.py et *.js) tourne sur GitHub Actions, jamais sur Vercel — c'est lui qui fait le gros travail (synchro Guesty, détection Gemini, classement...), déclenché par des workflows planifiés ou manuels.

Tout le développement actif se fait sur la branche v3. La branche main contient une ancienne version (V1), structurellement différente, encore en production sur un autre déploiement Vercel. Ne jamais fusionner v3 dans main sans accord explicite — décision volontaire du propriétaire, le risque de casser la prod est réel (fichiers totalement différents). Le site v3 réel tourne via un déploiement "Preview" Vercel qui suit la branche v3 (URL du type review-git-v3-*.vercel.app), pas via l'environnement "Production".

Piège GitHub Actions : un workflow avec schedule ou workflow_dispatch n'apparaît dans l'onglet Actions QUE s'il existe sur la branche par défaut (main) — même si son job fait ensuite checkout ref: v3 pour exécuter le code v3. Les workflows de ce projet sont donc présents sur les deux branches (le fichier .yml seulement, jamais le code applicatif).

Projet Supabase de MRM (id etztqbfoacmeiudiacze, organisation Melvane Pro). Tables principales :

• reviews, reply_actions, action_resolutions — avis et réponses (cœur historique de l'app)
• issues_v3 — une ligne par problème détecté (avis + échanges), status = nouveau/en_cours/resolu/ignore ; resolved_on_site = le client dit lui-même que c'est réglé (Gemini)
• guest_messages — messages Guesty captés par webhook, processed_at = déjà analysés par Gemini ou pas
• ticket_dispatch — annexe à issues_v3 (jamais de clé étrangère) : catégorie/bloc, intervenant choisi, sent_at/provider_token (affectation réelle), colonnes provider_* (ce que fait le prestataire sur sa fiche, dont provider_planned_slot_start/end = créneau choisi sur le calendrier de disponibilité), colonnes monday_* (confirmation Monday.com)
• dispatch_providers / dispatch_assignments — liste des intervenants et règles d'affectation par bloc/logement
• monday_sweepit_items — audit des interventions SweepIt lues sur Monday.com, rapprochées par Gemini
• monday_snapshots — copie en lecture seule des tableaux Monday (facturation mensuelle, À faire, Prestataires, Réparations, Contacts sans mots de passe, Liens de paiement) pour Tickets > Monday
• mgb_property_knowledge — cache (partiel, sans les photos) des fiches M.G.B, alimenté par pipeline/sync_mgb_v3.py
• listing_addresses — adresses structurées par logement (depuis Guesty), utilisées pour les SMS, l'affichage et le calendrier de disponibilité
• push_subscriptions — abonnements Web Push des comptes prestataires ("Mes tickets" installé + notifications activées), un par navigateur/appareil
• user_roles — comptes : role (write=admin, read=reste), profile/permissions (droits par rubrique), provider_id (compte prestataire relié à dispatch_providers)
• invitations — liens d'inscription à usage unique (créés dans Administration → Utilisateurs et codes)
• guesty_token_cache, webhook_throttle — état technique interne (jetons, anti-rafale)

RLS activée partout ; la plupart des tables annexes n'ont AUCUNE policy — accessibles uniquement via la clé service, jamais depuis le navigateur. Les migrations sont des fichiers pipeline/migration_*.sql exécutés à la main dans l'éditeur SQL Supabase (pas d'outil de migration automatique).

Limite stricte de 12 fonctions sur le plan Vercel utilisé — ne jamais créer de nouveau fichier dans api/ sans vérifier qu'on est en dessous de la limite ; ajouter une action à une fonction existante à la place (ex. toutes les actions dispatch_* et provider_* vivent dans update-issue.js). Fonctions actuelles : update-issue.js (statuts, affectation, fiche prestataire), guesty-webhook.js (messages entrants), publish-reply.js, refresh-issues.js, trigger-sync.js, sync-status.js, check-reply-status.js, ticket-conversation.js, phone-calls.js, join.js (inscription par lien), admin-users.js, admin-invites.js.

• sync-reviews.yml — synchro quotidienne des avis (2 horaires, V1)
• sync-monday-sweepit.yml — toutes les 20 min, rapproche Monday.com ↔ tickets via Gemini
• backfill-historical-ratings-v3.yml — le "couteau suisse" : un seul workflow, des dizaines d'options via le menu déroulant check_only (détection de tickets, sondes de diagnostic temporaires, resynchronisations manuelles...). Déclenché aussi automatiquement par le webhook Guesty (option issues_messages) à chaque message client/équipe, avec un anti-rafale de 10 min (webhook_throttle).

Beaucoup de "sondes temporaires" (pipeline/probe_*.py) ont été créées pendant ce projet pour vérifier une hypothèse en lecture seule avant de coder — pattern à réutiliser plutôt que de deviner la forme d'une API.

• Guesty (PMS) — OAuth client credentials, jeton mis en cache dans guesty_token_cache (jamais redemandé inutilement). Variables : GUESTY_CLIENT_ID, GUESTY_CLIENT_SECRET.
• M.G.B (gestion-des-biens.vercel.app) — base de connaissance des logements (codes, clés, équipements, photos). API REST simple, clé MGB_API_KEY. Les photos vivent dans un tableau attachments à part, reliées par entityType/entityId aux clés/équipements — accès API étendu le 2026-09-29 (avant, seulement visible en scrappant la page web).
• Gemini (Google) — détection des problématiques, classement, rapprochement Monday. Variable GEMINI_KEY. Modèles en rotation, sys.exit(3) volontaire si crédits épuisés (n'efface jamais les messages en attente, ils sont repris au run suivant).
• Anthropic/Claude — secours du chatbot si Gemini échoue, et bancs d'essai. Variable ANTHROPIC_API_KEY. Chatbot jamais déployé en vrai sans la phrase exacte convenue avec le propriétaire.
• Zadarma — téléphonie (appels) + SMS de secours aux prestataires (WhatsApp bloqué en attente de vérification Meta). Variables ZADARMA_KEY/ZADARMA_SECRET, SMS_TEST_RECIPIENT, MESSAGING_CHANNEL. Les SMS sont forcés vers un numéro de test sauf si un prestataire a un phone réel sur sa fiche (opt-in explicite, un seul cas en prod pour l'instant).
• WhatsApp Business (Meta Cloud API) — prêt côté code, jamais activé (vérification d'entreprise Meta en attente).
• Web Push (notifications navigateur, "Mes tickets") — EN PLUS du SMS, jamais à la place. Variables VAPID_PUBLIC_KEY/VAPID_PRIVATE_KEY/VAPID_SUBJECT (générées une seule fois : les régénérer invalide tous les abonnements existants). lib/push.js + service worker sw.js ; dépendance npm web-push (première du projet, voir package.json à la racine).
• Monday.com — tableau interne de SweepIt, lu (jamais écrit) pour confirmer qu'une intervention a réellement eu lieu.

1. issues_v3.status (nouveau/en_cours/resolu/ignore) — jamais touché par le reste, historique brut.
2. État calculé (lib/ticket-state.js, pur, sans écriture) — nouveau/vu/intervention/terminé/écarté, calculé à la lecture à partir de issues_v3 + ticket_dispatch + Monday. Un ticket n'est "terminé" que sur preuve d'action réelle, jamais sur une simple réponse d'équipe.
3. Affectation (ticket_dispatch) — catégorie, intervenant, envoi (réel ou simulé selon TD_DRY_TEST dans index.html), fiche prestataire (prestataire.html, lien à jeton unique par ticket) et tableau de bord compte (mes-tickets.html, un compte "prestataire" ne voit que ses propres tickets envoyés).

Deux rôles de base (write = tout, read = lecture). Au-dessus, un système de droits par rubrique (permissions jsonb) pour les comptes créés par lien d'invitation (Administration → Utilisateurs et codes → Lien de connexion), profils prédéfinis SweepIt/Direction/Personnalisé. Les comptes prestataires sont un profil à part (profile = 'prestataire') : jamais l'app admin, redirigés de force vers mes-tickets.html, ne voient que les tickets reliés à leur dispatch_providers.id.

• Pas de dédoublonnage entre plusieurs tickets décrivant le même problème (demandé, pas fait).
• "Tickets bruts" à renommer en "Log tickets" (demandé, pas fait).
• WhatsApp Business en attente de vérification Meta — SMS Zadarma en secours.
• Pipeline Merci Germain (pipeline/merci_germain/) séparé, autonome, piloté en local (pas sur GitHub Actions) — automatise la fiche prestataire Merci Germain, pas branché au reste.
• Le cache mgb_property_knowledge ne contient jamais les photos (l'API en direct oui, depuis le 2026-09-29) — la fiche prestataire appelle donc M.G.B en direct, pas ce cache, pour les photos.

• index.html — tout le front (une seule page, recherche par nom de fonction)
• api/ — fonctions serveur Vercel
• lib/ — logique pure partagée (testable sans réseau, voir test/)
• pipeline/ — scripts Python/Node exécutés par GitHub Actions
• pipeline/migration_*.sql — historique des évolutions de schéma (à exécuter à la main)
• .github/workflows/ — définitions des automatisations
• prestataire.html, mes-tickets.html, join.html — pages publiques autonomes (pas dans l'app principale)