Reines de reference

En genetique, la qualite des evaluations depend directement de la taille et de la diversite de la population de reference. Plus le nombre de reines documentees est important, plus les estimations genetiques sont fiables. Les reines de reference constituent cette fondation : elles forment la base genetique publique de BeePass, accessible a tous les eleveurs.

Contrairement aux reines personnelles (liees a un eleveur via owner_id), les reines de reference ont owner_id IS NULL et sont visibles par tous les utilisateurs de la plateforme. Elles proviennent d'imports de bases de donnees externes (BeeBreed, Index Mellifera) et enrichissent le pedigree global.

Architecture : table unifiee queens_f0

ARCHI-02 -- Table unifiee

Depuis la migration ARCHI-02 (2026-03-01), la table queens_reference a ete supprimee. Toutes les reines -- personnelles et de reference -- sont dans la table unifiee queens_f0. Les reines de reference ont simplement owner_id IS NULL. Ce choix simplifie enormement les requetes de pedigree : plus besoin de joindre deux tables pour reconstituer un arbre genealogique.

Type de reine	owner_id	Visibilite	Ecriture
Reine personnelle	UUID de l'eleveur	Tous (RLS SELECT = true)	Proprietaire uniquement
Reine de reference	NULL	Tous (RLS SELECT = true)	Admin uniquement (service_role)

La politique RLS queens_f0 SELECT true rend toutes les reines lisibles par tous les utilisateurs authentifies. Seules les operations d'ecriture (INSERT, UPDATE, DELETE) sont restreintes au proprietaire via owner_id = auth.uid().

Role des reines de reference

Pourquoi investir du temps a importer des milliers de reines de reference ? Parce qu'elles sont le socle sur lequel repose tout le systeme d'evaluation genetique. Sans elles, les arbres genealogiques seraient tronques, les matrices de parente incomplets et les estimations genetiques peu fiables.

Concretement, les reines de reference servent de fondation genetique pour l'ensemble de la communaute :

Usage	Description
Pedigree	Elles apparaissent dans les arbres genealogiques comme ancetres communs, permettant de relier les reines de differents eleveurs (resolution par serial_number + fallback queen_name)
AINV	Elles sont incluses dans la matrice inverse des relations genetiques additives (A^-1, un outil mathematique qui quantifie les liens de parente entre toutes les reines), calculee par le package ainv-honeybees
BLUPF90+	Elles participent au modele d'evaluation genetique comme population de reference, augmentant la precision des estimations
Index BeePass	Elles sont consultables par tous dans l'Index BeePass (/apps/queens/index-beepass), page publique /breeders et profils publics /breeders/[code]

Schema DB queens_f0

