feat(doc): page documentation /doc (guide + captures) + lien footer + PDF téléchargeable
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
7 changed files +158 −0
modified
src/api/main.py
+6 −0
@@ -116,6 +116,12 @@ KA_DIR = WEB_DIR / "ka" | |||||
| 116 | if KA_DIR.is_dir(): | 116 | if KA_DIR.is_dir(): | ||
| 117 | app.mount("/ka", StaticFiles(directory=KA_DIR), name="ka") | 117 | app.mount("/ka", StaticFiles(directory=KA_DIR), name="ka") | ||
| 118 | 118 | ||||
| 119 | +# Documentation utilisateur (guide pas à pas + PDF) — html=True sert | ||||
| 120 | +# web/doc/index.html à /doc/ (et redirige /doc → /doc/). | ||||
| 121 | +DOC_DIR = WEB_DIR / "doc" | ||||
| 122 | +if DOC_DIR.is_dir(): | ||||
| 123 | + app.mount("/doc", StaticFiles(directory=DOC_DIR, html=True), name="doc") | ||||
| 124 | + | ||||
| 119 | 125 | ||||
| 120 | @app.get("/", tags=["root"]) | 126 | @app.get("/", tags=["root"]) | ||
| 121 | @app.head("/", include_in_schema=False) | 127 | @app.head("/", include_in_schema=False) | ||
added
src/api/web/doc/api-ka-documentation.pdf
+0 −0
Binary file not shown.
added
src/api/web/doc/img/etape1.png
+0 −0
Binary file not shown.
added
src/api/web/doc/img/etape2.png
+0 −0
Binary file not shown.
added
src/api/web/doc/img/etape3.png
+0 −0
Binary file not shown.
added
src/api/web/doc/index.html
+151 −0
@@ -0,0 +1,151 @@ | |||||
| 1 | +<!DOCTYPE html> | ||||
| 2 | +<!-- Auteur : Simon-Pierre Boucher — contact@spboucher.ai --> | ||||
| 3 | +<!-- GABARIT COMMUN — page /doc des sites du Groupe KA (2026-08-24). | ||||
| 4 | + À adapter par site : remplacer api-ka (id, ex. lou-ka), API·Ka (ex. Lou·Ka), | ||||
| 5 | + L'API centrale du Groupe KA : collecte quotidienne des données des plateformes de l'écosystème, base PostgreSQL unifiée, API publique et KA Agent (IA)., #3b5bdb (couleur accent du site, ex. #b7f000), les sections | ||||
| 6 | + et les étapes (captures dans ./img/). Page auto-suffisante (aucun JS requis). --> | ||||
| 7 | +<html lang="fr"> | ||||
| 8 | +<head> | ||||
| 9 | +<meta charset="utf-8"> | ||||
| 10 | +<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> | ||||
| 11 | +<title>Documentation — API·Ka</title> | ||||
| 12 | +<meta name="description" content="Comment fonctionne API·Ka : guide pas à pas, données, architecture."> | ||||
| 13 | +<style> | ||||
| 14 | + :root{ --ink:#101014; --paper:#faf9f6; --accent:#3b5bdb; --muted:#6b6b70; --line:#e6e4de; } | ||||
| 15 | + *{box-sizing:border-box} html,body{margin:0;padding:0;background:var(--paper);color:var(--ink); | ||||
| 16 | + font:16px/1.65 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;-webkit-text-size-adjust:100%} | ||||
| 17 | + .container{max-width:960px;margin:0 auto;padding:0 20px} | ||||
| 18 | + header.doc{background:var(--ink);color:var(--paper);padding:20px 0} | ||||
| 19 | + header.doc .container{display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap} | ||||
| 20 | + header.doc a{color:var(--paper);text-decoration:none} | ||||
| 21 | + .wordmark{font-weight:800;font-size:20px;letter-spacing:.02em} | ||||
| 22 | + .wordmark .ka{color:var(--accent)} | ||||
| 23 | + .btn-pdf{display:inline-block;background:var(--accent);color:var(--ink);font-weight:700; | ||||
| 24 | + padding:10px 18px;border-radius:999px;text-decoration:none;font-size:15px} | ||||
| 25 | + .hero{padding:48px 0 8px} | ||||
| 26 | + .hero h1{font-size:clamp(28px,5vw,44px);line-height:1.1;margin:0 0 12px} | ||||
| 27 | + .hero h1 mark{background:var(--accent);color:var(--ink);padding:2px 8px} | ||||
| 28 | + .hero p.lead{font-size:18px;color:var(--muted);max-width:640px} | ||||
| 29 | + .kicker{font-size:12px;letter-spacing:.14em;text-transform:uppercase;color:var(--muted); | ||||
| 30 | + border-left:3px solid var(--accent);padding-left:10px;margin:40px 0 8px;font-weight:700} | ||||
| 31 | + section{padding:8px 0 16px} | ||||
| 32 | + h2{font-size:26px;margin:6px 0 12px} | ||||
| 33 | + .step{display:grid;grid-template-columns:56px 1fr;gap:16px;margin:26px 0;align-items:start} | ||||
| 34 | + .step .num{width:44px;height:44px;border-radius:50%;background:var(--ink);color:var(--accent); | ||||
| 35 | + display:flex;align-items:center;justify-content:center;font-weight:800;font-size:18px} | ||||
| 36 | + .step h3{margin:6px 0 6px;font-size:19px} | ||||
| 37 | + .step p{margin:0 0 12px;color:#3a3a40} | ||||
| 38 | + .shot{border:1px solid var(--line);border-radius:12px;overflow:hidden;box-shadow:0 8px 30px rgba(16,16,20,.08)} | ||||
| 39 | + .shot img{display:block;width:100%;height:auto} | ||||
| 40 | + .cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px;margin:16px 0} | ||||
| 41 | + .card{border:1px solid var(--line);border-radius:12px;padding:16px;background:#fff} | ||||
| 42 | + .card b{display:block;margin-bottom:6px} | ||||
| 43 | + table{border-collapse:collapse;width:100%;font-size:15px} | ||||
| 44 | + th,td{border:1px solid var(--line);padding:8px 10px;text-align:left;vertical-align:top} | ||||
| 45 | + th{background:var(--ink);color:var(--paper)} | ||||
| 46 | + footer.doc{margin-top:56px;background:var(--ink);color:var(--paper);padding:28px 0;font-size:14px} | ||||
| 47 | + footer.doc a{color:var(--accent);text-decoration:none} | ||||
| 48 | + @media print{ | ||||
| 49 | + header.doc .btn-pdf{display:none} | ||||
| 50 | + .shot{box-shadow:none;break-inside:avoid} | ||||
| 51 | + .step{break-inside:avoid} | ||||
| 52 | + a{color:inherit;text-decoration:none} | ||||
| 53 | + } | ||||
| 54 | + @media(max-width:640px){ .step{grid-template-columns:40px 1fr} .step .num{width:34px;height:34px;font-size:15px} } | ||||
| 55 | +</style> | ||||
| 56 | +</head> | ||||
| 57 | +<body> | ||||
| 58 | +<header class="doc"> | ||||
| 59 | + <div class="container"> | ||||
| 60 | + <a class="wordmark" href="/">API<span class="ka">·Ka</span></a> | ||||
| 61 | + <nav style="display:flex;gap:14px;align-items:center"> | ||||
| 62 | + <a href="/">← Retour au site</a> | ||||
| 63 | + <a class="btn-pdf" href="./api-ka-documentation.pdf" download>Télécharger le PDF</a> | ||||
| 64 | + </nav> | ||||
| 65 | + </div> | ||||
| 66 | +</header> | ||||
| 67 | + | ||||
| 68 | +<div class="container"> | ||||
| 69 | + <div class="hero"> | ||||
| 70 | + <p class="kicker">Documentation · mise à jour 2026-08-24</p> | ||||
| 71 | + <h1>Comment fonctionne <mark>API·Ka</mark></h1> | ||||
| 72 | + <p class="lead">L'API centrale du Groupe KA : collecte quotidienne des données des plateformes de l'écosystème, base PostgreSQL unifiée, API publique et KA Agent (IA).</p> | ||||
| 73 | + </div> | ||||
| 74 | + | ||||
| 75 | + <section> | ||||
| 76 | + <p class="kicker">Vue d'ensemble</p> | ||||
| 77 | + <h2>À quoi sert le site</h2> | ||||
| 78 | + <p><b>API·Ka</b> (<a href="https://www.api-ka.com">www.api-ka.com</a>) est la plateforme de données centrale de | ||||
| 79 | + l'écosystème Groupe KA. Chaque jour à 02:00, <b>8 collecteurs</b> (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, | ||||
| 80 | + sorti-ka, crea-ka) sauvegardent les données des plateformes dans une base <b>PostgreSQL</b> unifiée, puis les exposent via une | ||||
| 81 | + API FastAPI publique : données paginées, historiques par date, statistiques, rapports PDF. Elle héberge aussi le | ||||
| 82 | + <b>KA Agent</b> — l'assistant IA du groupe servi en widget aux 13 domaines — et sert de <b>superviseur des connecteurs</b> | ||||
| 83 | + (historique des collectes, santé par service, alertes).</p> | ||||
| 84 | + <div class="cards"> | ||||
| 85 | + <div class="card"><b>8 collecteurs quotidiens</b>Un par plateforme Ka : fetch → validation → checksum → insertion → backup → journal de run.</div> | ||||
| 86 | + <div class="card"><b>Retry 3× + backfill</b>Backoff 30 s → 2 min → 10 min ; les dates manquées des 7 derniers jours sont rattrapées automatiquement.</div> | ||||
| 87 | + <div class="card"><b>Backups 90 jours</b>Backups quotidiens horodatés par service, rétention 90 jours.</div> | ||||
| 88 | + <div class="card"><b>KA Agent (IA)</b>Assistant Claude branché en direct sur les données des plateformes, servi aux 13 sites du groupe.</div> | ||||
| 89 | + </div> | ||||
| 90 | + </section> | ||||
| 91 | + | ||||
| 92 | + <section> | ||||
| 93 | + <p class="kicker">Guide pas à pas</p> | ||||
| 94 | + <h2>Utiliser la plateforme en 3 étapes</h2> | ||||
| 95 | + <div class="step"> | ||||
| 96 | + <div class="num">1</div> | ||||
| 97 | + <div> | ||||
| 98 | + <h3>Explorez le site de documentation</h3> | ||||
| 99 | + <p>L'accueil présente la plateforme, les 8 services collectés et un playground interactif pour tester les endpoints. Les clients API qui appellent la racine reçoivent le statut JSON ; les navigateurs reçoivent cette documentation.</p> | ||||
| 100 | + <div class="shot"><img src="./img/etape1.png" alt="Étape 1 — Explorez le site de documentation"></div> | ||||
| 101 | + </div> | ||||
| 102 | + </div> | ||||
| 103 | + <div class="step"> | ||||
| 104 | + <div class="num">2</div> | ||||
| 105 | + <div> | ||||
| 106 | + <h3>Parcourez l'API dans Swagger (/docs)</h3> | ||||
| 107 | + <p>La référence interactive OpenAPI liste tous les endpoints : GET /api/v1/{service} (pagination, limite 500), /latest, /date/{YYYY-MM-DD}, /stats, /api/v1/runs (historique des collectes), /health… pour les services louka, immoka, foodka, autoka, fabrika, restoka, sortika et creaka. L'API produit exige une session KA ID ou un jeton Bearer kapi_ (généré sur groupe-ka.com/compte) ; monitoring, stats et agent restent ouverts.</p> | ||||
| 108 | + <div class="shot"><img src="./img/etape2.png" alt="Étape 2 — Parcourez l'API dans Swagger (/docs)"></div> | ||||
| 109 | + </div> | ||||
| 110 | + </div> | ||||
| 111 | + <div class="step"> | ||||
| 112 | + <div class="num">3</div> | ||||
| 113 | + <div> | ||||
| 114 | + <h3>Surveillez les collectes sur /stats</h3> | ||||
| 115 | + <p>Le tableau de bord montre l'état des collectes par service, les volumes et l'historique des runs ; les rapports PDF (plateforme et écosystème consolidé) se téléchargent depuis la même page.</p> | ||||
| 116 | + <div class="shot"><img src="./img/etape3.png" alt="Étape 3 — Surveillez les collectes sur /stats"></div> | ||||
| 117 | + </div> | ||||
| 118 | + </div> | ||||
| 119 | + </section> | ||||
| 120 | + | ||||
| 121 | + <section> | ||||
| 122 | + <p class="kicker">Sous le capot</p> | ||||
| 123 | + <h2>D'où viennent les données</h2> | ||||
| 124 | + <p>Chaque collecteur hérite d'une classe de base commune : <b>fetch → validation → checksum → insertion PostgreSQL → | ||||
| 125 | + backup → journal de run</b>, avec retry 3× (backoff exponentiel 30 s → 2 min → 10 min) ; tout échec après 3 tentatives est | ||||
| 126 | + journalisé (<code>collection_runs</code>, alertes). Le scheduler APScheduler lance le job quotidien à 02:00 (collecteurs en parallèle | ||||
| 127 | + et indépendants) et un <b>backfill automatique</b> rattrape les dates manquées des 7 derniers jours. Les backups quotidiens sont | ||||
| 128 | + horodatés par service et conservés 90 jours. La base est PostgreSQL via SQLAlchemy 2 (migrations Alembic) : une table de | ||||
| 129 | + données par service plus le journal des collectes.</p> | ||||
| 130 | + </section> | ||||
| 131 | + | ||||
| 132 | + <section> | ||||
| 133 | + <p class="kicker">Questions fréquentes</p> | ||||
| 134 | + <h2>FAQ</h2> | ||||
| 135 | + <div class="card" style="margin:10px 0"><b>Comment obtenir un accès à l'API ?</b><p style="margin:6px 0 0">Créez un compte KA ID sur groupe-ka.com puis générez votre jeton personnel « kapi_ » sur la page /compte ; passez-le en en-tête Authorization: Bearer. Une session KA ID fonctionne aussi.</p></div> | ||||
| 136 | + <div class="card" style="margin:10px 0"><b>Quels endpoints sont ouverts sans authentification ?</b><p style="margin:6px 0 0">Le monitoring, les statistiques et le KA Agent. L'API produit (données des services) exige une session KA ID ou un jeton kapi_.</p></div> | ||||
| 137 | + <div class="card" style="margin:10px 0"><b>À quelle fréquence les données sont-elles collectées ?</b><p style="margin:6px 0 0">Une fois par jour à 02:00 (heure de l'Est), avec retry automatique et backfill des 7 derniers jours en cas de date manquée.</p></div> | ||||
| 138 | + <div class="card" style="margin:10px 0"><b>Quels services sont couverts ?</b><p style="margin:6px 0 0">louka, immoka, foodka, autoka, fabrika, restoka, sortika et creaka — un collecteur et une table par service.</p></div> | ||||
| 139 | + <div class="card" style="margin:10px 0"><b>Qu'est-ce que le KA Agent ?</b><p style="margin:6px 0 0">L'assistant IA central du groupe (Claude, streaming SSE, boucle d'outils branchés sur les API publiques des plateformes), servi en widget de chat aux 13 domaines de l'écosystème.</p></div> | ||||
| 140 | + </section> | ||||
| 141 | +</div> | ||||
| 142 | + | ||||
| 143 | +<footer class="doc"> | ||||
| 144 | + <div class="container"> | ||||
| 145 | + <p><b>API·Ka</b> — un service <a href="https://www.groupe-ka.com">Groupe KA</a>. | ||||
| 146 | + Écosystème : les 13 plateformes sont liées au pied de chaque site.</p> | ||||
| 147 | + <p>© 2026 Groupe KA — Simon-Pierre Boucher · <a href="mailto:contact@spboucher.ai">contact@spboucher.ai</a></p> | ||||
| 148 | + </div> | ||||
| 149 | +</footer> | ||||
| 150 | +</body> | ||||
| 151 | +</html> | ||||
modified
src/api/web/ka/ka-shell.js
+1 −0
@@ -53,6 +53,7 @@ function kaRenderFooter(eco) { | |||||
| 53 | ${eco.contacts.map((c) => `<p style="margin:0"><a href="mailto:${c.email}">${c.email}</a><span>${esc(c.role)}</span></p>`).join("")} | 53 | ${eco.contacts.map((c) => `<p style="margin:0"><a href="mailto:${c.email}">${c.email}</a><span>${esc(c.role)}</span></p>`).join("")} | ||
| 54 | </div> | 54 | </div> | ||
| 55 | <p class="legal">© ${year} ${esc(eco.org.copyrightHolder)} | 55 | <p class="legal">© ${year} ${esc(eco.org.copyrightHolder)} | ||
| 56 | + · <a href="/doc/">Documentation</a> | ||||
| 56 | ${eco.legal.map((l) => ` · <a href="${l.href}" target="_blank" rel="noopener noreferrer">${esc(l.label)}</a>`).join("")} | 57 | ${eco.legal.map((l) => ` · <a href="${l.href}" target="_blank" rel="noopener noreferrer">${esc(l.label)}</a>`).join("")} | ||
| 57 | </p>`; | 58 | </p>`; | ||
| 58 | } | 59 | } | ||
| 59 | 60 | ||||