docs: README ultra détaillé + visite guidée en 10 captures
11 changed files +69 −27
modified
README.md
+69 −27
@@ -62,41 +62,79 @@ En production : **https://www.trouve-ka.com** — **302 000+ pages indexées** ( | ||
| 62 | 62 | | Latence de recherche (sémantique + rerank actifs) | **258–425 ms** sur 8 requêtes tests | `/api/search` (`took_ms`) | |
| 63 | 63 | | Workers de crawl | **9**, répartis sur **5 nœuds** | `pm2 ls` + satellites | |
| 64 | 64 | |
| 65 | −## Visite guidée | |
| 65 | +## Visite guidée — le site en 10 captures | |
| 66 | 66 | |
| 67 | −*Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900).* | |
| 67 | +*Captures du 2026-08-28, prises en production sur [www.trouve-ka.com](https://www.trouve-ka.com) (desktop 1440×900, mobile 390×844).* | |
| 68 | 68 | |
| 69 | −### Mobile | |
| 69 | +### 1 · Accueil — la porte d'entrée du Groupe KA | |
| 70 | 70 | |
| 71 | −<table> | |
| 72 | − <tr> | |
| 73 | − <td align="center"><img src="docs/screenshots/mobile/home.webp" width="240" alt="Accueil mobile"><br><sub><b>Accueil — le moteur de recherche du Groupe KA</b></sub></td> | |
| 74 | − <td align="center"><img src="docs/screenshots/mobile/recherche.webp" width="240" alt="Recherche mobile"><br><sub><b>Résultats — recherche sémantique, filtres par univers</b></sub></td> | |
| 75 | − <td align="center"><img src="docs/screenshots/mobile/menu-mobile.webp" width="240" alt="Menu mobile"><br><sub><b>Nav v2 — panneau plein écran</b></sub></td> | |
| 76 | − </tr> | |
| 77 | −</table> | |
| 71 | +<img src="docs/screenshots/01-accueil.jpg" width="820" alt="Accueil — www.trouve-ka.com"> | |
| 78 | 72 | |
| 79 | −### Desktop | |
| 73 | +La page d'accueil ([`/`](https://www.trouve-ka.com)) : une barre de recherche unique, sobre, avec **suggestions à la saisie** et **compteur live de pages indexées** — chaque visite affiche l'état réel du moteur, pas un chiffre figé. C'est le point d'entrée vers les 14 univers de l'écosystème : logements, propriétés, emplois, restos, événements, produits, véhicules, créateurs… | |
| 80 | 74 | |
| 81 | −<table> | |
| 82 | − <tr> | |
| 83 | − <td align="center"><img src="docs/screenshots/desktop/home.webp" width="420" alt="Accueil desktop"><br><sub><b>Accueil — compteur live de pages indexées</b></sub></td> | |
| 84 | − <td align="center"><img src="docs/screenshots/desktop/recherche.webp" width="420" alt="Recherche desktop"><br><sub><b>Résultats — badges par univers KA, temps de réponse</b></sub></td> | |
| 85 | − </tr> | |
| 86 | − <tr> | |
| 87 | − <td align="center"><img src="docs/screenshots/desktop/stats.webp" width="420" alt="Stats"><br><sub><b>Statistiques du moteur</b></sub></td> | |
| 88 | − <td align="center"><img src="docs/screenshots/desktop/status.webp" width="420" alt="Status"><br><sub><b>État du moteur — index, frontier, couverture sémantique</b></sub></td> | |
| 89 | − </tr> | |
| 90 | −</table> | |
| 75 | +### 2 · L'accueil, suite — comprendre le moteur d'un coup d'œil | |
| 76 | + | |
| 77 | +<img src="docs/screenshots/09-accueil-section-1.jpg" width="820" alt="Accueil — section explicative"> | |
| 78 | + | |
| 79 | +En défilant sous la barre de recherche, l'accueil **explique le moteur** : ce qu'il indexe (les sites du Groupe KA), comment il fonctionne (crawl continu, indexation immédiate, recherche sémantique) et les chiffres vivants de l'index. La transparence fait partie du produit. | |
| 80 | + | |
| 81 | +### 3 · TrouveKABot — un robot qui se présente | |
| 82 | + | |
| 83 | +<img src="docs/screenshots/02-trouveka-bot.jpg" width="820" alt="Page TrouveKABot"> | |
| 84 | + | |
| 85 | +[`/trouveka-bot`](https://www.trouve-ka.com/trouveka-bot) : la carte d'identité publique du crawler. Qui est `TrouveKABot`, quel User-Agent il envoie, comment il respecte `robots.txt` et `Crawl-delay`, comment le **bloquer ou l'inviter**. Un moteur de recherche assumé commence par un robot qui se présente. | |
| 86 | + | |
| 87 | +### 4 · État du moteur — les entrailles en public | |
| 88 | + | |
| 89 | +<img src="docs/screenshots/03-status.jpg" width="820" alt="Page /status — état du moteur"> | |
| 90 | + | |
| 91 | +[`/status`](https://www.trouve-ka.com/status) : pages indexées, sites KA couverts, pages fetchées/indexées dans la dernière heure, taille du frontier, état du crawler, couverture sémantique — **rafraîchi toutes les 10 secondes**, branché sur [`/api/status`](https://www.trouve-ka.com/api/status). Aucun compteur simulé : c'est une règle du projet. | |
| 92 | + | |
| 93 | +### 5 · Statistiques — le tableau de bord public | |
| 94 | + | |
| 95 | +<img src="docs/screenshots/04-stats.jpg" width="820" alt="Page /stats — statistiques du moteur"> | |
| 96 | + | |
| 97 | +[`/stats`](https://www.trouve-ka.com/stats) : KPI, jauges et séries sur 30 jours (pages crawlées, erreurs, latences, répartition par univers), plus les **rapports PDF Groupe KA** — standard ou personnalisés bloc par bloc via le ReportBuilder (`/api/stats/report`, `/api/stats/report/custom`). | |
| 98 | + | |
| 99 | +### 6 · Soumettre une page — inviter le crawler | |
| 100 | + | |
| 101 | +<img src="docs/screenshots/05-soumettre.jpg" width="820" alt="Page /soumettre — soumission d'URL"> | |
| 102 | + | |
| 103 | +[`/soumettre`](https://www.trouve-ka.com/soumettre) : n'importe qui peut proposer une URL au crawl (`POST /api/submit`). L'URL passe par les mêmes gardes que tout le reste (robots.txt, SSRF, politesse) avant d'entrer au frontier — puis devient cherchable en quelques secondes une fois fetchée. | |
| 104 | + | |
| 105 | +### 7 · Favoris — « Mon univers Ka » (KA ID) | |
| 106 | + | |
| 107 | +<img src="docs/screenshots/07-favoris.jpg" width="820" alt="Page /favoris — Mon univers Ka"> | |
| 108 | + | |
| 109 | +[`/favoris`](https://www.trouve-ka.com/favoris) : connecté avec son **KA ID** (le SSO du Groupe KA), le membre retrouve ici ses favoris **unifiés à travers les 12 sites** de l'écosystème — un logement épinglé sur Lou-Ka, un resto sur Resto-Ka et un emploi sur Job-Ka vivent dans le même univers personnel. | |
| 110 | + | |
| 111 | +### 8 · Documentation — le guide illustré | |
| 112 | + | |
| 113 | +<img src="docs/screenshots/08-doc-index-html.jpg" width="820" alt="Page /doc — guide utilisateur illustré"> | |
| 114 | + | |
| 115 | +[`/doc`](https://www.trouve-ka.com/doc/index.html) : le guide utilisateur illustré (accueil, recherche, images, état du moteur, soumission), avec sa version **PDF téléchargeable**. La documentation publique est traitée comme une page du produit, pas comme une annexe. | |
| 116 | + | |
| 117 | +### 9 · Contact | |
| 118 | + | |
| 119 | +<img src="docs/screenshots/06-contact.jpg" width="820" alt="Page /contact"> | |
| 120 | + | |
| 121 | +[`/contact`](https://www.trouve-ka.com/contact) : la page contact au design Groupe KA — pour joindre l'équipe, signaler un problème d'indexation ou demander un retrait. | |
| 122 | + | |
| 123 | +### 10 · Mobile — le moteur dans la poche | |
| 124 | + | |
| 125 | +<p><img src="docs/screenshots/10-accueil-mobile.jpg" width="300" alt="Accueil mobile"></p> | |
| 126 | + | |
| 127 | +L'accueil en **390×844** : barre de recherche pleine largeur, navigation v2 en panneau plein écran, safe-areas et hauteurs `dvh` respectées — le standard mobile du Groupe KA (campagne 2026-08-19) appliqué au moteur. | |
| 128 | + | |
| 129 | +> 🗄️ Les galeries WebP du 2026-08-25 (résultats de recherche, menu mobile, stats/status desktop) restent dans [`docs/screenshots/mobile/`](docs/screenshots/mobile/) et [`docs/screenshots/desktop/`](docs/screenshots/desktop/) ; les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/) et celles du guide public dans `apps/web/public/doc/img/`. | |
| 91 | 130 | |
| 92 | 131 | ### Nouveautés (2026-08) |
| 93 | 132 | |
| 94 | 133 | - **Moteur Groupe KA d'abord** — index `tk-ka-pages` dédié aux 14 sites de l'écosystème, ingestion par sitemaps. |
| 95 | 134 | - **Favoris unifiés « Mon univers Ka »** (KA ID). |
| 96 | 135 | - **Nav mobile v2** — panneau plein écran avec fermeture interne. |
| 97 | −- **Widget ka-agent v4** — cartes de résultats cliquables. | |
| 98 | − | |
| 99 | −> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/) ; celles du guide public restent dans `apps/web/public/doc/img/`. | |
| 136 | +- **Widget ka-agent v4** — cartes de résultats cliquables (v4.2 : parseur ka-card tolérant, choix de clarification en boutons). | |
| 137 | +- **KA ID v2 / v2.1** (2026-08-26) — journal des recherches vers le feature store KA ID (événement `search` signé HMAC, session vérifiée côté API, best-effort) et **reclassement personnalisé léger** de la fenêtre de résultats (profil transversal du membre, blend 0.25, fail-open, champ `personalized` dans la réponse). | |
| 100 | 138 | |
| 101 | 139 | ## Fonctionnalités |
| 102 | 140 | |
@@ -109,7 +147,8 @@ En production : **https://www.trouve-ka.com** — **302 000+ pages indexées** ( | ||
| 109 | 147 | - **Onglet Images** : galerie des pages avec image représentative (hotlink + attribution, jamais de crawl d'images). |
| 110 | 148 | - **Métriques publiques réelles** : `/status` et `/stats` (tableau de bord + rapports PDF Groupe KA personnalisables) — aucun compteur simulé, c'est une règle du projet. Les chiffres se rafraîchissent toutes les 10 secondes — et les pastilles de ce README interrogent la même API. |
| 111 | 149 | - **Crawl distribué multi-nœuds auto-guéri** : **9 workers sur 5 nœuds** (2 sur le hub M2M32, 3 sur M2M32c, 2 sur M4BP48, 1 sur M1M32, 1 sur m4ma), coordonnés **sans orchestrateur** via le frontier Postgres (`FOR UPDATE SKIP LOCKED`) et les verrous Redis. Tout le trafic inter-nœuds passe par des **tunnels SSH sur 127.0.0.1** (contournement du filtre « réseau local » de macOS 26, qui bloque les binaires non signés). Watchdog toutes les 2 min, passe de flotte ~30 min, survie au reboot prouvée (API tuée → ressuscitée en 40 s ; reboot complet de m4ma → tunnels + worker revenus seuls). |
| 112 | −- **SSO KA ID** + favoris « Mon univers Ka », design Groupe KA, SEO complet (canonical, JSON-LD WebSite/SearchAction/Organization, sitemap) et widget **KA Agent** (bulle de chat IA déplaçable). | |
| 150 | +- **SSO KA ID** + favoris « Mon univers Ka », design Groupe KA, SEO complet (canonical, JSON-LD WebSite/SearchAction/Organization, sitemap) et widget **KA Agent** (bulle de chat IA déplaçable, cartes de résultats cliquables depuis v4). | |
| 151 | +- **Personnalisation KA ID (opt-in, fail-open)** : pour un membre connecté, les recherches alimentent le feature store du hub KA ID (événement signé HMAC, best-effort) et un **reclassement personnalisé léger** réordonne la fenêtre de résultats selon le profil transversal du membre (blend 0.25) — jamais bloquant, la réponse expose le champ `personalized`. | |
| 113 | 152 | |
| 114 | 153 | ## Pipeline complet |
| 115 | 154 | |
@@ -130,7 +169,7 @@ L'API FastAPI (`trouveka.api`) est servie derrière le proxy Next.js (`/api/*`) | ||
| 130 | 169 | |
| 131 | 170 | | Endpoint | Méthode | Rôle | |
| 132 | 171 | |---|---|---| |
| 133 | −| `/api/search` | GET | Recherche principale — requête, filtres univers KA/langue/fraîcheur, onglet images ; renvoie `total`, `took_ms`, `semantic`, `reranked`, `related` | | |
| 172 | +| `/api/search` | GET | Recherche principale — requête, filtres univers KA/langue/fraîcheur, onglet images ; renvoie `total`, `took_ms`, `semantic`, `reranked`, `related`, `personalized` (reclassement KA ID) | | |
| 134 | 173 | | `/api/suggest` | GET | Suggestions de saisie (autocomplete) | |
| 135 | 174 | | `/api/status` | GET | État du moteur en JSON : `pages_indexed`, `domains_count`, `indexed_last_hour`, `fetched_last_hour`, `errors_last_hour`, `frontier_pending`, `frontier_in_progress`, `crawler_state`, `search_ok`, `embedding_coverage` | |
| 136 | 175 | | `/api/live` | GET | Flux « en ce moment » — la page en cours de crawl (url, domaine, issue) | |
@@ -299,7 +338,7 @@ Runbook et observabilité : [docs/RUNBOOK.md](docs/RUNBOOK.md), dashboard `/admi | ||
| 299 | 338 | |
| 300 | 339 | ## Historique |
| 301 | 340 | |
| 302 | −28 commits en 11 jours — de la première ligne au moteur distribué du Groupe KA : | |
| 341 | +De la première ligne au moteur distribué et personnalisé du Groupe KA, en deux semaines : | |
| 303 | 342 | |
| 304 | 343 | | Date | Jalon | |
| 305 | 344 | |---|---| |
@@ -310,6 +349,9 @@ Runbook et observabilité : [docs/RUNBOOK.md](docs/RUNBOOK.md), dashboard `/admi | ||
| 310 | 349 | | 2026-08-22 | **SEO complet** — canonical, JSON-LD WebSite/SearchAction, sitemap, fr-CA (`491f0f6`) · standard header/menu KA (`8678110`) | |
| 311 | 350 | | 2026-08-23 | **Pivot Groupe KA** (`42bf528`) — le moteur n'indexe plus que les 14 sites KA ; rebrand « le moteur de recherche du Groupe KA » (`fd0b68c`) · stats v3, rapports PDF personnalisés (`105720d`) · favoris « Mon univers Ka » (`1e29ebf`) | |
| 312 | 351 | | 2026-08-24 | **Documentation publique** `/doc` + guide PDF (`8880849`) · README v2 puis v3 — l'index passe de 181 k à 302 k pages dans la journée | |
| 352 | +| 2026-08-25 | **Nav mobile v2** — panneau plein écran (`8c96449`, `c343205`) · **widget ka-agent v4 → v4.2** — cartes d'annonces cliquables + choix en boutons (`9f92551` → `eee42bf`) · campagne visuelle WebP (`76fa1eb`) | | |
| 353 | +| 2026-08-26 | **KA ID v2** — journal des recherches vers le feature store du hub (`0d63aa1`) · **KA ID v2.1** — reclassement personnalisé léger des résultats, fail-open (`9ff0126`) | | |
| 354 | +| 2026-08-28 | **README v4** — visite guidée du site en 10 captures fraîches (`docs/screenshots/`) | | |
| 313 | 355 | |
| 314 | 356 | ## Écosystème Groupe KA |
| 315 | 357 | |
added
docs/screenshots/01-accueil.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/02-trouveka-bot.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/03-status.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/04-stats.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/05-soumettre.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/06-contact.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/07-favoris.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/08-doc-index-html.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/09-accueil-section-1.jpg
+0 −0
Binary file not shown.
added
docs/screenshots/10-accueil-mobile.jpg
+0 −0
Binary file not shown.