Colonne	Type	Description
id	UUID PK	Identifiant unique interne
serial_number	TEXT UNIQUE	Numero de serie (identifiant canonique prioritaire -- c'est le "numero d'identite" de la reine)
owner_id	UUID / NULL	FK auth.users ON DELETE SET NULL. NULL = reine de reference publique
queen_name	TEXT	Nom de la reine
birth_date	DATE	Date de naissance
race	TEXT	Race ou sous-espece (B=Buckfast, C=Carnica, M=Mellifera...)
breeder_code	TEXT	Code eleveur d'origine
mating_code	TEXT	Code d'insemination (INS, NAT...)
sdi_code	INTEGER	1=SDI (Single Drone Insemination, insemination par un seul drone), 2=MDI (Multiple, par plusieurs drones)
dam_external_id	TEXT	ID externe mere (pas FK, texte libre -- pointe vers le serial_number de la mere)
drone_sire_id	TEXT	ID du groupe de males (sire-group, le groupe de drones utilises pour l'insemination)
drone_sire_name	TEXT	Nom du sire-group
life_status	TEXT	Cycle de vie : testing, production, sold, dead
origin	TEXT	Pays ou region d'origine
is_external	BOOLEAN	true = reine importee/claimee (pas creee manuellement dans BeePass)
claimed_by	UUID / NULL	FK auth.users ON DELETE SET NULL -- eleveur ayant reclame la reine
claimed_at	TIMESTAMPTZ	Date de reclamation
import_batch_id	TEXT	Identifiant du lot d'import (permet de retracer la provenance)
imported_at	TIMESTAMPTZ	Date d'import
source_url	TEXT	URL source des donnees importees
creator_id	UUID / NULL	FK auth.users ON DELETE SET NULL
created_at	TIMESTAMPTZ	Date de creation de la fiche
updated_at	TIMESTAMPTZ	Derniere modification (trigger auto)

Index

Index	Colonne	Description
idx_queens_f0_owner_id	owner_id	Filtre par proprietaire
idx_queens_f0_search	queen_name (gin_trgm_ops)	Recherche full-text (recherche tolerante aux fautes de frappe)
Contrainte UNIQUE	serial_number	Deduplication globale -- empeche l'import de doublons

Import de reines

L'import est l'operation la plus courante pour enrichir la base de reference. L'interface d'import est le SmartImportWizard en mode admin, accessible depuis /backoffice/reference-queens. Ce wizard guide l'administrateur etape par etape, de la selection du fichier a la confirmation de l'import.

Etape 1 -- Destination

Choisissez ou importer les reines. Cette distinction est importante : les reines de reference sont publiques et alimentent le modele genetique global, tandis que les reines importees pour un eleveur specifique lui appartiennent.

Option	Effet	API
Pool de reference (public)	owner_id = NULL -- visibles par tous	/api/admin/reference-queens/import
Compte eleveur specifique	owner_id = UUID de l'eleveur selectionne (autocomplete)	/api/admin/queens/f0/bulk + /api/admin/queens/evaluations/bulk

Lors de l'import pour un eleveur, un badge "Import pour [Nom eleveur]" est visible pendant l'operation.

Etape 2 -- Upload des donnees

Televersez un fichier contenant les donnees des reines. Le systeme est capable de detecter automatiquement le format parmi 5 formats supportes :

Format	Extension	Description	Mapping specifique
Index Mellifera	.csv, .xlsx	Export standard Index Mellifera	Colonnes standards
BeeBreed Daten	.csv, .txt	Export BeeBreed (Hohen Neuendorf) -- Daten	RAMMother -> drone_sire_id + drone_sire_name
BeeBreed Stockkarten	.csv	Export BeeBreed -- Stockkarten (fiches de suivi avec evaluations)	Evaluations incluses
BeeBreed Zuchtwerte	.csv	Export BeeBreed -- Zuchtwerte (valeurs genetiques de reference)	EBV de reference
CSV generique	.csv	Format libre avec colonnes nommees	Mapping IA optionnel (Ollama tente de deviner la correspondance des colonnes)

Les dates Excel (numeros de serie, comme "44927" au lieu de "01/01/2023") sont automatiquement converties en format ISO.

Etape 3 -- Previsualisation et validation

Avant d'inserer quoi que ce soit en base, le systeme analyse le fichier et affiche un apercu des reines detectees. C'est l'occasion de verifier que le mapping des colonnes est correct et de corriger les erreurs avant import.

Colonne	Description	Obligatoire
serial_number	Numero de serie unique de la reine	Recommande
race	Race ou sous-espece	oui
birth_year	Annee de naissance	oui
origin	Pays ou region d'origine	Recommande
insemination_type	SDI ou MDI	Recommande
mother_ref	Reference de la mere (dam_external_id ou serial_number)	Optionnel
father_group	Identifiant du sire-group	Optionnel

Les erreurs de validation sont signalees ligne par ligne :

• Champs obligatoires manquants
• Formats de date invalides
• Doublons detectes (serial_number existant)

Identifiant canonique

L'identifiant canonique (canonicalId) d'une reine est son serial_number s'il est renseigne, sinon son UUID interne. Lors de l'import, le serial_number est prioritaire pour le dedoublonnage (upsert) -- si une reine avec le meme numero de serie existe deja, elle est mise a jour plutot que dupliquee.

Etape 4 -- Confirmation

Recapitulatif de l'import avec le nombre de reines a creer, les doublons ignores et les avertissements. La confirmation declanche l'insertion en base par batch de 500 via /api/admin/reference-queens/import (limite max : 5000 reines par import, decoupees en lots pour respecter les limites PostgREST).

Chaque import genere un evenement queen_import dans le journal d'audit avec le nombre de reines importees et le format source.

Champs d'evaluation (v8.1)

Certains formats d'import (notamment BeeBreed Stockkarten) contiennent non seulement les informations de la reine, mais aussi ses evaluations de terrain. Ces donnees sont importees dans la table queen_evaluations :

Colonne	Type	Description
honey_yield_kg	NUMERIC	Production miel (kg)
gentleness	INTEGER	Douceur (1-4, ou 4 = tres douce)
comb_sitting	INTEGER	Tenue de cadre (1-4, ou 4 = excellente)
vigor	INTEGER	Vigueur printaniere (1-4, ou 4 = tres vigoureuse)
wintering	INTEGER	Hivernage (1-4, ou 4 = excellent)
non_swarming	INTEGER	Non-essaimage (1-4, ou 4 = n'essaime pas)
hyg6_cleaned	INTEGER	Cellules nettoyees a 6h (0-50, test hygienique Pin Test)
hyg24_cleaned	INTEGER	Cellules nettoyees a 24h (0-50, test hygienique Pin Test)
time_quality_hyg6	TEXT	Qualite du timing 6h : exact (chronometre), declared (approximatif), unknown (non mesure)
time_quality_hyg24	TEXT	Qualite du timing 24h : exact, declared, unknown
evaluation_source	TEXT	native (saisie manuelle dans BeePass) ou import (import CSV)
env_feature_id	UUID FK	Reference vers env_season_features(id) -- peuple par le pipeline env_compute
postal_code	TEXT	Code postal du site d'evaluation (utilise pour le geocodage environnemental)
country_code	TEXT	Code pays du site d'evaluation

CHECK constraints v8.1

Ces contraintes protegent la qualite des donnees en distinguant les evaluations saisies manuellement (ou le timing doit etre connu) des imports (ou le timing peut etre inconnu) :

• time_quality_hyg6 = 'unknown' est interdit quand evaluation_source = 'native' (CHECK tq6_import_only)
• time_quality_hyg24 = 'unknown' est interdit quand evaluation_source = 'native' (CHECK tq24_import_only)
• L'import bulk force automatiquement evaluation_source = 'import' cote serveur

Mecanisme de claim

Lorsqu'un eleveur s'inscrit sur BeePass, il est possible que des reines lui appartenant aient deja ete importees comme reines de reference (par exemple depuis BeeBreed). Le mecanisme de claim permet a l'eleveur de reclamer ces reines.

Trigger auto-claim desactive

Le trigger automatique trg_profiles_auto_claim est desactive depuis AUTH v2.7.0. Le claim se fait desormais exclusivement via une action manuelle avec confirmation.

Flux actuel

1. L'eleveur renseigne son code eleveur (breeder_code) dans son profil
   |
2. Le systeme detecte des reines orphelines correspondantes (owner_id IS NULL + meme breeder_code)
   |
3. Un AlertDialog de confirmation s'affiche :
   "X reine(s) correspondent a votre code eleveur. Voulez-vous les reclamer ?"
   |
4. Si l'eleveur accepte : POST /api/queens/claim
   |
5. UPDATE queens_f0 SET owner_id = user_id, claimed_by = user_id, claimed_at = NOW()
   WHERE breeder_code = code AND owner_id IS NULL
   |
6. Si l'eleveur refuse : le code eleveur est bloque (ne peut pas etre sauvegarde sans claim)

Le claim est un UPDATE in-place (pas de copie). Le serial_number est preserve. L'endpoint /api/queens/claim est authentifie via Supabase SSR.

Index BeePass

L'Index BeePass est l'annuaire public de la base genetique. Il permet a n'importe quel eleveur de decouvrir les reines de reference disponibles, d'explorer les pedigrees et de trouver des eleveurs partageant des lignees interessantes.

Il est accessible depuis /apps/queens/index-beepass et organise de maniere hierarchique Pays -> Eleveurs -> Reines -> Detail :

Vue	Contenu	Filtres
Pays	~115 pays avec drapeaux emoji, nombre d'eleveurs, recherche animee	Recherche pays, code pays, code eleveur
Eleveurs	Code, pays, nombre reines, evaluations (ratio %), badge EBV	Avec/Sans evaluations
Reines	Tableau pagine avec couleurs annee apicole (bleu/blanc/jaune/rouge/vert -- un systeme de couleurs international pour identifier l'annee de naissance d'une reine)	Filtre par race
Detail	Fiche reine + arbre genealogique (@xyflow/react, 3/5/7 generations)	--

Les API breeders retournent evaluation_count et has_ebv (query ebv_results entity_type='queen').

Pages publiques

Ces pages sont accessibles sans authentification, ce qui permet aux eleveurs de partager leur profil et leurs reines avec des partenaires non-inscrits.

Route	Auth	Description
/breeders	Aucune	Index public (publicMode, service_role, next/dynamic SSR false)
/breeders/[code]	Aucune	Profil eleveur public (3 onglets : Profil, Testeurs, Reines)
/apps/queens/index-beepass	Supabase SSR	Index authentifie (avec ContactBreederButton)
/apps/queens/index-beepass/[id]	Supabase SSR	Detail reine reference avec arbre genealogique

API Routes

Route	Methode	Auth	Description
/api/admin/reference-queens/import	POST	admin	Import CSV queens_f0 avec owner_id NULL (batch 500)
/api/admin/queens/f0/bulk	POST	admin	Import F0 pour un eleveur (owner_id dans body)
/api/admin/queens/evaluations/bulk	POST	admin	Import evaluations pour un eleveur
/api/queens/f0	GET	Supabase SSR	Liste reines F0 (pagination, recherche, tri)
/api/queens/f0/[id]	GET/PUT/DELETE	Supabase SSR	CRUD reine (owner check)
/api/queens/f0/bulk	POST	Supabase SSR	Import en masse eleveur (max 500)
/api/queens/f0/lookup	GET	Supabase SSR	Recherche par external_id
/api/queens/f0/[id]/pedigree	GET	Supabase SSR	Arbre genealogique (3/5/7 generations)
/api/queens/f0/[id]/offspring-stats	GET	Supabase SSR	Stats descendance (f1_count, eval_count, moyennes)
/api/queens/reference/[id]	GET	Supabase SSR	Detail reine reference
/api/queens/reference/[id]/pedigree	GET	Supabase SSR	Arbre reine reference
/api/queens/reference/breeders	GET	Supabase SSR	Agregation pays/eleveurs (queen_count + evaluation_count)
/api/queens/reference/breeders/[code]	GET	Supabase SSR	Reines par eleveur
/api/queens/reference/breeders/public	GET	Aucune	Agregation publique (service_role)
/api/queens/reference/breeders/public/[code]	GET	Aucune	Reines par eleveur (public)
/api/queens/claim	POST	Supabase SSR	Claim manuel des reines non reclamees

Bonnes pratiques

• Importez les meres avant les filles pour que les liens de parente soient etablis automatiquement via dam_external_id / serial_number. Si vous importez les filles d'abord, le lien ne sera pas cree car la mere n'existe pas encore
• Utilisez des serial_number coherents entre les fichiers d'import pour garantir la continuite des pedigrees -- un meme animal doit toujours avoir le meme identifiant
• Verifiez les doublons avant chaque import en masse -- le systeme les detecte (upsert serial_number) mais ne les corrige pas automatiquement
• Privilegiez le format BeeBreed ou Index Mellifera qui contiennent les metadonnees de parente les plus completes
• L'import par batch de 500 evite la limite PostgREST de 1000 lignes par requete

---

Voir aussi : Pipeline EBV | Vue d'ensemble