docs: README ultra détaillé + visite guidée en 10 captures

Simon-Pierre Boucher committed 26 days ago (Aug 29, 2026) parent 4faea71

11 changed files +97 −29

modified README.md +97 −29

		`@@ -5,7 +5,7 @@ Auteur : Simon-Pierre Boucher`
5	5	Contact : contact@spboucher.ai
6	6	Fichier : README.md
7	7	Rôle : Documentation principale du projet
8		−Créé : 2026-08-17 Modifié : 2026-08-24
	8	+Créé : 2026-08-17 Modifié : 2026-08-28
9	9	=============================================================================
10	10	-->
11	11
		`@@ -47,28 +47,91 @@ Créé : 2026-08-17 Modifié : 2026-08-24`
47	47
48	48	</div>
49	49
50		−Les grands sites d'emploi mélangent annonces payantes, doublons repostés et offres mortes. L'offre originale — celle de la page carrière de l'employeur — est la seule source fiable. Job·Ka se branche directement sur les systèmes de recrutement (ATS) des employeurs québécois : 969 connecteurs employeurs directs sur 21 plateformes ATS (Workday, SmartRecruiters, Dayforce, Workable, Workland/réseau Atlas, SuccessFactors, Njoyn, Greenhouse, WP Job Manager, Lever, Breezy, Ashby, Recruitee, BambooHR, Taleo Business Edition, Taleo, Digital Recruiters, iCIMS, UltiPro/UKG, ADP WFN + sites carrières maison), complétés par 3 portails publics (Guichet-Emplois, Jobillico, Espresso-Jobs) — l'offre directe gagne toujours.
	50	+Les grands sites d'emploi mélangent annonces payantes, doublons repostés et offres mortes. L'offre originale — celle de la page carrière de l'employeur — est la seule source fiable. Job·Ka se branche directement sur les systèmes de recrutement (ATS) des employeurs québécois : 1 104 connecteurs employeurs directs sur 23 plateformes ATS (Workday, SmartRecruiters, Greenhouse, Dayforce, Breezy, Workable, Lever, Ashby, BambooHR, JazzHR, Recruitee, ADP WFN, Zoho Recruit, SuccessFactors, Njoyn, Teamtailor, WP Job Manager, iCIMS, Taleo Business Edition, Taleo, UltiPro/UKG, Digital Recruiters, Workland/réseau Atlas + sites carrières maison), complétés par 3 portails publics (Guichet-Emplois, Jobillico, Espresso-Jobs) — l'offre directe gagne toujours.
51	51
52		−Résultat en base (au 2026-08-24) : 21 492 offres actives de 1 653 employeurs (963 sources), dont 19 856 offres directes et 6 856 avec salaire affiché (moyenne 62 283 $/an) — salaires normalisés en $/h et $/an, jamais inventés. Chaque offre est traçable à sa source et la candidature se fait chez l'employeur. Pour qui ? Les chercheurs d'emploi québécois qui veulent l'inventaire réel, à jour et transparent, des postes affichés dans la province — resynchronisé jour et nuit.
	52	+Résultat en base (au 2026-08-28) : 22 634 offres actives de 1 733 employeurs (1 048 sources actives), dont 21 243 offres directes et 7 114 avec salaire affiché (moyenne 61 681 $/an, médiane 57 325 $/an) — salaires normalisés en $/h et $/an, jamais inventés. Chaque offre est traçable à sa source et la candidature se fait chez l'employeur. Pour qui ? Les chercheurs d'emploi québécois qui veulent l'inventaire réel, à jour et transparent, des postes affichés dans la province — resynchronisé jour et nuit.
53	53
54		−## Chiffres clés (live sur [/api/stats](https://www.job-ka.com/api/stats), vérifiés au 2026-08-24)
	54	+## Chiffres clés (live sur [/api/stats](https://www.job-ka.com/api/stats), vérifiés au 2026-08-28)
