feat(doc): page documentation /doc (guide + captures) + lien footer + PDF téléchargeable
7 changed files +210 −0
modified
apps/web/app/layout.tsx
+1 −0
@@ -96,6 +96,7 @@ const LOCAL_FOOTER_LINKS = [ | ||
| 96 | 96 | { href: "/trouveka-bot", label: "À propos du robot" }, |
| 97 | 97 | { href: "/status", label: "État du moteur" }, |
| 98 | 98 | { href: "/stats", label: "Statistiques" }, |
| 99 | + { href: "/doc/index.html", label: "Documentation" }, | |
| 99 | 100 | { href: "/soumettre", label: "Soumettre une page" }, |
| 100 | 101 | { href: "/contact", label: "Contact" }, |
| 101 | 102 | ]; |
added
apps/web/public/doc/img/etape1.png
+0 −0
Binary file not shown.
added
apps/web/public/doc/img/etape2.png
+0 −0
Binary file not shown.
added
apps/web/public/doc/img/etape3.png
+0 −0
Binary file not shown.
added
apps/web/public/doc/img/etape4.png
+0 −0
Binary file not shown.
added
apps/web/public/doc/index.html
+209 −0
@@ -0,0 +1,209 @@ | ||
| 1 | +<!DOCTYPE html> | |
| 2 | +<!-- Page /doc de trouve-ka — générée à partir du gabarit commun Groupe KA (2026-08-24). --> | |
| 3 | +<html lang="fr"> | |
| 4 | +<head> | |
| 5 | +<meta charset="utf-8"> | |
| 6 | +<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> | |
| 7 | +<title>Documentation — Trouve·Ka</title> | |
| 8 | +<meta name="description" content="Comment fonctionne Trouve·Ka : guide pas à pas, données, architecture."> | |
| 9 | +<style> | |
| 10 | + :root{ --ink:#101014; --paper:#faf9f6; --accent:#1c7ed6; --muted:#6b6b70; --line:#e6e4de; } | |
| 11 | + *{box-sizing:border-box} html,body{margin:0;padding:0;background:var(--paper);color:var(--ink); | |
| 12 | + font:16px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;-webkit-text-size-adjust:100%} | |
| 13 | + .container{max-width:960px;margin:0 auto;padding:0 20px} | |
| 14 | + header.doc{background:var(--ink);color:var(--paper);padding:20px 0} | |
| 15 | + header.doc .container{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap} | |
| 16 | + header.doc a{color:var(--paper);text-decoration:none} | |
| 17 | + .wordmark{font-weight:800;font-size:20px;letter-spacing:.02em} | |
| 18 | + .wordmark .ka{color:var(--accent)} | |
| 19 | + .btn-pdf{display:inline-block;background:var(--accent);color:#fff;font-weight:700; | |
| 20 | + padding:10px 18px;border-radius:999px;text-decoration:none;font-size:15px} | |
| 21 | + .hero{padding:48px 0 8px} | |
| 22 | + .hero h1{font-size:clamp(28px,5vw,44px);line-height:1.1;margin:0 0 12px} | |
| 23 | + .hero h1 mark{background:var(--accent);color:#fff;padding:2px 8px} | |
| 24 | + .hero p.lead{font-size:18px;color:var(--muted);max-width:640px} | |
| 25 | + .kicker{font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:var(--muted); | |
| 26 | + border-left:3px solid var(--accent);padding-left:10px;margin:40px 0 8px;font-weight:700} | |
| 27 | + section{padding:8px 0 16px} | |
| 28 | + h2{font-size:26px;margin:6px 0 12px} | |
| 29 | + .step{display:grid;grid-template-columns:56px 1fr;gap:16px;margin:26px 0;align-items:start} | |
| 30 | + .step .num{width:44px;height:44px;border-radius:50%;background:var(--ink);color:var(--accent); | |
| 31 | + display:flex;align-items:center;justify-content:center;font-weight:800;font-size:18px} | |
| 32 | + .step h3{margin:6px 0 6px;font-size:19px} | |
| 33 | + .step p{margin:0 0 12px;color:#3a3a40} | |
| 34 | + .shot{border:1px solid var(--line);border-radius:12px;overflow:hidden;box-shadow:0 8px 30px rgba(16,16,20,.08)} | |
| 35 | + .shot img{display:block;width:100%;height:auto} | |
| 36 | + .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px;margin:16px 0} | |
| 37 | + .card{border:1px solid var(--line);border-radius:12px;padding:16px;background:#fff} | |
| 38 | + .card b{display:block;margin-bottom:6px} | |
| 39 | + table{border-collapse:collapse;width:100%;font-size:15px} | |
| 40 | + th,td{border:1px solid var(--line);padding:8px 10px;text-align:left;vertical-align:top} | |
| 41 | + th{background:var(--ink);color:var(--paper)} | |
| 42 | + footer.doc{margin-top:56px;background:var(--ink);color:var(--paper);padding:28px 0;font-size:14px} | |
| 43 | + footer.doc a{color:var(--accent);text-decoration:none} | |
| 44 | + @media print{ | |
| 45 | + header.doc .btn-pdf{display:none} | |
| 46 | + .shot{box-shadow:none;break-inside:avoid} | |
| 47 | + .step{break-inside:avoid} | |
| 48 | + a{color:inherit;text-decoration:none} | |
| 49 | + } | |
| 50 | + @media(max-width:640px){ .step{grid-template-columns:40px 1fr} .step .num{width:34px;height:34px;font-size:15px} } | |
| 51 | +</style> | |
| 52 | +</head> | |
| 53 | +<body> | |
| 54 | +<header class="doc"> | |
| 55 | + <div class="container"> | |
| 56 | + <a class="wordmark" href="/">Trouve<span class="ka">·Ka</span></a> | |
| 57 | + <nav style="display:flex;gap:14px;align-items:center"> | |
| 58 | + <a href="/">← Retour au site</a> | |
| 59 | + <a class="btn-pdf" href="./trouve-ka-documentation.pdf" download>Télécharger le PDF</a> | |
| 60 | + </nav> | |
| 61 | + </div> | |
| 62 | +</header> | |
| 63 | + | |
| 64 | +<div class="container"> | |
| 65 | + <div class="hero"> | |
| 66 | + <p class="kicker">Documentation · mise à jour 2026-08-24</p> | |
| 67 | + <h1>Comment fonctionne <mark>Trouve·Ka</mark></h1> | |
| 68 | + <p class="lead">Cherche le Québec. Un moteur de recherche web indépendant, Québec-first — son propre | |
| 69 | + crawler, son propre index, son propre ranking, sans dépendre de Google, Bing ou Brave.</p> | |
| 70 | + </div> | |
| 71 | + | |
| 72 | + <section> | |
| 73 | + <p class="kicker">Vue d'ensemble</p> | |
| 74 | + <h2>À quoi sert le site</h2> | |
| 75 | + <p><b>Trouve·Ka</b> est un vrai moteur de recherche québécois — pas un métamoteur : les résultats | |
| 76 | + viennent exclusivement de son propre index. Le crawler <code>TrouveKABot</code> découvre le web | |
| 77 | + québécois à partir de 64 seeds à forte autorité (gouvernement, municipalités, universités, médias), | |
| 78 | + suit les liens, juge la pertinence québécoise de chaque page et l'indexe immédiatement : une page | |
| 79 | + téléchargée est cherchable en 2 à 4 secondes. La recherche est bilingue (français/anglais, avec des | |
| 80 | + synonymes comme « thermopompe » ↔ « heat pump ») et couvre aussi les 13 autres plateformes du | |
| 81 | + Groupe KA — logements, propriétés, produits, restos, emplois, événements…</p> | |
| 82 | + <div class="cards"> | |
| 83 | + <div class="card"><b>7 900+ domaines québécois</b>découverts par le crawler à partir de 64 seeds | |
| 84 | + à forte autorité — et le frontier continue de grandir en permanence.</div> | |
| 85 | + <div class="card"><b>Recherche en 20–95 ms</b>latence mesurée en production, affichée à côté du | |
| 86 | + compteur de résultats sur chaque recherche.</div> | |
| 87 | + <div class="card"><b>Cherchable en ~2–4 s</b>une page fetchée est indexée inline et devient | |
| 88 | + trouvable en quelques secondes ; l'enrichissement arrive après, en asynchrone.</div> | |
| 89 | + <div class="card"><b>Métriques publiques réelles</b>les pages <a href="/status">/status</a> et | |
| 90 | + <a href="/stats">/stats</a> montrent les vrais compteurs du moteur, en direct — aucun chiffre | |
| 91 | + simulé, c'est une règle du projet.</div> | |
| 92 | + </div> | |
| 93 | + </section> | |
| 94 | + | |
| 95 | + <section> | |
| 96 | + <p class="kicker">Guide pas à pas</p> | |
| 97 | + <h2>Utiliser le site en 4 étapes</h2> | |
| 98 | + | |
| 99 | + <div class="step"> | |
| 100 | + <div class="num">1</div> | |
| 101 | + <div> | |
| 102 | + <h3>Tapez votre recherche sur l'accueil</h3> | |
| 103 | + <p>La page d'accueil va droit au but : une barre de recherche. Écrivez ce que vous cherchez en | |
| 104 | + français ou en anglais — « cabane à sucre », « plombier Gatineau », « heat pump » — puis appuyez | |
| 105 | + sur <b>Chercher</b> (ou Entrée).</p> | |
| 106 | + <div class="shot"><img src="./img/etape1.png" alt="Étape 1 — page d'accueil de Trouve·Ka avec la barre de recherche"></div> | |
| 107 | + </div> | |
| 108 | + </div> | |
| 109 | + | |
| 110 | + <div class="step"> | |
| 111 | + <div class="num">2</div> | |
| 112 | + <div> | |
| 113 | + <h3>Parcourez les résultats et affinez avec les filtres</h3> | |
| 114 | + <p>La page de résultats affiche le nombre de résultats et la latence réelle de la requête | |
| 115 | + (souvent moins de 100 ms). Chaque résultat montre le fil d'Ariane du site source, un extrait | |
| 116 | + avec vos mots surlignés et, s'il y a lieu, une image. Les pastilles sous la barre permettent de | |
| 117 | + filtrer par site du Groupe KA (Lou·Ka, Immo·Ka, Fabri·Ka…), par langue (français/anglais) ou | |
| 118 | + par fraîcheur (24 h, semaine, mois, année). Le bouton « + Recherche sémantique » élargit la | |
| 119 | + recherche au sens des mots, pas seulement aux mots exacts.</p> | |
| 120 | + <div class="shot"><img src="./img/etape2.png" alt="Étape 2 — résultats pour « cabane à sucre » avec compteur, latence et filtres"></div> | |
| 121 | + </div> | |
| 122 | + </div> | |
| 123 | + | |
| 124 | + <div class="step"> | |
| 125 | + <div class="num">3</div> | |
| 126 | + <div> | |
| 127 | + <h3>Passez en mode Images</h3> | |
| 128 | + <p>La pastille <b>Images</b> transforme les résultats en galerie : chaque vignette est l'image | |
| 129 | + représentative d'une page indexée, avec son titre et son domaine source. Les images sont | |
| 130 | + affichées depuis leur site d'origine avec attribution — Trouve·Ka ne crawle jamais les images | |
| 131 | + elles-mêmes. Un clic ouvre la page d'origine.</p> | |
| 132 | + <div class="shot"><img src="./img/etape3.png" alt="Étape 3 — onglet Images : galerie de résultats pour « cabane à sucre »"></div> | |
| 133 | + </div> | |
| 134 | + </div> | |
| 135 | + | |
| 136 | + <div class="step"> | |
| 137 | + <div class="num">4</div> | |
| 138 | + <div> | |
| 139 | + <h3>Suivez le moteur en direct — et proposez vos pages</h3> | |
| 140 | + <p>La page <a href="/status">État du moteur</a> montre les vrais chiffres, actualisés toutes les | |
| 141 | + 10 secondes : pages indexées, pages téléchargées et indexées dans la dernière heure, URL en | |
| 142 | + attente de crawl, couverture sémantique de l'index. Vous pouvez aussi | |
| 143 | + <a href="/soumettre">soumettre une page</a> à indexer, consulter les | |
| 144 | + <a href="/stats">statistiques détaillées</a> ou lire la page | |
| 145 | + <a href="/trouveka-bot">À propos du robot</a> si vous administrez un site web.</p> | |
| 146 | + <div class="shot"><img src="./img/etape4.png" alt="Étape 4 — page État du moteur avec les compteurs en direct"></div> | |
| 147 | + </div> | |
| 148 | + </div> | |
| 149 | + </section> | |
| 150 | + | |
| 151 | + <section> | |
| 152 | + <p class="kicker">Sous le capot</p> | |
| 153 | + <h2>D'où viennent les données</h2> | |
| 154 | + <p>Tout part du crawler maison. Le pipeline complet : | |
| 155 | + <b>Crawler → Frontier → Fetcher → Parser → Classification Québec → Déduplication → Indexer → | |
| 156 | + Index → Ranking → API → Web App</b>.</p> | |
| 157 | + <p>Le crawl démarre de <b>64 seeds à forte autorité</b> (gouvernement, municipalités, universités, | |
| 158 | + médias) et suit les liens sortants ; il a ainsi découvert <b>plus de 7 900 domaines québécois</b>. | |
| 159 | + Chaque page reçoit un score de pertinence québécoise (<code>page_quebec_score</code> et | |
| 160 | + <code>domain_quebec_score</code>) calculé de façon déterministe — TLD .qc.ca/.quebec, toponymes, | |
| 161 | + codes postaux G/H/J, indicatifs 418/514/438…, organisations connues (Hydro-Québec, RAMQ, UQAM…), | |
| 162 | + JSON-LD, langue française — aucun modèle d'IA dans le chemin chaud. Les pages jugées pertinentes | |
| 163 | + sont indexées immédiatement dans <b>OpenSearch</b> (cherchables en 2–4 secondes), puis enrichies en | |
| 164 | + asynchrone : autorité de domaine, entités, embeddings pour la recherche sémantique — sans jamais | |
| 165 | + bloquer l'indexation.</p> | |
| 166 | + <p>Le classement des résultats combine la pertinence textuelle bilingue (BM25 FR/EN avec synonymes), | |
| 167 | + les scores Québec, l'autorité du domaine, la fraîcheur de la page et un boost de localité | |
| 168 | + (« plombier Gatineau » remonte les documents avec une preuve géographique). Le recrawl est | |
| 169 | + adaptatif : une page qui ne change pas est revisitée moins souvent, une page volatile plus souvent.</p> | |
| 170 | + <p>Le robot est poli et assumé : identifié <code>TrouveKABot</code> avec sa page publique | |
| 171 | + <a href="/trouveka-bot">/trouveka-bot</a>, il respecte <code>robots.txt</code> et le | |
| 172 | + <code>Crawl-delay</code>, espace ses requêtes par hôte (2 s par défaut) et évite les pièges de | |
| 173 | + crawl (calendriers infinis, identifiants de session, facettes explosives).</p> | |
| 174 | + </section> | |
| 175 | + | |
| 176 | + <section> | |
| 177 | + <p class="kicker">Questions fréquentes</p> | |
| 178 | + <h2>FAQ</h2> | |
| 179 | + <div class="cards"> | |
| 180 | + <div class="card"><b>Est-ce que Trouve·Ka utilise Google ou Bing ?</b> | |
| 181 | + Non. C'est un moteur indépendant : son propre crawler, son propre index, son propre ranking. | |
| 182 | + Aucune dépendance à Google, Bing ou Brave pour les résultats.</div> | |
| 183 | + <div class="card"><b>Pourquoi mes mots en anglais trouvent des pages en français ?</b> | |
| 184 | + La recherche est bilingue : des synonymes FR ↔ EN sont intégrés au moteur (« heat pump » trouve | |
| 185 | + « thermopompe »), et la recherche sémantique retrouve les pages par le sens.</div> | |
| 186 | + <div class="card"><b>Comment faire indexer mon site ?</b> | |
| 187 | + Utilisez <a href="/soumettre">Soumettre une page</a>. Si votre site est québécois et accessible, | |
| 188 | + le crawler le visitera en respectant votre <code>robots.txt</code>. Détails pour les webmestres : | |
| 189 | + <a href="/trouveka-bot">/trouveka-bot</a>.</div> | |
| 190 | + <div class="card"><b>Les compteurs affichés sont-ils réels ?</b> | |
| 191 | + Oui. Les chiffres de <a href="/status">/status</a> et <a href="/stats">/stats</a> viennent | |
| 192 | + directement du moteur en production, actualisés en continu — aucun compteur simulé.</div> | |
| 193 | + <div class="card"><b>C'est quoi, les pastilles Lou·Ka, Immo·Ka… sous la barre ?</b> | |
| 194 | + Des filtres par plateforme du Groupe KA : Trouve·Ka indexe aussi les autres sites de | |
| 195 | + l'écosystème (logements, propriétés, produits, restos, emplois, événements…) et permet de | |
| 196 | + restreindre la recherche à l'un d'eux.</div> | |
| 197 | + </div> | |
| 198 | + </section> | |
| 199 | +</div> | |
| 200 | + | |
| 201 | +<footer class="doc"> | |
| 202 | + <div class="container"> | |
| 203 | + <p><b>Trouve·Ka</b> — un service <a href="https://www.groupe-ka.com">Groupe KA</a>. | |
| 204 | + Écosystème : les 13 plateformes sont liées au pied de chaque site.</p> | |
| 205 | + <p>© 2026 Groupe KA — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></p> | |
| 206 | + </div> | |
| 207 | +</footer> | |
| 208 | +</body> | |
| 209 | +</html> | |
added
apps/web/public/doc/trouve-ka-documentation.pdf
+0 −0
Binary file not shown.