Immojudis

Plateforme d'exploration des ventes immobilières aux enchères judiciaires en France. L'application aide l'investisseur à décider jusqu'à combien enchérir : pour chaque bien, un assistant calcule une mise plafond à partir du marché local (DVF), des frais, des travaux et d'une marge de sécurité, avec la localisation Mapbox et les documents officiels.

Le dépôt réunit deux briques :

Brique	Dossier	Stack	Rôle
Application web	racine (src/)	Next.js App Router · React 19	Front + API serveur consommés par l'investisseur
Pipeline de données	services/data-pipeline/	Python 3.12	Scraping → normalisation → déduplication → Supabase

---

Stack technique (web)

• Framework : Next.js App Router (SSR, routes serveur et API routes)
• UI : React 19, Tailwind CSS v4, composants shadcn/ui (Radix UI)
• Routing / data : App Router Next.js + adaptateur de compatibilité pour les anciennes routes + TanStack Query
• Backend : Supabase (Postgres, Auth, RLS)
• Cartographie : Mapbox GL JS + Mapbox Static Images, avec fallback OSM legacy
• Formulaires / validation : formulaires natifs + Zod
• Langage : TypeScript strict
• Hébergement : Vercel

Prérequis

• Node 24 (>=24.15.0 <25, voir .nvmrc — nvm use) et npm 11 (>=11.18.0 <12) : .npmrc active engine-strict=true, donc npm install / npm ci refusent une autre version de Node. Le npm livré avec Node peut être plus ancien : npm install --global [email protected] (version épinglée par la CI et par vercel.json). npm run check:versions vérifie que .nvmrc, .node-version, engines, la CI, vercel.json et l'image Playwright de la CI concordent.
• Un projet Supabase (URL + clé publishable)

Démarrage rapide

npm install
cp .env.example .env.local      # puis renseigner les variables (voir ci-dessous)
npm run dev                     # http://localhost:3000

npm run dev:ready est une alternative qui attend que Next.js et les routes SSR répondent réellement avant d'afficher l'URL. Pour préchauffer une annonce :

npm run dev:ready -- --warm-path /sales/<uuid>

Variables d'environnement

Le circuit commun de lecture est src/lib/env.ts (validé par zod : valeurs nettoyées, une valeur vide vaut « non définie »), mais plusieurs modules lisent encore process.env directement. La liste des variables facultatives, de leurs valeurs par défaut et des constantes qui n'en sont pas (pépites, inondation, loyers, essai) est dans docs/reference/variables-environnement.md.