55	55
56	56	\| Métrique \| Valeur \|
57	57	\|---\|---\|
58		−\| Offres actives \| 21 492 (98 doublons inter-sources masqués, 227 en quarantaine qualité) \|
59		−\| Offres directes (pages carrières / ATS) \| 19 856 — de 1 048 employeurs directs \|
60		−\| Offres portails (complément) \| 1 863 \|
61		−\| Employeurs \| 1 653 \|
62		−\| Sources actives \| 963 (registre : 973 entrées ; 969 employeurs directs connectés via 21 plateformes ATS + 3 portails + dépôt direct) \|
63		−\| Avec salaire affiché \| 6 856 — salaire moyen affiché ≈ 62 283 $/an \|
64		−\| Télétravail \| 1 013 \|
65		−\| Offres géocodées (carte) \| 16 303 \|
66		−\| Top villes \| Montréal 7 645 · Québec 3 637 · Dorval 734 · Laval 733 \|
67		−\| Top catégories \| TI 2 699 · Santé 2 302 · Service à la clientèle 1 380 · Ventes 1 297 \|
	58	+\| Offres actives \| 22 634 (129 doublons inter-sources masqués, 570 en quarantaine qualité) \|
	59	+\| Offres directes (pages carrières / ATS) \| 21 243 — de 1 132 employeurs directs \|
	60	+\| Offres portails (complément) \| 1 959 \|
	61	+\| Employeurs \| 1 733 \|
	62	+\| Sources actives \| 1 048 (registre : 1 108 entrées dont 1 en modération ; 1 104 employeurs directs connectés via 23 plateformes ATS + 3 portails + dépôt direct) \|
	63	+\| Avec salaire affiché \| 7 114 — salaire moyen affiché ≈ 61 681 $/an (médiane 57 325 $/an) \|
	64	+\| Télétravail \| 1 044 \|
	65	+\| Offres géocodées (carte) \| 21 044 \|
	66	+\| Top villes \| Montréal 8 176 · Québec 3 908 · Laval 769 · Dorval 720 \|
	67	+\| Top catégories \| TI 2 802 · Santé 2 428 · Service à la clientèle 1 402 · Ventes 1 338 \|
