# API-Ka — L'API de données du Groupe Ka

**API-Ka** collecte, sauvegarde et centralise **chaque jour** les données des **8 plateformes** de l'écosystème **Groupe Ka** dans une base **PostgreSQL** unifiée, puis les expose via une API publique sur **www.api-ka.com** — avec en prime le **KA Agent** (assistant IA de l'écosystème) et le **hub SSO KA ID**.

![Aperçu de API-Ka](docs/screenshot.png)

## Description

**API-Ka** est la **plateforme centrale** de l'écosystème **Groupe Ka** :

- **8 collecteurs** quotidiens (**lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka**) : fetch → validation → **checksum** → insertion → **backup** → journal de run, avec **retry 3×** (backoff **30 s → 2 min → 10 min**).
- Un **scheduler** (**APScheduler**) qui lance le job quotidien à **02:00**, collecteurs **en parallèle** et indépendants, plus un **backfill automatique** des dates manquées (**7 derniers jours**).
- Une **API FastAPI** publique (données paginées, historiques, stats, rapports **PDF**).
- Le **KA Agent** — assistant IA central du Groupe Ka (**Claude Haiku 4.5**) en **SSE**, avec une boucle de **12 outils** branchés sur les API publiques des plateformes (logements, propriétés, véhicules, emplois, épicerie, produits, restos, sorties, créateurs, web QC, stats live, état des services) et **CORS** ouvert aux **13 domaines** de l'écosystème.
- Le **hub SSO KA ID** (login **ka_id** partagé) + l'échange de jetons pour l'**app iOS native KA**.
- Des **backups quotidiens** horodatés par service (`data/backups/YYYY-MM-DD/`, rétention **90 jours**).

## Endpoints

### Données des plateformes

- `GET /` — **statut** de la plateforme + version
- `GET /health` — nœud (**m3u96b**), état **DB**, dernière collecte par service
- `GET /api/v1/{service}` — données **paginées** (`?page=&limit=`, limit max **500**)
- `GET /api/v1/{service}/latest` — **dernière collecte**
- `GET /api/v1/{service}/date/{YYYY-MM-DD}` — données d'une **date précise**
- `GET /api/v1/{service}/stats` — enregistrements par jour, dernière réussite
- `GET /api/v1/runs` — **historique des collectes** (filtrable par service/statut)

`{service}` ∈ **`louka`**, **`immoka`**, **`foodka`**, **`autoka`**, **`fabrika`**, **`restoka`**, **`sortika`**, **`creaka`**.

### Stats & rapports

- `GET /stats` — **tableau de bord analytique** de la plateforme (page web)
- `GET /api/stats/dashboard` — stats live de la plateforme
- `GET /api/stats/report` — rapport **PDF** de la plateforme
- `GET /api/stats/ecosystem-report` — **rapport PDF consolidé** des **12 plateformes** du Groupe Ka (nombre de plateformes **dynamique** via `ecosystem.json`)

### KA Agent (IA)

- `POST /api/agent/chat` — chat en **SSE** avec le **KA Agent** (boucle d'outils, prompt par site, cache système)
- `GET /ka-agent.js` — **widget de chat** embarquable sur les sites du Groupe Ka

### Auth (KA ID / iOS)

- `GET /api/auth/ka/login` + `GET /api/auth/ka/callback` — **SSO KA ID** (hub groupe-ka.com)
- `GET /api/auth/me`, `POST /api/auth/logout` — session
- `POST /api/ios/auth/exchange` — échange du **ka_token** (vérification **HS256**, `aud=ka-ios`) contre un **profil hub signé** pour l'**app iOS KA**

Assets de partage servis à la racine : **`og.png`**, **`favicon.svg`**, **`apple-touch-icon.png`**, page **`/contact`**.

## Stack

- **Python 3** — **FastAPI** + **Uvicorn**
- **PostgreSQL** — **SQLAlchemy 2** + **Alembic** (migrations), `psycopg2`
- **APScheduler** — job quotidien + backfill
- **httpx** — collecteurs et outils de l'agent
- **fpdf2** — rapports PDF
- **PM2** + **ngrok** — exécution résiliente et exposition publique
- **pytest** — tests (`tests/`)

## Structure

```
/opt/api-ka
├── src/
│   ├── api/            # FastAPI : main, routes/ (health, services, runs, stats, agent, auth, iosauth), web/, PDF
│   ├── collectors/     # 8 collecteurs quotidiens (un par plateforme Ka)
│   ├── scheduler/      # daily_job.py (02:00) + backfill.py
│   ├── database/       # modèles + init DB
│   ├── utils/          # backup.py (dumps quotidiens, rétention 90 j)
│   └── config.py
├── scripts/            # deploy_m3u96b.sh, start_ngrok.sh…
├── systemd/            # unités historiques (le déploiement actuel utilise PM2)
├── tests/              # pytest
├── data/               # backups/YYYY-MM-DD/
├── logs/
├── alembic.ini · pyproject.toml · requirements.txt
└── docs/screenshot.png
```

## Démarrage local

```bash
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Initialiser la base
python -m src.database.db --init

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

# Collecte manuelle immédiate (tous les services)
python -m src.scheduler.daily_job --now

# Backfill d'une date manquée
python -m src.scheduler.backfill --date 2026-08-15

# Vérifier la santé
curl http://127.0.0.1:8000/health

# Tests
pytest tests/ -v
```

## Déploiement

- **Nœud** : **M3U96b** (Mac Studio, cluster MacLustr) — répertoire **`/opt/api-ka`**. Chaque service **vérifie le hostname** au démarrage et refuse de tourner ailleurs en production.
- **Port** : **8000** (API liée à `127.0.0.1`, exposée uniquement via le tunnel).
- **Domaine** : **https://www.api-ka.com** (tunnel **ngrok**).
- **PM2** (3 process, auto-restart) :
  - **`apika-api`** — l'API FastAPI/Uvicorn sur le port **8000**
  - **`apika-scheduler`** — le job quotidien **02:00** + backfill
  - **`apika-ngrok`** — le tunnel **www.api-ka.com**

```bash
pm2 ls | grep apika        # état des 3 process
pm2 restart apika-api      # après un changement de code
pm2 logs apika-scheduler   # suivre les collectes
```

## Développement remote-first (IMPORTANT)

La **source de vérité** est le **repo git sur le nœud M3U96b** (`/opt/api-ka`), **pas** une copie sur le laptop. Toute modification se fait **via SSH sur le nœud** : édition, test, `pm2 restart`, puis commit/push **depuis le nœud**.

- Remote **`origin`** = **spbgit** (git perso **git.spboucher.ai**, bare repos sur M3U96a) — **pas GitHub**.
- **Agent forwarding** actif : le `git push origin main` fonctionne pendant une session SSH depuis le laptop.

---

Un service **Groupe Ka** — créé par **Simon-Pierre Boucher** (contact@spboucher.ai)