docs: README ultra détaillé + visite guidée en 10 captures · d5ebd56 · groupe-ka

47

48

</div>

49

50

−**Groupe·Ka** ([www.groupe-ka.com](https://www.groupe-ka.com)) est le **hub central de l'écosystème ·Ka**. Il joue trois rôles : la **vitrine du groupe** (présentation des plateformes québécoises, métriques live tirées en direct des `/api/stats` de chaque site, pages corporatives `/agents`, `/investisseurs`, `/telecharger`, `/marque`) ; le **KA ID**, l'identité centrale du groupe — un seul compte (courriel + mot de passe, Google, Apple) et un `ka_id` partagé par toutes les plateformes via un **SSO maison** ; et une **tour de contrôle publique** — pages `/status` (disponibilité de **16 cibles** : les 13 sites de l'écosystème + les 3 agents gardiens ka2.bot/ka4.bot/ka6.bot, historique 90 jours, ticks aux 5 min) et `/stats` (tableau de bord maître consolidé).

50

+## Présentation & mission

51

52

−Pour qui ? Les visiteurs qui découvrent le groupe, les membres qui gèrent leur compte KA ID (profil, favoris « Mon univers Ka », carte de membre, jeton API personnel), et les investisseurs (dossier corporatif PDF).

52

+**Groupe·Ka** ([www.groupe-ka.com](https://www.groupe-ka.com)) est le **hub central de l'écosystème ·Ka** — la constellation d'agrégateurs automatisés du groupe, née au Québec et désormais étendue au Canada (House·Ka, Rent·Ka). Le hub joue trois rôles :

53

+

54

+1. **La vitrine du groupe** — présentation des plateformes, métriques live tirées en direct des `/api/stats` de chaque site, pages corporatives `/agents`, `/investisseurs`, `/telecharger`, `/marque`.

55

+2. **Le KA ID**, l'identité centrale du groupe — un seul compte (courriel + mot de passe, Google, Apple, lien magique) et un `ka_id` partagé par toutes les plateformes via un **SSO maison**, avec carte de membre, passe Apple Wallet, favoris unifiés et un **moteur de personnalisation** (« Mon univers Ka » / `/mon-ka`).

56

+3. **Une tour de contrôle publique** — pages `/status` (disponibilité de **19 cibles** : les 16 sites d'`ecosystem.json` + les 3 agents gardiens ka2.bot/ka4.bot/ka6.bot, historique 90 jours, ticks aux 5 min) et `/stats` (tableau de bord maître consolidé).

57

+

58

+Pour qui ? Les visiteurs qui découvrent le groupe, les membres qui gèrent leur compte KA ID (profil, favoris « Mon univers Ka », carte de membre, jeton API personnel, alertes personnalisées), et les investisseurs (dossier corporatif PDF).

59

+

60

+## Sommaire

61

+

62

+- [Visite guidée (10 captures)](#visite-guidée)

63

+- [KA ID — l'identité centrale](#ka-id--lidentité-centrale)

64

+- [Fonctionnalités](#fonctionnalités)

65

+- [Pages & routes](#pages--routes)

66

+- [API](#api-54-routes)

67

+- [Métriques live consolidées](#métriques-live-consolidées-sources)

68

+- [Architecture](#architecture)

69

+- [Transparence, données & conformité](#données--conformité)

70

+- [Déploiement](#déploiement) · [Développement remote-first](#développement-remote-first)

71

+- [L'écosystème en images](#lécosystème-en-images) · [Écosystème Groupe KA](#écosystème-groupe-ka)

72

+- [Contact](#contact)

53

73

54

74

## Visite guidée

55

75

56

−*Captures du 2026-08-25 — accueil v2 « HQ » (mobile 390×844 · desktop 1440×900).*

76

+*10 captures desktop du **2026-08-28** — l'état actuel du hub, page par page, telles que servies sur www.groupe-ka.com.*

77

+

78

+### 1 · Accueil — « Mille sites. Un seul ·Ka. »

79

+

80

+![Accueil du hub Groupe·Ka](docs/screenshots/01-accueil.jpg)

81

+

82

+La page d'accueil « HQ » v2 : héros géant, banderole carrousel des marques du groupe, figures d'agrégation **live** (tirées en direct des `/api/stats` de chaque plateforme, cache ISR 10 min) et index des plateformes en filets — House·Ka et Rent·Ka y sont intégrés partout depuis le 2026-08-28.

83

+

84

+### 2 · Contact — le guichet unique du groupe

85

+

86

+![Page contact](docs/screenshots/02-contact.jpg)

87

+

88

+Le formulaire `/contact` alimente le **hub de communication interne** (fini les courriels publics exposés) : chaque soumission arrive dans la console d'administration, où l'équipe la traite, l'annote et y répond via les boîtes courriel du groupe (Resend).

89

+

90

+### 3 · Recherche — tout l'écosystème en une barre

91

+

92

+![Recherche globale](docs/screenshots/03-recherche.jpg)

93

+

94

+`/recherche` interroge le moteur **Trouve·Ka** et cherche d'un coup dans toutes les plateformes du groupe : logements, propriétés, véhicules, produits, restos, sorties, emplois, créateurs… Résultats typés avec l'accent de couleur de chaque univers.

95

+

96

+### 4 · Stats — le tableau de bord maître

97

+

98

+![Tableau de bord maître /stats](docs/screenshots/04-stats.jpg)

99

+

100

+`/stats` consolide en direct les métriques de tout l'écosystème : KPI par plateforme, sparklines, croissance en indice 100, et le **ReportBuilder** pour composer un rapport PDF personnalisé à partir du catalogue de métriques.

101

+

102

+### 5 · Rapports — la mémoire quotidienne du groupe

103

+

104

+![Rapports quotidiens](docs/screenshots/05-rapports.jpg)

105

+

106

+`/rapports` archive le **rapport quotidien automatisé** : chaque matin à 6 h, une rédaction générée par Claude + un PDF sont produits et publiés sur `/rapports/[date]` — l'historique complet reste consultable.

107

+

108

+### 6 · Status — la tour de contrôle publique

109

+

110

+![Page status](docs/screenshots/06-status.jpg)

111

+

112

+`/status` vérifie **19 cibles** (les 16 sites d'`ecosystem.json` + les agents gardiens ka2/ka4/ka6.bot) : état en direct, temps de réponse, barres d'**uptime 24 h / 7 j / 30 j** sur un historique de 90 jours alimenté par un tick PM2 aux 5 minutes.

57

113

58

−### Mobile

114

+### 7 · Télécharger — les apps natives

115

+

116

+![Page télécharger](docs/screenshots/07-telecharger.jpg)

117

+

118

+`/telecharger` distribue les applications du groupe : iOS (TestFlight), APK Android signé (avec SHA-256 publié) et DMG macOS notarié — le registre officiel des versions.

119

+

120

+### 8 · Marque — l'identité visuelle des univers

121

+

122

+![Page marque](docs/screenshots/08-marque.jpg)

123

+

124

+`/marque` expose l'identité de chaque plateforme : logos téléchargeables, palettes d'accents officielles et bannières — la source publique du design system **ka-ui** partagé par tout l'écosystème.

125

+

126

+### 9 · Avis — notre rôle d'agrégateur

127

+

128

+![Page avis](docs/screenshots/09-avis.jpg)

129

+

130

+`/avis` explique noir sur blanc ce que le groupe est (un agrégateur d'informations publiques) et n'est pas (ni courtier, ni vendeur, ni intermédiaire) : provenance des données, limites, et comment demander une correction ou un retrait.

131

+

132

+### 10 · Bots — la déclaration de transparence

133

+

134

+![Page bots](docs/screenshots/10-bots.jpg)

135

+

136

+`/bots` est la déclaration de transparence des robots d'indexation du groupe : données publiques uniquement, respect de `robots.txt`, identification claire des user-agents — l'engagement de collecte responsable, publié.

137

+

138

+### Galerie mobile & desktop (2026-08-25)

139

+

140

+*Captures d'époque de l'accueil v2 « HQ » (mobile 390×844 · desktop 1440×900).*

59

141

60

142

<table>

61

143

<tr>

65

147

</tr>

66

148

<tr>

67

149

<td align="center"><img src="docs/screenshots/mobile/rapports.webp" width="240" alt="Rapports mobile"> Rapports PDF quotidiens et personnalisés</td>

68

− <td align="center"><img src="docs/screenshots/mobile/marque.webp" width="240" alt="Marque mobile"> Page marque — logos des 13 univers</td>

150

+ <td align="center"><img src="docs/screenshots/mobile/marque.webp" width="240" alt="Marque mobile"> Page marque — logos des univers</td>

69

151

<td align="center"><img src="docs/screenshots/mobile/menu-mobile.webp" width="240" alt="Menu mobile"> Nav v2 — panneau plein écran</td>

70

152

</tr>

71

153

</table>

72

154

73

−### Desktop

74

−

75

155

<table>

76

156

<tr>

77

157

<td align="center"><img src="docs/screenshots/desktop/home.webp" width="420" alt="Accueil desktop"> Accueil HQ v2 — héros géant, bandes d'encre, index des plateformes en filets</td>

90

170

</tr>

91

171

</table>

92

172

93

−### Nouveautés front-end (2026-08-25)

173

+### Nouveautés récentes (2026-08-25 → 28)

94

174

95

−- **Accueil v2 « HQ »** — recomposition éditoriale majeure : héros géant, bandes d'encre pleine largeur, index des plateformes en filets, figures redessinées, nav épurée.

175

+- **Accueil v2 « HQ »** — recomposition éditoriale majeure : héros géant, bandes d'encre pleine largeur, index des plateformes en filets, figures redessinées, nav épurée ; banderole carrousel des marques sous le héros (2026-08-28).

176

+- **House·Ka et Rent·Ka rejoignent l'écosystème** (2026-08-27) — maisons à vendre et loyers **Canada hors Québec**, intégrés à `ecosystem.json`, au SSO KA ID, aux figures d'accueil, à `/status` et aux alertes.

177

+- **KA ID v2 — moteur de personnalisation** (2026-08-26) — feature store central, page `/mon-ka`, alertes actives par courriel, filtrage collaboratif et matrix factorization (voir la section [KA ID](#ka-id--lidentité-centrale)).

178

+- **Hub de communication interne** (2026-08-26) — fini les courriels publics : formulaire `/contact` → console admin, boîtes courriel du groupe via Resend (envoi, réception webhook, pièces jointes, gabarits signés).

96

179

- **Widget ka-agent v4** — cartes d'annonces cliquables (ka-card, palette écosystème) et choix de clarification en boutons (ka-choix).

97

180

- **Jeton API personnel** (API·Ka) par KA ID + rapports PDF personnalisés (stats v3).

98

−- **/status** surveille 16 cibles : les 13 sites + les 3 agents gardiens ka2/ka4/ka6.bot.

99

181

100

182

> 🗄️ Les captures d'époque sont conservées dans [`docs/archive/`](docs/archive/).

101

183

102

−## Fonctionnalités

184

+## KA ID — l'identité centrale

185

+

186

+Le KA ID est la pièce maîtresse du hub : **un seul compte pour tout l'écosystème**.

103

187

104

−- **KA ID** — identifiant membre unique (`ka-` + 10 chiffres) créé au hub, source de vérité de tout le groupe.

105

−- **Trois modes de connexion** : Google OAuth 2.0, Sign in with Apple, courriel + mot de passe (scrypt natif Node, zéro dépendance).

106

−- **SSO maison** vers les 12 plateformes et les apps natives — **16 clients au registre** (`src/lib/sso.ts`) : les 12 plateformes actives, les apps `ka-ios` et `ka-android`, plus les alias historiques Ora·Ka et Toit·Ka — jeton JWT signé par plateforme, valide 5 min (`/sso/authorize?client=<plateforme>`).

188

+- **Identifiant membre unique** (`ka-` + 10 chiffres) créé au hub, source de vérité de tout le groupe.

189

+- **Quatre modes de connexion** : Google OAuth 2.0, Sign in with Apple, courriel + mot de passe (scrypt natif Node, zéro dépendance), et **lien magique** sans mot de passe ; **vérification d'adresse** à l'inscription et **2FA par code courriel** au login mot de passe (courriels transactionnels Resend).

190

+- **SSO maison** vers les plateformes et les apps natives — **18 clients au registre** (`src/lib/sso.ts`) : les 14 plateformes actives (dont House·Ka et Rent·Ka depuis le 2026-08-27), les apps `ka-ios` et `ka-android`, plus les alias historiques Ora·Ka et Toit·Ka — jeton JWT signé par plateforme, valide 5 min (`/sso/authorize?client=<plateforme>`).

107

191

- **Profil enrichi** (bio, ville, réseaux sociaux, rôle) affiché par toutes les plateformes, avec page publique `/u/[kaId]`.

108

192

- **Favoris unifiés « Mon univers Ka »** — magasin central ; les plateformes poussent et lisent via `/api/sso/favorites`.

193

+- **Personnalisation v2 (`/mon-ka`)** — feature store central : journal d'interactions (le hub journalise aussi les favorite/unfavorite reçus par SSO pour couvrir les plateformes sans instrumentation), recherches sauvegardées avec **alertes courriel actives** (évaluées sur les API publiques, adaptateurs 9 apps, cadence choisie par le membre), éléments masqués, profil de préférences avec décroissance 30 j et signaux négatifs, filtrage collaboratif item-item par co-favoris, et **matrix factorization implicite** (ALS Hu-Koren-Volinsky, cron quotidien) qui s'active seule dès que le volume le permet. Le tout servi aux plateformes par les endpoints s2s HMAC `/api/sso/{events,prefs,saved-searches,hide}`.

194

+- **Confidentialité Loi 25 intégrée** — dans `/mon-ka` : 3 interrupteurs de consentement, effacement, réinitialisation et **export JSON** de ses données.

109

195

- **Carte de membre** avec QR code + passe **Apple Wallet** signée (`/api/wallet/pass`).

110

196

- **Jeton API personnel** (`kapi_`) généré depuis `/compte` pour l'API·Ka.

111

−- **Page `/status`** — 16 cibles vérifiées en direct (13 sites + agents ka2/ka4/ka6) + historique de disponibilité 90 jours (`data/status/history.jsonl`, ticks aux 5 min), uptime 24 h / 7 j / 30 j.

197

+

198

+## Fonctionnalités

199

+

200

+- **Page `/status`** — 19 cibles vérifiées en direct (16 sites + agents ka2/ka4/ka6) + historique de disponibilité 90 jours (`data/status/history.jsonl`, ticks aux 5 min), uptime 24 h / 7 j / 30 j.

112

201

- **Page `/stats`** — consolidation live des métriques de l'écosystème + rapports PDF personnalisés (`/rapports`, catalogue et ReportBuilder).

113

202

- **Rapport quotidien automatisé** — rédaction Claude + PDF chaque matin (6 h), archivé sur `/rapports/[date]`.

114

203

- **Recherche écosystème** — barre dans le header + page `/recherche` propulsée par le moteur Trouve·Ka.

115

−- **Pages corporatives** : `/agents` (agents gardiens ka2/ka4/ka6), `/investisseurs` (6 documents corporatifs PDF), `/telecharger` (apps iOS/Android/macOS), `/avis`, `/bots`, `/marque` (logos + palettes des 13 plateformes).

204

+- **Hub de communication interne** — formulaire `/contact` → console `/admin` (soumissions, notes, réponses) + boîtes courriel du groupe via Resend (webhook entrant, pièces jointes, gabarits signés Groupe KA).

205

+- **Pages corporatives** : `/agents` (agents gardiens ka2/ka4/ka6), `/investisseurs` (6 documents corporatifs PDF), `/telecharger` (apps iOS/Android/macOS), `/avis`, `/bots`, `/marque` (logos + palettes des plateformes).

116

206

- **Conformité** : `/loi-25`, `/conditions`, `/confidentialite`, `/retrait` (droit de retrait des données).

117

−- **KA Agent** — bulle de chat IA du groupe (`public/ka-agent.js`) câblée sur toutes les pages (v3 : déplaçable, plein écran, Markdown streaming).

207

+- **KA Agent** — bulle de chat IA du groupe (`public/ka-agent.js`) câblée sur toutes les pages (v4 : cartes d'annonces cliquables + choix en boutons ; déplaçable, plein écran, Markdown streaming).

118

208

- **ka-ui vendoré** (`src/ka/` + `ecosystem.json`) — design system, accents officiels et footer partagés de l'écosystème.

119

209

120

−## API (25 routes)

210

+## Pages & routes

121

211

122

−Toutes les routes vivent dans `src/app/api/` (App Router Next.js) — **25 fichiers `route.ts`** au total.

212

+Toutes les pages vivent dans `src/app/` (App Router). Vue d'ensemble :

213

+

214

+| Route | Rôle |

215

+|---|---|

216

+| `/` | accueil « HQ » — héros, banderole des marques, figures live, index des plateformes |

217

+| `/recherche` | recherche globale de l'écosystème (moteur Trouve·Ka) |

218

+| `/stats` | tableau de bord maître consolidé + ReportBuilder |

219

+| `/rapports` · `/rapports/[date]` | rapports quotidiens automatisés (rédaction Claude + PDF), archivés |

220

+| `/status` | tour de contrôle publique — 19 cibles, uptime 24 h / 7 j / 30 j, historique 90 j |

221

+| `/connexion` | connexion KA ID (Google, Apple, courriel + mot de passe, lien magique, 2FA) |

222

+| `/compte` · `/compte/carte` | gestion du compte : profil, avatar, rôle, favoris, jeton `kapi_`, carte de membre + Wallet |

223

+| `/mon-ka` | personnalisation : « Pour vous », « Ce que KA a appris » (corrigeable), recherches + alertes, confidentialité Loi 25 |

224

+| `/u/[kaId]` | page publique d'un membre |

225

+| `/sso/authorize` | point d'entrée SSO des plateformes clientes |

226

+| `/agents` | les agents IA du groupe (gardiens ka2/ka4/ka6) |

227

+| `/investisseurs` | dossier corporatif — 6 documents PDF |

228

+| `/telecharger` | apps natives iOS / Android / macOS |

229

+| `/marque` | identité visuelle : logos, palettes, bannières téléchargeables |

230

+| `/contact` · `/nous-joindre` | guichet unique — alimente le hub de communication interne |

231

+| `/avis` | avis : notre rôle d'agrégateur |

232

+| `/bots` | déclaration de transparence des robots d'indexation |

233

+| `/loi-25` · `/conditions` · `/confidentialite` · `/retrait` | conformité et droit de retrait |

234

+| `/admin` | console interne (connexion dédiée) : soumissions de contact, boîtes courriel, équipe |

235

+| `/doc/` | guide en ligne + PDF (servi depuis `public/doc/`) |

236

+

237

+## API (54 routes)

238

+

239

+Toutes les routes vivent dans `src/app/api/` (App Router Next.js) — **54 fichiers `route.ts`** au total, regroupés par domaine :

123

240

124

241

| Méthode(s) & route | Rôle |

125

242

|---|---|

126

243

| `POST /api/auth/register` · `POST /api/auth/login` · `POST /api/auth/logout` | comptes courriel + mot de passe (scrypt) |

244

+| `POST /api/auth/2fa` · `/api/auth/magic` · `/api/auth/magic/verify` · `/api/auth/email/verify` | 2FA par code courriel, lien magique, vérification d'adresse (Resend) |

127

245

| `GET /api/auth/google` · `GET /api/auth/callback/google` | connexion Google OAuth 2.0 (vérification `id_token` par JWKS) |

128

246

| `GET /api/auth/apple` · `POST /api/auth/callback/apple` | Sign in with Apple (`client_secret` ES256 signé à la volée) |

129

247

| `GET /api/auth/me` | session courante (témoin HttpOnly `ka_session`, HS256, 30 jours) |

130

248

| `GET/POST /api/profile` · `/api/profile/avatar` · `/api/profile/public` · `/api/profile/role` | profil enrichi + avatar (sharp) + page publique `/u/[kaId]` |

131

−| `GET/POST /api/sso/favorites` · `/api/sso/profile` · `/api/sso/token-verify` | contrats SSO consommés par les 12 plateformes |

249

+| `GET/POST /api/sso/favorites` · `/api/sso/profile` · `/api/sso/token-verify` | contrats SSO consommés par les plateformes |

250

+| `/api/sso/events` · `/api/sso/prefs` · `/api/sso/saved-searches` · `/api/sso/hide` | personnalisation s2s (HMAC) : journal d'interactions, profil de préférences + recos MF, recherches sauvegardées, éléments masqués |

132

251

| `GET/POST /api/favorites` | favoris « Mon univers Ka » du membre connecté |

252

+| `/api/monka/prefs` · `/api/monka/searches` · `/api/monka/privacy` · `/api/monka/export` | page `/mon-ka` : préférences corrigeables, alertes, consentements Loi 25, export JSON |

253

+| `GET /api/kaid/alerts/tick` | évaluation des alertes de recherches sauvegardées (clé `KAID_TICK_KEY`, cron PM2 horaire) |

133

254

| `POST /api/account/token` | génération du jeton API personnel `kapi_` |

134

255

| `GET /api/wallet/pass` | passe Apple Wallet signée (carte de membre) |

256

+| `POST /api/contact` · `POST /api/mail/inbound` | soumission du formulaire de contact ; webhook courriel entrant (Resend) |

257

+| `/api/admin/*` (15 routes) | console interne : login/logout/badge, soumissions (notes, réponses), boîtes courriel (envoi, aperçu, pièces jointes), équipe, mot de passe |

135

258

| `GET /api/stats/report` · `/api/stats/catalog` · `POST /api/stats/report/custom` · `GET /api/stats/ecosystem-report` | rapports PDF (plateforme, catalogue, personnalisés, écosystème) |

136

259

| `GET /api/rapports/[date]/pdf` | rapport quotidien archivé |

137

−| `GET /api/status/tick` | tick de disponibilité — vérifie les 16 cibles et enregistre l'historique (appelé aux 5 min par PM2 ; ⚠️ effet de bord, ne pas l'appeler en boucle) |

260

+| `GET /api/status/tick` | tick de disponibilité — vérifie les 19 cibles et enregistre l'historique (appelé aux 5 min par PM2 ; ⚠️ effet de bord, ne pas l'appeler en boucle) |

138

261

| `GET /api/health` | santé du service → `{"status":"ok","app":"groupe-ka"}` |

139

262

140

263

## Métriques live consolidées (sources)

141

264

142

−Le hub tire ses chiffres **en direct** des endpoints publics des plateformes (`src/lib/live.ts`, cache serveur ISR 10 min, valeurs de repli en cas de panne). Instantané **au 2026-08-24** :

265

+Le hub tire ses chiffres **en direct** des endpoints publics des plateformes (`src/lib/live.ts`, cache serveur ISR 10 min, valeurs de repli en cas de panne). Instantané **au 2026-08-24** (House·Ka/Rent·Ka au 2026-08-28) :

143

266

144

−| Plateforme | Endpoint consommé | Volume live (au 2026-08-24) |

267

+| Plateforme | Endpoint consommé | Volume live |

145

268

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

146

269

| Lou·Ka | `lou-ka.com/api/stats` | 45 762 logements · 190 sources |

147

270

| Immo·Ka | `immo-ka.com/api/stats` | 67 735 propriétés · 48 sources · 3 273 villes |

271

+| House·Ka | `house-ka.com/api/stats` | 260 279 maisons (Canada) · ~5 900 villes |

272

+| Rent·Ka | `rent-ka.com/api/stats` | 8 955 loyers (Canada) · 78 sources |

148

273

| Vrai-Prix | `vrai-prix.com/api/stats` | 3 747 008 unités évaluées · 1 097 municipalités |

149

274

| Auto·Ka | `auto-ka.com/api/stats` | 48 388 véhicules · 129 sources |

150

275

| Fabri·Ka | `fabri-ka.com/api/stats` | 385 308 produits · 1 582 boutiques live |

158

283

159

284

## Architecture

160

285

161

−- **Next.js 16 (App Router, Turbopack) + React 19 + TypeScript 5 + Tailwind CSS 4** — pages et API dans `src/app/` (20 pages + accueil, 25 routes API).

162

−- **SQLite (better-sqlite3, mode WAL)** dans `data/` — comptes, profils, favoris ; zéro serveur de base de données.

286

+- **Next.js 16 (App Router, Turbopack) + React 19 + TypeScript 5 + Tailwind CSS 4** — pages et API dans `src/app/` (20+ pages, 54 routes API).

287

+- **SQLite (better-sqlite3, mode WAL)** dans `data/` — deux bases : `ka-id.db` (comptes, profils, favoris, feature store de personnalisation) et `ka-comms.db` (hub de communication : soumissions, courriels, équipe) ; zéro serveur de base de données.

163

288

- **jose** pour les JWT/JWKS (sessions HS256 en témoin HttpOnly `ka_session` 30 jours ; vérification des `id_token` Google par JWKS ; `client_secret` Apple signé ES256 à la volée).

289

+- **Resend** pour les courriels : transactionnels KA ID (vérification, lien magique, 2FA, alertes) et boîtes du hub de communication (envoi + webhook entrant).

164

290

- **sharp** (avatars), **qrcode** (carte de membre), **pdfkit** (rapports).

165

−- Bibliothèques internes : `src/lib/` (`auth.ts`, `sso.ts`, `db.ts`, `live.ts`, `ecostats.ts`, `status.ts`).

291

+- Bibliothèques internes : `src/lib/` (`auth.ts`, `sso.ts`, `db.ts`, `live.ts`, `ecostats.ts`, `status.ts`, `kaid-data.ts`, `personal.ts`, `alerts.ts`, `search.ts`, `rapports.ts`, `report-stats.ts`, `roles.ts`, `email.ts`, `comms/`).

166

292

167

293

Processus PM2 sur le nœud (commandes de lancement réelles) :

168

294

172

298

173

299

174

300

301

302

175

303

176

304

## Structure du repo

177

305

178

306

```

179

307

groupe-ka/

180

−├── src/ # app/ (App Router : pages + API), ka/ (ka-ui vendoré + ecosystem.json), lib/ (auth, sso, db, live…)

308

+├── src/ # app/ (App Router : pages + API), ka/ (ka-ui vendoré + ecosystem.json), lib/ (auth, sso, db, live, personal…)

181

309

├── public/ # favicon, og.png, ka-agent.js (widget IA), doc/ (guide + captures), documents publics

182

310

├── assets/ # captures d'écran historiques

183

−├── data/ # SQLite (WAL) + status/history.jsonl (90 jours) — gitignoré

184

−├── scripts/ # status-tick.sh (tick de disponibilité) + rapport-quotidien.sh

185

−└── docs/ # captures d'écran du README

311

+├── data/ # SQLite WAL (ka-id.db, ka-comms.db) + status/history.jsonl (90 jours) — gitignoré

312

+├── scripts/ # status-tick.sh, rapport-quotidien.sh, kaid-mf.mjs (entraînement recos)

313

+└── docs/ # captures d'écran du README (visite guidée, mobile/, desktop/, ecosysteme/, archive/)

186

314

```

187

315

188

316

## Démarrage rapide

197

325

npm run lint # eslint

198

326

```

199

327

200

−Sans `.env.local`, le site tourne mais les connexions Google/Apple, le SSO et la passe Wallet sont inactifs. La base SQLite (`data/`) se crée toute seule au premier lancement.

328

+Sans `.env.local`, le site tourne mais les connexions Google/Apple, le SSO, les courriels et la passe Wallet sont inactifs. Les bases SQLite (`data/`) se créent toutes seules au premier lancement.

201

329

202

330

## Variables d'environnement

203

331

205

333

206

334

| Groupe | Variables |

207

335

|---|---|

208

−| Base | `BASE_URL`, `KA_AUTH_SECRET` |

336

+| Base | `BASE_URL`, `KA_AUTH_SECRET`, `KA_DB_PATH`, `KA_COMMS_DB_PATH` |

209

337

| Google OAuth | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

210

338

| Sign in with Apple | `APPLE_CLIENT_ID`, `APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_PRIVATE_KEY` |

211

339

| Apple Wallet (carte de membre) | `KA_PASS_DIR`, `KA_PASS_TYPE_ID`, `KA_PASS_TEAM_ID` |

340

+| Courriels (Resend) | `RESEND_API_KEY`, `RESEND_READ_API_KEY`, `RESEND_FROM`, `RESEND_WEBHOOK_SECRET`, `KA_MAIL_DEBUG` |

212

341

| KA Agent | `ANTHROPIC_API_KEY` |

213

−| Secrets SSO (un par client) | `KA_SSO_SECRET_LOU_KA`, `KA_SSO_SECRET_IMMO_KA`, `KA_SSO_SECRET_VRAI_PRIX`, `KA_SSO_SECRET_AUTO_KA`, `KA_SSO_SECRET_FABRI_KA`, `KA_SSO_SECRET_FOOD_KA`, `KA_SSO_SECRET_RESTO_KA`, `KA_SSO_SECRET_SORTI_KA`, `KA_SSO_SECRET_CREA_KA`, `KA_SSO_SECRET_TROUVE_KA`, `KA_SSO_SECRET_API_KA`, `KA_SSO_SECRET_JOB_KA`, `KA_SSO_SECRET_KA_IOS`, `KA_SSO_SECRET_KA_ANDROID`, `KA_SSO_SECRET_ORA_KA`, `KA_SSO_SECRET_TOIT_KA`, `KA_SSO_SECRET_VALOPLEX` |

342

+| Personnalisation & recherche | `KAID_TICK_KEY`, `TROUVEKA_SEARCH_URL` |

343

+| Secrets SSO (un par client) | `KA_SSO_SECRET_LOU_KA`, `KA_SSO_SECRET_IMMO_KA`, `KA_SSO_SECRET_HOUSE_KA`, `KA_SSO_SECRET_RENT_KA`, `KA_SSO_SECRET_VRAI_PRIX`, `KA_SSO_SECRET_AUTO_KA`, `KA_SSO_SECRET_FABRI_KA`, `KA_SSO_SECRET_FOOD_KA`, `KA_SSO_SECRET_RESTO_KA`, `KA_SSO_SECRET_SORTI_KA`, `KA_SSO_SECRET_CREA_KA`, `KA_SSO_SECRET_TROUVE_KA`, `KA_SSO_SECRET_API_KA`, `KA_SSO_SECRET_JOB_KA`, `KA_SSO_SECRET_KA_IOS`, `KA_SSO_SECRET_KA_ANDROID`, `KA_SSO_SECRET_ORA_KA`, `KA_SSO_SECRET_TOIT_KA`, `KA_SSO_SECRET_VALOPLEX` |

214

344

215

345

## Données & conformité

216

346

217

347

- **Provenance** : les métriques affichées par le hub proviennent exclusivement des **endpoints publics `/api/stats`** (ou `/api/status` pour Trouve·Ka) des plateformes du groupe — aucune collecte externe.

218

−- **Cadences** : métriques live rafraîchies aux **10 min** (cache serveur `live.ts`) ; disponibilité vérifiée aux **5 min** (tick PM2 → historique 90 jours) ; rapport quotidien généré chaque matin à **6 h**.

219

−- **Données personnelles** : les comptes KA ID (courriel, profil, favoris) vivent dans une SQLite locale au nœud (`data/`, gitignorée) — mots de passe hachés scrypt, sessions JWT HttpOnly 30 jours. Aucun tiers.

220

−- **Pages légales** publiées sur le site : [Conditions d'utilisation](https://www.groupe-ka.com/conditions), [Politique de confidentialité](https://www.groupe-ka.com/confidentialite), [Protection des renseignements personnels (Loi 25)](https://www.groupe-ka.com/loi-25), [Transparence des robots d'indexation](https://www.groupe-ka.com/bots), plus le **droit de retrait** (`/retrait`).

348

+- **Cadences** : métriques live rafraîchies aux **10 min** (cache serveur `live.ts`) ; disponibilité vérifiée aux **5 min** (tick PM2 → historique 90 jours) ; rapport quotidien généré chaque matin à **6 h** ; alertes membres évaluées à l'heure ; recos MF entraînées chaque nuit.

349

+- **Données personnelles** : les comptes KA ID (courriel, profil, favoris, interactions) vivent dans une SQLite locale au nœud (`data/`, gitignorée) — mots de passe hachés scrypt, sessions JWT HttpOnly 30 jours. Aucun tiers hors Resend (courriels transactionnels).

350

+- **Le membre garde la main** : `/mon-ka` offre 3 interrupteurs de consentement, la correction de « ce que KA a appris », l'effacement, la réinitialisation et l'**export JSON** de ses données (Loi 25).

351

+- **Pages légales** publiées sur le site : [Conditions d'utilisation](https://www.groupe-ka.com/conditions), [Politique de confidentialité](https://www.groupe-ka.com/confidentialite), [Protection des renseignements personnels (Loi 25)](https://www.groupe-ka.com/loi-25), [Avis — notre rôle d'agrégateur](https://www.groupe-ka.com/avis), [Transparence des robots d'indexation](https://www.groupe-ka.com/bots), plus le **droit de retrait** ([/retrait](https://www.groupe-ka.com/retrait)).

221

352

222

353

## Documentation

223

354

224

355

- **Guide en ligne** : [www.groupe-ka.com/doc/](https://www.groupe-ka.com/doc/) — à quoi sert le site, le parcours en 4 étapes (accueil → KA ID → /status → /stats), d'où viennent les données, FAQ.

225

356

- **Guide PDF** : [groupe-ka-documentation.pdf](https://www.groupe-ka.com/doc/groupe-ka-documentation.pdf) — la même documentation, téléchargeable.

357

+- **Catalogue PDF « L'écosystème en images »** — lié au footer du site.

226

358

- Les captures du guide sont versionnées dans `public/doc/img/` (etape1 → etape4).

227

359

228

360

## Historique

229

361

230

362

Jalons tirés du `git log` du repo :

231

363

232

−- **2026-08-17** — naissance du hub écosystème : métriques live (`live.ts`, ISR 10 min), page `/status` v2 (ticks 5 min, historique 90 j), tableau de bord maître `/stats`, widget KA Agent câblé partout, Job·Ka rejoint l'écosystème (13 sites dans `ecosystem.json`).

364

+- **2026-08-17** — naissance du hub écosystème : métriques live (`live.ts`, ISR 10 min), page `/status` v2 (ticks 5 min, historique 90 j), tableau de bord maître `/stats`, widget KA Agent câblé partout, Job·Ka rejoint l'écosystème.

233

365

- **2026-08-18** — page `/telecharger` (iOS TestFlight, APK Android signé + SHA-256, DMG macOS notarié) et client SSO `ka-android`.

234

366

- **2026-08-19** — `/stats` maître v2 (KPI + sparklines, croissance indice 100, kit kacharts/kapdf) + KA Agent v2 plein écran + campagne mobile (tokens.css, overlay menu).

235

367

- **2026-08-22** — SEO complet (canonical, JSON-LD Organization+WebSite, robots.txt, sitemap.xml) + KA Agent v3 (bulle déplaçable).

236

368

- **2026-08-23** — rapports quotidiens automatisés (rédaction Claude + PDF), onglet `/investisseurs` (6 documents corporatifs), `/recherche` propulsée par Trouve·Ka, pages `/agents` et `/marque`, jeton API personnel `kapi_`, stats v3 (ReportBuilder).

237

−- **2026-08-24** — page documentation `/doc` (guide + captures + PDF téléchargeable) et refonte du README.

369

+- **2026-08-24** — page documentation `/doc` (guide + captures + PDF téléchargeable) et README v3 (chiffres live vérifiés, pastilles dynamiques).

370

+- **2026-08-25** — accueil v2 « HQ » (recomposition éditoriale majeure), widget ka-agent v4 (ka-card/ka-choix), vitrine « L'écosystème en images » + catalogue PDF.

371

+- **2026-08-26** — **KA ID v2** : courriels transactionnels Resend (vérification, lien magique, 2FA), moteur de personnalisation (feature store, `/mon-ka`, endpoints s2s HMAC), alertes actives (cron horaire), filtrage collaboratif + matrix factorization ALS (cron 03:12) ; **hub de communication interne** (console admin v2, boîtes courriel Resend, pièces jointes, gabarits signés).

372

+- **2026-08-27** — **House·Ka et Rent·Ka** rejoignent l'écosystème (clients KA ID, surfaces marketing, alerts, ka-agent) — le groupe s'étend au Canada hors Québec.

373

+- **2026-08-28** — banderole carrousel des marques sous le héros, House·Ka/Rent·Ka intégrés partout sur l'accueil, README v4 (visite guidée en 10 captures).

238

374

239

375

## Développement (remote-first)

240

376

257

393

258

394

- **Nœud** : M3U96b (Mac Studio, cluster MacLustr) — répertoire `~/apps/groupe-ka`

259

395

- **Port** : **8110** (local, exposé uniquement via le tunnel)

260

−- **Processus PM2** : `groupe-ka` (serveur Next.js) + `groupe-ka-ngrok` (tunnel) + `groupe-ka-status-tick` (ticks 5 min) + `groupe-ka-rapport-quotidien` (rapport 6 h)

396

+- **Processus PM2** : `groupe-ka` (serveur Next.js) + `groupe-ka-ngrok` (tunnel) + `groupe-ka-status-tick` (ticks 5 min) + `groupe-ka-rapport-quotidien` (rapport 6 h) + `groupe-ka-kaid-alerts` (alertes, horaire) + `groupe-ka-kaid-mf` (recos, 03:12)

261

397

- **Domaine** : **https://www.groupe-ka.com** (tunnel ngrok)

398

+- **Healthcheck** : `GET /api/health` → `{"status":"ok","app":"groupe-ka"}`

262

399

263

400

## L'écosystème en images

264

401

308

445

| Plateforme | Vocation |

309

446

|---|---|

310

447

| [groupe-ka.com](https://www.groupe-ka.com) | portail du groupe et compte unique KA ID *(ce repo)* |

311

−| [lou-ka.com](https://www.lou-ka.com) | logements à louer |

312

−| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre |

448

+| [lou-ka.com](https://www.lou-ka.com) | logements à louer (Québec) |

449

+| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre (Québec) |

450

+| [house-ka.com](https://www.house-ka.com) | maisons à vendre (Canada hors Québec) |

451

+| [rent-ka.com](https://www.rent-ka.com) | loyers (Canada hors Québec) |

313

452

| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière |

314

453

| [valoplex.com](https://www.valoplex.com) | évaluation spécialisée plex |

315

454

| [toit-ka.com](https://www.toit-ka.com) | louer + acheter unifiés |