Documentation Index

Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt

Use this file to discover all available pages before exploring further.

​

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)

⚠️ 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

• 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)

​

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)

​

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)

​

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

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}, ...]

​

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)

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

• 1 rapport markdown par exemple
• 1 rapport agrégé _summary.md

💡 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)

​

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

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)

​

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)

​

Agent 6.A — Link checker + structure

• 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

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)

• ✅ 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

Compression possible : Phase 5 démarre en chevauchement avec Phase 4 → 5-6j calendaires réalistes.

​

Critère “stop the line”

• 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)

• 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)

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

• __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

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.