docs: README v3 — chiffres live vérifiés, pastilles dynamiques, sections complètes · 38bd2f4 · api-ka

6

7

<p align="center"><b>La donnée de l'écosystème, par API</b></p>

8

9

−<p align="center">

10

− <a href="https://www.api-ka.com"><img src="https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com&up_color=3b5bdb&up_message=en%20ligne" alt="Site"></a>

11

− <a href="https://www.api-ka.com/doc/"><img src="https://img.shields.io/badge/📖_documentation-%2Fdoc-3b5bdb?style=flat-square" alt="Documentation"></a>

12

− <a href="https://www.api-ka.com/doc/api-ka-documentation.pdf"><img src="https://img.shields.io/badge/guide-PDF-3b5bdb?style=flat-square" alt="PDF"></a>

13

− <img src="https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square" alt="Nœud">

14

− <img src="https://img.shields.io/badge/port-8000-141814?style=flat-square" alt="Port">

15

− <img src="https://img.shields.io/badge/process-PM2-2b037a?style=flat-square" alt="PM2">

16

−</p>

17

−<p align="center">

18

− <img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">

19

− <img src="https://img.shields.io/badge/FastAPI-API-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI">

20

− <img src="https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL">

21

− <img src="https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square" alt="APScheduler">

22

− <img src="https://img.shields.io/badge/Groupe-KA-3b5bdb?style=flat-square" alt="Groupe KA">

23

−</p>

24

−

25

