Skip to main content

​
PLAN D’ACTION CONCRET — Refonte doc Fluximmo

Fichier d’exécution (≠ RECOMMENDATION_IMPROVE_DOC.md qui est la spec/recommandation). Objectif : refondre doc.fluximmo.io en 6 phases (dont 4 parallélisées). Estimation totale : 8-12 jours-homme (compressible à 4-6 jours calendaires si exécution parallèle agressive).

​
Pré-requis (à valider avant lancement)

#Pré-requisOwnerStatus
1Clé API test gratuite active sur my.fluximmo.io (1 semaine) — pour validation live des exemplesTimÀ fournir
2URL de base API publique confirmée (https://api.fluximmo.io/v2/... ou autre)TimÀ confirmer
3Accès lecture aux 3 repos : api_fluximmo_v2, elasticimmo, prod_fluximmo/v2/_workersOK✅
4mintlify CLI installé localement (npm i -g mintlify) pour previewDoc ownerÀ installer
5Clé API test pour validator agent (lecture seule) — peut être la même que #1TimÀ fournir
6Décision palette validée : indigo #1E40AF / emerald #10B981✅Acté
7Accès écriture sur le repo doc (branche feature/refonte-doc-v2)Doc ownerOK
⚠️ Sans pré-requis #1 + #2 + #5, la Phase 3 (validation live) est bloquée. Les autres phases peuvent démarrer.

​
Vue d’ensemble — 6 phases

Phase 1  ──> Foundation (mint.json, frontmatter, palette, snippets)  [parallèle x3]    ~1j
Phase 2  ──> Concepts + Onboarding + Modèles                          [parallèle x3]    ~1.5j
Phase 3  ──> API Reference enrichie + EXEMPLES + VALIDATION LIVE      [parallèle + V]   ~2-3j  ⚠️ critique
Phase 4  ──> Playbooks (8 playbooks)                                  [parallèle x4]    ~2j
Phase 5  ──> LLM-ready + Ressources + UI polish                       [parallèle x4]    ~1.5j
Phase 6  ──> QA finale (links + re-validation + journeys)             [parallèle x3]    ~0.5j
Dépendances strictes :
  • Phase 2 dépend de Phase 1 (structure mint.json en place)
  • Phase 3 dépend de Phase 2 (concepts en place pour cross-link)
  • Phase 4 dépend de Phase 3 (exemples validés réutilisés dans playbooks)
  • Phase 5 partiellement indépendant (peut démarrer pendant Phase 4)
  • Phase 6 dépend de tout

​
Phase 1 — Foundation (parallèle x3, ~1 jour)

Goal : poser une base saine (navigation, titres, brand) avant tout enrichissement. Lancer en parallèle (single message, 3 tool calls simultanés) :

​
Agent 1.A — Refonte mint.json

  • Mission : appliquer la structure 5 sections Démarrer / Concepts / Playbooks / API Reference / Ressources (cf RECOMMENDATION §6).
  • Actions :
    • Réorganiser navigation selon §6
    • Retirer entrées orphelines / doublons (mais garder Analytics tel quel per consigne — placeholder v3)
    • Retirer toute référence aux endpoints /v1/* (legacy supprimés de la doc publique)
    • Mettre à jour colors : primary #1E40AF, accent #10B981, gradient anchors
    • Ajouter background.decoration: "gradient" + colors light/dark
    • Activer appearance.default: "system"
    • Topbar : retirer Réserver un appel (Calendly), garder Mon compte + Nous contacter (email)
  • Output : mint.json propre, validé via mintlify dev.
  • Acceptance : 0 lien cassé, structure 5 sections visible en sidebar.

​
Agent 1.B — Override frontmatter MDX OpenAPI (~70 fichiers)

  • Mission : remplacer les titres auto-générés illisibles par des titres FR clairs.
  • Actions : pour chaque .mdx sous api-v2-reference/, api-ai-reference/, api-geocoding-reference/ :
    • Ajouter frontmatter complet : 
      ---
title: "<titre FR clair>"
sidebarTitle: "<titre court>"
description: "<1 phrase orientée cas d'usage>"
icon: "<lucide ou font-awesome cohérent par groupe>"
tag: "STABLE" | "BETA" | "DEPRECATED"
openapi: "<inchangé>"
---
    • Convention icônes : Properties = home, Adverts = newspaper, Alerts = bell, AI = sparkles, GEO = map-pin, Sample = flask-conical.
  • Output : tous les .mdx OpenAPI ont un frontmatter custom.
  • Acceptance : grep -c '^title:' sur chaque fichier MDX OpenAPI = 1.

​
Agent 1.C — Snippets Mintlify réutilisables

  • Mission : créer les snippets centralisés pour les contenus dédupliqués.
  • Actions : créer /snippets/ :
    • decision-matrix-property-vs-advert.mdx (le tableau §5 de la reco)
    • cta-cle-test-gratuite.mdx (footer : “Clé test gratuite 1 semaine sur my.fluximmo.io”)
    • banniere-llm-context.mdx (”🤖 Page LLM-ready disponible”)
    • banniere-startups.mdx (encart discret early-stage)
    • warning-city-deprecated.mdx (city ignoré → utiliser postalCode/inseeCode/department)
    • warning-cycle-vie-alerte.mdx (perte historique sur recreate)
  • Output : 6 snippets réutilisables.
  • Acceptance : chaque snippet rendu en standalone via mintlify dev.

​
Phase 2 — Concepts + Onboarding + Modèles (parallèle x3, ~1.5 jour)

Goal : poser les pages pédagogiques fondatrices (autonomie #1) avant d’enrichir les endpoints. Dépend de : Phase 1.

​
Agent 2.A — Concepts (5 pages)

  • concepts/property-vs-advert.mdx — decision matrix (snippet) + diagramme Mermaid + cas d’usage
  • concepts/webhooks.mdx (refonte) — archi, IDs vs payload complet, samples webhook live, Mermaid pipeline
  • concepts/match-types-cycle-alerte.mdx — CREATED / MERGED / ADVERT_EVENT, perte historique sur recreate (warning gras), pas de backfill, events PRICE/REPUBLISHED/UNPUBLISHED
  • concepts/filtres-communs.mdx — location / offer / price / habitation / meta.isTotallyOffline + warning city ignoré (snippet)
  • concepts/recherche-geographique.mdx — 4 modes (postalCode/inseeCode/department admin + geoBoundingBox + geoDistance + geoShape + multi-zones OR), contraintes (cf RECOMMENDATION §C.1), anti-patterns
  • Style : exemples > texte. Mermaid systématique.

​
Agent 2.B — Onboarding (4 pages)

  • introduction.mdx (réécrite) — vision FR-first depuis 2017, 0 mention proéminente Calendly, lien samples no-auth + clé test gratuite
  • demarrer/quickstart.mdx — 5 min sans appel : sample → clé test → 1er search (curl + Python + Node via <CodeGroup>)
  • demarrer/sample-data.mdx — valoriser les 4 endpoints /v2/sample/* (no-auth) + bouton “Try it” Mintlify activé
  • authentification.mdx (réécrite) — clé test gratuite via my.fluximmo.io + clé prod, mention discrète email contact
  • Acceptance : un lecteur sans clé peut atteindre un sample no-auth en ≤ 2 clics.

​
Agent 2.C — Modèles Property / Advert

  • api-v2-reference/_api-models/property.mdx — schéma champs + descriptions + warning city + meta.isTotallyOffline clé prod + lien decision matrix (snippet)
  • api-v2-reference/_api-models/advert.mdx — schéma champs + différences avec property + lien decision matrix
  • Source : DTOs réels dans api_fluximmo_v2/src/modules/app/dto/ (cf RECOMMENDATION §C.7).

​
Phase 3 — API Reference enrichie + EXEMPLES + VALIDATION LIVE (parallèle + Validator, ~2-3 jours)

Goal : enrichir chaque endpoint Search/Alerts/AI/GEO avec prose + exemples curated, et valider chaque exemple PROPERTIES search live contre l’API. Dépend de : Phase 1 + Phase 2. Bloquant : pré-requis #1, #2, #5.

​
Agent 3.A — Enrichir Search Properties (full + lite + similar)

Ajouter prose au-dessus de l’OpenAPI block + section Exemples avec 6 exemples curated :
  1. ★★ Combo standard : postalCode Paris achat [FLAT, HOUSE] (pas PROGRAM), prix 100-350k€, surface 30-110m², isTotallyOffline=false, sort FIRST_SEEN_AT DESC, size 100
  2. Recherche par department (ex: 13) location maison surface ≥ 80m² 3+ chambres
  3. ★ geoDistance rayon 20 km autour d’une adresse géocodée
  4. ★ geoBoundingBox carte interactive Paris
  5. ★ geoShape POLYGON quartier custom (Le Marais)
  6. Multi-zones via location: [{postalCode}, {postalCode}, ...]
Pagination cursor searchAfterHash documentée.

​
Agent 3.B — Enrichir Search Adverts + tous les Alerts

  • Search Adverts : 4 exemples (achat appart dpt, geoDistance autour métro, seller/agence, propertyFlxId)
  • Alerts ADVERT CREATE : 3 exemples (chasseur dpt simple, +events ADVERT_EVENT, multi-dpt)
  • Alerts PROPERTIES CREATE : 3 exemples
    • Combo standard match=[CREATED] (défaut)
    • Dpt + isTotallyOffline=false match=[CREATED]
    • match=[CREATED, MERGED] en exemple AVANCÉ uniquement (ne pas mettre en avant)
  • Tous les autres alerts (LIST, GET, PATCH, DELETE, ACTIVATE, HISTORY) avec prose courte + cas d’usage

​
Agent 3.C — Enrichir AI / GEO / Sample

  • AI : estimate/property/lite + experimental/estimate — input/output, exemples appart Paris + maison province
  • GEO : préciser origine BAN/BANO Gouv (pas proprio Fluximmo) + exemples search/reverse/CSV
  • Sample : valoriser les 4 endpoints, “Try it” actifs

​
⚠️ Agent 3.V — VALIDATOR (CRITIQUE — lancé après 3.A et 3.B)

Mission CRITIQUE : pour chaque exemple PROPERTIES search créé en Phase 3.A et 3.B, exécuter live + vérifier que les résultats respectent les filtres. Procédure par exemple :
  1. Parser le payload JSON depuis le .mdx
  2. POST vers https://api.fluximmo.io/v2/protected/properties/search (header x-api-key)
  3. Récupérer la réponse (jusqu’à size résultats)
  4. Vérifier filtre par filtre que chaque résultat respecte les contraintes (cf Annexe A)
  5. Émettre rapport __validation_reports/<example_slug>.md
  6. Bloquer le merge si ≥ 1 exemple échoue
Output : dossier __validation_reports/ à la racine doc :
  • 1 rapport markdown par exemple
  • 1 rapport agrégé _summary.md
Acceptance : 100% des exemples PROPERTIES retournent ≥ 1 résultat ET passent toutes les vérifications de filtre.
💡 Pourquoi un validator dédié : c’est la consigne explicite. Détecte en amont les exemples mal formés (impossible en review humain pur) et révèle de potentiels bugs API.

​
Phase 4 — Playbooks (parallèle x4, ~2 jours)

Goal : 8 playbooks orientés cas d’usage, réutilisant les exemples validés Phase 3. Dépend de : Phase 3 (exemples validés disponibles). Lancer 4 agents en parallèle, chacun produit 2 playbooks :

​
Agent 4.A

  • playbooks/alerte-advert-departement.mdx — chasseur immo (use case #1)
  • playbooks/search-properties-analytique.mdx — analytics Paris achat (use case #2)

​
Agent 4.B

  • playbooks/recherche-geographique-avancee.mdx — bbox / distance / polygon / multi-zones (★ feature distinctive)
  • playbooks/replicate-bdd-adverts.mdx — sync continue marketplace

​
Agent 4.C

  • playbooks/track-price-changes.mdx — events PRICE / REPUBLISHED / UNPUBLISHED (alerte ADVERT)
  • playbooks/estimer-un-bien.mdx — AVM AI lite

​
Agent 4.D

  • playbooks/geocoder-pour-search.mdx — chaîne BAN/BANO → search Fluximmo
  • playbooks/webhook-volume-architecture.mdx — RabbitMQ / SQS, idempotence, ack rapide, retry/DLX
Format de chaque playbook :
  1. Goal (1 phrase, orienté outcome client)
  2. Scénario (qui je suis, ce que je veux)
  3. Étapes (<Steps> Mintlify) avec curl + Python + Node (<CodeGroup>)
  4. Diagramme Mermaid du flow
  5. Pièges fréquents (<Warning>)
  6. Liens vers concepts + endpoints API

​
Phase 5 — LLM-ready + Ressources + UI polish (parallèle x4, ~1.5 jour)

Goal : finaliser autonomie #2 (LLM) + ressources support + polish visuel. Peut démarrer en parallèle de Phase 4 (pas de dépendance forte).

​
Agent 5.A — Page LLM-ready

  • llms-context.mdx — manuel (cf RECOMMENDATION §7.27.A) :
    • Identité Fluximmo 3 lignes
    • Decision matrix condensée
    • Schémas TS-like des DTOs (FilterProperty, FilterAdvert, FilterLocation, FilterPrice, FilterTypeHabitation, FilterMeta, SaveSearchPropertiesPayload, SaveSearchAdvertsPayload)
    • Enums littéraux
    • Limites strictes (size 25/100, max keywords 20, distance > 0)
    • Match types & events
    • 8 archetypes payloads JSON minifiés (issus de Phase 3 validés)
    • Anti-patterns (city ignoré, GeoJSON [lon,lat] vs API , pas de backfill)
    • Cible : 2 000–4 000 tokens
  • Activer llms.txt + llms-full.txt natifs Mintlify dans mint.json

​
Agent 5.B — Ressources (5 pages)

  • ressources/faq.mdx — top 15 questions (collecter auprès du support)
  • ressources/codes-erreur.mdx — codes 10001/10002/10003 + format réponse erreur
  • ressources/webhooks-livraison.mdx — x-webhook-key, retry 2+10×5min, DROP après ~50min, codes 200-205, SLO 30-50s
  • ressources/bonnes-pratiques.mdx — pagination, retry, idempotence, refetch, validation webhook par x-webhook-key
  • ressources/limites-rate-limits.mdx — quotas (neutre, sans surpromettre)

​
Agent 5.C — Pages stratégiques (3 pages)

  • concepts/dvf-vs-fluximmo.mdx — comparatif honnête + DVF dispo sur demande dès aujourd’hui
  • api-reference/capabilities-sur-demande.mdx — DPE, similar, market analytics, properties analytics, agences, consumption (descriptif, no OpenAPI)
  • ressources/startups-et-sur-mesure.mdx — discount sans %, qualif sur demande, 0 noms clients publics, études de cas anonymisées OK

​
Agent 5.D — UI polish

  • Confirmer palette #1E40AF / #10B981 dans mint.json (raffinage Phase 1)
  • Ajouter Mermaid diagrammes (style Default Mintlify) dans :
    • concepts/webhooks.mdx
    • concepts/match-types-cycle-alerte.mdx
    • concepts/recherche-geographique.mdx
    • playbooks/replicate-bdd-adverts.mdx
    • playbooks/webhook-volume-architecture.mdx
  • Activer API playground sur les 4 sample endpoints uniquement
  • Vérifier dark mode lisible sur toutes les pages

​
Phase 6 — QA finale (parallèle x3, ~0.5 jour)

Goal : validation cross-platform + zéro régression avant release. Dépend de : tout.
  • mintlify dev lancé → vérifier 0 lien cassé
  • Vérifier que mint.json valide tous les paths référencés
  • Recompter les .mdx orphelins (objectif : 0)
  • Test Lighthouse sur 5 pages représentatives → Performance ≥ 90, Accessibility ≥ 95

​
Agent 6.B — Re-validation exemples PROPERTIES

  • Re-exécuter l’agent 3.V VALIDATOR sur tous les exemples PROPERTIES (incluant ceux dans les playbooks et llms-context.mdx).
  • Garantit zéro régression depuis Phase 3.

​
Agent 6.C — User journeys cold-start

Simuler 3 parcours :
  1. Découverte sans clé : depuis /, atteindre un sample no-auth en ≤ 2 clics → succès copy-paste curl
  2. Quickstart 5 min : suivre demarrer/quickstart.mdx from scratch sur clé test → premier search OK
  3. Génération payload via LLM : copier llms-context.mdx dans Claude/ChatGPT, demander “alerte ADVERT achat appartement département 75 prix max 600k€” → vérifier que le LLM produit un payload valide (re-validate via agent 3.V)
Acceptance globale (release-ready) :
  • ✅ 0 lien cassé
  • ✅ 100% des exemples PROPERTIES validés (Phase 3 + Phase 6)
  • ✅ Les 3 user journeys passent
  • ✅ Lighthouse Performance ≥ 90, Accessibility ≥ 95
  • ✅ 0 mention proéminente Calendly avant la 3ᵉ page profondeur
  • ✅ Decision matrix Property vs Advert accessible en ≤ 2 clics

​
Récap effort + parallélisation

PhaseAgents parallèlesDurée séquentielleDurée si parallèleBloquant
133j1jPré-req #4, #6
234.5j1.5jPhase 1
33 + Validator7j2-3jPhase 2 + Pré-req #1, #2, #5
448j2jPhase 3
546j1.5jPhase 2 (partiel)
631.5j0.5jTout
Total—30j~8.5j calendaires—
Compression possible : Phase 5 démarre en chevauchement avec Phase 4 → 5-6j calendaires réalistes.

​
Critère “stop the line”

Bloquer la progression si :
  • Phase 3 Validator détecte ≥ 1 exemple PROPERTIES qui échoue → corriger l’exemple ou remonter un bug API
  • Lighthouse Accessibility < 90 sur une page → corriger avant Phase suivante
  • Un user journey échoue en Phase 6 → ne pas release

​
Annexe A — Spec technique de l’agent VALIDATOR (Phase 3.V & 6.B)

Inputs :
  • Liste des exemples à valider (extraits depuis tous les .mdx — chercher les blocks ```json à but “exemple search PROPERTIES”)
  • Clé API test (FLUXIMMO_TEST_API_KEY)
  • Base URL API (FLUXIMMO_API_BASE_URL)
Pour chaque exemple :
  1. Parser le payload JSON
  2. curl -X POST "$BASE/v2/protected/properties/search" \
     -H "x-api-key: $KEY" \
     -H "Content-Type: application/json" \
     -d "$payload"
  3. Parser response.results[]
  4. Pour chaque result, vérifier filtre par filtre selon mapping ci-dessous
  5. Émettre rapport markdown
Mapping filtre → vérification (à coder en Python avec shapely pour la géométrie) :
Filtre payloadVérification sur chaque result
filterProperty.location[].postalCoderesult.location.postalCode == filter
filterProperty.location[].inseeCoderesult.location.inseeCode == filter
filterProperty.location[].departmentresult.location.department == filter
location[].locationCoordinate.location.geoDistanceplane_distance(filter.pin, result.location) <= filter.distanceKm (DistanceType=Plane côté code, pas Haversine)
location[].locationCoordinate.location.geoBoundingBoxtopLeft.lat ≥ result.lat ≥ bottomRight.lat ET topLeft.lon ≤ result.lon ≤ bottomRight.lon
location[].locationCoordinate.location.geoShape POLYGONpoint_in_polygon(result.lat, result.lon, filter.coordinates) (shapely ou ray-casting)
filterProperty.offer[].typeresult.offer.type ∈ filter
filterProperty.price.initial.value.{min,max}filter.min ≤ result.price.initial.value ≤ filter.max
filterProperty.habitation.surface.total.{min,max}filter.min ≤ result.habitation.surface.total ≤ filter.max
filterProperty.habitation.bedroomCount.{min,max}filter.min ≤ result.habitation.bedroomCount ≤ filter.max
filterProperty.type[]result.type ∈ filter
filterProperty.meta.isTotallyOfflineresult.meta.isTotallyOffline == filter
Multi-zones (location est un array de N>1 entries) : → result.location matche AU MOINS UNE des entries (OR logic, cf RECOMMENDATION §C elasticimmo bool.should) Output :
  • __validation_reports/<example_slug>.md (1 par exemple)
  • __validation_reports/_summary.md (agrégé : passes / fails / warnings)
  • Exit code != 0 si ≥ 1 fail (pour bloquer CI/merge)

​
Pour démarrer l’exécution

Une fois ce plan validé :
  1. Créer la branche feature/refonte-doc-v2 sur le repo doc
  2. Confirmer pré-requis #1 + #2 + #5 (clé API test + URL base)
  3. Lancer Phase 1 (3 agents en parallèle dans un seul message Agent)
  4. Attendre Phase 1 → lancer Phase 2 (3 agents)
  5. Etc.
Référence spec complète : RECOMMENDATION_IMPROVE_DOC.md à la racine du repo doc.