68	68
69	69	## Visite guidée
70	70
71		−Captures du 2026-08-25 — refonte « éditorial premium » (mobile 390×844 · desktop 1440×900).
	71	+Captures du 2026-08-28 (desktop 1440×900) — design « éditorial premium ». Chaque capture pointe vers la page réelle sur [www.job-ka.com](https://www.job-ka.com).
	72	+
	73	+### 1. Accueil — [job-ka.com](https://www.job-ka.com/)
	74	+
	75	+<img src="docs/screenshots/01-accueil.jpg" width="760" alt="Accueil de Job·Ka — recherche d'offres et chiffres live">
	76	+
	77	+La porte d'entrée : recherche plein texte + filtres (ville, catégorie, salaire, télétravail…), chiffres clés live tirés de `/api/stats` et offres récentes. Le badge « Offre directe » distingue immédiatement les offres captées sur la page carrière de l'employeur.
	78	+
	79	+### 2. Répertoire des villes — [/villes](https://www.job-ka.com/villes)
	80	+
	81	+<img src="docs/screenshots/02-villes.jpg" width="760" alt="Répertoire des villes du Québec avec compte d'offres">
	82	+
	83	+Toutes les villes du Québec où des offres sont actives, avec leur volume — des pages SEO programmatiques rendues en HTML côté serveur (`/ville/{slug}`), indexables et rapides.
	84	+
	85	+### 3. Carte des offres — [/carte](https://www.job-ka.com/carte)
	86	+
	87	+<img src="docs/screenshots/03-carte.jpg" width="760" alt="Carte MapLibre des offres géocodées au Québec">
	88	+
	89	+Les 21 044 offres géocodées sur une carte MapLibre GL (sans jeton), alimentée par `GET /api/jobs.geojson`. Géocodage Nominatim + repli officiel Adresses Québec (MERN), validé par bounding box provinciale — jamais inventé.
	90	+
	91	+### 4. Sources — [/sources](https://www.job-ka.com/sources)
	92	+
	93	+<img src="docs/screenshots/04-sources.jpg" width="760" alt="Registre public des sources et connecteurs de Job·Ka">
	94	+
	95	+La transparence au premier plan : le registre public des 1 048 sources actives (employeurs directs par plateforme ATS + portails), avec l'état de chaque connecteur. Chaque offre est traçable à son origine.
	96	+
	97	+### 5. Observatoire de l'emploi — [/stats](https://www.job-ka.com/stats)
	98	+
	99	+<img src="docs/screenshots/05-stats.jpg" width="760" alt="Statistiques de l'emploi au Québec — tableau de bord Job·Ka">
	100	+
	101	+Le tableau de bord analytique (kit stats v3 Groupe KA) : volumes par ville, catégorie, salaire, mode de travail… avec rapports PDF téléchargeables, y compris des rapports personnalisés.
	102	+
	103	+### 6. Espace employeurs — [/employeurs](https://www.job-ka.com/employeurs)
	104	+
	105	+<img src="docs/screenshots/06-employeurs.jpg" width="760" alt="Dépôt direct d'offres par les employeurs">
	106	+
	107	+Les employeurs québécois peuvent déposer leurs offres directement (`POST /api/employeurs/offres`) — modération manuelle avant publication.
	108	+
	109	+### 7. Contact — [/contact](https://www.job-ka.com/contact)
	110	+
	111	+<img src="docs/screenshots/07-contact.jpg" width="760" alt="Page contact de Job·Ka">
	112	+
	113	+Contact direct avec le Groupe KA — questions, retraits, partenariats, signalements.
	114	+
	115	+### 8. Page ville — [/ville/montreal](https://www.job-ka.com/ville/montreal)
	116	+
	117	+<img src="docs/screenshots/08-ville-montreal.jpg" width="760" alt="Offres d'emploi à Montréal sur Job·Ka">
	118	+
	119	+L'exemple type des pages villes : 8 176 offres à Montréal, filtrables sur place, avec métriques claires (salaire affiché, séniorité, mode de travail) issues de l'enrichissement des connecteurs.
	120	+
	121	+### 9. Fiche d'offre — [/emploi/{uid}](https://www.job-ka.com/emploi/4refuel%3A5666)
	122	+
	123	+<img src="docs/screenshots/09-emploi-4refuel-3A5666.jpg" width="760" alt="Fiche d'offre Job·Ka — candidature directe chez l'employeur">
	124	+
	125	+Une fiche complète (ici un poste chez 4Refuel, capté directement sur son ATS Dayforce) : description, salaire normalisé, exigences, localisation, JSON-LD JobPosting pour le SEO — et le bouton Postuler qui mène chez l'employeur, jamais ailleurs.
	126	+
	127	+### 10. Favoris « Mon univers Ka » — [/favoris](https://www.job-ka.com/favoris)
	128	+
	129	+<img src="docs/screenshots/10-favoris.jpg" width="760" alt="Page favoris — Mon univers Ka">
	130	+
	131	+Les offres sauvegardées avec le cœur, synchronisées via KA ID (le SSO du Groupe KA) — le même compte retrouve ses favoris sur les 13 sites de l'écosystème.
	132	+
	133	+<details>
	134	+<summary>📷 Captures précédentes (refonte du 2026-08-25, mobile + desktop)</summary>
72	135
73	136	### Mobile
74	137
		`@@ -102,16 +165,18 @@ Résultat en base (au 2026-08-24) : 21 492 offres actives de **1 653 employe`
102	165	</tr>
103	166	</table>
104	167
	168	+> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
	169	+
	170	+</details>
	171	+
105	172	### Nouveautés front-end (2026-08-25)
106	173
107	174	- Refonte visuelle majeure — design éditorial premium sur tout le site.
108		−- Affichage des offres repensé — métriques claires (salaire, exigences, séniorité) issues de l'enrichissement des 1 050+ connecteurs (phase 3).
109		−- Vagues D et E de connecteurs ATS — +135 employeurs (JazzHR, Teamtailor, Zoho Recruit…), 1 044+ employeurs suivis.
	175	+- Affichage des offres repensé — métriques claires (salaire, exigences, séniorité) issues de l'enrichissement des 1 100+ connecteurs (phase 3).
	176	+- Vagues D et E de connecteurs ATS — +135 employeurs (JazzHR, Teamtailor, Zoho Recruit…).
110	177	- Nav mobile v2 — hamburger + panneau plein écran (standard KA 2026-08-25).
111	178	- Widget ka-agent v4 — cartes d'offres cliquables et choix en boutons.
112	179
113		−> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).
114		−
115	180	### Guide pas à pas (« Utiliser le site en 4 étapes », depuis [/doc](https://www.job-ka.com/doc/))
116	181
117	182	<table>
		`@@ -137,26 +202,27 @@ Résultat en base (au 2026-08-24) : 21 492 offres actives de **1 653 employe`