−**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, **8 collecteurs** (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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.

26

−

27

−Elle héberge aussi le **KA Agent** — l'assistant IA central du groupe (Claude Haiku, SSE, boucle d'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** (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).

9

+<div align="center">

10

+

11

+[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.api-ka.com&style=flat-square&label=www.api-ka.com&up_color=3b5bdb&up_message=en%20ligne)](https://www.api-ka.com)

12

+[![Documentation](https://img.shields.io/badge/📖_documentation-%2Fdoc-3b5bdb?style=flat-square)](https://www.api-ka.com/doc/)

13

+[![PDF](https://img.shields.io/badge/guide-PDF-3b5bdb?style=flat-square)](https://www.api-ka.com/doc/api-ka-documentation.pdf)

14

+[![Swagger](https://img.shields.io/badge/Swagger-%2Fdocs-3b5bdb?style=flat-square)](https://www.api-ka.com/docs)

15

+![Nœud](https://img.shields.io/badge/n%C5%93ud-M3U96b-1f6feb?style=flat-square)

16

+![Port](https://img.shields.io/badge/port-8000-141814?style=flat-square)

17

+![PM2](https://img.shields.io/badge/PM2-3_processus-2b037a?style=flat-square)

18

+

19

+[![Collectes 7 j](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fapi%2Fstats&query=%24.data.runs_7d.ok&label=collectes%207%20j%20OK&color=3b5bdb&style=flat-square)](https://www.api-ka.com/api/stats)

20

+[![Enregistrements 7 j](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fapi%2Fstats&query=%24.data.runs_7d.records&label=enregistrements%207%20j&color=3b5bdb&style=flat-square)](https://www.api-ka.com/api/stats)

21

+[![Appels API 7 j](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fapi%2Fstats&query=%24.data.api.calls_7d&label=appels%20API%207%20j&color=3b5bdb&style=flat-square)](https://www.api-ka.com/api/stats)

22

+[![Connecteurs OK](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fapi%2Fstats&query=%24.data.connectors.ok&label=connecteurs%20OK&color=2f9e44&style=flat-square)](https://www.api-ka.com/stats)

23

+[![Connecteurs en panne](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fapi%2Fstats&query=%24.data.connectors.broken&label=connecteurs%20en%20panne&color=e03131&style=flat-square)](https://www.api-ka.com/stats)

24

+[![PostgreSQL](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fhealth&query=%24.data.database&label=PostgreSQL&color=3b5bdb&style=flat-square)](https://www.api-ka.com/health)

25

+[![Dernière collecte](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.api-ka.com%2Fhealth&query=%24.data.last_collections.louka.date_key&label=derni%C3%A8re%20collecte&color=3b5bdb&style=flat-square)](https://www.api-ka.com/health)

26

+

27

+![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)

28

+![FastAPI](https://img.shields.io/badge/FastAPI-Uvicorn-009688?style=flat-square&logo=fastapi&logoColor=white)

29

+![PostgreSQL](https://img.shields.io/badge/PostgreSQL-SQLAlchemy_2-4169E1?style=flat-square&logo=postgresql&logoColor=white)

30

+![APScheduler](https://img.shields.io/badge/APScheduler-job_02%3A00-1c5c41?style=flat-square)

31

+![Claude](https://img.shields.io/badge/KA_Agent-Claude_Haiku_4.5-cc785c?style=flat-square&logo=anthropic&logoColor=white)

32

+![pytest](https://img.shields.io/badge/tests-pytest-0A9EDC?style=flat-square&logo=pytest&logoColor=white)

33

+![PM2](https://img.shields.io/badge/process-PM2-2B037A?style=flat-square&logo=pm2&logoColor=white)

34

+![ngrok](https://img.shields.io/badge/tunnel-ngrok-1F1E37?style=flat-square&logo=ngrok&logoColor=white)

35

+![Groupe KA](https://img.shields.io/badge/Groupe-KA-3b5bdb?style=flat-square)

36

+![spbgit](https://img.shields.io/badge/remote--first-spbgit-141814?style=flat-square&logo=git&logoColor=white)

37

+

38

+</div>

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.

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).

43

+

44

+## Chiffres live (au 2026-08-24)

45

+

46

+Instantané de `GET /api/stats` et `GET /health` — les pastilles dynamiques ci-dessus restent à jour en continu.

47

+

48

+| Métrique | Valeur |

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é |

55

+

56

+Dernière collecte par service (2026-08-24) :

57

+

58

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** |

28

65

29

66

## Visite guidée

30

67

44

81

45

82

## Fonctionnalités

46

83

47

−- **8 collecteurs quotidiens** — un par plateforme Ka, avec validation, checksum, retry 3× (backoff exponentiel) et journal de run ; tout échec après 3 tentatives est loggé (`collection_runs`, `logs/alerts.log`).

84

+- **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`).

48

85

- **Scheduler APScheduler** — job quotidien à 02:00 (collecteurs en parallèle et indépendants) + **backfill automatique** des dates manquées (7 derniers jours).

49

−- **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.

86

+- **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.

50

87

- **Authentification obligatoire sur l'API produit** — session KA ID ou jeton Bearer `kapi_` ; monitoring, stats et agent restent ouverts.

51

−- **KA Agent (IA)** — `POST /api/agent/chat` en SSE (Claude Haiku, boucle d'outils sur les données live des plateformes : logements, propriétés, véhicules, emplois, épicerie, produits, restos, sorties, créateurs, stats, état des services) + widget embarquable `GET /ka-agent.js`, CORS ouvert aux 13 domaines.

52

−- **SSO KA ID** — `GET /api/auth/ka/{login,callback}`, session `/api/auth/me`, et échange de jeton pour l'app iOS native (`POST /api/ios/auth/exchange`, vérification HS256 `aud=ka-ios`).

53

−- **Stats & rapports** — tableau de bord `/stats`, `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).

88

+- **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.

89

+- **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).

90

+- **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).

91

+- **Recherche transversale** — `GET /api/v1/search` + `GET /api/v1/suggest` (proxy du moteur Trouve-Ka, pivot moteur de recherche Groupe KA).

54

92

- **Backups quotidiens** horodatés par service (`data/backups/YYYY-MM-DD/`, rétention 90 jours).

55

93

- **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`.

56

94

- **SEO du site de doc** — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.

59

97

60

98

Référence interactive complète : **Swagger sur [/docs](https://www.api-ka.com/docs)**. 🔒 = session KA ID ou jeton Bearer `kapi_` requis.

61

99

62

−| Endpoint | Rôle |

100

+| Méthode & endpoint | Description |

63

101

|---|---|

64

102

| `GET /health` | santé : nœud, état DB, dernière collecte par service |

65

−| 🔒 `GET /api/v1/{service}` | données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka |

66

−| 🔒 `GET /api/v1/{service}/latest` · `/date/{YYYY-MM-DD}` | dernière collecte, collecte d'une date précise |

103

+| `GET /api/stats` | KPI compact JSON : collectes 7 j, enregistrements, appels API, connecteurs (alimente les pastilles ci-dessus) |

104

+| 🔒 `GET /api/v1/{service}` | données paginées (limit max 500) — service ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka |

105

+| 🔒 `GET /api/v1/{service}/latest` | dernière collecte du service |

106

+| 🔒 `GET /api/v1/{service}/date/{YYYY-MM-DD}` | collecte d'une date précise |

67

107

| 🔒 `GET /api/v1/{service}/stats` | statistiques du service |

68

−| 🔒 `GET /api/v1/louka/fairvalue/{uid}` | juste prix d'une annonce Lou·Ka |

108

+| 🔒 `GET /api/v1/louka/fairvalue/{uid}` | juste prix d'une annonce Lou·Ka (proxy live, utilisé par l'app iOS KA) |

69

109

| `GET /api/v1/runs` | historique des runs de collecte (supervision) |

70

−| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` | santé des connecteurs de l'écosystème |

110

+| `GET /api/v1/monitoring/connectors` · `/connectors/{service}` | santé des connecteurs de l'écosystème (~3 270 suivis) |

71

111

| `GET /api/stats/dashboard` · `/report` · `/catalog` · `POST /api/stats/report/custom` | tableau de bord + rapports PDF (catalogue, personnalisés) |

72

112

| `GET /api/stats/ecosystem-report` | rapport PDF consolidé des 13 plateformes |

73

−| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` | KA Agent (Claude Haiku + outils live) et son widget embarquable |

74

−| `GET /api/search` · `GET /api/suggest` | recherche transversale (incl. recherche floue) et suggestions |

75

−| `GET /api/auth/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout` | SSO KA ID |

76

−| `POST /api/ios/auth/exchange` | échange de jeton pour l'app iOS (`aud=ka-ios`) |

113

+| `POST /api/agent/chat` (SSE) · `GET /ka-agent.js` | KA Agent (Claude Haiku 4.5 + 24 outils live) et son widget embarquable |

114

+| `GET /api/v1/search` · `GET /api/v1/suggest` | recherche transversale (incl. recherche floue) et suggestions — proxy Trouve-Ka |

115

+| `GET /api/auth/config` · `/ka/login` · `/ka/callback` · `/me` · `POST /api/auth/logout` | SSO KA ID |

116

+| `POST /api/ios/auth/exchange` | échange de jeton pour les apps natives (`aud` ka-ios / ka-android) |

77

117

78

118

## Architecture

79

119

80

−- **FastAPI + Uvicorn** (`src/api/`) : routes health, services, runs, monitoring, stats, search, agent, auth, iosauth + pages web et PDF (fpdf2).

81

−- **PostgreSQL** via **SQLAlchemy 2** (+ **Alembic** pour les migrations, `psycopg2`) : une table de données par service + journal `collection_runs`.

82

−- **Collecteurs** (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 8 collecteurs concrets, httpx.

120

+- **FastAPI + Uvicorn** (`src/api/`) : 9 routeurs (health, auth, runs, monitoring, stats, search, services, agent, iosauth) + pages web et PDF (fpdf2).

121

+- **PostgreSQL** via **SQLAlchemy 2** (+ **Alembic** pour les migrations, `psycopg2`) : une table de données par service (`{service}_data`) + journal `collection_runs`.

122

+- **Collecteurs** (`src/collectors/`) : classe abstraite `base_collector` (fetch, validate, save, retry) + 9 collecteurs concrets, httpx.

83

123

- **Scheduler** (`src/scheduler/`) : `daily_job.py` (02:00) + `backfill.py`.

84

124

- **Utils** (`src/utils/`) : backups quotidiens, rétention 90 jours ; `src/monitoring/` pour la supervision.

85

125

- **anthropic** SDK pour le KA Agent.

88

128

89

129

| Collecteur | Source | Cadence |

90

130

|---|---|---|

91

−| `louka` · `immoka` · `foodka` · `autoka` · `fabrika` · `restoka` · `sortika` · `creaka` | API publique de chaque plateforme Ka | quotidien 02:00 (parallèle, indépendants) |

131

+| `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) |

92

132

| backfill | dates manquées des 7 derniers jours | au démarrage du job quotidien |

93

133

| backups | dump horodaté par service (`data/backups/YYYY-MM-DD/`) | quotidien, rétention 90 jours |

94

134

95

−Processus PM2 sur le nœud :

135

+Processus PM2 sur le nœud (commandes de start réelles) :

96

136

97

−| Processus | Rôle | Cadence |

137

+| Processus | Commande | Rôle |

98

138

|---|---|---|

99

−| `apika-api` | l'API FastAPI/Uvicorn sur le port **8000** (liée à 127.0.0.1) | continu |

100

−| `apika-scheduler` | le job quotidien 02:00 + backfill (`python -m src.scheduler.daily_job`) | quotidien 02:00 |

101

−| `apika-ngrok` | tunnel ngrok vers **www.api-ka.com** | continu |

139

+| `apika-api` | `venv/bin/uvicorn src.api.main:app --host 127.0.0.1 --port 8000` | l'API FastAPI/Uvicorn sur le port **8000** (liée à 127.0.0.1) |

140

+| `apika-scheduler` | `venv/bin/python -m src.scheduler.daily_job` | le job quotidien 02:00 + backfill |

141

+| `apika-ngrok` | `ngrok http --domain=www.api-ka.com 8000 --log stdout` | tunnel vers **www.api-ka.com** |

142

+

143

+## Démarrage rapide

144

+

145

+```bash

146

+git clone gitsrv:api-ka.git && cd api-ka

147

+python3 -m venv venv && source venv/bin/activate

148

+pip install -r requirements.txt

149

+cp .env.example .env # puis remplir les valeurs

150

+

151

+python -m src.database.db --init # initialiser la base PostgreSQL

152

+uvicorn src.api.main:app --reload --port 8000 # API en dev → http://127.0.0.1:8000

153

+python -m src.scheduler.daily_job --now # collecte manuelle immédiate

154

+python -m src.scheduler.backfill --date 2026-08-15

155

+pytest tests/ -v # 8 modules de tests (api, collectors, retry, backfill, search, stats, connector_health)

156

+```

102

157

103

−Points de configuration notables (`src/config.py`, variables d'environnement — aucun secret dans le repo) : URL PostgreSQL, clé Anthropic du KA Agent, secret SSO partagé avec le hub KA ID, garde-fou de hostname (`m3u96b`).

158

+## Variables d'environnement

159

+

160

+Déclarées dans `.env.example` (copier vers `.env`, jamais commité — aucun secret dans le repo) :

161

+

162

+| Variable | Rôle |

163

+|---|---|

164

+| `APP_ENV` · `NODE_NAME` | environnement + garde-fou de hostname (`m3u96b` en prod) |

165

+| `DATABASE_URL` | connexion PostgreSQL (SQLAlchemy) |

166

+| `API_PORT` · `RATE_LIMIT_PER_MINUTE` | port de l'API (8000) et rate-limit |

167

+| `DAILY_RUN_HOUR` · `BACKUP_RETENTION_DAYS` | heure du job quotidien (02) et rétention des backups (90) |

168

+| `NGROK_AUTHTOKEN` · `NGROK_DOMAIN` | tunnel ngrok (www.api-ka.com) |

169

+| `LOUKA_SOURCE_URL` … `JOBKA_SOURCE_URL` (×9) | URL source de chaque collecteur |

170

+| `TROUVEKA_SEARCH_URL` · `TROUVEKA_SUGGEST_URL` | proxy du moteur de recherche Trouve-Ka |

171

+| `KA_HUB_URL` · `KA_SSO_SECRET` · `KA_IOS_SSO_SECRET` · `SESSION_SECRET` | SSO KA ID (hub groupe-ka.com) + sessions |

172

+| `ANTHROPIC_API_KEY` | clé du KA Agent (lue par le SDK anthropic) |

173

+| `APIKA_BASE_URL` | base URL publique de l'API |

174

+

175

+## Données & conformité

176

+

177

+- **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.

178

+- **Cadence** : resynchronisation **quotidienne à 02:00** (collecteurs parallèles) + backfill automatique des 7 derniers jours ; backups quotidiens horodatés, rétention 90 jours.

179

+- **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.

180

+- **Traçabilité** : chaque run de collecte est journalisé (`collection_runs`, exposé via `/api/v1/runs`) ; alertes dans `logs/alerts.log`.

104

181

105

182

## Structure du repo

106

183

107

184

```

108

185

/opt/api-ka

109

−├── src/ # api/ (routes, web, PDF), collectors/ (8), scheduler/, database/, monitoring/, utils/, config.py

110

−├── scripts/ # deploy_m3u96b.sh, start_ngrok.sh…

186

+├── src/ # api/ (routes, web, PDF), collectors/ (9), scheduler/, database/, monitoring/, utils/, config.py

187

+├── scripts/ # deploy_m3u96b.sh, healthcheck.sh, run_daily_backup.sh, start_ngrok.sh…

111

188

├── systemd/ # unités historiques (le déploiement actuel utilise PM2)

112

−├── tests/ # pytest

189

+├── tests/ # pytest (8 modules)

113

190

├── data/ # backups/YYYY-MM-DD/ (rétention 90 jours)

114

191

├── logs/ # logs centralisés + alerts.log

115

192

├── docs/ # captures d'écran

123

200

- **Swagger interactif** : [www.api-ka.com/docs](https://www.api-ka.com/docs) — tous les endpoints, schémas et essais en direct.

124

201

- Les captures du guide sont versionnées dans `src/api/web/doc/img/` (etape1 → etape3).

125

202

203

+## Historique

204

+

205

+| Date | Jalon |

206

+|---|---|

207

+| 2026-08-17 | naissance de la plateforme : collecte quotidienne des 8 services KA + API publique (`d8b3b82`), design Groupe KA + SSO KA ID, page `/stats`, rapport écosystème PDF, **KA Agent v1** (Claude Haiku, SSE, 12 outils, CORS 13 domaines) |

208

+| 2026-08-18 | **Job-Ka devient le 9ᵉ service** (collecteur + supervision, `609d6bb`) ; supervision centralisée des connecteurs de l'écosystème ; auth mobile ka-ios/ka-android |

209

+| 2026-08-19 | **KA Agent v2** : 24 outils + recherche floue en cascade + widget v2 (`e548e0d`) ; socle mobile (anti-zoom 16 px) |

210

+| 2026-08-22 | ka-agent v3 : bulle déplaçable, position mémorisée par site ; standard header KA |

211

+| 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) |

212

+| 2026-08-24 | page documentation `/doc` + guide PDF ; README v2 puis **v3** (chiffres live, pastilles dynamiques) |

213

+

126

214

## Développement (remote-first)

127

215

128

216

**La source de vérité est le repo git sur le nœud M3U96b** (`/opt/api-ka`) — on n'édite jamais les copies laptop. Toute modification se fait sur le nœud via SSH : édition, tests, `pm2 restart`, puis commit/push depuis le nœud.

132

220

- Chaque fichier du dépôt porte l'en-tête d'auteur obligatoire (voir `CLAUDE.md`).

133

221

134

222

```bash

135

−python3 -m venv venv && source venv/bin/activate

136

−pip install -r requirements.txt

137

−

138

−python -m src.database.db --init # initialiser la base

139

−uvicorn src.api.main:app --reload --port 8000 # API en dev

140

−python -m src.scheduler.daily_job --now # collecte manuelle immédiate

141

−python -m src.scheduler.backfill --date 2026-08-15

142

−pytest tests/ -v

143

−

144

223

pm2 restart apika-api # après un changement en production

145

224

```

146

225

147

226