Melvane Review Management

Planifie une visite sur place pour compléter la fiche M.G.B avant qu'un ticket ne soit assigné à 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).

Le compte créé a toujours le rôle Lecture & écriture.

Les prestataires assignables aux tickets. Chacun peut avoir un compte "Mes tickets" (lien à usage unique : la personne saisit son numéro de téléphone et valide un code reçu par SMS, sans e-mail ni mot de passe ; ce numéro sert aussi au SMS d'assignation) qui ne montre QUE ses propres tickets et leurs codes d'accès — jamais les rubriques admin. « Couper l'accès » déconnecte la personne tout de suite ; sans aucun usage pendant 1 mois, la session se coupe d'elle-même (une nouvelle connexion par SMS suffit).

Chaque modification d'une fiche logement (Melvane App, Front Desk, Prestataire-Immo) garde l'ancienne valeur. Filtre, coche ce qu'il faut défaire, puis « Remettre les anciennes valeurs ». Un champ modifié depuis par quelqu'un d'autre n'est jamais écrasé (signalé). L'annulation est elle-même inscrite ici.

Choisis l'utilisateur Guesty de la personne (liste tirée des messages de l'équipe, sans rien écrire dans Guesty), confirme son prénom, puis crée le lien de connexion. Le prénom signe ses messages dans le Front desk. Le lien ne sert qu'une fois et n'est affiché qu'une fois ; rien n'est envoyé automatiquement. La personne se connecte ensuite avec son numéro de téléphone (code reçu par SMS), sans mot de passe.

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 (assignation 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'assignation 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, assignation, 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/écarté (jamais « terminé » : un ticket est actif ou clos), calculé à la lecture à partir de issues_v3 + ticket_dispatch + Monday. Une réponse d'équipe met seulement le badge « Vu par SweepIt » ; la clôture se fait à la main ou automatiquement sur preuve (lib/auto-close.js).
3. Assignation (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)
• retired-listings.js — liste des logements RETIRÉS de toutes les listes de l'app (décision de Roman, 2026-10-16) : 5CHE, 5CHE2, 64 rue Pajol, 7TRE, 362JAC. Rien n'est supprimé en base (avis, messages, fiches restent), ils ne sont simplement plus proposés (avis, recherche, visites, Informations, client mystère). Pour retirer un autre logement ou en remettre un : modifier la liste RETIRED de ce fichier (un seul endroit, utilisé par le navigateur et par le serveur) puis pousser. Les tickets d'un logement retiré ne sont pas filtrés.

Sélections de tickets envoyées par lien à quelqu'un qui n'a pas l'app (prestataire, David pour Moret, propriétaire). Créez-en un depuis « À dispatcher » : cochez des tickets, puis « Lien (N) ». Les tickets restent dans « À dispatcher » ; « C'est fait » sur la page les met en « Fait · à confirmer ». Un lien vit 30 jours.