Vue d'ensemble
Bienvenue dans la documentation d'administration de BeePass. Ce guide couvre l'ensemble des outils disponibles dans le backoffice pour superviser la plateforme, gerer les utilisateurs, piloter les finances, executer le pipeline genetique et surveiller l'infrastructure.
Le backoffice est concu pour donner aux administrateurs une visibilite complete sur la sante de la plateforme, tout en protegeant les donnees sensibles derriere plusieurs couches de securite. Que vous ayez besoin de verifier l'etat d'un abonnement, d'investiguer un incident de securite ou de lancer une evaluation genetique, tout est accessible depuis une interface centralisee.
Prerequis
L'acces au backoffice est strictement controle pour proteger les donnees des eleveurs et la stabilite de la plateforme. Trois conditions doivent etre reunies avant de pouvoir y acceder :
| Condition | Description |
|---|---|
| Role administrateur | Le compte doit posseder le role admin ou super_admin dans profiles.roles (JSONB) |
| TOTP 2FA obligatoire | L'authentification a deux facteurs par code TOTP (un code temporaire a 6 chiffres genere par une application comme Google Authenticator) est imposee pour tous les comptes admin -- elle ne peut pas etre desactivee (tentative de desactivation = 403) |
| VPN WireGuard | Le sous-domaine admin.beepass.io est protege par une allowlist IP Traefik limitee au reseau WireGuard (10.0.0.0/24). Concretement, seuls les appareils connectes au VPN peuvent atteindre la page de connexion |
Sans connexion WireGuard active, admin.beepass.io retourne une erreur 403 meme avec des identifiants admin valides. Contactez un super-admin pour obtenir votre configuration WireGuard.
Flux d'authentification
La connexion au backoffice se fait en plusieurs etapes. Ce processus multi-couches garantit qu'un mot de passe vole ne suffit pas a acceder au panneau d'administration -- il faudrait aussi le VPN et le code TOTP.
1. Connexion VPN WireGuard
|
2. Acces a admin.beepass.io
|
3. Saisie email + mot de passe -> cookie pre-authentification (TTL 10 min)
|
4. Validation du code TOTP (6 chiffres)
|
5. Emission du cookie HMAC admin (jose JWT HS256, HttpOnly, Secure, SameSite=Lax, TTL 8h)
|
6. Acces au backoffice -- le cookie coexiste avec le cookie Supabase SSR
Le cookie admin est signe avec SUPABASE_SERVICE_ROLE_KEY en HMAC (une methode cryptographique qui garantit que le cookie n'a pas ete modifie) et couvre le domaine .beepass.io. Apres 8 heures d'inactivite, une nouvelle authentification TOTP est requise.
Chaque compte admin dispose de 8 codes de secours (backup codes) generes lors de l'activation TOTP. Ces codes sont hashes SHA-256 avec salt individuel et ne peuvent etre utilises qu'une seule fois. Conservez-les dans un gestionnaire de mots de passe -- ils sont votre filet de securite si vous perdez l'acces a votre application TOTP.
Architecture double session
Pourquoi deux sessions ? Parce qu'un administrateur est aussi un eleveur. Il doit pouvoir gerer ses propres reines (session eleveur) tout en administrant la plateforme (session admin), sans avoir a se deconnecter de l'un pour acceder a l'autre.
Le backoffice utilise un systeme de double session independant. L'administrateur peut etre connecte simultanement en tant qu'eleveur (cookie Supabase SSR) et en tant qu'admin (cookie HMAC) dans le meme navigateur.
| Session | Cookie | Auth | Portee |
|---|---|---|---|
| Eleveur | sb-xxx-auth-token | Supabase SSR | /dashboard, /apps/* |
| Admin | beepass-admin-token | jose JWT HS256 HMAC | /backoffice/* |
Le cookie admin couvre le domaine .beepass.io (cross-subdomain), ce qui permet la coexistence entre beepass.io et admin.beepass.io.
Sections du backoffice
📄️ Tableau de bord
KPIs, revenus, inscriptions, sante serveur, 12 widgets temps reel
📄️ Gestion des utilisateurs
Comptes, roles, sessions, MFA, bannissement, suppression FK safety
📄️ Journal d'audit
19 types d'evenements, geolocalisation IP, filtres avances
📄️ Finances & Abonnements
Commandes Stripe, 4 plans tarifaires, couts infrastructure
📄️ Reines de reference
Import CSV multi-format, table unifiee queens_f0, auto-claim
📄️ Pipeline EBV
Pipeline ONE SHOT : Environnement, XGBoost, BLUPF90+, Gibbs, Normalisation
📄️ CRM & Emails
Campagnes Brevo, contacts, templates email
📄️ Assistant IA
Agent conversationnel admin, configuration IA, RAG support
📄️ Monitoring serveur
Beszel, Docker, Cloudflare, backups, cron jobs, seuils d'alerte
📄️ Centre de securite
19 outils d'audit, findings, rapports, WireGuard VPN
Modules de la plateforme
BeePass est compose de modules independants mais interconnectes. Chacun repond a un besoin specifique des eleveurs ou de l'administration. Voici l'etat de chaque module :
| # | Module | Statut | Description |
|---|---|---|---|
| A | Passeport Genetique | 100% | Reines F0/F1, evaluations, pedigree, QR codes |
| B | Tracabilite QR | 100% | QR codes SVG, passeports publics, batch PDF/ZPL |
| C | Chat Communautaire | 100% | DM + groupes, Realtime, fichiers/vocal/emoji, reactions |
| D | Centre Support | 100% | Peppermint, RAG IA, SLA tracking, pieces jointes |
| E | Calendrier Elevage | 90% | Google + Apple CalDAV sync, countdowns, OAuth |
| F | Moteur BeeMatch | 25% | Appariement genetique (en cours) |
| G | Environnement | 70% | Worker env_compute, geocodage, meteo saisonniere |
| H | Moteur EBV | 90% | Pipeline ONE SHOT complet, 8 traits, normalisation BeeBreed |
| I | Admin Dashboard | 100% | Dashboard, monitoring, securite, 30+ pages backoffice |
| J | Parametres & Securite | 100% | TOTP, sessions, MFA, audit, rate limiting configurables, feature flags, alert channels (email/push/webhook), maintenance notify cron, session config |
| K | Infrastructure | 100% | 18 services Docker, Traefik v3, Prometheus/Grafana |
| L | AINV-honeybees v20 | 90% | Matrice A^-1, package TS, 56 tests |
| M | Documentation | 100% | Docusaurus 3.9, 48 pages, 8 locales (FR/EN/DE/IT/ES/RU/NL/PT) |
| N | Billing Stripe | 100% | 4 plans, webhook, checkout, Customer Portal |
| O | Contacts | 100% | Carnet hybride, enrichissement profil, CSV, geocoding |
| P | API Keys | 100% | CRUD, wizard 4 etapes, permissions granulaires, SHA-256 |
| Q | SEO & Metadata | 100% | Routing multilingue, hreflang 6 langues, sitemap index, OG images, JSON-LD, GA4, Search Console |
| R | Chatbot IA | 90% | RAG pgvector, Ollama embeddings, escalade support |
| S | Recherche globale | 100% | Recherche unifiee multi-entites (F0, F1, contacts, calendar, tickets) |
| T | Testeurs | 100% | Page testeurs, evaluations, carte Google Maps, profil eleveur |
Roles administrateur
La plateforme distingue deux niveaux d'administration. Cette separation existe pour limiter les risques : un admin peut gerer le quotidien, mais les operations irreversibles (suppression de comptes, attribution de roles admin) sont reservees aux super-admins.
| Role | Perimetre |
|---|---|
admin | Acces complet au backoffice, gestion utilisateurs, finances, monitoring, pipeline genetique |
super_admin | Droits admin + gestion des roles admin + suppression de comptes + creation d'utilisateurs + configuration infrastructure |
Les roles sont stockes dans le champ JSONB profiles.roles. Un meme compte peut cumuler plusieurs roles (ex : ["admin", "eleveur"]). Le trigger validate_user_roles() valide les roles cote base de donnees, empechant les combinaisons invalides.
profiles.roles est un champ JSONB. Toujours utiliser Array.isArray(roles) avant .includes() pour eviter les erreurs a l'execution. Ne jamais presumer que le champ est un tableau -- dans de rares cas, il peut etre null ou mal formate.
Conventions techniques
Ces conventions s'appliquent a toutes les routes et composants du backoffice. Elles garantissent une securite uniforme et facilitent la maintenance du code.
| Convention | Description |
|---|---|
| Prefixe API | Toutes les routes API admin sont prefixees /api/admin/ |
| Credentials | Les appels fetch() cote client vers /api/admin/* incluent systematiquement credentials: "include" pour transmettre le cookie HMAC |
| Auth helper | Les routes admin utilisent verifyAdminFromRequest() (src/lib/verify-admin.ts) -- jamais createSupabaseServerClient() directement. Ce helper verifie le cookie HMAC + fallback SSR + verifie le role en base (cache 2 min) |
| Service role | Les routes admin utilisent createClient() direct avec SUPABASE_SERVICE_ROLE_KEY pour les operations DB, contournant les politiques RLS (Row Level Security) |
| Audit | Les actions sensibles sont enregistrees dans le journal d'audit (18 types d'evenements) |
| Rate limiting | Admin login : 5 tentatives / 15 min. Admin TOTP : 5 / 15 min (Upstash Redis) |
| i18n | Textes admin en francais uniquement (pas de traduction multi-langue pour le backoffice) |
Infrastructure sous-jacente
Le backoffice repose sur une infrastructure Docker de 18 services heberges sur un serveur Hetzner (Nuremberg). Chaque service est un container Docker isole, avec son propre healthcheck (verification de sante automatique) qui permet a Traefik de retirer un service defaillant du routage.
| Service | Role | Healthcheck |
|---|---|---|
beepass-web | Next.js 15 + API Routes | wget 127.0.0.1:3000 |
beepass-worker | Pipeline EBV (Python + BLUPF90+) | curl 127.0.0.1:8000/health |
beepass-redis | File d'attente rq (gere les jobs asynchrones comme le pipeline genetique) | redis-cli ping |
beepass-docs | Documentation Docusaurus | curl 127.0.0.1:80 |
beepass-traefik | Reverse proxy SSL (redirige le trafic et gere les certificats HTTPS) | traefik healthcheck --ping |
beepass-backup | pg_dump cron quotidien (sauvegarde automatique de la base de donnees) | pgrep crond |
beepass-ollama | LLM (Llama 3.2 3B) pour les suggestions IA | ollama list |
beepass-beszel | Monitoring systeme (CPU, RAM, disque) | -- (image scratch) |
beepass-zap | Scanner OWASP ZAP (detecte les vulnerabilites web) | Endpoint /JSON/core/view/version/ |
beepass-nuclei | Scanner Nuclei (tests de securite cibles) | -- (ephemere) |
beepass-prometheus | Collecte metriques pour les tableaux de bord Grafana | wget 127.0.0.1:9090/-/healthy |
beepass-grafana | Dashboards monitoring (visualisation graphique des metriques) | wget 127.0.0.1:3000/api/health |
Traefik v3 exclut automatiquement les containers unhealthy du routing. Un healthcheck defaillant rend le service invisible et provoque des erreurs 404 sur l'ensemble du site. Toujours verifier les healthchecks apres un deploiement -- c'est souvent la premiere chose a investiguer en cas de 404 generalise.
PWA (Progressive Web App)
BeePass est installable comme une application native sur mobile et desktop. Le manifest est dynamique (GET /api/manifest) et adapte le nom et la page d'accueil selon le domaine :
| Domaine | Nom application | Page d'accueil | Fond |
|---|---|---|---|
admin.beepass.io | Admin BeePass | /backoffice | Dark (#202936) |
beepass.io | BeePass | / | Blanc (#ffffff) |
Les notifications push (Web Push VAPID) permettent de recevoir les alertes admin directement sur le telephone, meme quand le navigateur est ferme. Voir Notifications pour la configuration.