137	202	- Dépôt direct employeurs — `/employeurs` (`POST /api/employeurs/offres`), modération manuelle.
138	203	- SEO programmatique — SSR léger (accueil, fiches JSON-LD JobPosting, pages statiques), robots.txt, sitemaps, pages `/villes` + `/ville/{slug}` rendues en HTML.
139	204	- Page /stats — tableau de bord analytique + rapports PDF Groupe-KA (kit kacharts/kapdf v3, rapports personnalisés) ; favoris « Mon univers Ka » (KA ID, cœur sur cartes et fiche, page `/favoris`).
140		−- Conformité documentée — `docs/CONFORMITE.md` (base d'accès par famille de sources, attribution, zéro donnée personnelle de candidat) + une fiche générée par connecteur dans `docs/connecteurs/` (995 fiches).
	205	+- Conformité documentée — `docs/CONFORMITE.md` (base d'accès par famille de sources, attribution, zéro donnée personnelle de candidat) + une fiche générée par connecteur dans `docs/connecteurs/` (1 133 fiches).
141	206	- Tests hors ligne — 74 tests pytest : fixtures HTTP enregistrées et rejouées, invariants (uid uniques, URLs absolues, salaires plausibles).
	207	+- Supervision par agents gardiens — les connecteurs sont surveillés en continu (gardien ka6) : chaque panne de source est diagnostiquée (panne externe vs bug), documentée dans le connecteur et commitée — un sync en échec ne purge jamais rien.
142	208
143	209	## Connecteurs & sources
144	210
145	211	\| Famille \| Détail \| Volume \|
146	212	\|---\|---\|---\|
147		−\| Employeurs directs (ATS) \| 969 connecteurs sur 21 plateformes : Workday (206 employeurs), SmartRecruiters (158), Greenhouse (129), Dayforce (122), Breezy (72), Workable (70), Lever (57), Ashby (40), BambooHR (34), Recruitee (30), SuccessFactors (9), WP Job Manager (8), Njoyn (6), Taleo Business Edition (6), iCIMS (6), ADP WFN (5), Taleo (4), UltiPro/UKG (3), Digital Recruiters (2), réseau Atlas Workland (1 connecteur ≈ 80 employeurs QC), sites maison \| 19 856 offres directes (au 2026-08-24) \|
	213	+\| Employeurs directs (ATS) \| 1 104 connecteurs sur 23 plateformes : Workday (233 employeurs), SmartRecruiters (172), Greenhouse (131), Dayforce (128), Breezy (72), Workable (71), Lever (58), Ashby (41), BambooHR (37), JazzHR (31), Recruitee (30), ADP WFN (17), Zoho Recruit (17), SuccessFactors (11), Njoyn (11), Teamtailor (9), WP Job Manager (8), iCIMS (7), Taleo Business Edition (7), Taleo (5), UltiPro/UKG (4), Digital Recruiters (2), réseau Atlas Workland (1 connecteur ≈ 80 employeurs QC) + sites carrières maison \| 21 243 offres directes de 1 132 employeurs (au 2026-08-28) \|
148	214	\| Sites carrières maison \| pages carrières sans ATS standard (certaines via Scrapfly) \| inclus ci-dessus \|
149		−\| Portails publics \| Guichet-Emplois, Jobillico, Espresso-Jobs — complément, jamais prioritaire sur l'offre directe \| 1 863 offres \|
	215	+\| Portails publics \| Guichet-Emplois, Jobillico, Espresso-Jobs — complément, jamais prioritaire sur l'offre directe \| 1 959 offres \|
150	216	\| Dépôt direct \| formulaire `/employeurs`, modération manuelle \| à la demande \|
151	217
152		−Registre descriptif : `data/sources.json` (973 entrées, dont 1 en modération) ; une fiche de conformité par connecteur dans `docs/connecteurs/` (995 fiches, index : `docs/connecteurs/INDEX.md`, régénérables par `scripts/gen_connector_docs.py`).
	218	+Registre descriptif : `data/sources.json` (1 108 entrées, dont 1 en modération) ; une fiche de conformité par connecteur dans `docs/connecteurs/` (1 133 fiches, index : `docs/connecteurs/INDEX.md`, régénérables par `scripts/gen_connector_docs.py`).
153	219
154	220	Cadence de resync : horaire, jour et nuit — le watcher PM2 `job-ka-sync` (`run.py watch 60`) enchaîne sync + géocodage + déduplication ; le diff engine par `content_hash` gère le cycle de vie (retrait après 2 syncs d'absence, anti-dérive à ≤ 25 % de la médiane historique). Les connecteurs fragiles passent par une chaîne de fetch anti-bot résiliente (Oxylabs → Scrapfly → Bright Data).
155	221
156	222	## Architecture
157	223
158	224	```
159		−Sources (21 plateformes ATS + sites maison + 3 portails)
	225	+Sources (23 plateformes ATS + sites maison + 3 portails)
160	226	→ connecteurs auto-découverts (jobka/connectors/)
161	227	→ finalize() — normalisation commune (schema.py, normalize.py)
162	228	→ SQLite data/jobka.db — diff par content_hash, cycle de vie, anti-dérive (db.py)
		`@@ -192,19 +258,19 @@ Sources (21 plateformes ATS + sites maison + 3 portails)`
192	258	- Attribution : chaque offre conserve son URL originale ; la candidature se fait chez l'employeur (badge « Offre directe » sur les sources directes).
193	259	- Cadence : resync horaire jour et nuit (`run.py watch 60`) ; retrait doux après 2 syncs d'absence ; anti-dérive à ≤ 25 % de la médiane historique.
194	260	- Salaires : jamais inventés — signe monétaire ou unité explicite obligatoire, bornes de plausibilité, conversion $/h ↔ $/an documentée.
195		−- Traçabilité : 995 fiches de conformité générées (`docs/connecteurs/`), registre `data/sources.json` auditable (sources écartées documentées avec raisons).
	261	+- Traçabilité : 1 133 fiches de conformité générées (`docs/connecteurs/`), registre `data/sources.json` auditable (sources écartées documentées avec raisons).
196	262
197	263	## Structure du repo
198	264
199	265	\| Répertoire / fichier \| Rôle \|
200	266	\|---\|---\|
201	267	\| `jobka/` \| paquet Python : schéma `JobPosting`, normalisation, DB/diff, ingestion, dédup, géocodage, quarantaine qualité, web/API, stats, PDF, auth KA ID \|
202		−\| `jobka/connectors/` \| base commune + 21 plateformes ATS + ~970 connecteurs (1 fichier = 1 employeur) + portails — 995 modules au total \|
	268	+\| `jobka/connectors/` \| base commune + 23 plateformes ATS + ~1 100 connecteurs (1 fichier = 1 employeur) + portails — 1 133 modules au total \|
203	269	\| `frontend/` \| React 18 + Vite + TS (carte MapLibre) — `dist/` non versionné ; guide `/doc` dans `frontend/public/doc/` \|
204		−\| `data/` \| `sources.json` (registre descriptif, 973 entrées) + `jobka.db` (non versionnée) \|
	270	+\| `data/` \| `sources.json` (registre descriptif, 1 108 entrées) + `jobka.db` (non versionnée) \|
205	271	\| `tests/` \| pytest : normalisation + rejeu hors ligne des fixtures connecteurs — 74 tests \|
206	272	\| `scripts/` \| `check_headers.py` (en-tête d'auteur obligatoire), `gen_connector_docs.py` (fiches connecteurs), `probe_ats.py` + éclaireur Serper (campagnes connecteurs) \|
207		−\| `docs/` \| `CONFORMITE.md`, `connecteurs/` (995 fiches + INDEX), `deploiement.md`, captures d'écran \|
	273	+\| `docs/` \| `CONFORMITE.md`, `connecteurs/` (1 133 fiches + INDEX), `deploiement.md`, `screenshots/` (visite guidée) \|
208	274	\| `run.py` \| CLI : `sync` · `watch` · `serve` · `geocode` · `record` \|
209	275	\| `requirements.txt` \| fastapi, uvicorn, requests, beautifulsoup4, fpdf2 \|
210	276
		@@ -267,7 +333,7 @@ Détails : `docs/deploiement.md`.
267	333
268	334	- Guide utilisateur en ligne : [www.job-ka.com/doc/](https://www.job-ka.com/doc/) — à quoi sert le site, utilisation en 4 étapes, provenance des données, FAQ.
269	335	- Guide PDF téléchargeable : [job-ka-documentation.pdf](https://www.job-ka.com/doc/job-ka-documentation.pdf).
270		−- Conformité & connecteurs : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/` (995 fiches, index : `docs/connecteurs/INDEX.md`).
	336	+- Conformité & connecteurs : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/` (1 133 fiches, index : `docs/connecteurs/INDEX.md`).
271	337
272	338	## Historique
273	339
		@@ -278,6 +344,8 @@ Détails : `docs/deploiement.md`.
278	344	\| 2026-08-22 \| vague B : +110 sources (dont la famille Dayforce, 26 connecteurs) ; SEO SSR (fiches JobPosting, sitemaps) ; chaîne de fetch anti-bot résiliente ; page Publier \|
279	345	\| 2026-08-23 \| vague C : +620 connecteurs employeurs directs (350 → 968) ; SEO villes programmatique ; stats v3 (rapports PDF personnalisés) ; favoris « Mon univers Ka » \|
280	346	\| 2026-08-24 \| page `/doc` (guide + captures + PDF), README v3 — état : 969 employeurs directs, 21 plateformes ATS, 21 492 offres actives \|
	347	+\| 2026-08-25 \| refonte « éditorial premium » + vagues D-E : +135 employeurs (nouvelles familles JazzHR, Teamtailor, Zoho Recruit) ; nav mobile v2 ; widget ka-agent v4 \|
	348	+\| 2026-08-28 \| README v4 + visite guidée en 10 captures (`docs/screenshots/`) — état : 1 104 connecteurs directs sur 23 plateformes ATS, 22 634 offres actives de 1 733 employeurs \|
281	349
282	350	## Écosystème Groupe KA
283	351

added docs/screenshots/01-accueil.jpg +0 −0

Binary file not shown.

added docs/screenshots/02-villes.jpg +0 −0

Binary file not shown.

added docs/screenshots/03-carte.jpg +0 −0

Binary file not shown.

added docs/screenshots/04-sources.jpg +0 −0

Binary file not shown.

added docs/screenshots/05-stats.jpg +0 −0

Binary file not shown.

added docs/screenshots/06-employeurs.jpg +0 −0

Binary file not shown.

added docs/screenshots/07-contact.jpg +0 −0

Binary file not shown.

added docs/screenshots/08-ville-montreal.jpg +0 −0

Binary file not shown.

added docs/screenshots/09-emploi-4refuel-3A5666.jpg +0 −0

Binary file not shown.

added docs/screenshots/10-favoris.jpg +0 −0

Binary file not shown.