SPB Git forge

spb/sorti-ka

Public

Toutes les sorties et tous les événements du Québec, un seul endroit — 7 connecteurs, fiches SSR, design Groupe KA.

58commits 1branches 0releases
13.7 MBsize
maindefault branch
17 days agolast push
HTML 82.9% Python 15.2% TypeScript 0.9% JavaScript 0.7%
26.9 KB · 366 lines markdown
Rendered Raw Blame History
1<!--2  Author: Simon-Pierre Boucher <contact@spboucher.ai>3  File:   README.md4  Desc:   Documentation du dépôt Sorti-Ka — agrégateur de sorties & événements5-->67<p align="center">8  <a href="https://www.sorti-ka.com"><img src="https://www.sorti-ka.com/og.png" width="760" alt="Sorti·Ka — Toutes les sorties, dans les 17 régions"></a>9</p>1011<h1 align="center">Sorti·Ka</h1>1213<p align="center"><b>Toutes les sorties, dans les 17 régions</b></p>1415<div align="center">1617[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.sorti-ka.com&style=flat-square&label=www.sorti-ka.com&up_color=d6336c)](https://www.sorti-ka.com)18[![Documentation](https://img.shields.io/badge/📖_documentation-%2Fdoc-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/)19[![PDF](https://img.shields.io/badge/guide-PDF-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf)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)2324[![É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)3132![Python](https://img.shields.io/badge/Python-3.14-3776ab?style=flat-square&logo=python&logoColor=white)33![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSR-009688?style=flat-square&logo=fastapi&logoColor=white)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-131%20tests%20hors%20ligne-141814?style=flat-square&logo=pytest)36![ngrok](https://img.shields.io/badge/tunnel-ngrok-140a3c?style=flat-square&logo=ngrok)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)3940</div>4142**Sorti·Ka** est un **agrégateur indépendant de sorties et d'événements** couvrant les **17 régions administratives du Québec** : **26 559 événements actifs** (au 2026-08-28) dans **517 villes**, avec dates, lieux, gratuité (**5 050 événements gratuits à venir**), fiche par événement et **lien direct vers la billetterie ou la source originale**. Mise à jour **horaire**, automatiquement.4344Trouver 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** (**61 sources actives**, **68 au registre** — les 7 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.4546## Chiffres clés (live sur [/api/stats](https://www.sorti-ka.com/api/stats), vérifiés au 2026-08-28)4748| Métrique | Valeur |49|---|---|50| Événements actifs | **26 559** (dont 26 488 à venir) |51| Gratuits à venir | **5 050** |52| Villes couvertes | **517** — rattachées aux **17/17 régions administratives** |53| Sources actives / au registre | **61 / 68** (6 abandonnées documentées + 1 morte à la source) |54| Connecteurs (modules) | **62** dans `sortika/connectors/` |55| Catégories canoniques | **14** |56| En quarantaine qualité | 8 |57| Top régions | Montréal 8 919 · Capitale-Nationale 4 263 · Estrie 2 141 · Centre-du-Québec 1 619 |58| Top catégories | arts-scène 4 225 · musique 4 070 · sport 1 439 · famille 932 |5960## Visite guidée — le site en 10 captures6162*Captures du 2026-08-28 — frontend v2 « guide culturel » en production sur [www.sorti-ka.com](https://www.sorti-ka.com).*6364<table>65  <tr>66    <td align="center" width="50%">67      <img src="docs/screenshots/01-accueil.jpg" alt="Accueil de Sorti·Ka" width="440"><br>68      <sub><b>1 · Accueil</b> — <a href="https://www.sorti-ka.com/">sorti-ka.com</a><br>69      Hero éditorial avec mosaïque d'images réelles et compteurs live en phrase, recherche centrale, accès rapides (Ce soir · Fin de semaine · Gratuit · Près de moi), timeline de jours et sections « À la une » dédoublonnées.</sub>70    </td>71    <td align="center" width="50%">72      <img src="docs/screenshots/02-regions.jpg" alt="Répertoire des 17 régions" width="440"><br>73      <sub><b>2 · Répertoire des régions</b> — <a href="https://www.sorti-ka.com/regions">/regions</a><br>74      Les 17 régions administratives du Québec, chacune avec son compteur d'événements actifs — porte d'entrée géographique de tout le catalogue.</sub>75    </td>76  </tr>77  <tr>78    <td align="center">79      <img src="docs/screenshots/03-categories.jpg" alt="Répertoire des catégories" width="440"><br>80      <sub><b>3 · Répertoire des catégories</b> — <a href="https://www.sorti-ka.com/categories">/categories</a><br>81      Les 14 catégories canoniques (musique, arts-scène, festival, sport, famille, plein-air, exposition-musée…) vers lesquelles chaque source est normalisée.</sub>82    </td>83    <td align="center">84      <img src="docs/screenshots/04-stats.jpg" alt="Tableau de bord statistiques" width="440"><br>85      <sub><b>4 · Statistiques</b> — <a href="https://www.sorti-ka.com/stats">/stats</a><br>86      Tableau de bord analytique du catalogue (kit stats v3 Groupe KA) : répartitions par région, catégorie, gratuité, sources — et rapports PDF téléchargeables.</sub>87    </td>88  </tr>89  <tr>90    <td align="center">91      <img src="docs/screenshots/05-contact.jpg" alt="Page contact" width="440"><br>92      <sub><b>5 · Contact</b> — <a href="https://www.sorti-ka.com/contact">/contact</a><br>93      Page contact standardisée Groupe KA : coordonnées du fondateur, mission du site et liens vers l'écosystème.</sub>94    </td>95    <td align="center">96      <img src="docs/screenshots/06-region-montreal.jpg" alt="Page région Montréal" width="440"><br>97      <sub><b>6 · Page région — Montréal</b> — <a href="https://www.sorti-ka.com/region/montreal">/region/montreal</a><br>98      Résultats filtrés par région (8 919 événements à Montréal) : cartes image-first, bascule Liste|Carte (Leaflet à la demande), pilules de filtres actifs, page SEO rendue en HTML.</sub>99    </td>100  </tr>101  <tr>102    <td align="center">103      <img src="docs/screenshots/07-categorie-arts-scene.jpg" alt="Page catégorie arts et scène" width="440"><br>104      <sub><b>7 · Page catégorie — Arts & scène</b> — <a href="https://www.sorti-ka.com/categorie/arts-scene">/categorie/arts-scene</a><br>105      Vue par catégorie (4 225 événements arts-scène) combinable avec les filtres région, ville, période et gratuité — indexable par les moteurs.</sub>106    </td>107    <td align="center">108      <img src="docs/screenshots/08-evenement-abitibi-16522.jpg" alt="Fiche événement" width="440"><br>109      <sub><b>8 · Fiche événement</b> — <a href="https://www.sorti-ka.com/evenement/abitibi:16522">/evenement/{uid}</a><br>110      La fiche complète (ici un événement d'Abitibi-Témiscamingue) : dates et heure locale, lieu géocodé sur carte, prix original (`price_label`), événements similaires, CTA sticky vers la billetterie ou la source — SSR + JSON-LD Event.</sub>111    </td>112  </tr>113  <tr>114    <td align="center">115      <img src="docs/screenshots/09-favoris.jpg" alt="Favoris Mon univers Ka" width="440"><br>116      <sub><b>9 · Favoris « Mon univers Ka »</b> — <a href="https://www.sorti-ka.com/favoris">/favoris</a><br>117      Les événements sauvegardés via KA ID (SSO du hub groupe-ka.com) — le même compte et les mêmes favoris sur les 12 sites du Groupe KA.</sub>118    </td>119    <td align="center">120      <img src="docs/screenshots/10-docs.jpg" alt="Documentation en ligne" width="440"><br>121      <sub><b>10 · Documentation</b> — <a href="https://www.sorti-ka.com/docs">/docs</a><br>122      Le guide utilisateur en ligne : à quoi sert Sorti·Ka, utilisation pas à pas, provenance des données, FAQ — aussi disponible en PDF téléchargeable.</sub>123    </td>124  </tr>125</table>126127### Galerie mobile & desktop (frontend v2, 2026-08-25)128129<details>130<summary><b>Mobile (390×844)</b> — 6 captures WebP</summary>131132<table>133  <tr>134    <td align="center"><img src="docs/screenshots/mobile/home.webp" width="240" alt="Accueil mobile"><br><sub><b>Accueil — hero mosaïque, accès rapides, timeline de jours</b></sub></td>135    <td align="center"><img src="docs/screenshots/mobile/region.webp" width="240" alt="Région mobile"><br><sub><b>Résultats par région — cartes image-first</b></sub></td>136    <td align="center"><img src="docs/screenshots/mobile/evenement.webp" width="240" alt="Fiche événement mobile"><br><sub><b>Fiche événement — CTA billetterie sticky</b></sub></td>137  </tr>138  <tr>139    <td align="center"><img src="docs/screenshots/mobile/categorie.webp" width="240" alt="Catégorie mobile"><br><sub><b>Catégorie — musique</b></sub></td>140    <td align="center"><img src="docs/screenshots/mobile/stats.webp" width="240" alt="Stats mobile"><br><sub><b>Tableau de bord /stats</b></sub></td>141    <td align="center"><img src="docs/screenshots/mobile/menu-mobile.webp" width="240" alt="Menu mobile"><br><sub><b>Nav v2 — panneau plein écran</b></sub></td>142  </tr>143</table>144145</details>146147<details>148<summary><b>Desktop (1440×900)</b> — 6 captures WebP</summary>149150<table>151  <tr>152    <td align="center"><img src="docs/screenshots/desktop/home.webp" width="420" alt="Accueil desktop"><br><sub><b>Accueil — sections « À la une », carrousels, ticker</b></sub></td>153    <td align="center"><img src="docs/screenshots/desktop/evenement.webp" width="420" alt="Fiche événement"><br><sub><b>Fiche événement — date, lieu, prix, lien billetterie</b></sub></td>154  </tr>155  <tr>156    <td align="center"><img src="docs/screenshots/desktop/region.webp" width="420" alt="Région"><br><sub><b>Page région — Montréal</b></sub></td>157    <td align="center"><img src="docs/screenshots/desktop/categorie.webp" width="420" alt="Catégorie"><br><sub><b>Page catégorie — pages SEO indexables</b></sub></td>158  </tr>159  <tr>160    <td align="center"><img src="docs/screenshots/desktop/regions.webp" width="420" alt="Répertoire des régions"><br><sub><b>Répertoire des 17 régions</b></sub></td>161    <td align="center"><img src="docs/screenshots/desktop/stats.webp" width="420" alt="Stats"><br><sub><b>Statistiques — 22 900+ événements, 61 sources</b></sub></td>162  </tr>163</table>164165</details>166167> 🗄️ Les captures d'époque (v1) sont conservées dans [`docs/archive/`](docs/archive/).168169### Guide pas à pas (« Utiliser le site en 4 étapes », depuis [/doc](https://www.sorti-ka.com/doc/))170171<table>172  <tr>173    <td align="center"><img src="frontend/doc/img/etape1.png" width="420" alt="Étape 1 — accueil de Sorti·Ka"><br><sub><b>Étape 1 — Arriver sur l'accueil</b></sub></td>174    <td align="center"><img src="frontend/doc/img/etape2.png" width="420" alt="Étape 2 — recherche filtrée d'événements"><br><sub><b>Étape 2 — Filtrer la liste</b></sub></td>175  </tr>176  <tr>177    <td align="center"><img src="frontend/doc/img/etape3.png" width="420" alt="Étape 3 — fiche d'événement avec lien billetterie"><br><sub><b>Étape 3 — Ouvrir la fiche d'un événement</b></sub></td>178    <td align="center"><img src="frontend/doc/img/etape4.png" width="420" alt="Étape 4 — tableau de bord statistiques"><br><sub><b>Étape 4 — Consulter les statistiques</b></sub></td>179  </tr>180</table>181182## Fonctionnalités183184- **Recherche filtrée** — région, ville, catégorie (14 catégories canoniques), période, **gratuité**, texte libre, **proximité (`near=lat,lng` + tri par distance)**, tri et pagination (`GET /api/events`).185- **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.186- **61 sources actives via 62 connecteurs** (`sortika/connectors/`) couvrant billetteries, données ouvertes, diffuseurs, ATR (associations touristiques régionales), calendriers municipaux et portails régionaux (tableau ci-dessous).187- **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.188- **Répertoire des municipalités MAMH** — 1 250 villes + arrondissements + alias, homonymes résolus par population ; rattachement automatique aux 17 régions.189- **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.190- **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.191- **Page /stats** — tableau de bord analytique + **rapports PDF Groupe-KA** (kit kacharts/kapdf v3, rapports personnalisés par catalogue de blocs).192- **Personnalisation KA ID v2** (`sortika/kaid.py` + `/api/kaid`) — journal serveur (recherches, fiches vues, favoris), recommandations « Recommandé pour vous » en mode annotation (ordre chronologique préservé), filtrage collaboratif (modèle ALS partagé Groupe KA), pilules « Sauvegarder cette recherche » / « Pas pour moi ».193- **Frontend v2 « guide culturel »** — mobile-first : bascule Liste|Carte (Leaflet à la demande), bottom sheet de filtres, CTA sticky, **KA Tabbar v1** (barre de navigation mobile commune Groupe KA : Découvrir · Recherche · Carte · Favoris).194- **Widget KA Agent** (v4, cartes d'événements cliquables + choix en boutons) + **favoris « Mon univers Ka »** (KA ID, hub groupe-ka.com).195- **Tests sur fixtures réelles, zéro réseau** — **131 tests pytest** (connecteurs, normalisation, DB, auth, expansion, phases 4+).196197## Connecteurs & sources198199**61 sources actives / 68 au registre** (`data/sources.json` : 61 actives, 6 abandonnées avec preuves, 1 morte à la source) — **62 modules connecteurs** dans `sortika/connectors/` et **70 fiches de conformité** générées dans `docs/connecteurs/`.200201| Famille | Sources (exemples) | Accès |202|---|---|---|203| **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 |204| **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 |205| **Diffuseurs & salles** | La Vitrine, Place des Arts, salles via JSON-LD (dont Odyscène — +13 salles à la vague du 2026-08-25) | pages publiques structurées |206| **ATR & portails régionaux** | Abitibi-Témiscamingue, Charlevoix, Côte-Nord, Gaspésie, Îles-de-la-Madeleine, Mauricie, Laurentides, Lanaudière, Montérégie, Outaouais, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Centre-du-Québec, Saguenay, Eeyou Istchee… | calendriers régionaux publics |207| **Calendriers municipaux** | Gatineau, Lévis, Trois-Rivières, Sherbrooke, Drummondville, Granby, Magog, Joliette, Terrebonne, Saint-Jérôme, Saint-Hyacinthe, Sorel-Tracy, Shawinigan, Rimouski, Rouyn-Noranda, Victoriaville, Signé Laval… | sites municipaux publics |208| **Agrégateurs & autres** | Atuvu.ca (via Scrapfly), Quoi faire, MTL.org, Québec Cité, BAnQ, Bandsintown, LHJMQ, Québec animée, Événements & Attractions | HTML/JSON publics |209| **Prêt (clé requise)** | Ticketmaster (`TICKETMASTER_API_KEY`) | API officielle |210| **Sondées et écartées (avec preuves)** | Zeffy, Showpass, Weezevent… (6 abandonnées + 1 morte à la source, documentées au registre) | documentées au registre |211212**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).213214## Architecture215216```217connecteurs (1 module / source)    normalisation (Event)       SQLite (diff + grâce)218sortika/connectors/*.py        →   schema.py + normalize.py →  db.py219      ▲ auto-découverts             + regions.py (MAMH)            │220      │                                                            ▼221watcher horaire (PM2)           frontend SPA + fiches   ←   API FastAPI + SSR SEO222run.py watch                    frontend/index.html          web.py + seo.py223```224225- **Backend** : Python 3.14 + **FastAPI** (uvicorn) — API JSON, SSR SEO des fiches, stats, PDF (fpdf2), SSO/favoris KA ID (`auth.py`, `hubfav.py`), personnalisation (`kaid.py`).226- **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).227- **Frontend** : SPA **sans build** (HTML/JS, routeur History API), design system Groupe KA « éditorial sharp » (ka-ui), KA Tabbar mobile, widget KA Agent.228- **Anti-bot** : chaîne résiliente Oxylabs → Scrapfly → Bright Data (Atuvu via `SCRAPFLY_API_KEY`).229230## API — endpoints principaux231232| Endpoint | Méthode | Rôle |233|---|---|---|234| `/api/events` | GET | recherche filtrée : région, ville, catégorie, période, gratuité, texte, `near=lat,lng`, tri, pagination |235| `/api/events/{uid}` | GET | fiche complète d'un événement (+ SSR SEO sur `/evenement/{uid}`) |236| `/api/regions` · `/api/categories` | GET | référentiels (17 régions, 14 catégories canoniques) |237| `/api/sources` | GET | registre des sources, état et santé des connecteurs (68 entrées) |238| `/api/stats` | GET | agrégats publics (source des pastilles dynamiques ci-dessus) |239| `/api/stats/catalog` · `/api/stats/dashboard` | GET | catalogue de blocs + tableau de bord (kit stats v3 Groupe KA) |240| `/api/stats/report` · `/api/stats/report/custom` | GET/POST | rapports PDF Groupe-KA (modèles + personnalisés) |241| `/api/favorites` · `/api/favorites/toggle` | GET/POST | favoris « Mon univers Ka » (KA ID) |242| `/api/kaid/*` | GET/POST | personnalisation KA ID v2 — journal d'événements, recommandations, préférences |243| `/api/health` · `/healthz` | GET | santé du service |244245## Données & conformité246247- **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**.248- **Cadence** : resync **horaire** (watcher `run.py watch --interval 3600`) ; retrait doux après 2 syncs d'absence, alerte de dérive par source.249- **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.250- **Registre auditable** : `data/sources.json` — 68 sources dont 61 actives ; chaque abandon est documenté avec preuves (Zeffy, Showpass, Weezevent…).251- **Fiches de conformité** : `docs/CONFORMITE.md` + 70 fiches générées dans `docs/connecteurs/` (base d'accès légale, extraction, cadence par source).252253## Structure du repo254255| Répertoire / fichier | Rôle |256|---|---|257| `sortika/` | paquet Python : connecteurs, schéma `Event`, normalisation, régions MAMH, DB, web/SSR, stats, PDF, auth KA ID, personnalisation `kaid.py` |258| `sortika/connectors/` | un module par source (auto-découverts), base commune + `_resilient.py` (chaîne anti-bot) — 62 modules |259| `frontend/` | SPA sans build (`index.html`, `ka-agent.js`, `ka-id.js`, assets) + guide `/doc` (page, images, PDF) |260| `data/` | base SQLite + `villes_regions.json` (répertoire MAMH) + `sources.json` (registre) — la BD n'est pas versionnée |261| `tests/` | pytest sur fixtures réelles, zéro réseau — 131 tests (`test_connectors`, `test_normalize`, `test_db`, `test_auth`, `test_expansion`, `test_phase4`…) |262| `scripts/` | utilitaires (génération de docs, maintenance) |263| `docs/` | `CONFORMITE.md`, fiches `connecteurs/` (70), captures d'écran (`screenshots/` : visite guidée + galeries mobile/desktop, archives v1 dans `archive/`) |264| `apify/` | acteurs/outils d'appoint pour l'ingestion (ka-tuxedo…) |265| `run.py` | point d'entrée CLI : `sync` · `web` · `watch` |266| `requirements.txt` | fastapi, uvicorn, requests, fpdf2, pytest |267268## Démarrage rapide269270```bash271ssh M3U96a && cd ~/apps/sorti-ka272python3 -m venv .venv && .venv/bin/pip install -r requirements.txt   # au besoin273.venv/bin/python -m pytest tests/ -q          # 131 tests — fixtures réelles, zéro réseau274.venv/bin/python run.py sync                  # ingestion des sources275.venv/bin/python run.py web --port 8120       # API + frontend + SSR276.venv/bin/python run.py watch --interval 3600 # watcher horaire (en prod : PM2)277```278279## Développement (remote-first)280281⚠️ **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**.282283- 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).284285```bash286cd ~/apps/sorti-ka287.venv/bin/python -m pytest tests/ -q          # avant de pousser288pm2 restart sorti-ka-web                      # après changement289git add <fichiers> && git commit -m "…" && git push origin main290```291292## Variables d'environnement293294Noms seulement — **aucun secret n'est versionné** (gabarit : `.env.example`).295296| Variable | Rôle |297|---|---|298| `SCRAPFLY_API_KEY` | anti-bot pour le connecteur Atuvu.ca (et repli de la chaîne résiliente) |299| `TICKETMASTER_API_KEY` | active le connecteur Ticketmaster (prêt, en attente de clé) |300| `SESSION_SECRET` | signature des sessions |301| `KA_SSO_SECRET` · `KA_HUB_URL` | SSO KA ID (hub groupe-ka.com) |302| `SORTIKA_BASE_URL` | URL canonique du site (SEO, liens absolus) |303304## Déploiement305306| | |307|---|---|308| **Nœud** | **M3U96a** (cluster MacLustr) — `~/apps/sorti-ka` |309| **Port** | **8120** |310| **Domaine** | [www.sorti-ka.com](https://www.sorti-ka.com) via tunnel ngrok |311312| Processus PM2 | Commande réelle | Rôle |313|---|---|---|314| `sorti-ka-web` | `run.py web --host 0.0.0.0 --port 8120` | API + frontend + SSR SEO |315| `sorti-ka-sync` | `run.py watch --interval 3600` | watcher **horaire** — ingestion continue des sources |316| `sorti-ka-ngrok` | `ngrok http --url=www.sorti-ka.com 8120` | tunnel vers www.sorti-ka.com |317318## Documentation319320- **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.321- **Guide PDF téléchargeable** : [sorti-ka-documentation.pdf](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf).322- **Conformité & connecteurs** : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/` (70 fiches).323324## Historique325326| Date | Jalon |327|---|---|328| 2026-08-17 | Sorti·Ka v1 — agrégateur de sorties & événements du Québec + connexion KA ID |329| 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 |330| 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é |331| 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 |332| 2026-08-23 | SEO programmatique (régions + catégories en HTML), stats v3 (rapports PDF personnalisés), favoris « Mon univers Ka » |333| 2026-08-24 | page `/doc` (guide + captures + PDF), README v3 |334| 2026-08-25 | vague connecteurs : **+26 sources actives** (10 ATR, 15 municipales, 6 billetteries/agrégateurs), 20 connecteurs enrichis, +13 salles JSON-LD → **61 sources actives** ; frontend v2 « guide culturel » (refonte mobile-first) + filtre `near=lat,lng` + KA Tabbar v1 |335| 2026-08-26 | personnalisation KA ID v2 (`kaid.py`, journal serveur, recommandations en mode annotation, filtrage collaboratif ALS, SDK `ka-id.js`) |336| 2026-08-28 | README v4 — visite guidée du site en 10 captures (`docs/screenshots/`) |337338## Écosystème Groupe KA339340| Site | Univers |341|---|---|342| [groupe-ka.com](https://www.groupe-ka.com) | portail |343| [lou-ka.com](https://www.lou-ka.com) | logements à louer |344| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre |345| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière |346| [auto-ka.com](https://www.auto-ka.com) | véhicules |347| [fabri-ka.com](https://www.fabri-ka.com) | produits québécois |348| [food-ka.com](https://www.food-ka.com) | épicerie / alimentation |349| [resto-ka.com](https://www.resto-ka.com) | restaurants |350| [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements |351| [job-ka.com](https://www.job-ka.com) | emplois |352| [crea-ka.com](https://www.crea-ka.com) | créateurs |353| [trouve-ka.com](https://www.trouve-ka.com) | petites annonces |354| [api-ka.com](https://www.api-ka.com) | API de données |355356## Contact357358**Simon-Pierre Boucher** — fondateur, Groupe KA359📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)360361---362363© Groupe KA — Simon-Pierre Boucher · [contact@spboucher.ai](mailto:contact@spboucher.ai)364365*Ce dépôt vit sur **spbgit** (git perso — https://git.spboucher.ai).*366