docs: README ultra détaillé + visite guidée en 10 captures

- README v4 : 11 services (house-ka, rent-ka), KA Agent 34 outils,
  chiffres live 2026-08-28, ~4 460 connecteurs supervisés, section
  authentification (KA ID / kapi_) et rôle central dans l ecosysteme.
- docs/screenshots/ : 10 captures JPG du 2026-08-28 (accueil desktop
  + 3 sections + mobile, /contact, /stats, /docs Swagger, /doc x2).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Simon-Pierre Boucher committed 26 days ago (Aug 29, 2026) parent 6c64acd

11 changed files +81 −40

modified README.md +81 −40

		`@@ -37,87 +37,123 @@`
37	37
38	38	</div>
39	39
40		−API·Ka ([www.api-ka.com](https://www.api-ka.com)) est la plateforme de données centrale de l'écosystème Groupe KA. Chaque jour, 9 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka, job-ka) sauvegardent les données des plateformes dans une base PostgreSQL unifiée (fetch → validation → checksum → insertion → backup → journal de run, retry 3× avec backoff 30 s → 2 min → 10 min), puis les exposent via une API FastAPI publique : données paginées, historiques par date, statistiques, rapports PDF.
	40	+API·Ka ([www.api-ka.com](https://www.api-ka.com)) est la plateforme de données centrale de l'écosystème Groupe KA. Chaque jour, 11 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka, job-ka, house-ka, rent-ka) sauvegardent les données des plateformes dans une base PostgreSQL unifiée (fetch → validation → checksum → insertion → backup → journal de run, retry 3× avec backoff 30 s → 2 min → 10 min), puis les exposent via une API FastAPI publique : données paginées, historiques par date, statistiques, rapports PDF.
41	41
42		−Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku 4.5, SSE, boucle de 24 outils branchés sur les API publiques des plateformes) servi en widget (`/ka-agent.js`) aux 13 domaines de l'écosystème — et sert de superviseur des connecteurs (~3 270 connecteurs suivis au 2026-08-24 : historique des collectes `/api/v1/runs`, santé par service, alertes). L'accès à l'API produit exige une authentification : session KA ID ou jeton personnel (`kapi_`, généré sur groupe-ka.com/compte).
	42	+Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku 4.5, SSE, boucle de 34 outils branchés sur les API publiques des plateformes) servi en widget (`/ka-agent.js`) aux 13 domaines de l'écosystème — et sert de superviseur des connecteurs (~4 460 connecteurs suivis au 2026-08-28 : historique des collectes `/api/v1/runs`, santé par service, alertes). L'accès à l'API produit exige une authentification : session KA ID ou jeton personnel (`kapi_`, généré sur groupe-ka.com/compte).
43	43
44		−## Chiffres live (au 2026-08-24)
	44	+## Chiffres live (au 2026-08-28)
45	45
46	46	Instantané de `GET /api/stats` et `GET /health` — les pastilles dynamiques ci-dessus restent à jour en continu.
47	47
48	48	\| Métrique \| Valeur \|
49	49	\|---\|---\|
50		−\| Collectes sur 7 jours \| 63 / 63 réussies (0 échec) \|
51		−\| Enregistrements collectés sur 7 jours \| 4 158 204 \|
52		−\| Enregistrements de la collecte du jour (9 services) \| 663 770 \|
53		−\| Appels API sur 7 jours \| 6 196 \|
54		−\| Connecteurs supervisés (écosystème) \| 3 271 — 3 098 OK · 169 dégradés · 3 en panne · 1 périmé \|
	50	+\| Collectes sur 7 jours \| 70 / 74 réussies (4 échecs, rattrapées par le backfill) \|
	51	+\| Enregistrements collectés sur 7 jours \| 4 522 761 \|
	52	+\| Appels API sur 7 jours \| 5 680 \|
	53	+\| Services collectés \| 11 (house-ka et rent-ka intégrés les 2026-08-27/28) \|
	54	+\| Connecteurs supervisés (écosystème) \| 4 458 — 4 179 OK · 133 dégradés · 3 en panne · 85 périmés · 58 retirés \|
55	55
56		−Dernière collecte par service (2026-08-24) :
	56	+Dernière collecte par service (2026-08-28) :
57	57
58	58	\| Service \| Enregistrements \| \| Service \| Enregistrements \|
59	59	\|---\|---\|---\|---\|---\|
60		−\| fabrika \| 385 061 \| \| autoka \| 48 446 \|
61		−\| immoka \| 67 702 \| \| jobka \| 21 492 \|
62		−\| foodka \| 50 936 \| \| sortika \| 17 147 \|
63		−\| louka \| 45 479 \| \| restoka \| 14 716 \|
64		−\| creaka \| 12 791 \| \| Total \| 663 770 \|
	60	+\| fabrika \| 384 574 \| \| jobka \| 2 297 \|
	61	+\| rentka \| 55 241 \| \| immoka \| 36 \|
	62	+\| sortika \| 17 168 \| \| autres* \| 0 \|
	63	+\| louka \| 7 365 \| \| Total du jour \| 466 681 \|
	64	+
	65	+<sub>* creaka, restoka, autoka, foodka et houseka rapportaient 0 enregistrement pour la date du jour au moment de la capture (collectes différentielles / heure de passage) — le statut du run restait `success`. Les valeurs live sont sur [/health](https://www.api-ka.com/health).</sub>
65	66
66	67	## Visite guidée
67	68
68		−Captures du 2026-08-25 (mobile 390×844 · desktop 1440×900).
	69	+10 captures du 2026-08-28 (desktop 1440×900 · mobile 390×844), versionnées dans [`docs/screenshots/`](docs/screenshots/).
69	70
70	71	<table>
71	72	<tr>
72		− <td align="center"><img src="docs/screenshots/desktop/doc.webp" width="420" alt="Documentation"><br><sub><b>www.api-ka.com/doc — le guide public de l'API (desktop)</b></sub></td>
73		− <td align="center"><img src="docs/screenshots/mobile/doc.webp" width="220" alt="Documentation mobile"><br><sub><b>Guide — version mobile</b></sub></td>
	73	+ <td align="center" colspan="2"><img src="docs/screenshots/01-accueil.jpg" width="720" alt="Accueil API·Ka"><br><sub><b>Accueil — « Toutes les données KA, centralisées chaque jour »</b><br>Le héros de <a href="https://www.api-ka.com">www.api-ka.com</a> : badge « API opérationnelle · M3U96B », réponse live de <code>GET /health</code> (nœud, base, dernières collectes) et compteurs en direct.</sub></td>
	74	+ </tr>
	75	+ <tr>
	76	+ <td align="center"><img src="docs/screenshots/07-accueil-section-1.jpg" width="420" alt="Accueil — section Sources"><br><sub><b>Accueil · 01 — Sources</b><br>Les services collectés en cartes : vocation, route <code>/api/v1/{service}</code>, enregistrements historisés et lien vers chaque plateforme Ka.</sub></td>
	77	+ <td align="center"><img src="docs/screenshots/08-accueil-section-2.jpg" width="420" alt="Accueil — section Endpoints"><br><sub><b>Accueil · 02 — Référence des endpoints</b><br>Chaque endpoint documenté en place : description, paramètres, extraits <code>curl</code> / Python / JavaScript copiables et bouton « Essayer ».</sub></td>
	78	+ </tr>
	79	+ <tr>
	80	+ <td align="center"><img src="docs/screenshots/09-accueil-section-3.jpg" width="420" alt="Accueil — endpoints historiques"><br><sub><b>Accueil — les endpoints d'historique</b><br><code>/api/v1/{service}/latest</code> et <code>/api/v1/{service}/date/{YYYY-MM-DD}</code> : paramètres requis/optionnels, pagination (limit max 500).</sub></td>
	81	+ <td align="center"><img src="docs/screenshots/03-stats.jpg" width="420" alt="Page /stats"><br><sub><b>/stats — la supervision de la plateforme</b><br>Appels API, latences moyenne et p95, taux d'erreur, collectes réussies/échouées, enregistrements — filtres de période et rapports PDF (complet, personnalisés).</sub></td>
	82	+ </tr>
	83	+ <tr>
	84	+ <td align="center"><img src="docs/screenshots/04-docs.jpg" width="420" alt="Swagger /docs"><br><sub><b>/docs — l'API interactive (Swagger, OpenAPI 3.1)</b><br>Tous les routeurs (health, auth, runs, monitoring, stats, services, agent…) avec schémas et essais en direct.</sub></td>
	85	+ <td align="center"><img src="docs/screenshots/05-doc.jpg" width="420" alt="Guide /doc"><br><sub><b>/doc — « Comment fonctionne API·Ka »</b><br>Le guide public : vue d'ensemble (collecteurs quotidiens, retry 3× + backfill, backups 90 jours, KA Agent), téléchargeable en PDF.</sub></td>
74	86	</tr>
75	87	<tr>
76		− <td align="center" colspan="2"><img src="docs/screenshots/desktop/docs.webp" width="640" alt="Swagger"><br><sub><b>/docs — l'API interactive (OpenAPI)</b></sub></td>
	88	+ <td align="center"><img src="docs/screenshots/06-doc.jpg" width="420" alt="Guide /doc (route directe)"><br><sub><b>/doc — la même page servie sur la route sans barre oblique finale</b><br>Le guide reste accessible aux deux chemins (<code>/doc</code> et <code>/doc/</code>).</sub></td>
	89	+ <td align="center"><img src="docs/screenshots/02-contact.jpg" width="420" alt="Page /contact"><br><sub><b>/contact — « Nous joindre »</b><br>Les trois courriels officiels du Groupe KA (projets/partenariats, médias, légal & Loi 25) et le rappel que la connexion « Se connecter avec KA » est déléguée au hub KA ID.</sub></td>
	90	+ </tr>
	91	+ <tr>
	92	+ <td align="center" colspan="2"><img src="docs/screenshots/10-accueil-mobile.jpg" width="220" alt="Accueil mobile"><br><sub><b>Accueil — version mobile (390×844)</b><br>Le même héros et le statut <code>/health</code> live, en colonne unique avec la nav mobile v2.</sub></td>
77	93	</tr>
78	94	</table>
79	95
80		−### Nouveautés (2026-08-25)
	96	+> 🗄️ Les captures du guide et du Swagger en WebP restent dans [`docs/screenshots/desktop/`](docs/screenshots/desktop/) et [`docs/screenshots/mobile/`](docs/screenshots/mobile/) ; les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
	97	+
	98	+### Nouveautés
81	99
82		−- KA Agent v3.2 — 33 outils (recherche fédérée, annuaires déménageurs/inspecteurs, historique/coût réel/TAL logement, ValoPlex, KA Scores) ; cartes d'annonces construites côté serveur (`afficher_cartes`), lien public `lien_fiche` sur chaque résultat, reprise automatique après coupure `max_tokens`.
	100	+- 2026-08-28 — Rent-Ka devient le 11ᵉ service : collecteur `rentka` (pagination offset/2000 comme lou-ka), table `rentka_data`, supervision des ~680 sources du connecteur au premier run (`6c64acd`).
	101	+- 2026-08-27 — House-Ka devient le 10ᵉ service : collecteur + modèle + CORS + supervision (17 sources) (`eb543c9`).
	102	+- KA Agent v3.2 — 34 outils (recherche fédérée, annuaires déménageurs/inspecteurs, agences immobilières, historique/coût réel/TAL logement, ValoPlex, KA Scores) ; cartes d'annonces construites côté serveur (`afficher_cartes`), lien public `lien_fiche` sur chaque résultat, reprise automatique après coupure `max_tokens`.
83	103	- Widget ka-agent v4 servi aux 13 domaines — cartes cliquables (`ka-card`) et choix en boutons (`ka-choix`).
84	104	- Monitoring des connecteurs — statut `retired` pour les sources désactivées ou disparues.
85	105	- Nav mobile v2 sur les pages web.
86	106
87		−> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
	107	+## Rôle central dans l'écosystème
	108	+
	109	+API·Ka est le système nerveux du Groupe KA, avec trois missions :
	110	+
	111	+1. API unifiée des plateformes — un seul point d'entrée versionné (`/api/v1/{service}`) pour les données quotidiennes historisées des 11 services : mêmes conventions de pagination, mêmes enveloppes JSON, mêmes checksums, quel que soit le service interrogé. C'est ce qui alimente l'app iOS KA, Ka·Stats, les rapports PDF et les intégrations internes.
	112	+2. Superviseur des connecteurs — la santé des ~4 460 connecteurs de collecte de tout l'écosystème (les sources de lou-ka, immo-ka, rent-ka, etc.) est agrégée ici (`/api/v1/monitoring/connectors`), avec statuts `ok / degraded / broken / stale / retired`, fenêtres de fraîcheur par service et alertes journalisées.
	113	+3. Agent conversationnel central — le KA Agent répond en langage naturel sur les 13 sites via un seul backend (SSE), en s'appuyant sur les données live des plateformes plutôt que sur la base historisée : ce que l'agent dit est ce que les sites affichent.
88	114
89	115	## Fonctionnalités
90	116
91		−- 9 collecteurs quotidiens — un par plateforme Ka (Job-Ka intégré le 2026-08-18), avec validation, checksum, retry 3× (backoff exponentiel) et journal de run ; tout échec après 3 tentatives est loggé (`collection_runs`, `logs/alerts.log`).
	117	+- 11 collecteurs quotidiens — un par plateforme Ka (Job-Ka intégré le 2026-08-18, House-Ka le 2026-08-27, Rent-Ka le 2026-08-28), avec validation, checksum, retry 3× (backoff exponentiel) et journal de run ; tout échec après 3 tentatives est loggé (`collection_runs`, `logs/alerts.log`).
92	118	- Scheduler APScheduler — job quotidien à 02:00 (collecteurs en parallèle et indépendants) + backfill automatique des dates manquées (7 derniers jours).
93		−- API publique de données — `GET /api/v1/{service}` (pagination, limit max 500), `/latest`, `/date/{YYYY-MM-DD}`, `/stats`, `/api/v1/runs` (historique des collectes), pour `{service}` ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka.
	119	+- API publique de données — `GET /api/v1/{service}` (pagination, limit max 500), `/latest`, `/date/{YYYY-MM-DD}`, `/stats`, `/api/v1/runs` (historique des collectes), pour `{service}` ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka, houseka, rentka.
94	120	- Authentification obligatoire sur l'API produit — session KA ID ou jeton Bearer `kapi_` ; monitoring, stats et agent restent ouverts.
95		−- KA Agent (IA) — `POST /api/agent/chat` en SSE (Claude Haiku 4.5, boucle de 24 outils sur les données live des plateformes : logements, propriétés, véhicules, emplois, épicerie, produits, restos, plats, menus, inspections MAPAQ, sorties, créateurs, juste prix, estimateur Vrai-Prix, boutiques, suggestions, facettes, stats, état des services) + recherche floue en cascade + widget embarquable `GET /ka-agent.js` (v3 : bulle déplaçable, position mémorisée par site), CORS ouvert aux 13 domaines.
	121	+- KA Agent (IA) — `POST /api/agent/chat` en SSE (Claude Haiku 4.5, boucle de 34 outils sur les données live des plateformes : logements, propriétés, véhicules, rappels, emplois, épicerie et comparateur de prix, produits et boutiques QC, restos, plats, menus, inspections MAPAQ, sorties, créateurs, recherche web Québec, recherche globale fédérée, suggestions, facettes, fiches détail, estimateurs Vrai-Prix et ValoPlex, annuaires déménageurs/inspecteurs, agences immobilières, historique/coût réel/TAL logement, KA Scores, cartes d'annonces serveur, stats et état des services) + recherche floue en cascade + widget embarquable `GET /ka-agent.js` (v4 : bulle déplaçable, position mémorisée par site, cartes cliquables et boutons de choix), CORS ouvert aux 13 domaines.
96	122	- SSO KA ID — `GET /api/auth/ka/{login,callback}`, session `/api/auth/me`, et échange de jeton pour les apps natives (`POST /api/ios/auth/exchange`, vérification HS256, `aud` ∈ ka-ios, ka-android).
97	123	- Stats & rapports — tableau de bord `/stats`, `GET /api/stats` (KPI compact JSON), `GET /api/stats/report` (PDF de la plateforme) et `GET /api/stats/ecosystem-report` (rapport PDF consolidé de l'écosystème, liste dynamique via `ecosystem.json`) + rapports PDF personnalisés (catalogue + constructeur).
98	124	- Recherche transversale — `GET /api/v1/search` + `GET /api/v1/suggest` (proxy du moteur Trouve-Ka, pivot moteur de recherche Groupe KA).
99	125	- Backups quotidiens horodatés par service (`data/backups/YYYY-MM-DD/`, rétention 90 jours).
100		−- Santé & supervision — `GET /health` (nœud, état DB, dernière collecte par service) ; chaque service vérifie le hostname au démarrage et refuse de tourner en production ailleurs que sur `m3u96b`.
	126	+- Santé & supervision — `GET /health` (nœud, état DB, dernière collecte par service, compteurs de connecteurs) ; chaque service vérifie le hostname au démarrage et refuse de tourner en production ailleurs que sur `m3u96b`.
101	127	- SEO du site de doc — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.
102	128
	129	+## Authentification
	130	+
	131	+Deux façons d'accéder à l'API produit — aucun secret n'est stocké dans ce repo :
	132	+
	133	+- Session KA ID (SSO) — le bouton « Se connecter avec KA » délègue au hub [groupe-ka.com](https://www.groupe-ka.com) (compte unique de l'écosystème) : `GET /api/auth/ka/login` → callback → session serveur, introspectable via `GET /api/auth/me`.
	134	+- Jeton personnel `kapi_` — généré (et révocable) sur [groupe-ka.com/compte](https://www.groupe-ka.com/compte), passé en en-tête `Authorization: Bearer kapi_…`. C'est la voie recommandée pour les scripts et intégrations.
	135	+- Endpoints exemptés (publics sans authentification) : `GET /health`, `GET /api/stats`, la supervision (`/api/v1/runs`, `/api/v1/monitoring/*`), les pages web et le KA Agent (`/api/agent/chat`, `/ka-agent.js`).
	136	+- Apps natives : `POST /api/ios/auth/exchange` échange le jeton du hub contre une session API (HS256, `aud` ka-ios / ka-android).
	137	+- Rate-limit global : 120 req/min.
	138	+
103	139	## API (endpoints principaux)
104	140
105	141	Référence interactive complète : Swagger sur [/docs](https://www.api-ka.com/docs). 🔒 = session KA ID ou jeton Bearer `kapi_` requis.
106	142
107	143	\| Méthode & endpoint \| Description \|
108	144	\|---\|---\|
109		−\| `GET /health` \| santé : nœud, état DB, dernière collecte par service \|
	145	+\| `GET /health` \| santé : nœud, état DB, dernière collecte par service, compteurs de connecteurs \|
110	146	\| `GET /api/stats` \| KPI compact JSON : collectes 7 j, enregistrements, appels API, connecteurs (alimente les pastilles ci-dessus) \|
111		−\| 🔒 `GET /api/v1/{service}` \| données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka \|
	147	+\| 🔒 `GET /api/v1/{service}` \| données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka, houseka, rentka \|
112	148	\| 🔒 `GET /api/v1/{service}/latest` \| dernière collecte du service \|
113	149	\| 🔒 `GET /api/v1/{service}/date/{YYYY-MM-DD}` \| collecte d'une date précise \|
114	150	\| 🔒 `GET /api/v1/{service}/stats` \| statistiques du service \|
115	151	\| 🔒 `GET /api/v1/louka/fairvalue/{uid}` \| juste prix d'une annonce Lou·Ka (proxy live, utilisé par l'app iOS KA) \|
116	152	\| `GET /api/v1/runs` \| historique des runs de collecte (supervision) \|
117		−\| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` \| santé des connecteurs de l'écosystème (~3 270 suivis) \|
	153	+\| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` \| santé des connecteurs de l'écosystème (~4 460 suivis, statuts ok/degraded/broken/stale/retired) \|
118	154	\| `GET /api/stats/dashboard` · `/report` · `/catalog` · `POST /api/stats/report/custom` \| tableau de bord + rapports PDF (catalogue, personnalisés) \|
119	155	\| `GET /api/stats/ecosystem-report` \| rapport PDF consolidé des 13 plateformes \|
120		−\| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` \| KA Agent (Claude Haiku 4.5 + 24 outils live) et son widget embarquable \|
	156	+\| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` \| KA Agent (Claude Haiku 4.5 + 34 outils live) et son widget embarquable \|
121	157	\| `GET /api/v1/search` · `GET /api/v1/suggest` \| recherche transversale (incl. recherche floue) et suggestions — proxy Trouve-Ka \|
122	158	\| `GET /api/auth/config` · `/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout` \| SSO KA ID \|
123	159	\| `POST /api/ios/auth/exchange` \| échange de jeton pour les apps natives (`aud` ka-ios / ka-android) \|
		`@@ -126,16 +162,16 @@ Référence interactive complète : **Swagger sur [/docs](https://www.api-ka.com`
126	162
127	163	- FastAPI + Uvicorn (`src/api/`) : 9 routeurs (health, auth, runs, monitoring, stats, search, services, agent, iosauth) + pages web et PDF (fpdf2).
128	164	- PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, `psycopg2`) : une table de données par service (`{service}_data`) + journal `collection_runs`.
129		−- Collecteurs (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 9 collecteurs concrets, httpx.
	165	+- Collecteurs (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 11 collecteurs concrets, httpx.
130	166	- Scheduler (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.
131		−- Utils (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.
	167	+- Utils (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision (`connector_health` sonde les 11 apps).
132	168	- anthropic SDK pour le KA Agent.
133	169
134	170	Collecteurs et cadence :
135	171
136	172	\| Collecteur \| Source \| Cadence \|
137	173	\|---\|---\|---\|
138		−\| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` · `jobka` \| API publique de chaque plateforme Ka (`{SERVICE}_SOURCE_URL`) \| quotidien 02:00 (parallèle, indépendants) \|
	174	+\| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` · `jobka` · `houseka` · `rentka` \| API publique de chaque plateforme Ka (`{SERVICE}_SOURCE_URL`) \| quotidien 02:00 (parallèle, indépendants) \|
139	175	\| backfill \| dates manquées des 7 derniers jours \| au démarrage du job quotidien \|
140	176	\| backups \| dump horodaté par service (`data/backups/YYYY-MM-DD/`) \| quotidien, rétention 90 jours \|
141	177
		`@@ -159,7 +195,7 @@ python -m src.database.db --init # initialiser la base PostgreSQ`
159	195	uvicorn src.api.main:app --reload --port 8000 # API en dev → http://127.0.0.1:8000
160	196	python -m src.scheduler.daily_job --now # collecte manuelle immédiate
161	197	python -m src.scheduler.backfill --date 2026-08-15
162		−pytest tests/ -v # 8 modules de tests (api, collectors, retry, backfill, search, stats, connector_health)
	198	+pytest tests/ -v # modules de tests (api, collectors, retry, backfill, search, stats, connector_health)
163	199	```
164	200
165	201	## Variables d'environnement
		@@ -173,7 +209,7 @@ Déclarées dans `.env.example` (copier vers `.env`, jamais commité — aucun s
173	209	\| `API_PORT` · `RATE_LIMIT_PER_MINUTE` \| port de l'API (8000) et rate-limit \|
174	210	\| `DAILY_RUN_HOUR` · `BACKUP_RETENTION_DAYS` \| heure du job quotidien (02) et rétention des backups (90) \|
175	211	\| `NGROK_AUTHTOKEN` · `NGROK_DOMAIN` \| tunnel ngrok (www.api-ka.com) \|
176		−\| `LOUKA_SOURCE_URL` … `JOBKA_SOURCE_URL` (×9) \| URL source de chaque collecteur \|
	212	+\| `LOUKA_SOURCE_URL` … `RENTKA_SOURCE_URL` (×11) \| URL source de chaque collecteur \|
177	213	\| `TROUVEKA_SEARCH_URL` · `TROUVEKA_SUGGEST_URL` \| proxy du moteur de recherche Trouve-Ka \|
178	214	\| `KA_HUB_URL` · `KA_SSO_SECRET` · `KA_IOS_SSO_SECRET` · `SESSION_SECRET` \| SSO KA ID (hub groupe-ka.com) + sessions \|
179	215	\| `ANTHROPIC_API_KEY` \| clé du KA Agent (lue par le SDK anthropic) \|
		@@ -181,7 +217,7 @@ Déclarées dans `.env.example` (copier vers `.env`, jamais commité — aucun s
181	217
182	218	## Données & conformité
183	219
184		−- Provenance : les données proviennent exclusivement des API publiques des 9 plateformes Ka (aucun scraping tiers dans ce repo) ; chaque enregistrement passe par validation + checksum avant insertion.
	220	+- Provenance : les données proviennent exclusivement des API publiques des 11 plateformes Ka (aucun scraping tiers dans ce repo) ; chaque enregistrement passe par validation + checksum avant insertion.
185	221	- Cadence : resynchronisation quotidienne à 02:00 (collecteurs parallèles) + backfill automatique des 7 derniers jours ; backups quotidiens horodatés, rétention 90 jours.
186	222	- Accès : l'API produit exige une authentification (session KA ID ou jeton `kapi_` révocable sur groupe-ka.com/compte) ; monitoring, stats et agent restent publics ; rate-limit 120 req/min.
187	223	- Traçabilité : chaque run de collecte est journalisé (`collection_runs`, exposé via `/api/v1/runs`) ; alertes dans `logs/alerts.log`.
		@@ -190,13 +226,13 @@ Déclarées dans `.env.example` (copier vers `.env`, jamais commité — aucun s
190	226
191	227	```
192	228	/opt/api-ka
193		−├── src/ # api/ (routes, web, PDF), collectors/ (9), scheduler/, database/, monitoring/, utils/, config.py
	229	+├── src/ # api/ (routes, web, PDF), collectors/ (11), scheduler/, database/, monitoring/, utils/, config.py
194	230	├── scripts/ # deploy_m3u96b.sh, healthcheck.sh, run_daily_backup.sh, start_ngrok.sh…
195	231	├── systemd/ # unités historiques (le déploiement actuel utilise PM2)
196		−├── tests/ # pytest (8 modules)
	232	+├── tests/ # pytest (api, backfill, collectors, connector_health, retry, search, stats)
197	233	├── data/ # backups/YYYY-MM-DD/ (rétention 90 jours)
198	234	├── logs/ # logs centralisés + alerts.log
199		−├── docs/ # captures d'écran
	235	+├── docs/ # screenshots/ (visite guidée + desktop/mobile WebP) · archive/
200	236	└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md
201	237	```
202	238
		@@ -217,6 +253,9 @@ Déclarées dans `.env.example` (copier vers `.env`, jamais commité — aucun s
217	253	\| 2026-08-22 \| ka-agent v3 : bulle déplaçable, position mémorisée par site ; standard header KA \|
218	254	\| 2026-08-23 \| authentification obligatoire sur l'API produit (KA ID / jeton `kapi_`, `99ebb9e`) ; stats v3 (rapports PDF personnalisés) ; recherche `/api/v1/search` (proxy Trouve-Ka) ; SEO complet ; monitoring affiné (fenêtre 6 h, sources vides ≠ pannes) \|
219	255	\| 2026-08-24 \| page documentation `/doc` + guide PDF ; README v2 puis v3 (chiffres live, pastilles dynamiques) \|
	256	+\| 2026-08-25 \| KA Agent v3.2 (33 → 34 outils, cartes serveur `afficher_cartes`, reprise après `max_tokens`) ; widget ka-agent v4 ; statut `retired` au monitoring ; nav mobile v2 \|
	257	+\| 2026-08-27 \| House-Ka devient le 10ᵉ service (`eb543c9`) — collecteur, modèle, CORS, supervision (17 sources) \|
	258	+\| 2026-08-28 \| Rent-Ka devient le 11ᵉ service (`6c64acd`) — collecteur offset/2000, supervision (~680 sources) ; README v4 + visite guidée en 10 captures \|
220	259
221	260	## Développement (remote-first)
222	261
		`@@ -242,8 +281,8 @@ pm2 restart apika-api # après un changement en produ`
242	281	\| Plateforme \| Vocation \|
243	282	\|---\|---\|
244	283	\| [groupe-ka.com](https://www.groupe-ka.com) \| portail du groupe et compte unique KA ID \|
245		−\| [lou-ka.com](https://www.lou-ka.com) \| logements à louer \|
246		−\| [immo-ka.com](https://www.immo-ka.com) \| propriétés à vendre \|
	284	+\| [lou-ka.com](https://www.lou-ka.com) \| logements à louer (Québec) \|
	285	+\| [immo-ka.com](https://www.immo-ka.com) \| propriétés à vendre (Québec) \|
247	286	\| [vrai-prix.com](https://www.vrai-prix.com) \| estimation immobilière \|
248	287	\| [auto-ka.com](https://www.auto-ka.com) \| véhicules \|
249	288	\| [fabri-ka.com](https://www.fabri-ka.com) \| produits québécois \|
		`@@ -253,6 +292,8 @@ pm2 restart apika-api # après un changement en produ`
253	292	\| [job-ka.com](https://www.job-ka.com) \| emplois \|
254	293	\| [crea-ka.com](https://www.crea-ka.com) \| créateurs de contenu \|
255	294	\| [trouve-ka.com](https://www.trouve-ka.com) \| petites annonces \|
	295	+\| [house-ka.com](https://www.house-ka.com) \| maisons à vendre (Canada hors Québec) \|
	296	+\| [rent-ka.com](https://www.rent-ka.com) \| loyers (Canada hors Québec) \|
256	297	\| [api-ka.com](https://www.api-ka.com) \| API de données (ce repo) \|
257	298
258	299	## Contact

added docs/screenshots/01-accueil.jpg +0 −0

Binary file not shown.

added docs/screenshots/02-contact.jpg +0 −0

Binary file not shown.

added docs/screenshots/03-stats.jpg +0 −0

Binary file not shown.

added docs/screenshots/04-docs.jpg +0 −0

Binary file not shown.

added docs/screenshots/05-doc.jpg +0 −0

Binary file not shown.

added docs/screenshots/06-doc.jpg +0 −0

Binary file not shown.

added docs/screenshots/07-accueil-section-1.jpg +0 −0

Binary file not shown.

added docs/screenshots/08-accueil-section-2.jpg +0 −0

Binary file not shown.

added docs/screenshots/09-accueil-section-3.jpg +0 −0

Binary file not shown.

added docs/screenshots/10-accueil-mobile.jpg +0 −0

Binary file not shown.