> ## 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 ACTION CONCRET REFACTOR DOC # 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é-requis | Owner | Status | | - | ----------------------------------------------------------------------------------------------------- | --------- | ----------- | | 1 | **Clé API test gratuite** active sur `my.fluximmo.io` (1 semaine) — pour validation live des exemples | Tim | À fournir | | 2 | URL de base API publique confirmée (`https://api.fluximmo.io/v2/...` ou autre) | Tim | À confirmer | | 3 | Accès lecture aux 3 repos : `api_fluximmo_v2`, `elasticimmo`, `prod_fluximmo/v2/_workers` | OK | ✅ | | 4 | `mintlify` CLI installé localement (`npm i -g mintlify`) pour preview | Doc owner | À installer | | 5 | Clé API test pour validator agent (lecture seule) — peut être la même que #1 | Tim | À fournir | | 6 | Décision palette validée : indigo `#1E40AF` / emerald `#10B981` | ✅ | Acté | | 7 | Accès écriture sur le repo doc (branche `feature/refonte-doc-v2`) | Doc owner | OK | > ⚠️ **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 : ```yaml theme={null} --- title: "" sidebarTitle: "" description: "<1 phrase orientée cas d'usage>" icon: "" tag: "STABLE" | "BETA" | "DEPRECATED" openapi: "" --- ``` * **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 ``) * `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/.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** (`` Mintlify) avec curl + Python + Node (``) 4. **Diagramme Mermaid** du flow 5. **Pièges fréquents** (``) 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 {lat,lon}, 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. ### 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 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 | Phase | Agents parallèles | Durée séquentielle | Durée si parallèle | Bloquant | | --------- | ----------------- | ------------------ | ---------------------- | ---------------------------- | | 1 | 3 | 3j | **1j** | Pré-req #4, #6 | | 2 | 3 | 4.5j | **1.5j** | Phase 1 | | 3 | 3 + Validator | 7j | **2-3j** | Phase 2 + Pré-req #1, #2, #5 | | 4 | 4 | 8j | **2j** | Phase 3 | | 5 | 4 | 6j | **1.5j** | Phase 2 (partiel) | | 6 | 3 | 1.5j | **0.5j** | Tout | | **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 payload | Vérification sur chaque result | | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `filterProperty.location[].postalCode` | `result.location.postalCode == filter` | | `filterProperty.location[].inseeCode` | `result.location.inseeCode == filter` | | `filterProperty.location[].department` | `result.location.department == filter` | | `location[].locationCoordinate.location.geoDistance` | `plane_distance(filter.pin, result.location) <= filter.distanceKm` (DistanceType=Plane côté code, **pas Haversine**) | | `location[].locationCoordinate.location.geoBoundingBox` | `topLeft.lat ≥ result.lat ≥ bottomRight.lat` ET `topLeft.lon ≤ result.lon ≤ bottomRight.lon` | | `location[].locationCoordinate.location.geoShape` POLYGON | `point_in_polygon(result.lat, result.lon, filter.coordinates)` (shapely ou ray-casting) | | `filterProperty.offer[].type` | `result.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.isTotallyOffline` | `result.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/.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.