Variable	Requis	Description
NEXT_PUBLIC_SUPABASE_URL	✅	Nom canonique. URL du projet Supabase (https://xxx.supabase.co)
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	✅	Nom canonique. Clé anon / publishable (publique, côté client). Repli historique : NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SECRET_KEY	✅	Clé serveur Supabase pour les API routes, ou SUPABASE_SERVICE_ROLE_KEY sur les projets legacy
SUPABASE_DB_URL	✅	URL Postgres directe pour les migrations. Replis acceptés : POSTGRES_URL_NON_POOLING, POSTGRES_URL
CRON_SECRET	✅	Secret des routes Vercel Cron et de POST /api/pipeline/revalidate-sale (invalidation du cache d'une fiche par le pipeline)
SITE_URL	✅	Nom canonique. Origine canonique publique (https://immojudis.com). Replis : NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_APP_URL, APP_URL. VERCEL_URL n'est plus acceptée seule en production (garde-fou de build)
RESEND_API_KEY	✅	Clé serveur Resend pour envoyer les alertes email consenties et les emails aux avocats référencés
ALERT_EMAIL_FROM	✅	Expéditeur vérifié Resend, par exemple Immojudis <[email protected]>
NEXT_PUBLIC_LEGAL_*	✅	Mentions légales : ENTITY_NAME, ENTITY_FORM, ENTITY_ADDRESS, REGISTRATION, PUBLICATION_DIRECTOR, CONTACT_EMAIL, CONTACT_PHONE, MEDIATOR_NAME, MEDIATOR_ADDRESS, MEDIATOR_WEBSITE. Le build de production échoue si l'une manque
ADMIN_MFA_REQUIRED

Les variables NEXT_PUBLIC_* sont inlinées au moment du build (et les VITE_SUPABASE_* encore présentes y sont recopiées par next.config.ts). En production (Vercel) elles doivent être présentes dans Project Settings → Environment Variables et suivies d'un redéploiement. Ne retirez les VITE_* qu'après ce redéploiement : tant qu'elles sont la seule source en production, les supprimer coupe la connexion à la base. Voir docs/vercel_setup.md pour la configuration complète (Auth, secrets CI, runner admin).

npm run env:check:prod vérifie les groupes de variables nécessaires aux API serveur et aux migrations avant un déploiement complet. Si Vercel marque des variables comme sensibles, leurs valeurs peuvent rester illisibles localement : le check valide alors leur présence déclarée, mais npm run db:migrate exige toujours une URL Postgres réellement disponible.

⚠️ Ne jamais exposer SUPABASE_SECRET_KEY ou SUPABASE_SERVICE_ROLE_KEY côté front : elles contournent la RLS.

Cartographie Mapbox

La page /sales utilise Mapbox GL JS pour la carte interactive : source GeoJSON, clusters natifs, marqueurs de prix, popups enrichies et synchronisation de la bbox avec la liste de biens. Les mini-cartes affichées ailleurs dans le site utilisent Mapbox Static Images pour rester rapides et économes en JavaScript. Le filtre "autour d'une adresse" utilise Mapbox Geocoding v6 en priorité (country=fr, language=fr, types=address,street,postcode,place,locality,neighborhood), puis l'API adresse française en secours.

Configurez NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN et, si besoin, NEXT_PUBLIC_MAPBOX_STYLE. Le style par défaut est mapbox/streets-v12. Les vues cartographiques et leurs replis utilisent exclusivement les services Mapbox configurés pour l'application.

Scripts

Script	Effet
npm run dev	Serveur de dev Next.js (HMR)
npm run dev:ready	Dev + attente que le client et le SSR répondent
npm run build	Build de production pur (validation des variables puis compilation Next.js)
npm run preview	Smoke-test du build
npm run test	Tests unitaires Vitest
npm run lint	ESLint (flat config)
npm run env:check:prod	Vérifie les variables nécessaires aux API prod + migrations
npm run db:migrate	Applique les migrations Supabase en attente (SUPABASE_DB_URL, POSTGRES_URL_NON_POOLING ou POSTGRES_URL)
npm run check:schema-drift	Vérifie que le schéma Supabase correspond exactement aux migrations versionnées
npm run check:versions	Vérifie la cohérence des versions de Node, de npm et de l'image Playwright (CI)
npm run ops:health-scheduler:configure	Chiffre dans Vault l'URL et le secret du contrôle de santé toutes les 15 minutes
npm run valuation:publish	Publie explicitement les modèles de valorisation
npm run release:prepare	ÉCRIT EN PRODUCTION : applique les migrations, reconfigure Vault, publie les modèles (confirmation requise)
npm run format	Prettier (écriture)

Structure du dépôt

immojudis/
├─ src/                       # Application web (Next.js App Router)
│  ├─ app/                    # Routes Next.js (/, /sales, /sales/[id], /publish, /admin…)
│  ├─ routes/                 # Reste : les 3 documents juridiques (empreinte SHA-256 à ré-ancrer, voir P6-01)
│  ├─ components/             # Composants UI + localisation (SaleLocationHero, MapThumbnail…)
│  ├─ lib/                    # Métier : queries Supabase, format, géo, surface, tiles
│  ├─ hooks/                  # Hooks React
│  ├─ integrations/           # Client Supabase et intégrations
│  └─ types/                  # Types partagés
├─ services/data-pipeline/    # Pipeline Python (scraping → Supabase) — voir son README
├─ supabase/migrations/       # Migrations SQL versionnées
├─ sql/                       # Scripts d'amorçage à exécuter dans Supabase (vercel_app_setup.sql)
├─ docs/                      # Documentation (index : docs/README.md) : déploiement, ops, runbooks, référence
├─ scripts/                   # Outils de dev (dev-ready)
└─ .github/workflows/         # CI (ci.yml) et workflows d'exploitation, de collecte et de migrations

Base de données (Supabase)

Le front lit public.v_auction_sales_app_preview pour l'aperçu public limité, puis public.v_auction_sales_app pour les comptes connectés. Les détails d'annonce, documents, risques, cartes et tables user_favorites / user_alerts sont protégés par RLS. L'amorçage d'un nouveau projet se fait via sql/vercel_app_setup.sql ; l'historique des évolutions vit dans supabase/migrations/ et s'applique avec le workflow GitHub Apply Supabase Migrations ou npm run db:migrate. Les droits admin reposent sur auth.users.raw_app_meta_data.role = admin.

Pipeline de données

Le scraper Python collecte les ventes judiciaires publiques (Avoventes en source prioritaire, sources publiques complémentaires en croisement), normalise, dédoublonne, géocode, enrichit puis insère dans Supabase. Il tourne via GitHub Actions (data-pipeline.yml) et peut être déclenché depuis /admin. Détails et installation : services/data-pipeline/README.md.

Déploiement

Cible : Vercel (preset Next.js). Renseigner les variables d'environnement dans le projet Vercel puis déployer. Procédure complète (Auth Supabase, secrets CI, runner de scroll admin) : docs/vercel_setup.md.

Les SLO, dashboards et runbooks d'exploitation sont dans docs/operations-phase-3.md. La corrélation, la télémétrie Vercel et la sonde de production sont détaillées dans docs/operations-phase-5.md. La gouvernance Phase 6 est décrite dans docs/compliance-phase-6.md, avec le registre RGPD et la matrice de conservation.

Le build ne modifie plus la base et ne publie plus de modèle. Exécuter npm run release:prepare dans une étape de release explicitement autorisée, puis npm run build dans l'étape de compilation.

⚠️ npm run release:prepare écrit en production : il enchaîne db:migrate (migrations Supabase), ops:health-scheduler:configure (Vault) et valuation:publish (modèles de valorisation) sur la base désignée par SUPABASE_DB_URL, POSTGRES_URL_NON_POOLING ou POSTGRES_URL. Il n'est pas réversible et ne se lance ni pour « essayer » ni depuis un poste de développement. Il affiche la base ciblée et demande de taper production ; sans terminal interactif, il faut RELEASE_PREPARE_CONFIRM=production. Une migration et le code qui en dépend partent ensemble : voir supabase/README.md.

Intégration continue

À chaque push / PR sur main (.github/workflows/ci.yml) :

Les travaux tournent en parallèle ; le travail agrégé « Web (typecheck + lint) » échoue si l'un des travaux web échoue ou est annulé.

• Collecte unique : npm run check:manual-collection (aucune planification concurrente de la collecte)
• Web (Node 24) :
  • typecheck : tsc --noEmit ;
  • lint : npm run lint + npm run knip ;
  • tests : npm run test + npm run test:security-invariants ;
  • audit : npm audit --omit=dev --audit-level=high + npm run check:secrets ;
  • build : npm run build + npm run build:budgets (budgets de rendu serveur, de JavaScript et de médias)
• Pipeline (Python 3.12, base Postgres de test) : ruff check + pytest + pip-audit des fichiers de dépendances ; le travail nommé « Data pipeline (Python 3.11) » n'est plus qu'une porte historique de la protection de branche
• Base de données (Supabase local) : versions de migrations uniques et, sur une PR, chaque migration ajoutée plus récente que la dernière de main (npm run check:migrations -- --base-ref=origin/main en local, après git fetch origin main), rejeu depuis zéro, types générés à jour (non bloquant), dérive de schéma, test de concurrence des quotas, tests pgTAP (supabase test db), catalogue public en HTTP, intégration de l'agent d'information
• Parcours investisseur : npm run test:e2e (Playwright, image officielle du conteneur)
• Revue des dépendances (PR seulement) : échec dès une gravité haute

Les vérifications avant de livrer du code sont dans CLAUDE.md.