SPB Git
spboucher.ai

spb/job-ka

Public

Fondation Job·Ka : socle backend, 5 connecteurs pilotes, frontend, tests

- Schéma JobPosting + normalisation (salaires $/h↔$/an, dates ISO, villes
  canoniques, catégories) — 25 tests unitaires
- Pipeline hérité de Lou·Ka : diff par content_hash, délai de grâce,
  anti-dérive, expiration sur date limite, dédup union-find, géocodage
  Nominatim + Adresses Québec avec cache
- Plateformes ATS : Workday (facette Québec auto-découverte), Lever,
  Greenhouse, SmartRecruiters — connecteurs pilotes CAE, Desjardins, Poka,
  Mistplay, Ubisoft (442 offres QC)
- API FastAPI (/api/jobs, geojson, facets, sources, stats, /health) +
  frontend React/Vite (liste, fiche, carte MapLibre, stats)
- Fixtures HTTP enregistrées/rejouées hors ligne + hook pre-commit
  d'en-tête d'auteur (section 17)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Simon-Pierre Boucher committed (Aug 18, 2026) Browse files

54 changed files +7,657 −0

54 changed files
Load all 54 files Unified Split
added .env.example +11 −0
@@ -0,0 +1,11 @@
1 +# =============================================================================
2 +# Job·Ka — Groupe KA
3 +# Auteur : Simon-Pierre Boucher
4 +# Contact : contact@spboucher.ai
5 +# Fichier : .env.example
6 +# Rôle : Gabarit des variables d'environnement (copier vers .env)
7 +# Créé : 2026-08-17 Modifié : 2026-08-17
8 +# =============================================================================
9 +
10 +# Clé API Scrapfly (scraping des pages carrières protégées / rendu JS)
11 +SCRAPFLY_API_KEY=scp-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
added .gitignore +30 −0
@@ -0,0 +1,30 @@
1 +# =============================================================================
2 +# Job·Ka — Groupe KA
3 +# Auteur : Simon-Pierre Boucher
4 +# Contact : contact@spboucher.ai
5 +# Fichier : .gitignore
6 +# Rôle : Exclusions git (secrets, caches, artefacts de build)
7 +# Créé : 2026-08-17 Modifié : 2026-08-17
8 +# =============================================================================
9 +
10 +# Secrets — jamais commités
11 +.env
12 +
13 +# Python
14 +__pycache__/
15 +*.py[cod]
16 +.venv/
17 +.pytest_cache/
18 +
19 +# Node / frontend
20 +node_modules/
21 +dist/
22 +*.tsbuildinfo
23 +
24 +# macOS
25 +.DS_Store
26 +
27 +# Données locales et rapports générés
28 +data/*.db
29 +data/*.sqlite*
30 +data/cache/
added CLAUDE.md +159 −0
@@ -0,0 +1,159 @@
1 +# CLAUDE.md — Job·Ka
2 +
3 +> Agrégateur d'offres d'emploi québécoises du **Groupe KA** (groupe-ka.com).
4 +> Fichier d'instructions pour Claude Code. Lis-le en entier avant toute action.
5 +
6 +---
7 +
8 +## Règle nº 1 — En-tête d'auteur OBLIGATOIRE
9 +
10 +**Chaque fichier créé ou modifié** (code, script, config, doc, migration, test — sans exception) doit commencer par l'en-tête d'auteur suivant, adapté à la syntaxe de commentaire du langage :
11 +
12 +```python
13 +# =============================================================================
14 +# Job·Ka — Groupe KA
15 +# Auteur : Simon-Pierre Boucher
16 +# Contact : contact@spboucher.ai
17 +# Fichier : <chemin/nom_du_fichier>
18 +# Rôle : <description en une ligne>
19 +# Créé : <YYYY-MM-DD> Modifié : <YYYY-MM-DD>
20 +# =============================================================================
21 +```
22 +
23 +```javascript
24 +/**
25 + * =============================================================================
26 + * Job·Ka — Groupe KA
27 + * Auteur : Simon-Pierre Boucher
28 + * Contact : contact@spboucher.ai
29 + * Fichier : <chemin/nom_du_fichier>
30 + * Rôle : <description en une ligne>
31 + * Créé : <YYYY-MM-DD> Modifié : <YYYY-MM-DD>
32 + * =============================================================================
33 + */
34 +```
35 +
36 +- Aucun fichier sans cet en-tête ne doit être commité. Point final.
37 +- Si tu modifies un fichier existant sans en-tête : ajoute-le.
38 +- Si tu modifies un fichier avec en-tête : mets à jour la date `Modifié`.
39 +- Voir la **section 17** pour la politique complète d'attribution.
40 +
41 +---
42 +
43 +## 2. Contexte du projet
44 +
45 +**Job·Ka** agrège les offres d'emploi **directement depuis les pages carrières des employeurs québécois** (pas depuis Indeed/Jobillico). Même philosophie que les autres plateformes du Groupe KA (Lou·Ka, Immo·Ka, Vrai-Prix, ValoPlex, Auto·Ka, Fabri·Ka, Food·Ka) :
46 +
47 +1. **Zéro boîte noire** — chaque offre est traçable à sa source, avec URL originale.
48 +2. **Données réelles à la source** — connecteurs automatisés, aucune saisie manuelle.
49 +3. **Indépendance** — aucun employeur ne paie pour être mis en avant.
50 +
51 +Architecture cible : **un connecteur = un employeur** (ou une plateforme ATS partagée : Workday, Lever, Greenhouse, SmartRecruiters, BambooHR, etc.), un scheduler qui resynchronise jour et nuit, une normalisation vers un schéma unifié.
52 +
53 +---
54 +
55 +## 3. Règle nº 2 — Étudier le dépôt Lou·Ka AVANT tout connecteur
56 +
57 +**Avant d'écrire ou de modifier le moindre connecteur**, tu dois explorer le dépôt Lou·Ka et produire un résumé de ce que tu as compris. Job·Ka doit réutiliser les patterns éprouvés de Lou·Ka, pas les réinventer.
58 +
59 +À étudier obligatoirement dans Lou·Ka :
60 +
61 +- [ ] Structure d'un connecteur : interface commune, classe de base, conventions de nommage
62 +- [ ] Schéma de données normalisé et pipeline de normalisation
63 +- [ ] Gestion des erreurs, retries, timeouts, rate limiting par source
64 +- [ ] Scheduler / orchestration des resynchronisations
65 +- [ ] Déduplication des annonces entre sources
66 +- [ ] Détection et retrait des annonces expirées
67 +- [ ] Stockage (BD, index, cache) et exposition API/frontend
68 +- [ ] Logging et monitoring des connecteurs (taux de succès, fraîcheur)
69 +
70 +**Livrable avant de coder :** un rapport `docs/audit-louka.md` (avec en-tête d'auteur, règle nº 1) résumant l'architecture de Lou·Ka et le plan d'adaptation pour Job·Ka. Attends la validation de Simon-Pierre avant d'implémenter.
71 +
72 +---
73 +
74 +## 4. Schéma de données cible (offre d'emploi)
75 +
76 +Adapte les noms au style hérité de Lou·Ka, mais chaque connecteur doit tenter d'extraire :
77 +
78 +- `id_source` — identifiant unique chez l'employeur/ATS
79 +- `employeur` — nom de l'entreprise
80 +- `url_offre` — lien direct vers l'offre originale (obligatoire, zéro boîte noire)
81 +- `titre` — titre du poste
82 +- `description` — texte complet (HTML nettoyé)
83 +- `lieu` — ville, région, code postal si dispo
84 +- `mode_travail` — présentiel / hybride / télétravail
85 +- `type_emploi` — temps plein / partiel / contractuel / stage / saisonnier
86 +- `salaire_min`, `salaire_max`, `salaire_unite` — nombres, pas des strings (transparence salariale = différenciateur clé)
87 +- `avantages` — liste si disponible
88 +- `exigences` — scolarité, années d'expérience, langues
89 +- `date_publication`, `date_limite` — dates ISO normalisées
90 +- `categorie` — taxonomie interne (TI, santé, construction, etc.)
91 +- `ats` — plateforme source (workday, lever, custom, etc.)
92 +- `scrape_timestamp` — horodatage de la collecte
93 +
94 +Règles de normalisation : dates en ISO 8601, salaires convertis en $/h et $/an, géocodage adresse → lat/lng (réutiliser le pipeline Nominatim + cache de Lou·Ka, 1 req/s max).
95 +
96 +---
97 +
98 +## 5. Conventions de développement
99 +
100 +- Langue du code : anglais pour les identifiants, français pour la doc et les commentaires métier.
101 +- Un connecteur = un module isolé, testable seul (`make test-connector NAME=x`).
102 +- Jamais de scraping agressif : respecter robots.txt quand raisonnable, throttling par domaine, User-Agent identifiable `JobKaBot/1.0 (+https://www.job-ka.com; contact@spboucher.ai)`.
103 +- Aucun secret en dur dans le code : `.env` uniquement, jamais commité.
104 +- Chaque PR/commit : message clair en français, en-tête d'auteur vérifié (règle nº 1).
105 +- Avant de coder une fonctionnalité : présenter le plan et attendre validation.
106 +
107 +---
108 +
109 +## 6. Déploiement — node m3u96a + ngrok
110 +
111 +**Environnement de déploiement :**
112 +
113 +- Nœud cible : **`m3u96a`**
114 +- Exposition publique : **ngrok** avec le domaine réservé **`www.job-ka.com`**
115 +
116 +Procédure attendue :
117 +
118 +```bash
119 +# 1. Sur le node m3u96a — build et démarrage du service
120 +# (adapter au stack hérité de Lou·Ka : pm2, systemd, docker compose…)
121 +
122 +# 2. Tunnel ngrok vers le port de l'app (ex. 3000)
123 +ngrok http --domain=www.job-ka.com 3000
124 +```
125 +
126 +Règles :
127 +
128 +- Le tunnel ngrok doit être supervisé (pm2/systemd) pour redémarrer seul.
129 +- Vérifier après chaque déploiement : `https://www.job-ka.com` répond, healthcheck OK, connecteurs planifiés actifs.
130 +- Documenter toute variation dans `docs/deploiement.md` (avec en-tête, règle nº 1).
131 +- Ne jamais exposer d'interface d'admin ou de BD via le tunnel public.
132 +
133 +---
134 +
135 +## 7–16. Sections réservées
136 +
137 +Réservées pour les futures politiques (monitoring, SEO, alertes courriel, API publique, etc.). Ne pas supprimer la numérotation : la **section 17** doit rester la section 17.
138 +
139 +---
140 +
141 +## 17. Politique d'attribution d'auteur
142 +
143 +1. **Auteur unique du projet : Simon-Pierre Boucher** (`contact@spboucher.ai`). Toute contribution générée par Claude est réputée réalisée pour le compte de l'auteur.
144 +2. L'en-tête d'auteur (règle nº 1) est **non négociable** : il s'applique aux fichiers de code, scripts, configs, docs, tests, migrations, workflows CI, Dockerfiles et Makefiles.
145 +3. Les métadonnées de projet doivent refléter l'auteur :
146 + - `package.json` → `"author": "Simon-Pierre Boucher <contact@spboucher.ai>"`
147 + - `pyproject.toml` → `authors = [{name = "Simon-Pierre Boucher", email = "contact@spboucher.ai"}]`
148 + - `LICENSE` et `README.md` → copyright « © Groupe KA — Simon-Pierre Boucher »
149 +4. Configuration git du dépôt :
150 + ```bash
151 + git config user.name "Simon-Pierre Boucher"
152 + git config user.email "contact@spboucher.ai"
153 + ```
154 +5. Toute page publique de Job·Ka affiche dans le pied de page : « Une plateforme du Groupe KA » avec le contact `contact@spboucher.ai`.
155 +6. **Vérification automatique** : ajouter un hook pre-commit (ou étape CI) qui rejette tout fichier sans l'en-tête d'auteur. Ce hook porte lui-même l'en-tête.
156 +
157 +---
158 +
159 +*Dernière mise à jour : 2026-08-17 — Simon-Pierre Boucher (contact@spboucher.ai)*
added README.md +281 −0
@@ -0,0 +1,281 @@
1 +<!--
2 +=============================================================================
3 +Job·Ka — Groupe KA
4 +Auteur : Simon-Pierre Boucher
5 +Contact : contact@spboucher.ai
6 +Fichier : README.md
7 +Rôle : Documentation principale du projet
8 +Créé : 2026-08-17 Modifié : 2026-08-17
9 +=============================================================================
10 +-->
11 +
12 +<div align="center">
13 +
14 +# Job·Ka
15 +
16 +### Tous les emplois des employeurs québécois. Un seul endroit.
17 +
18 +**[www.job-ka.com](https://www.job-ka.com)**
19 +
20 +*Job·Ka collecte les offres directement sur les pages carrières des employeurs
21 +du Québec — pas sur les job boards. Chaque offre est traçable à sa source,
22 +les salaires sont normalisés en $/h et $/an, et la candidature se fait chez
23 +l'employeur. Zéro boîte noire, zéro intermédiaire.*
24 +
25 +</div>
26 +
27 +---
28 +
29 +## Sommaire
30 +
31 +- [Pourquoi Job·Ka ?](#pourquoi-job-ka-)
32 +- [L'architecture en 30 secondes](#larchitecture-en-30-secondes)
33 +- [Le pipeline en détail](#le-pipeline-en-détail)
34 +- [Structure du dépôt](#structure-du-dépôt)
35 +- [Démarrage rapide](#démarrage-rapide)
36 +- [CLI `run.py`](#cli-runpy)
37 +- [Variables d'environnement](#variables-denvironnement)
38 +- [API](#api)
39 +- [Ajouter un employeur (≈ 10 lignes)](#ajouter-un-employeur--10-lignes)
40 +- [Tests](#tests)
41 +- [Production](#production)
42 +- [Principes](#principes)
43 +- [Écosystème Groupe KA](#écosystème-groupe-ka)
44 +
45 +---
46 +
47 +## Pourquoi Job·Ka ?
48 +
49 +Les grands sites d'emploi mélangent annonces payantes, doublons repostés et
50 +offres mortes. L'offre originale — celle de la page carrière de l'employeur —
51 +est la seule source fiable : à jour, complète, sans frais de mise en avant.
52 +
53 +> Job·Ka se branche directement sur les systèmes de recrutement (ATS) des
54 +> employeurs : Workday, Lever, Greenhouse, SmartRecruiters, ou leur site
55 +> maison. Un connecteur = un employeur. Le tout resynchronisé jour et nuit.
56 +
57 +Ce n'est pas un job board qui vend de la visibilité, c'est un index fidèle de
58 +ce que les employeurs québécois affichent réellement — **avec les salaires en
59 +clair quand ils existent** (normalisés en $/h et $/an), parce que la
60 +transparence salariale est le différenciateur clé.
61 +
62 +## L'architecture en 30 secondes
63 +
64 +```mermaid
65 +flowchart LR
66 + subgraph Sources
67 + W["Workday"] --> C
68 + L["Lever"] --> C
69 + G["Greenhouse"] --> C
70 + S["SmartRecruiters"] --> C
71 + X["Sites maison<br/>(HTML / Scrapfly)"] --> C
72 + end
73 + C["Connecteurs<br/>(auto-découverts)"] --> N["finalize()<br/>normalisation"]
74 + N --> D[("SQLite<br/>data/jobka.db")]
75 + W2["⏱ Watcher horaire<br/>(PM2)"] -.-> C
76 + D --> A["FastAPI<br/>/api/*"]
77 + A --> F["React + Vite<br/>frontend/dist"]
78 + D --> GEO["Géocodage<br/>Nominatim + Adresses Québec"]
79 + GEO --> D
80 +```
81 +
82 +| Couche | Rôle | Fichiers |
83 +|---|---|---|
84 +| Connecteurs | 1 employeur = 1 module ; plateformes ATS partagées | `jobka/connectors/` |
85 +| Schéma | `JobPosting` + `finalize()` (normalisation commune) | `jobka/schema.py`, `jobka/normalize.py` |
86 +| Persistance | diff par `content_hash`, cycle de vie, anti-dérive | `jobka/db.py` |
87 +| Pipeline | ingestion, boucle `watch`, géocodage, dédup | `jobka/ingest.py`, `geocode.py`, `dedup.py` |
88 +| API + Web | FastAPI + frontend Vite servi en statique | `jobka/web.py`, `frontend/` |
89 +| Tests | fixtures HTTP enregistrées, rejeu hors ligne | `jobka/fixtures.py`, `tests/` |
90 +
91 +## Le pipeline en détail
92 +
93 +### Connecteurs auto-découverts
94 +Toute sous-classe de `BaseConnector` avec un `source_id` est enregistrée par
95 +`pkgutil` — aucun registre à maintenir. Les plateformes ATS (Workday, Lever,
96 +Greenhouse, SmartRecruiters) sont des classes de base : brancher un nouvel
97 +employeur = ~10 lignes. Politesse : throttling par source (`request_delay`),
98 +User-Agent identifiable `JobKaBot/1.0`, budgets de requêtes, cache BD des
99 +pages détail.
100 +
101 +### Diff engine avec garde-fou anti-dérive
102 +Chaque sync compare le `content_hash` de chaque offre : ajout, mise à jour, ou
103 +disparition. Une offre absente 2 syncs consécutifs passe `active=0` (jamais de
104 +DELETE). Si une source retourne ≤ 25 % de sa médiane historique, alerte et
105 +**retraits suspendus** — un connecteur cassé ne vide pas la base. Les offres
106 +dont la `date_limite` est dépassée sont retirées même si encore affichées.
107 +
108 +### Salaires normalisés — jamais inventés
109 +`parse_salary()` exige un signe monétaire ou une unité explicite, applique des
110 +bornes de plausibilité par unité, et convertit en $/h et $/an (40 h × 52 sem.).
111 +Une offre sans salaire reste sans salaire. L'historique des changements est
112 +conservé (`salary_log`).
113 +
114 +### Géocodage sans invention
115 +Nominatim (1 req/1,1 s) + repli officiel Adresses Québec (MERN, lots de 200),
116 +cache persistant par lieu normalisé, validation par bounding box provinciale.
117 +Sans adresse : centroïde de ville. Introuvable : `geocode_failed=1`, jamais de
118 +coordonnées bidon.
119 +
120 +### Déduplication inter-sources
121 +Blocage par clé exacte `titre normalisé | employeur | ville` + union-find avec
122 +exigence d'un second signal concordant (type, salaire ±4 %, date ±7 j). Le
123 +canonique est la source la plus autoritaire (page carrière avant agrégat) ;
124 +les doublons sont masqués (`dup_of`), jamais supprimés.
125 +
126 +## Structure du dépôt
127 +
128 +```
129 +job-ka/
130 +├── run.py # point d'entrée : sync | watch | serve | geocode | record
131 +├── requirements.txt # fastapi, uvicorn, requests, beautifulsoup4
132 +├── jobka/
133 +│ ├── schema.py # dataclass JobPosting + finalize()
134 +│ ├── normalize.py # salaires, dates, mode/type, lieux, catégories
135 +│ ├── db.py # SQLite : diff, cycle de vie, anti-dérive
136 +│ ├── ingest.py # run() / watch() — orchestration
137 +│ ├── dedup.py # déduplication inter-sources (union-find)
138 +│ ├── geocode.py # Nominatim + Adresses Québec + cache
139 +│ ├── web.py # API FastAPI + /health + frontend statique
140 +│ ├── fixtures.py # enregistrement/rejeu HTTP pour les tests
141 +│ └── connectors/
142 +│ ├── base.py # BaseConnector (throttling, Scrapfly, cache détail)
143 +│ ├── workday.py # plateforme Workday (facette Québec auto-découverte)
144 +│ ├── lever.py # plateforme Lever
145 +│ ├── greenhouse.py # plateforme Greenhouse
146 +│ ├── smartrecruiters.py # plateforme SmartRecruiters
147 +│ └── <employeur>.py # 1 fichier = 1 employeur (sous-classe)
148 +├── data/sources.json # registre descriptif des employeurs
149 +├── frontend/ # React 18 + Vite + TS (carte MapLibre, sans jeton)
150 +├── tests/ # pytest : normalisation + rejeu des connecteurs
151 +├── scripts/check_headers.py # hook pre-commit : en-tête d'auteur obligatoire
152 +└── docs/ # audit Lou·Ka, déploiement
153 +```
154 +
155 +## Démarrage rapide
156 +
157 +```bash
158 +git clone <repo> job-ka && cd job-ka
159 +
160 +# Backend
161 +python3 -m venv .venv
162 +.venv/bin/pip install -r requirements.txt
163 +
164 +# Frontend
165 +cd frontend && npm install && npm run build && cd ..
166 +
167 +# Secrets (Scrapfly pour les sites anti-bot — facultatif au départ)
168 +cp .env.example .env # puis remplir SCRAPFLY_API_KEY
169 +
170 +# Amorçage : première synchronisation + géocodage
171 +.venv/bin/python run.py sync
172 +.venv/bin/python run.py geocode
173 +
174 +# Service (API + frontend) — http://localhost:8096
175 +.venv/bin/python run.py serve 8096
176 +```
177 +
178 +En dev frontend : `npm run dev` dans `frontend/` (proxy `/api` → :8096).
179 +
180 +## CLI `run.py`
181 +
182 +| Commande | Rôle |
183 +|---|---|
184 +| `run.py sync [source ...]` | synchronise les offres (toutes les sources ou celles données) |
185 +| `run.py watch [minutes]` | boucle : sync + géocodage + dédup (défaut 60 min) |
186 +| `run.py serve [port]` | API + frontend (défaut 8096) |
187 +| `run.py geocode [n]` | géocode les offres sans coordonnées |
188 +| `run.py record <source ...>` | enregistre les fixtures de test d'une source |
189 +
190 +## Variables d'environnement
191 +
192 +| Variable | Rôle |
193 +|---|---|
194 +| `SCRAPFLY_API_KEY` | rendu JS / anti-bot pour les pages carrières maison |
195 +| `JOBKA_WORKDAY_DETAIL_LIMIT` | plafond de pages détail Workday par sync (défaut 300) |
196 +| `JOBKA_SR_DETAIL_LIMIT` | plafond de pages détail SmartRecruiters (défaut 300) |
197 +
198 +## API
199 +
200 +| Route | Rôle |
201 +|---|---|
202 +| `GET /health` | healthcheck (BD + fraîcheur des syncs) |
203 +| `GET /api/jobs` | recherche : `q, city, category, work_mode, employment_type, salary_min, with_salary, sort, limit, offset` |
204 +| `GET /api/jobs.geojson` | offres géolocalisées (carte), `bbox` + mêmes filtres |
205 +| `GET /api/jobs/{uid}` | fiche complète + historique salarial |
206 +| `GET /api/facets` | valeurs distinctes pour les filtres |
207 +| `GET /api/sources` | registre des employeurs + fraîcheur par source |
208 +| `GET /api/stats` | totaux, catégories, villes, dernières syncs |
209 +| `POST /api/sync` | déclenche une synchronisation (webhook) |
210 +
211 +## Ajouter un employeur (≈ 10 lignes)
212 +
213 +```python
214 +# jobka/connectors/mon_employeur.py (+ en-tête d'auteur, règle nº 1)
215 +from .workday import WorkdayConnector
216 +
217 +class MonEmployeurConnector(WorkdayConnector):
218 + source_id = "mon_employeur"
219 + EMPLOYER = "Mon Employeur inc."
220 + TENANT = "monemployeur" # monemployeur.wd3.myworkdayjobs.com
221 + HOST = "wd3"
222 + SITE = "Careers"
223 +```
224 +
225 +Puis : ajouter l'entrée dans `data/sources.json`, `run.py sync mon_employeur`
226 +pour valider, `run.py record mon_employeur` pour figer les fixtures de test.
227 +
228 +## Tests
229 +
230 +```bash
231 +.venv/bin/python -m pytest # tout
232 +.venv/bin/python -m pytest tests/test_normalize.py # normalisation seule
233 +```
234 +
235 +- `test_normalize.py` — salaires, dates, modes, types, lieux, catégories ;
236 +- `test_connectors.py` — rejeu hors ligne des fixtures : instantané exact +
237 + invariants (uid uniques, URLs absolues, salaires plausibles, valeurs jamais
238 + inventées) + `finalize()` sûr.
239 +
240 +## Production
241 +
242 +```
243 +job-ka-web .venv/bin/python run.py serve 8096 # API + frontend
244 +job-ka-sync .venv/bin/python run.py watch 60 # resync horaire, jour et nuit
245 +job-ka-ngrok ngrok http --url=www.job-ka.com 8096 # tunnel public
246 +```
247 +
248 +**Philosophie d'exploitation : on ne pousse que le code — le serveur maintient
249 +ses données lui-même.** `data/*.db`, `frontend/dist/` et `.env` ne sont jamais
250 +versionnés. Détails : `docs/deploiement.md`.
251 +
252 +## Principes
253 +
254 +1. **Politesse** — throttling par source, robots.txt respecté, User-Agent
255 + identifiable, budgets de requêtes, caches.
256 +2. **Fidélité** — les champs reflètent la source ; une donnée absente reste
257 + absente, jamais de valeur inventée (salaire, date, coordonnées).
258 +3. **Traçabilité** — chaque offre garde son URL originale ; la candidature se
259 + fait chez l'employeur. Zéro boîte noire.
260 +4. **Robustesse** — une source cassée ne bloque pas les autres et ne vide pas
261 + la base (délai de grâce + anti-dérive).
262 +5. **Transparence salariale** — salaires numériques normalisés en $/h et
263 + $/an ; filtre « salaire affiché » de premier ordre.
264 +
265 +## Écosystème Groupe KA
266 +
267 +Job·Ka partage la philosophie et l'architecture des plateformes sœurs :
268 +[Lou·Ka](https://www.lou-ka.com) (logements), Immo·Ka, Vrai-Prix, ValoPlex,
269 +Auto·Ka, Fabri·Ka, Food·Ka.
270 +
271 +---
272 +
273 +<div align="center">
274 +
275 +## Auteur
276 +
277 +**Simon-Pierre Boucher** — [contact@spboucher.ai](mailto:contact@spboucher.ai)
278 +
279 +© 2026 Groupe KA — Simon-Pierre Boucher. Tous droits réservés.
280 +
281 +</div>
added data/sources.json +60 −0
@@ -0,0 +1,60 @@
1 +{
2 + "_meta": {
3 + "project": "Job·Ka — Groupe KA",
4 + "author": "Simon-Pierre Boucher <contact@spboucher.ai>",
5 + "role": "Registre descriptif des sources (alimente la page Sources)",
6 + "updated": "2026-08-17"
7 + },
8 + "sources": [
9 + {
10 + "id": "cae",
11 + "name": "CAE",
12 + "url": "https://www.cae.com",
13 + "careers_url": "https://cae.wd3.myworkdayjobs.com/career",
14 + "sectors": ["Aéronautique", "Simulation", "TI"],
15 + "connector": "workday",
16 + "status": "actif",
17 + "region": "Montréal"
18 + },
19 + {
20 + "id": "desjardins",
21 + "name": "Mouvement Desjardins",
22 + "url": "https://www.desjardins.com",
23 + "careers_url": "https://desjardins.wd10.myworkdayjobs.com/Desjardins",
24 + "sectors": ["Finance", "Assurance", "TI"],
25 + "connector": "workday",
26 + "status": "actif",
27 + "region": "Lévis / province"
28 + },
29 + {
30 + "id": "poka",
31 + "name": "Poka",
32 + "url": "https://www.poka.io",
33 + "careers_url": "https://job-boards.greenhouse.io/poka",
34 + "sectors": ["TI", "SaaS manufacturier"],
35 + "connector": "greenhouse",
36 + "status": "actif",
37 + "region": "Québec"
38 + },
39 + {
40 + "id": "mistplay",
41 + "name": "Mistplay",
42 + "url": "https://www.mistplay.com",
43 + "careers_url": "https://jobs.lever.co/mistplay",
44 + "sectors": ["TI", "Jeu mobile"],
45 + "connector": "lever",
46 + "status": "actif",
47 + "region": "Montréal"
48 + },
49 + {
50 + "id": "ubisoft",
51 + "name": "Ubisoft",
52 + "url": "https://www.ubisoft.com",
53 + "careers_url": "https://jobs.smartrecruiters.com/company/Ubisoft2",
54 + "sectors": ["Jeux vidéo", "TI", "Création"],
55 + "connector": "smartrecruiters",
56 + "status": "actif",
57 + "region": "Montréal / Québec / Sherbrooke"
58 + }
59 + ]
60 +}
added docs/audit-louka.md +354 −0
@@ -0,0 +1,354 @@
1 +<!--
2 +=============================================================================
3 +Job·Ka — Groupe KA
4 +Auteur : Simon-Pierre Boucher
5 +Contact : contact@spboucher.ai
6 +Fichier : docs/audit-louka.md
7 +Rôle : Audit de l'architecture Lou·Ka et plan d'adaptation pour Job·Ka
8 +Créé : 2026-08-17 Modifié : 2026-08-17
9 +=============================================================================
10 +-->
11 +
12 +# Audit Lou·Ka → Plan d'adaptation Job·Ka
13 +
14 +> Livrable de la règle nº 2 du `CLAUDE.md`. Dépôt étudié : `~/Desktop/lou-ka`
15 +> (212 connecteurs, ~18 500 annonces actives, SQLite + FastAPI + React/Vite,
16 +> production PM2 + ngrok). **Aucune implémentation n'a été faite : ce document
17 +> attend la validation de Simon-Pierre avant tout code.**
18 +
19 +---
20 +
21 +## Partie A — Ce que fait Lou·Ka (architecture éprouvée)
22 +
23 +### A.1 Connecteurs : interface, conventions, découverte
24 +
25 +- **Classe de base** `BaseConnector` (`louka/connectors/base.py`), contrat minimal :
26 + - attributs de classe : `source_id: str`, `request_delay: float = 0.6`,
27 + `timeout: int = 30`, `use_detail_cache: bool = True` ;
28 + - une **seule méthode abstraite par convention** (pas d'`abc`) :
29 + `fetch(self) -> list[Listing]` ;
30 + - helpers fournis : `get()`/`post()` (session `requests` throttlée +
31 + `raise_for_status`), `get_rendered()` (Firecrawl), `scrapfly()`/`get_scrapfly()`
32 + (rendu JS + anti-bot), `detail()` (cache BD des pages détail).
33 +- **Conventions** : un fichier = un connecteur = un `source_id` ; fichier
34 + `snake_case.py` → classe `CamelCaseConnector` → `source_id` = nom du fichier.
35 + Bannière commentée en tête de fichier (site, plateforme, particularités,
36 + robots.txt).
37 +- **Découverte automatique** (`connectors/__init__.py`) : `pkgutil.iter_modules`
38 + + `importlib` remplissent le dict `CONNECTORS` avec toute sous-classe de
39 + `BaseConnector` ayant un `source_id`. Un module qui plante à l'import est
40 + **ignoré avec un avertissement** — jamais de liste à maintenir à la main.
41 +- **Plateformes partagées** : une classe de plateforme expose des constantes
42 + (`BASE`, `LIST_PATH`, `CITY_DEFAULT`…) et des *crochets* surchargeables
43 + (`_parse_card`, `_fetch_detail`…) ; un client de la plateforme = une
44 + sous-classe de ~15 lignes (ex. `DynamicConnector` → `AgenceSherbrookeConnector`).
45 +- **Registre descriptif parallèle** `data/sources.json`
46 + (`id, name, url, listing_url, sectors, connector, status, region`) — alimente
47 + la page publique « Sources », pas la découverte.
48 +
49 +### A.2 Schéma normalisé et pipeline de normalisation
50 +
51 +- **`@dataclass Listing`** (`louka/schema.py`) — stdlib, pas de Pydantic.
52 + Champs requis : `source`, `external_id`, `url`. Dérivés :
53 + `uid = "{source}:{external_id}"` (clé primaire), `content_hash()` (sha256 du
54 + dict trié → moteur de diff), `finalize()` (normalisation commune, idempotente,
55 + **n'écrase jamais une valeur explicite du connecteur**).
56 +- **`louka/normalize.py`** centralise : `parse_price` (exige `$` adjacent,
57 + bornes de plausibilité, retourne le min d'une fourchette),
58 + `parse_availability_date` (FR + EN → ISO, **jamais de date inventée**),
59 + `parse_area_sqft`, `normalize_unit_type`, `extract_details` (~20 règles à
60 + motifs positifs/négatifs, **dict sparse : clé absente = inconnu, jamais de
61 + `false` deviné**), `clean_address`, `strip_accents`.
62 +- Nettoyage HTML à trois niveaux : `BeautifulSoup.get_text()` dans le
63 + connecteur, helpers partagés `_detailutil.py` (JSON-LD, aplatissement,
64 + coordonnées Google Maps), et `textmine.py` (analyse regex FR déterministe de
65 + la description → digest structuré ; aucun LLM).
66 +- Garde-fou géographique dans `finalize()` : coordonnées hors Québec rejetées.
67 +
68 +### A.3 Erreurs, retries, timeouts, throttling
69 +
70 +- **Pas de retry HTTP générique** (ni tenacity ni urllib3.Retry) : la
71 + robustesse vient de `try/except` par source + par annonce, et de la reprise
72 + au cycle suivant. Philosophie : une panne coûte une heure, pas des données.
73 +- **Throttling par source** : `request_delay` (0.6 s défaut, jusqu'à 20 s quand
74 + le robots.txt exige un `Crawl-delay`), appliqué dans `get()/post()`.
75 +- **Budgets de requêtes** plutôt que rate limit externe : `max_pages`,
76 + `max_details`, plafonds surchargés par variables d'env
77 + (`LOUKA_<PORTAIL>_<LIMITE>`), exceptions sentinelles locales.
78 +- **User-Agent identifiable** unique, déclaré une fois dans `base.py`
79 + (`LouKaBot/1.0 (+https://www.lou-ka.com/bot; contact@spboucher.ai)`).
80 +- **Timeouts** : 30 s défaut, surchargables par classe ; Firecrawl 90-150 s,
81 + Scrapfly 180 s.
82 +- Scrapfly / Firecrawl = seule stratégie anti-bot et rendu JS ; aucun proxy
83 + maison ; tout est `requests` synchrone.
84 +
85 +### A.4 Scheduler / orchestration
86 +
87 +- **Boucle maison**, pas d'APScheduler ni cron : `run.py watch 60` →
88 + `ingest.watch(3600)` = `while True: run(); sleep(3600)`.
89 +- Cycle strictement séquentiel : **ingestion → géocodage en lot → POI →
90 + quartier → déduplication** (la dédup vient après le géocodage car les
91 + coordonnées alimentent le blocage). Étapes 2-5 chacune dans un `try/except`
92 + non bloquant.
93 +- Aucun parallélisme entre connecteurs (choix délibéré de politesse) ;
94 + `POST /api/sync` déclenche un cycle sous `threading.Lock`.
95 +- CLI unique `run.py` : `sync | watch | serve | geocode | record …`,
96 + dispatch manuel sur `sys.argv`, chargement `.env` maison, imports paresseux.
97 +
98 +### A.5 Déduplication inter-sources
99 +
100 +`louka/dedup.py` — **clé exacte + union-find, aucun fuzzy** :
101 +1. Blocage par clé d'adresse normalisée (`civique|mots-de-rue|ville`, sans
102 + accents ni types de voie) — la proximité GPS a été **abandonnée** (fusionnait
103 + des immeubles voisins).
104 +2. Confirmation d'une paire : même clé obligatoire + aucun signal contradictoire
105 + (unité, type, prix ±4 %) + **au moins un second signal concordant**.
106 +3. Union-find avec contrainte : jamais deux annonces de la même source dans une
107 + composante ; jamais de dédup intra-source.
108 +4. Canonique choisi par **autorité de la source** (site direct < portail <
109 + petites annonces) puis richesse du contenu. Les doublons sont **masqués**
110 + (`dup_of`), jamais supprimés ; recalcul intégral idempotent à chaque cycle.
111 +
112 +### A.6 Expiration des annonces
113 +
114 +- Marquage **vu/non-vu par cycle** : `last_seen`, `miss_count` ; non vue 2 cycles
115 + consécutifs (`MISS_GRACE = 2`) → `active = 0`. **Jamais de `DELETE`.**
116 +- **Garde-fou anti-dérive** (`_drift_alert`) : si une source retourne ≤ 25 % de
117 + sa médiane des 5 dernières syncs OK, ou si le taux de prix nuls explose →
118 + alerte consignée et **retraits suspendus** (un connecteur cassé ne vide pas
119 + la base).
120 +- SEO : annonce retirée → HTTP 410 Gone sur sa page.
121 +
122 +### A.7 Stockage et exposition
123 +
124 +- **SQLite unique** (`data/louka.db`, `sqlite3` stdlib, pas d'ORM). Schéma
125 + idempotent exécuté à chaque `connect()` ; **migrations maison** par
126 + `PRAGMA table_info` + `ALTER TABLE ADD COLUMN` (dict `_MIGRATIONS`).
127 +- Tables clés : `listings` (uid PK, colonnes du dataclass + cycle de vie),
128 + `sync_log` (monitoring), `price_log` (historique), `geocode_cache`,
129 + `detail_cache`, `poi_cache`, comptes/favoris.
130 +- Index : source, city, active, `(lat, lng)` pour les bbox de la carte.
131 +- **FastAPI** (`louka/web.py`) : `/api/listings` (filtres + pagination),
132 + `/api/listings.geojson` (bbox), `/api/listings/{uid}` (fiche enrichie),
133 + `/api/facets`, `/api/sources`, `/api/stats[.detailed]`, PDF, `POST /api/sync`.
134 + CORS ouvert + GZip. Frontend React 18 + Vite + TS servi en statique par
135 + FastAPI (catch-all avec vraies 404), SSR léger + sitemaps dans `seo.py`.
136 +- Géocodage : **Nominatim (1,1 s/req)** + repli **Adresses Québec (lot de 200)**,
137 + cache SQLite avec mémorisation des échecs (retente après 30 j), validation
138 + par bounding box, granularité par immeuble. Jamais de coordonnées inventées.
139 +
140 +### A.8 Logging, monitoring, tests
141 +
142 +- Pas de module `logging` : `print("[lou-ka] …")` capté par PM2. La vraie
143 + télémétrie est en base : `sync_log(source, ts, found, added, updated,
144 + removed, ok, message, stats JSON)` → exposée par `/api/stats`
145 + (20 dernières syncs) et `/api/sources` (`last_sync` par source).
146 +- **Fixtures HTTP enregistrées/rejouées** (`louka/fixtures.py`) :
147 + `run.py record <source>` capture les requêtes réelles (adapter monté sur la
148 + session, secrets caviardés) ; `pytest` rejoue **hors ligne** et compare à un
149 + instantané déterministe + invariants (uid uniques, URLs absolues, bornes de
150 + prix/superficie, pas de valeurs inventées). 193 sources couvertes.
151 +- Une **fiche Markdown par connecteur** dans `reports/connectors/<source>.md`
152 + (méthode, couverture des champs en %, fragilités, échantillon).
153 +- Production : 3 processus PM2 — `lou-ka-web` (serve 8095), `lou-ka-sync`
154 + (watch 60), `lou-ka-ngrok` (`ngrok http --url=www.lou-ka.com 8095`).
155 + Philosophie : « on ne pousse que le code — le serveur maintient ses données
156 + lui-même » (`data/*.db`, `dist/`, `.env` jamais versionnés).
157 +
158 +---
159 +
160 +## Partie B — Plan d'adaptation pour Job·Ka
161 +
162 +Principe directeur : **reprendre l'architecture de Lou·Ka telle quelle** —
163 +paquet `jobka/`, mêmes mécanismes (registre auto-découvrant, diff par
164 +`content_hash`, `miss_count` + anti-dérive, fixtures rejouables, SQLite,
165 +FastAPI, `run.py`, PM2 + ngrok) — et n'adapter que ce qui est propre au
166 +domaine de l'emploi.
167 +
168 +### B.1 Ce qui se transpose tel quel (≈ 80 %)
169 +
170 +| Brique Lou·Ka | Job·Ka |
171 +|---|---|
172 +| `BaseConnector` + registre auto-découvrant | Identique (`jobka/connectors/`) |
173 +| `finalize()` + `normalize.py` | Identique dans l'esprit ; parseurs adaptés (salaires, dates limites) |
174 +| Diff `content_hash` + `sync_log` + anti-dérive | Identique — critique pour l'emploi (offres qui disparaissent vite) |
175 +| Expiration `miss_count`/`MISS_GRACE=2` + `active=0` | Identique + prise en compte de `date_limite` dépassée |
176 +| Fixtures record/replay + tests d'invariants | Identique (`run.py record`, pytest hors ligne) |
177 +| SQLite + migrations maison + FastAPI + frontend Vite | Identique |
178 +| Géocodage Nominatim + Adresses Québec + cache | **Réutilisé tel quel** (le lieu de travail se géocode comme une adresse) |
179 +| CLI `run.py` (sync/watch/serve/record) | Identique |
180 +| Déploiement 3 processus PM2 + ngrok | Identique, domaine `www.job-ka.com`, nœud `m3u96a` |
181 +| Fiches `reports/connectors/<source>.md` | Identique |
182 +
183 +### B.2 Schéma `JobPosting` (adaptation du dataclass `Listing`)
184 +
185 +Mêmes conventions (champs requis `source`, `external_id`, `url` ; `uid`,
186 +`content_hash()`, `finalize()`), champs métier du `CLAUDE.md` §4 mappés au
187 +style Lou·Ka (identifiants en anglais) :
188 +
189 +```python
190 +@dataclass
191 +class JobPosting:
192 + source: str # id du connecteur (= employeur ou ATS) [id_source]
193 + external_id: str
194 + url: str # lien direct vers l'offre — zéro boîte noire
195 + employer: str = "" # [employeur]
196 + title: str = ""
197 + description: str = "" # HTML nettoyé
198 + address: str = "" # lieu de travail si dispo
199 + city: str = ""
200 + region: str = ""
201 + postal_code: str = ""
202 + work_mode: str | None = None # presentiel | hybride | teletravail
203 + employment_type: str | None = None # temps_plein | partiel | contractuel | stage | saisonnier
204 + salary_min: float | None = None # nombres, jamais des strings
205 + salary_max: float | None = None
206 + salary_unit: str | None = None # "hour" | "year" (+ conversions dérivées)
207 + benefits: list[str] = field(default_factory=list)
208 + requirements: dict = field(default_factory=dict) # scolarité, expérience, langues
209 + date_posted: str | None = None # ISO 8601
210 + date_deadline: str | None = None # ISO 8601
211 + category: str = "" # taxonomie interne (TI, santé, construction…)
212 + ats: str = "" # workday | lever | greenhouse | custom…
213 + details: dict = field(default_factory=dict) # sparse, comme Lou·Ka
214 + lat: float | None = None
215 + lng: float | None = None
216 +```
217 +
218 +Normalisation spécifique emploi (équivalents de `parse_price`/`parse_area_sqft`) :
219 +- `parse_salary(raw)` → `(min, max, unit)` ; bornes de plausibilité
220 + (~15–200 $/h, ~20 000–500 000 $/an) ; conversion $/h ↔ $/an
221 + (base 40 h × 52 sem.) stockée en champs dérivés — la **transparence salariale**
222 + est le différenciateur clé, jamais de salaire inventé ;
223 +- `parse_work_mode`, `parse_employment_type` : tables de mots-clés FR/EN
224 + (comme `_UNIT_WORDS`) ;
225 +- `parse_date` : réutilise `parse_availability_date` (FR + EN → ISO) ;
226 +- `categorize(title, description)` : taxonomie par mots-clés déterministes
227 + (approche `textmine.py`, pas de LLM au départ).
228 +
229 +### B.3 Connecteurs : l'avantage ATS
230 +
231 +Différence favorable vs l'immobilier : une grande part des employeurs québécois
232 +passe par un **ATS mutualisé** avec API JSON publique et stable. Une classe de
233 +plateforme par ATS (pattern `DynamicConnector`/`LaCourConnector`) donne des
234 +connecteurs-clients de ~10 lignes :
235 +
236 +| Classe de plateforme | Méthode | Coût par employeur |
237 +|---|---|---|
238 +| `WorkdayConnector` | API JSON `…/wday/cxs/<tenant>/<site>/jobs` (POST paginé) | tenant + site |
239 +| `LeverConnector` | `api.lever.co/v0/postings/<org>?mode=json` | slug org |
240 +| `GreenhouseConnector` | `boards-api.greenhouse.io/v1/boards/<org>/jobs?content=true` | slug org |
241 +| `SmartRecruitersConnector` | `api.smartrecruiters.com/v1/companies/<org>/postings` | slug org |
242 +| `BambooHRConnector` | `<org>.bamboohr.com/careers/list` (JSON) | sous-domaine |
243 +| `JazzHRConnector`, `RecruiteeConnector`, `UKGConnector`… | à documenter au fil des sources | — |
244 +| Connecteurs custom (HTML) | `BeautifulSoup`, ou **Scrapfly** si rendu JS / anti-bot | 1 module dédié |
245 +
246 +- **Scrapfly** : méthode `scrapfly()` reprise de `base.py` telle quelle ;
247 + clé déjà en place dans `.env` (`SCRAPFLY_API_KEY`). Usage réservé aux pages
248 + carrières à rendu JS ou protégées (rôle qu'avait `fb_marketplace` dans
249 + Lou·Ka) — les ATS JSON n'en ont pas besoin.
250 +- User-Agent : `JobKaBot/1.0 (+https://www.job-ka.com; contact@spboucher.ai)`
251 + (CLAUDE.md §5), déclaré une seule fois dans `base.py`.
252 +- Throttling par domaine (`request_delay`), budgets `max_pages`/`max_details`,
253 + plafonds par env `JOBKA_<SOURCE>_<LIMITE>` : repris à l'identique.
254 +
255 +### B.4 Déduplication adaptée à l'emploi
256 +
257 +Le blocage par adresse civique ne se transpose pas (une offre n'a pas toujours
258 +d'adresse précise). Même squelette (blocage + confirmation + union-find +
259 +autorité), clés adaptées :
260 +- **Blocage** : `titre normalisé (sans accents, stopwords RH retirés) | employeur normalisé | ville` ;
261 +- **Confirmation** : refus si signaux contradictoires (type d'emploi différent,
262 + salaires connus s'écartant de > 4 %) + exigence d'un second signal concordant
263 + (même date de publication ±7 j, même salaire, même code postal) ;
264 +- **Autorité** : page carrière de l'employeur (0) < ATS mutualisé (10) —
265 + pertinent le jour où des agrégats s'ajoutent ; masquage `dup_of`, jamais de
266 + suppression ; contrainte « jamais deux offres de la même source dans une
267 + composante » conservée.
268 +
269 +### B.5 Expiration spécifique emploi
270 +
271 +- `miss_count` + `MISS_GRACE = 2` + anti-dérive : repris tels quels ;
272 +- règle additionnelle : `date_deadline` dépassée → `active = 0` même si l'offre
273 + est encore en ligne (offres zombies fréquentes sur les pages carrières) ;
274 +- offre retirée → HTTP 410 sur sa page publique (pattern `seo.py`).
275 +
276 +### B.6 Structure de dépôt cible
277 +
278 +```
279 +job-ka/
280 +├── run.py # sync | watch | serve | geocode | record
281 +├── requirements.txt # fastapi, uvicorn, requests, beautifulsoup4
282 +├── jobka/
283 +│ ├── schema.py # JobPosting (dataclass) + finalize()
284 +│ ├── normalize.py # salaires, dates, mode/type d'emploi, catégories
285 +│ ├── db.py # SQLite, sync_log, anti-dérive, migrations
286 +│ ├── ingest.py # run() / watch()
287 +│ ├── dedup.py # blocage titre|employeur|ville + union-find
288 +│ ├── geocode.py # Nominatim + Adresses Québec + cache (repris)
289 +│ ├── web.py # FastAPI : /api/jobs, /api/facets, /api/sources, /api/stats
290 +│ ├── seo.py # SSR léger + sitemaps + 410
291 +│ ├── fixtures.py # record/replay hors ligne
292 +│ └── connectors/
293 +│ ├── base.py # BaseConnector (JobKaBot UA, scrapfly(), detail())
294 +│ ├── _atsutil.py # helpers partagés (équiv. _detailutil)
295 +│ ├── workday.py, lever.py, greenhouse.py, … # classes de plateforme
296 +│ └── <employeur>.py # 1 fichier = 1 source
297 +├── data/sources.json # registre descriptif des employeurs
298 +├── frontend/ # React + Vite + TS, servi par FastAPI
299 +├── tests/ # test_connectors (fixtures), test_normalize
300 +├── reports/connectors/ # 1 fiche .md par connecteur
301 +└── docs/
302 +```
303 +
304 +### B.7 Déploiement (CLAUDE.md §6)
305 +
306 +3 processus PM2 sur **m3u96a**, calqués sur Lou·Ka :
307 +
308 +```
309 +job-ka-web .venv/bin/python run.py serve <port> # API + SSR + frontend
310 +job-ka-sync .venv/bin/python run.py watch 60 # resync horaire, jour et nuit
311 +job-ka-ngrok ngrok http --url=www.job-ka.com <port>
312 +```
313 +
314 +Vérifications post-déploiement : `https://www.job-ka.com` répond,
315 +`/api/sources` montre des `last_sync` récents, `sync_log` sans alerte.
316 +Jamais d'admin/BD exposé par le tunnel. Enregistrement dans
317 +`~/Desktop/cluster-skill/cluster-deployments.json`. À noter : m3u96a est
318 +normalement réservé au staging/calcul — dérogation explicite du CLAUDE.md §6.
319 +
320 +### B.8 Écarts assumés vs Lou·Ka (améliorations légères)
321 +
322 +1. **Endpoint `/health`** ajouté (Lou·Ka n'en a pas ; le CLAUDE.md de Job·Ka
323 + exige un healthcheck au déploiement).
324 +2. `dedup.run()` aussi appelé en fin de `run.py sync` (bogue mineur relevé chez
325 + Lou·Ka : la dédup ne tourne que dans `watch`).
326 +3. Réinitialiser `geocode_failed` quand l'adresse d'une offre change (second
327 + bogue mineur relevé chez Lou·Ka).
328 +4. En-tête d'auteur Job·Ka (règle nº 1) sur chaque fichier + hook pre-commit de
329 + vérification (section 17 du CLAUDE.md).
330 +
331 +### B.9 Ordre d'implémentation proposé
332 +
333 +1. **Socle** : `schema.py`, `normalize.py` (+ tests), `db.py`, `base.py`,
334 + registre auto-découvrant, `run.py`, `fixtures.py`.
335 +2. **3 premiers connecteurs pilotes** : 1 Workday + 1 Lever ou Greenhouse
336 + (employeurs québécois à confirmer) + 1 custom HTML — pour valider le socle
337 + sur les trois familles.
338 +3. `ingest.py` + expiration + anti-dérive + `dedup.py`.
339 +4. `web.py` + frontend minimal (liste, fiche, filtres, sources, stats).
340 +5. Vague de connecteurs (choix des employeurs à valider avec Simon-Pierre).
341 +6. `seo.py`, géocodage, déploiement m3u96a + ngrok.
342 +
343 +---
344 +
345 +## Questions ouvertes pour validation
346 +
347 +1. **Liste des premiers employeurs/ATS cibles** — as-tu déjà une liste
348 + (ex. Desjardins, Hydro-Québec, CGI, gouvernement du Québec via Workday…) ou
349 + je propose une première vague de ~20 employeurs québécois par ATS ?
350 +2. **Port du service** sur m3u96a (Lou·Ka occupe 8095 ailleurs ; proposer 8096 ?).
351 +3. Le géocodage des lieux de travail est-il prioritaire dès la v1, ou la ville
352 + textuelle suffit-elle au lancement (carte en v2) ?
353 +
354 +**Statut : en attente de validation avant toute implémentation (règle nº 2).**
added docs/deploiement.md +84 −0
@@ -0,0 +1,84 @@
1 +<!--
2 +=============================================================================
3 +Job·Ka — Groupe KA
4 +Auteur : Simon-Pierre Boucher
5 +Contact : contact@spboucher.ai
6 +Fichier : docs/deploiement.md
7 +Rôle : Procédure de déploiement sur m3u96a + ngrok www.job-ka.com
8 +Créé : 2026-08-17 Modifié : 2026-08-17
9 +=============================================================================
10 +-->
11 +
12 +# Déploiement Job·Ka — nœud m3u96a
13 +
14 +## Cible
15 +
16 +- **Nœud** : `M3U96a.maclustr.io` (Mac Studio, 32 cœurs, 96 Go) — imposé par le
17 + CLAUDE.md du projet (§6). Dérogation assumée à la règle « M3U96a = staging » :
18 + demande explicite du projet, comme `vrai-prix` et `sorti-ka` déjà sur ce nœud.
19 +- **Répertoire** : `~/apps/job-ka` (convention des projets Ka remote-first)
20 +- **Port interne** : `8096` (8095 = lou-ka ; vérifier les conflits avec
21 + `pick-node.py`/`lsof` avant de démarrer)
22 +- **Exposition** : ngrok, domaine réservé `www.job-ka.com`
23 +- **Superviseur** : PM2 (3 processus)
24 +
25 +## Processus PM2
26 +
27 +```
28 +job-ka-web .venv/bin/python run.py serve 8096 # API + frontend
29 +job-ka-sync .venv/bin/python run.py watch 60 # resync horaire
30 +job-ka-ngrok ngrok http --url=www.job-ka.com 8096 # tunnel supervisé
31 +```
32 +
33 +## Procédure
34 +
35 +```bash
36 +# 1. Pousser le code (jamais les données : data/*.db, dist/, .env restent locaux au nœud)
37 +ssh M3U96a 'mkdir -p ~/apps'
38 +rsync -a --delete \
39 + --exclude .venv --exclude node_modules --exclude dist \
40 + --exclude 'data/*.db' --exclude .env --exclude .git \
41 + ~/Desktop/job-ka/ M3U96a:~/apps/job-ka/
42 +
43 +# 2. Sur le nœud : runtime + build + secrets
44 +ssh M3U96a 'cd ~/apps/job-ka \
45 + && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt \
46 + && cd frontend && npm install && npm run build'
47 +# .env : créer sur le nœud (SCRAPFLY_API_KEY) — jamais commité ni rsyncé
48 +
49 +# 3. Amorçage des données
50 +ssh M3U96a 'cd ~/apps/job-ka && .venv/bin/python run.py sync && .venv/bin/python run.py geocode'
51 +
52 +# 4. PM2
53 +ssh M3U96a 'cd ~/apps/job-ka \
54 + && pm2 start ".venv/bin/python run.py serve 8096" --name job-ka-web \
55 + && pm2 start ".venv/bin/python run.py watch 60" --name job-ka-sync \
56 + && pm2 start "ngrok http --url=www.job-ka.com 8096" --name job-ka-ngrok \
57 + && pm2 save'
58 +```
59 +
60 +## Vérifications post-déploiement
61 +
62 +1. `curl https://www.job-ka.com/health` → `{"status":"ok", ...}` avec
63 + `last_sync_age_s` < 7200 ;
64 +2. `https://www.job-ka.com` répond (frontend) ;
65 +3. `https://www.job-ka.com/api/sources` → `last_sync` récents sur chaque source ;
66 +4. `pm2 ls` : les 3 processus `online` ;
67 +5. Mettre à jour `~/Desktop/cluster-skill/cluster-deployments.json` (registre
68 + cross-session : app, node, port, domain, process_manager, dir, start, deployed).
69 +
70 +## Règles
71 +
72 +- Jamais d'interface d'admin ni de BD exposée par le tunnel (seuls `/`,
73 + `/api/*`, `/health` existent ; `POST /api/sync` est le seul point mutateur —
74 + il ne fait que déclencher une resynchronisation).
75 +- Les mises à jour de code passent par rsync (ou git sur le nœud, protocole
76 + remote-first des projets Ka) puis `pm2 restart job-ka-web job-ka-sync`.
77 +
78 +## Variations par rapport à Lou·Ka
79 +
80 +- Carte : **MapLibre GL + fond Carto libre** au lieu de Mapbox/ka-maps — aucun
81 + jeton requis, aucun paquet lié à builder à côté du dépôt.
82 +- `dedup.run()` s'exécute aussi après `run.py sync` (pas seulement dans
83 + `watch`) ; `geocode_failed` est remis à 0 quand l'adresse d'une offre change.
84 +- Endpoint `/health` dédié (Lou·Ka n'en a pas).
added frontend/index.html +27 −0
@@ -0,0 +1,27 @@
1 +<!doctype html>
2 +<!--
3 +=============================================================================
4 +Job·Ka — Groupe KA
5 +Auteur : Simon-Pierre Boucher
6 +Contact : contact@spboucher.ai
7 +Fichier : frontend/index.html
8 +Rôle : Coquille HTML de l'application (SPA React)
9 +Créé : 2026-08-17 Modifié : 2026-08-17
10 +=============================================================================
11 +-->
12 +<html lang="fr">
13 + <head>
14 + <meta charset="UTF-8" />
15 + <meta name="viewport" content="width=device-width, initial-scale=1.0" />
16 + <meta name="description" content="Job·Ka — toutes les offres d'emploi des employeurs québécois, directement à la source. Salaires transparents, zéro boîte noire." />
17 + <title>Job·Ka — L'emploi au Québec, à la source</title>
18 + <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='14' fill='%23141814'/%3E%3Ctext x='32' y='42' font-family='Inter,sans-serif' font-size='28' font-weight='800' fill='%23d9f26b' text-anchor='middle'%3EJ·K%3C/text%3E%3C/svg%3E" />
19 + <link rel="preconnect" href="https://fonts.googleapis.com" />
20 + <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
21 + <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet" />
22 + </head>
23 + <body>
24 + <div id="root"></div>
25 + <script type="module" src="/src/main.tsx"></script>
26 + </body>
27 +</html>
added frontend/package-lock.json +2212 −0
Large diff (2,212 lines) is not loaded by default to keep the page fast.Load diff
added frontend/package.json +26 −0
Large diff (26 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/App.tsx +60 −0
Large diff (60 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/api.ts +171 −0
Large diff (171 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/components/JobCard.tsx +30 −0
Large diff (30 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/main.tsx +23 −0
Large diff (23 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/pages/Home.tsx +136 −0
Large diff (136 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/pages/Job.tsx +71 −0
Large diff (71 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/pages/MapPage.tsx +98 −0
Large diff (98 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/pages/Sources.tsx +52 −0
Large diff (52 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/pages/Stats.tsx +79 −0
Large diff (79 lines) is not loaded by default to keep the page fast.Load diff
added frontend/src/styles.css +172 −0
Large diff (172 lines) is not loaded by default to keep the page fast.Load diff
added frontend/tsconfig.json +21 −0
Large diff (21 lines) is not loaded by default to keep the page fast.Load diff
added frontend/vite.config.ts +23 −0
Large diff (23 lines) is not loaded by default to keep the page fast.Load diff
added jobka/__init__.py +8 −0
Large diff (8 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/__init__.py +32 −0
Large diff (32 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/base.py +150 −0
Large diff (150 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/cae.py +18 −0
Large diff (18 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/desjardins.py +18 −0
Large diff (18 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/greenhouse.py +67 −0
Large diff (67 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/lever.py +85 −0
Large diff (85 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/mistplay.py +15 −0
Large diff (15 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/poka.py +16 −0
Large diff (16 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/smartrecruiters.py +124 −0
Large diff (124 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/ubisoft.py +16 −0
Large diff (16 lines) is not loaded by default to keep the page fast.Load diff
added jobka/connectors/workday.py +174 −0
Large diff (174 lines) is not loaded by default to keep the page fast.Load diff
added jobka/db.py +369 −0
Large diff (369 lines) is not loaded by default to keep the page fast.Load diff
added jobka/dedup.py +202 −0
Large diff (202 lines) is not loaded by default to keep the page fast.Load diff
added jobka/fixtures.py +194 −0
Large diff (194 lines) is not loaded by default to keep the page fast.Load diff
added jobka/geocode.py +344 −0
Large diff (344 lines) is not loaded by default to keep the page fast.Load diff
added jobka/ingest.py +96 −0
Large diff (96 lines) is not loaded by default to keep the page fast.Load diff
added jobka/normalize.py +480 −0
Large diff (480 lines) is not loaded by default to keep the page fast.Load diff
added jobka/schema.py +167 −0
Large diff (167 lines) is not loaded by default to keep the page fast.Load diff
added jobka/web.py +338 −0
Large diff (338 lines) is not loaded by default to keep the page fast.Load diff
added requirements.txt +12 −0
Large diff (12 lines) is not loaded by default to keep the page fast.Load diff
added run.py +65 −0
Large diff (65 lines) is not loaded by default to keep the page fast.Load diff
added scripts/check_headers.py +76 −0
Large diff (76 lines) is not loaded by default to keep the page fast.Load diff
added tests/conftest.py +12 −0
Large diff (12 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/mistplay/b53675f2801b6632ebba.json +1 −0
Large diff (2 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/mistplay/expected.json +47 −0
Large diff (48 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/mistplay/index.json +9 −0
Large diff (10 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/poka/0b773b59b34e454db34d.json +1 −0
Large diff (2 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/poka/expected.json +75 −0
Large diff (76 lines) is not loaded by default to keep the page fast.Load diff
added tests/fixtures/poka/index.json +9 −0
Large diff (10 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_connectors.py +79 −0
Large diff (79 lines) is not loaded by default to keep the page fast.Load diff
added tests/test_normalize.py +178 −0
Large diff (179 lines) is not loaded by default to keep the page fast.Load diff
Menu

Theme
↑↓ navigate ↵ open esc close / or ⌘K anywhere