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

20

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

21

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

22

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

23

+

24

+[![Événements actifs](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sorti-ka.com%2Fapi%2Fstats&query=%24.total_active&label=%C3%A9v%C3%A9nements%20actifs&color=d6336c&style=flat-square)](https://www.sorti-ka.com/api/stats)

25

+[![À venir](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sorti-ka.com%2Fapi%2Fstats&query=%24.upcoming&label=%C3%A0%20venir&color=d6336c&style=flat-square)](https://www.sorti-ka.com/api/stats)

26

+[![Gratuits à venir](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sorti-ka.com%2Fapi%2Fstats&query=%24.free_upcoming&label=gratuits%20%C3%A0%20venir&color=d6336c&style=flat-square)](https://www.sorti-ka.com/api/stats)

27

+[![Villes](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sorti-ka.com%2Fapi%2Fstats&query=%24.cities&label=villes&color=d6336c&style=flat-square)](https://www.sorti-ka.com/api/stats)

28

+[![Sources actives](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fwww.sorti-ka.com%2Fapi%2Fstats&query=%24.sources&label=sources%20actives&color=d6336c&style=flat-square)](https://www.sorti-ka.com/api/stats)

29

+![Régions](https://img.shields.io/badge/r%C3%A9gions-17%2F17-d6336c?style=flat-square)

30

+![Catégories](https://img.shields.io/badge/cat%C3%A9gories-14-d6336c?style=flat-square)

31

+

23

32

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

24

33

![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSR-009688?style=flat-square&logo=fastapi&logoColor=white)

25

34

![SQLite](https://img.shields.io/badge/SQLite-diff%20%2B%20historique-141814?style=flat-square&logo=sqlite)

35

+![pytest](https://img.shields.io/badge/pytest-69%20tests%20hors%20ligne-141814?style=flat-square&logo=pytest)

36

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

26

37

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

38

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

27

39

28

40

</div>

29

41

30

−**Sorti·Ka** est un **agrégateur indépendant de sorties et d'événements** couvrant les **17 régions administratives du Québec** : plus de **18 000 événements actifs** dans **~330 villes**, avec dates, lieux, gratuité (plus de 3 600 événements gratuits à venir), fiche par événement et **lien direct vers la billetterie ou la source originale**. Mise à jour **horaire**, automatiquement.

42

+**Sorti·Ka** est un **agrégateur indépendant de sorties et d'événements** couvrant les **17 régions administratives du Québec** : **18 186 événements actifs** (au 2026-08-24) dans **332 villes**, avec dates, lieux, gratuité (**3 614 événements gratuits à venir**), fiche par événement et **lien direct vers la billetterie ou la source originale**. Mise à jour **horaire**, automatiquement.

31

43

32

−Trouver quoi faire au Québec, c'est normalement ouvrir dix sites : les billetteries ne montrent que leurs propres spectacles, les calendriers municipaux que leur ville, les sites touristiques que leurs membres. Sorti·Ka retourne le problème : un **connecteur dédié par source** (une trentaine de connecteurs actifs, 44 sources au registre) visite chaque calendrier, normalise chaque événement vers un **schéma unique**, **déduplique les doublons inter-sources** et détecte les changements en continu. Sorti·Ka **n'est pas une billetterie** : c'est un **index fidèle** — aucun prix inventé, aucune date devinée, chaque fiche est attribuée à sa source. Pour qui ? Quiconque cherche quoi faire, ce soir ou cet été, n'importe où au Québec.

44

+Trouver quoi faire au Québec, c'est normalement ouvrir dix sites : les billetteries ne montrent que leurs propres spectacles, les calendriers municipaux que leur ville, les sites touristiques que leurs membres. Sorti·Ka retourne le problème : un **connecteur dédié par source** (**30 connecteurs actifs**, **44 sources au registre** — les 14 restantes sont documentées comme abandonnées ou mortes à la source, avec preuves) visite chaque calendrier, normalise chaque événement vers un **schéma unique**, **déduplique les doublons inter-sources** et détecte les changements en continu. Sorti·Ka **n'est pas une billetterie** : c'est un **index fidèle** — aucun prix inventé, aucune date devinée, chaque fiche est attribuée à sa source. Pour qui ? Quiconque cherche quoi faire, ce soir ou cet été, n'importe où au Québec.

45

+

46

+## Chiffres clés (live sur [/api/stats](https://www.sorti-ka.com/api/stats), vérifiés au 2026-08-24)

47

+

48

+| Métrique | Valeur |

49

+|---|---|

50

+| Événements actifs | **18 186** (dont 18 170 à venir) |

51

+| Gratuits à venir | **3 614** |

52

+| Villes couvertes | **332** — rattachées aux **17/17 régions administratives** |

53

+| Sources actives / au registre | **30 / 44** (13 abandonnées documentées + 1 morte à la source) |

54

+| Catégories canoniques | **14** |

55

+| En quarantaine qualité | 2 |

56

+| Top régions | Montréal 6 703 · Capitale-Nationale 3 185 · Montérégie 1 067 · Estrie 918 |

57

+| Top catégories | arts-scène 3 031 · musique 2 893 · sport 1 079 · plein-air 749 |

33

58

34

59

## Visite guidée

35

60

85

61

86

- **Recherche filtrée** — région, ville, catégorie (14 catégories canoniques), période, **gratuité**, texte libre, tri et pagination (`GET /api/events`).

62

87

- **Fiche par événement** — dates, heure locale, artistes, lieu, prix (avec `price_label` original), carte, événements similaires ; **SSR + JSON-LD Event** (`/evenement/{uid}`) pour le SEO, sitemaps et robots.txt.

63

−- **~30 connecteurs actifs** couvrant billetteries, données ouvertes, diffuseurs et portails régionaux (tableau ci-dessous).

88

+- **30 connecteurs actifs** (31 modules dans `sortika/connectors/`, dont Ticketmaster prêt) couvrant billetteries, données ouvertes, diffuseurs et portails régionaux (tableau ci-dessous).

64

89

- **Déduplication inter-sources** — empreinte titre + ville + date : un même concert publié par 3 sources = une seule carte, la fiche la plus riche gagne.

65

90

- **Répertoire des municipalités MAMH** — 1 250 villes + arrondissements + alias, homonymes résolus par population ; rattachement automatique aux 17 régions.

66

−- **Persistance robuste** — upsert par hash de contenu, délai de grâce de 2 syncs avant retrait, alerte de dérive quand une source casse, historique des synchronisations.

67

−- **Page /stats** — tableau de bord analytique + **rapports PDF Groupe-KA** (kit kacharts/kapdf v3, rapports personnalisés).

68

−- **Widget KA Agent** + **favoris « Mon univers Ka »** (KA ID, hub groupe-ka.com).

69

−- **Tests sur fixtures réelles, zéro réseau** (pytest).

91

+- **Persistance robuste** — upsert par hash de contenu, délai de grâce de 2 syncs avant retrait, alerte de dérive quand une source casse, quarantaine qualité, historique des synchronisations.

92

+- **SEO programmatique** — SSR de l'accueil (title avec stats live, JSON-LD WebSite/Organization), pages régions + catégories rendues en HTML, hreflang/BreadcrumbList sur les fiches.

93

+- **Page /stats** — tableau de bord analytique + **rapports PDF Groupe-KA** (kit kacharts/kapdf v3, rapports personnalisés par catalogue de blocs).

94

+- **Widget KA Agent** (v3, bulle déplaçable) + **favoris « Mon univers Ka »** (KA ID, hub groupe-ka.com).

95

+- **Tests sur fixtures réelles, zéro réseau** — **69 tests pytest** (connecteurs, normalisation, DB, auth, expansion).

70

96

71

97

## Connecteurs & sources

72

98

99

+30 connecteurs actifs / 44 sources au registre (`data/sources.json` : 30 actives, 13 abandonnées avec preuves, 1 morte à la source) — 45 fiches de conformité générées dans `docs/connecteurs/`.

100

+

73

101

| Famille | Sources | Accès |

74

102

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

75

−| **Billetteries** | Le point de vente, evenko (Algolia), Ticketpro, Ticket Accès, Tuxedo Billet, Ovation, Eventbrite | API/JSON publics des billetteries |

76

−| **Données ouvertes officielles** | SIT Québec / Tourinsoft, Ville de Montréal (CKAN), Laval, Sherbrooke, Brossard, Longueuil | portails de données ouvertes |

77

−| **Diffuseurs & salles** | La Vitrine, Place des Arts, salles via JSON-LD | pages publiques structurées |

103

+| **Billetteries** | Le point de vente, evenko (Algolia), Ticketpro (API multi-tenants : St-Denis, Fun Nation, ExpoCité…), Ticket Accès, Tuxedo Billet (acteur Apify ka-tuxedo), Réseau Ovation, Eventbrite | API/JSON publics des billetteries |

104

+| **Données ouvertes officielles** | SIT Québec / Tourinsoft (licence CC 4.0), Ville de Montréal (CKAN, CC BY 4.0), Laval, Sherbrooke, Brossard, Longueuil | portails de données ouvertes |

105

+| **Diffuseurs & salles** | La Vitrine, Place des Arts, salles via JSON-LD (dont Odyscène) | pages publiques structurées |

78

106

| **Portails régionaux** | Montérégie, Outaouais, Lanaudière, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Gaspésie, Centre-du-Québec, Saguenay… | calendriers régionaux publics |

79

107

| **Autres** | Atuvu.ca (via Scrapfly), Bandsintown, LHJMQ, Québec animée | HTML/JSON publics |

80

108

| **Prêt (clé requise)** | Ticketmaster (`TICKETMASTER_API_KEY`) | API officielle |

109

+| **Sondées et écartées (avec preuves)** | Zeffy, Showpass, Weezevent, Accès culture… (13 abandonnées + 1 morte à la source) | documentées au registre |

81

110

82

−**Cadence de resync : horaire** — le watcher PM2 `sorti-ka-sync` (`run.py watch`) visite les sources en continu ; chaque événement passe par la normalisation (`schema.py` + `normalize.py`), l'upsert par hash, le délai de grâce (2 syncs) et l'alerte de dérive. Une fiche de conformité par connecteur est générée dans `docs/connecteurs/` (voir `docs/CONFORMITE.md`).

111

+**Cadence de resync : horaire** — le watcher PM2 `sorti-ka-sync` (`run.py watch --interval 3600`) visite les sources en continu ; chaque événement passe par la normalisation (`schema.py` + `normalize.py`), l'upsert par hash, le délai de grâce (2 syncs) et l'alerte de dérive. Les connecteurs fragiles passent par une **chaîne de fetch anti-bot résiliente** (Oxylabs → Scrapfly → Bright Data).

83

112

84

113

## Architecture

85

114

93

122

```

94

123

95

124

- **Backend** : Python 3.14 + **FastAPI** (uvicorn) — API JSON, SSR SEO des fiches, stats, PDF (fpdf2), SSO/favoris KA ID (`auth.py`, `hubfav.py`).

96

−- **Base de données** : **SQLite** — événements, diff par hash, délai de grâce, historique de syncs, géocodage (`geocode.py`, `venues.py`).

125

+- **Base de données** : **SQLite** — événements, diff par hash, délai de grâce, quarantaine, historique de syncs, géocodage (`geocode.py`, `venues.py` — annuaire de salles appris/OSM/Nominatim).

97

126

- **Frontend** : SPA **sans build** (HTML/JS, routeur History API), design system Groupe KA « éditorial sharp » (ka-ui), widget KA Agent.

98

−- **Anti-bot** : **Scrapfly** pour Atuvu (clé `SCRAPFLY_API_KEY` dans `.env`).

127

+- **Anti-bot** : chaîne résiliente Oxylabs → Scrapfly → Bright Data (Atuvu via `SCRAPFLY_API_KEY`).

99

128

100

129

## API — endpoints principaux

101

130

102

−| Endpoint | Rôle |

103

−|---|---|

104

−| `GET /api/events` | recherche filtrée : région, ville, catégorie, période, gratuité, texte, tri, pagination |

105

−| `GET /api/events/{uid}` | fiche complète d'un événement (+ SSR SEO sur `/evenement/{uid}`) |

106

−| `GET /api/regions` · `GET /api/categories` | référentiels (17 régions, 14 catégories canoniques) |

107

−| `GET /api/sources` | registre des sources et état des connecteurs |

108

−| `GET /api/stats` · `/api/stats/catalog` · `/api/stats/dashboard` · `/api/stats/report(/custom)` | tableau de bord + rapports PDF Groupe-KA |

109

−| `GET /api/favorites` · `POST /api/favorites/toggle` | favoris « Mon univers Ka » (KA ID) |

110

−| `GET /api/health` · `GET /healthz` | santé du service |

131

+| Endpoint | Méthode | Rôle |

132

+|---|---|---|

133

+| `/api/events` | GET | recherche filtrée : région, ville, catégorie, période, gratuité, texte, tri, pagination |

134

+| `/api/events/{uid}` | GET | fiche complète d'un événement (+ SSR SEO sur `/evenement/{uid}`) |

135

+| `/api/regions` · `/api/categories` | GET | référentiels (17 régions, 14 catégories canoniques) |

136

+| `/api/sources` | GET | registre des sources, état et santé des connecteurs (44 entrées) |

137

+| `/api/stats` | GET | agrégats publics (source des pastilles dynamiques ci-dessus) |

138

+| `/api/stats/catalog` · `/api/stats/dashboard` | GET | catalogue de blocs + tableau de bord (kit stats v3 Groupe KA) |

139

+| `/api/stats/report` · `/api/stats/report/custom` | GET/POST | rapports PDF Groupe-KA (modèles + personnalisés) |

140

+| `/api/favorites` · `/api/favorites/toggle` | GET/POST | favoris « Mon univers Ka » (KA ID) |

141

+| `/api/health` · `/healthz` | GET | santé du service |

142

+

143

+## Données & conformité

144

+

145

+- **Provenance** : uniquement des sources publiques — API de billetteries, données ouvertes officielles (SIT Québec CC 4.0, Montréal CC BY 4.0…), pages publiques structurées (JSON-LD). Chaque fiche cite et **lie sa source originale**.

146

+- **Cadence** : resync **horaire** (watcher `run.py watch --interval 3600`) ; retrait doux après 2 syncs d'absence, alerte de dérive par source.

147

+- **Index fidèle, pas une billetterie** : aucun prix inventé, aucune date devinée ; `price_label` original conservé ; la billetterie encaisse, Sorti·Ka référence.

148

+- **Registre auditable** : `data/sources.json` — 44 sources dont 30 actives ; chaque abandon est documenté avec preuves (Zeffy, Showpass, Weezevent, Accès culture, laval…).

149

+- **Fiches de conformité** : `docs/CONFORMITE.md` + 45 fiches générées dans `docs/connecteurs/` (base d'accès légale, extraction, cadence par source).

111

150

112

151

## Structure du repo

113

152

114

153

| Répertoire / fichier | Rôle |

115

154

|---|---|

116

155

| `sortika/` | paquet Python : connecteurs, schéma `Event`, normalisation, régions MAMH, DB, web/SSR, stats, PDF, auth KA ID |

117

−| `sortika/connectors/` | un module par source (auto-découverts), base commune + `_resilient.py` |

156

+| `sortika/connectors/` | un module par source (auto-découverts), base commune + `_resilient.py` (chaîne anti-bot) — 31 modules |

118

157

| `frontend/` | SPA sans build (`index.html`, `ka-agent.js`, assets) + guide `/doc` (page, images, PDF) |

119

−| `data/` | base SQLite + `villes_regions.json` (répertoire MAMH) — non versionnés pour la BD |

120

−| `tests/` | pytest sur fixtures réelles, zéro réseau |

158

+| `data/` | base SQLite + `villes_regions.json` (répertoire MAMH) + `sources.json` (registre) — la BD n'est pas versionnée |

159

+| `tests/` | pytest sur fixtures réelles, zéro réseau — 69 tests (`test_connectors`, `test_normalize`, `test_db`, `test_auth`, `test_expansion`, `test_phase4`) |

121

160

| `scripts/` | utilitaires (génération de docs, maintenance) |

122

−| `docs/` | `CONFORMITE.md`, fiches `connecteurs/`, captures d'écran |

123

−| `apify/` | acteurs/outils d'appoint pour l'ingestion |

161

+| `docs/` | `CONFORMITE.md`, fiches `connecteurs/` (45), captures d'écran |

162

+| `apify/` | acteurs/outils d'appoint pour l'ingestion (ka-tuxedo…) |

124

163

| `run.py` | point d'entrée CLI : `sync` · `web` · `watch` |

125

164

| `requirements.txt` | fastapi, uvicorn, requests, fpdf2, pytest |

126

165

166

+## Démarrage rapide

167

+

168

+```bash

169

+ssh M3U96a && cd ~/apps/sorti-ka

170

+python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # au besoin

171

+.venv/bin/python -m pytest tests/ -q # 69 tests — fixtures réelles, zéro réseau

172

+.venv/bin/python run.py sync # ingestion des sources

173

+.venv/bin/python run.py web --port 8120 # API + frontend + SSR

174

+.venv/bin/python run.py watch --interval 3600 # watcher horaire (en prod : PM2)

175

+```

176

+

127

177

## Développement (remote-first)

128

178

129

179

⚠️ **La source de vérité est le repo git sur le nœud M3U96a** (`~/apps/sorti-ka`) — on n'édite **jamais** les copies laptop. Toute modification se fait sur le nœud via SSH : édition, tests, redémarrage PM2, puis commit + push **depuis le nœud**.

131

181

- Remote **`origin` = spbgit** (git perso, https://git.spboucher.ai) — sur M3U96a, l'origin est le chemin local **`/Users/simon-pierreboucher/srv/git/sorti-ka.git`** (bare repo).

132

182

133

183

```bash

134

−ssh M3U96a

135

184

cd ~/apps/sorti-ka

136

−python3 -m venv .venv && .venv/bin/pip install -r requirements.txt # au besoin

137

−.venv/bin/python -m pytest tests/ -q # tests (fixtures réelles, zéro réseau)

138

−.venv/bin/python run.py sync # ingestion des sources

139

−.venv/bin/python run.py web --port 8120 # API + frontend + SSR

185

+.venv/bin/python -m pytest tests/ -q # avant de pousser

140

186

pm2 restart sorti-ka-web # après changement

141

187

git add <fichiers> && git commit -m "…" && git push origin main

142

188

```

143

189

144

−### Configuration notable (sans secrets)

190

+## Variables d'environnement

191

+

192

+Noms seulement — **aucun secret n'est versionné** (gabarit : `.env.example`).

145

193

146

194

| Variable | Rôle |

147

195

|---|---|

148

−| `SCRAPFLY_API_KEY` | anti-bot pour le connecteur Atuvu.ca |

196

+| `SCRAPFLY_API_KEY` | anti-bot pour le connecteur Atuvu.ca (et repli de la chaîne résiliente) |

149

197

| `TICKETMASTER_API_KEY` | active le connecteur Ticketmaster (prêt, en attente de clé) |

150

−

151

−Gabarit : `.env.example` — aucun secret n'est versionné.

198

+| `SESSION_SECRET` | signature des sessions |

199

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

200

+| `SORTIKA_BASE_URL` | URL canonique du site (SEO, liens absolus) |

152

201

153

202

## Déploiement

154

203

158

207

| **Port** | **8120** |

159

208

| **Domaine** | [www.sorti-ka.com](https://www.sorti-ka.com) via tunnel ngrok |

160

209

161

−| Processus PM2 | Rôle |

162

−|---|---|

163

−| `sorti-ka-web` | uvicorn sur le port **8120** — API + frontend + SSR SEO |

164

−| `sorti-ka-sync` | watcher **horaire** (`run.py watch`) — ingestion continue des sources |

165

−| `sorti-ka-ngrok` | tunnel ngrok vers www.sorti-ka.com |

210

+| Processus PM2 | Commande réelle | Rôle |

211

+|---|---|---|

212

+| `sorti-ka-web` | `run.py web --host 0.0.0.0 --port 8120` | API + frontend + SSR SEO |

213

+| `sorti-ka-sync` | `run.py watch --interval 3600` | watcher **horaire** — ingestion continue des sources |

214

+| `sorti-ka-ngrok` | `ngrok http --url=www.sorti-ka.com 8120` | tunnel vers www.sorti-ka.com |

166

215

167

216

## Documentation

168

217

169

218

- **Guide utilisateur en ligne** : [www.sorti-ka.com/doc/](https://www.sorti-ka.com/doc/) — à quoi sert le site, utilisation en 4 étapes, provenance des données, FAQ.

170

219

- **Guide PDF téléchargeable** : [sorti-ka-documentation.pdf](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf).

171

−- **Conformité & connecteurs** : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/`.

220

+- **Conformité & connecteurs** : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/` (45 fiches).

221

+

222

+## Historique

223

+

224

+| Date | Jalon |

225

+|---|---|

226

+| 2026-08-17 | Sorti·Ka v1 — agrégateur de sorties & événements du Québec + connexion KA ID |

227

+| 2026-08-18 | vagues 2-3 d'enrichissement : heure précise, artistes, géocodage des salles, Ticketmaster/Eventbrite/Longueuil/Cantons-de-l'Est, docs standardisées |

228

+| 2026-08-19 | phases 2-3 : archivage des passés, statut/end_time, quarantaine, séances, villes MAMH, annuaire de salles (venues), registre 34 sources + conformité |

229

+| 2026-08-21/22 | phases 4-5 : 7 connecteurs régions + billetteries QC (Ticket Accès, Ovation, Tuxedo, Ticketpro), chaîne anti-bot résiliente, SSR SEO de l'accueil, 4 billetteries écartées avec preuves |

230

+| 2026-08-23 | SEO programmatique (régions + catégories en HTML), stats v3 (rapports PDF personnalisés), favoris « Mon univers Ka » |

231

+| 2026-08-24 | page `/doc` (guide + captures + PDF), README v3 |

172

232

173

233

## Écosystème Groupe KA

174

234

175

235