​

Modèle de données Convex (constats vérifiés)

Source technique principale : convex/schema.ts, complétée par les définitions de @convex-dev/auth pour les tables Auth injectées par ...authTables. Repères :

• id est l’identifiant métier/partagé.
• _id est l’identifiant interne Convex.
• Le schéma effectif contient 71 tables : 66 tables déclarées explicitement dans convex/schema.ts et 5 tables supplémentaires fournies par @convex-dev/auth.
• Le catalogue ci-dessous est exhaustif pour les noms de tables. Les sections détaillées documentent ensuite les invariants qui nécessitent davantage de contexte.

​

Catalogue exhaustif

Les tables authAccounts, authSessions, authRefreshTokens, authVerificationCodes et authRateLimits viennent du spread authTables. La table users et authVerifiers sont redéfinies par CEL dans le schéma principal.

​

Authentification

​

users

• Champs clés: id, role, accountStatus, accountStatusUpdatedAt, selfDeletedAt, username, email, userProfiles?, searchText.
• Enum vérifiés:
  • users.role -> USER, ADMIN, MODERATOR
  • users.accountStatus -> ACTIVE, DEACTIVATED, DELETED
• Index vérifiés: by_accountStatus, by_role, by_external_id.

​

user_profiles

• eaGamertagNormalized reste la clé d’identité EA en minuscules.
• eaGamertagSearchKey est une clé de recherche compacte (casse, accents et séparateurs ignorés), alimentée à chaque écriture et pour les profils existants par le backfill paginé migration/user_profiles_ea_identity.
• Index de recherche ciblée vérifié: by_eaGamertagSearchKey.

​

authTables + authVerifiers

• authTables provient de @convex-dev/auth/server dans le schéma (...authTables).
• authAccounts: provider, providerAccountId, secret?, userId, emailVerified?, phoneVerified?.
  • Index vérifiés: providerAndAccountId, userIdAndProvider.
• authSessions: userId, expirationTime.
  • Index vérifié: userId.
• authRefreshTokens: expirationTime, firstUsedTime?, parentRefreshTokenId?, sessionId.
  • Index vérifiés: sessionId, sessionIdAndParentRefreshTokenId.
• authVerificationCodes: accountId, code, provider, verifier?, expirationTime, emailVerified?, phoneVerified?.
  • Index vérifiés: accountId, code.
• authRateLimits: table générée en plus d’authTables (champ attemptsLeft confirmé).
• authVerifiers (défini dans schema.ts) :
  • sessionId?, signature?.
  • Index: sessionId, signature.

​

Matchs et planification

​

bets

• Champs clés vérifiés: matchId, userId, prediction, status, pointsWon, bettingWave?, settledAt?, cancelledAt?, cancelReason?.
• Enum de prediction vérifiée: HOME, DRAW, AWAY, EXACT_SCORE.
• Enum de status vérifiée: PENDING, WON, LOST, CANCELLED.
• cancelReason reprend les raisons métier: MATCH_CANCELLED, MATCH_RESCHEDULED, BETTING_DISABLED, ADMIN_INVALIDATION, ADMIN_ERROR, MATCH_FORFEITED.
• Index de lifecycle vérifié: by_matchId_bettingWave_status, utilisé pour traiter les mises à jour de paris par batch borné.

​

bet_lifecycle_jobs

• Table opérationnelle de reprise pour les traitements longs sur les paris d’un match.
• Champs clés vérifiés: operation, dedupeKey, matchId, sourceWave, targetWave?, cursor?, statusIndex, processedCount, status, createdAt, updatedAt, completedAt?.
• Payload opérationnel vérifié selon operation: scores et settledAt pour SETTLE, reopenedAt pour REOPEN, reason et cancelledAt pour CANCEL / CANCEL_PENDING.
• Enum de operation vérifiée: SETTLE, REOPEN, CANCEL, CANCEL_PENDING.
• Enum de status vérifiée: RUNNING, COMPLETED, FAILED.
• Index vérifiés: by_external_id, by_dedupeKey, by_matchId_operation, by_status_createdAt.
• La création du job et la planification de sa continuation sont atomiques avec la mutation appelante ; le parcours des pages suivantes est asynchrone.

​

match_forfeits

• Table d’historique des forfaits ponctuels de match.
• Champs clés vérifiés: matchId, leagueId, forfeitClubId, winnerClubId, homeScore, awayScore, declaredAt, declaredById, status, reason?, adminNote?, cancelledAt?, cancelledById?, cancelReason?.
• Snapshots de restauration vérifiés: previousMatchStatus?, previousHomeScore?, previousAwayScore?, previousResultOrigin?, previousForfeitClubId?, previousIsDisputed?, previousValidatedAt?, previousValidatedById?, previousWasValidated?, forfeitCreatedResult.
• Résumé opérationnel vérifié: pendingBetsCancelled, betCancellationInProgress?, betCancellationJobId?.
• Enum de status vérifiée: ACTIVE, CANCELLED.
• match_results.resultOrigin supporte NORMAL, CLUB_FORFEIT, MATCH_FORFEIT.
• Index vérifiés: by_external_id, by_matchId_status, by_leagueId_status, by_leagueId_createdAt, by_status_createdAt.

​

Snapshots match_results des forfaits club

• resultOrigin = CLUB_FORFEIT, forfeitClubId et doubleForfeit? portent la projection sportive courante. Les serializers exposent doubleForfeit comme booléen strict (true seulement si le champ vaut explicitement true).
• clubForfeitSnapshotTaken? marque explicitement un résultat contrôlé par le lifecycle club, indépendamment d’une dérive éventuelle de resultOrigin.
• Champs de restauration vérifiés : previousHomeScore?, previousAwayScore?, previousResultOrigin?, previousForfeitClubId?, previousMatchStatus?, previousIsDisputed?, previousValidatedAt?, previousValidatedById?, previousValidatedBy?, forfeitCreatedResult?.
• Le snapshot est pris lors de la première conversion en forfait club et reste inchangé pendant les transitions simple/double forfait et les réapplications. La restauration finale efface le marqueur et doubleForfeit; un résultat créé par le moteur est supprimé.
• Le runtime ne déduit jamais le marqueur de resultOrigin. Les lignes historiques CLUB_FORFEIT sans marqueur doivent être traitées par le backfill paginé migration/club_forfeit_snapshot_marker, qui conserve les champs de snapshot, de création et de provenance existants.

​

match_reports

• Champs vérifiés: matchId, leagueId, reportingClubId, reportedByUserId, scheduledAtBefore, scheduledAtAfter, counterProposedDate?, respondedAt?, respondedById?, status?, createdAt.
• Références: match, league, reportingClub, reportedBy, respondedBy.
• Enum de statut (vérifié): PENDING, ACCEPTED, COUNTER_PROPOSED, CANCELLED, REJECTED.
• Index vérifiés:
  • by_matchId, by_matchId_status, by_leagueId_reportingClubId, by_reportingClubId_createdAt, by_external_id, by_league.

​

match_lineups

• Champs vérifiés: matchId, clubId, formation, assignments, status, createdAt, updatedAt, submittedAt?, submittedById?.
• assignments contient slotKey, playerProfileId, positionDetailed.
• Enum de positionDetailed vérifiée: GK, DG, DC, DD, MDC, MC, MOC, MG, MD, AG, AD, BU.
• Enum de status vérifiée: draft, submitted.
• Index vérifiés:
  • by_matchId_clubId, by_status_submittedAt, by_clubId_status_updatedAt, by_clubId_updatedAt, by_external_id.

​

Rôles de club et historique

​

club_members

• Enum de rôle vérifié: MANAGER, CO_MANAGER, COACH, MEMBER.
• Index staff vérifié: by_playerProfileId_status_role, utilisé pour retrouver les memberships actifs MANAGER / CO_MANAGER à partir de l’identifiant public du profil.
• Index d’adhésion courante: by_playerProfileId_status_leftAt_roleAssignedAt, utilisé par la session avec status = IN_CLUB, leftAt absent, ordre décroissant de roleAssignedAt et lecture bornée à deux lignes.

​

role_changes

• Champs vérifiés: clubMemberId, type, fromRole, toRole, initiatedById, reason?, createdAt, clubMember, initiatedBy.
• Enum vérifiés:
  • type: PROMOTION, DEMOTION
  • fromRole / toRole: MANAGER, CO_MANAGER, COACH, MEMBER.
• Index vérifiés: by_clubMemberId, by_createdAt, by_external_id.

​

Awards / TOTS / TOTW

​

season_awards, season_award_previews, season_award_entries

• season_awards.status est un champ statut figé en PUBLISHED (publication des récompenses).
• Champs structurants: leagueId, season, publishedAt, status, publishedByUserId, emailStatus, coverage, snapshots formule.
• season_awards conserve warningCount et compteur de destinataires.
• season_award_previews stocke: leagueId, season, preview, generatedAt, generatedByUserId.
• season_award_entries.category: CHAMPION, RUNNER_UP, SEASON_MVP, BEST_GK, TOTS.
• season_award_entries.recipientType: PLAYER, CLUB.

​

award_recipients et TOTW

• awardType vérifiés: season_champion, season_runner_up, season_mvp, best_gk, tots, totw, motm.
• sourceType vérifié: season_award, team_of_the_week, match.

​

award_congratulations

• Champs clés:
  • id: identifiant métier/partagé (compat ID),
  • seasonAwardId: identifiant métier du season_awards,
  • entryId: identifiant métier du season_award_entry concerné,
  • congratulatorUserId: identifiant métier de l’utilisateur qui réagit,
  • reaction: enum MERITE, QUELLE_SAISON, FIER, RENDEZVOUS,
  • createdAt: timestamp ms,
  • leagueId: identifiant métier de la ligue,
  • seasonAward: référence _id vers season_awards,
  • seasonAwardEntry: référence _id vers season_award_entries,
  • user: référence _id vers users,
  • league: référence _id vers leagues.
• Contraintes observées par index:
  • by_external_id sur id,
  • by_entry sur entryId,
  • by_entry_user sur entryId + congratulatorUserId.

​

award_congratulation_counts

• Champs clés:
  • id: identifiant métier/partagé (compat ID),
  • entryId: identifiant métier de season_award_entry,
  • count: total des réactions sur l’entrée,
  • byReaction: objet de compte par réaction avec clés MERITE, QUELLE_SAISON, FIER, RENDEZVOUS,
  • seasonAwardId: identifiant métier du season_awards,
  • entry: référence _id vers season_award_entries,
  • seasonAward: référence _id vers season_awards,
  • league: référence _id vers leagues.
• Contraintes observées par index:
  • by_external_id sur id,
  • by_entry sur entryId.
• Usage B4:
  • award_congratulations stocke la réaction active par utilisateur.
  • award_congratulation_counts dénormalise les totaux pour éviter les collect().length.

​

team_of_the_week, team_of_the_week_players

• team_of_the_week.calcVersion vérifié: totw-v1, totw-v2, totw-v3.
• Champs structurants: leagueId, season, matchdayFrom, matchdayTo, periodStartAt, periodEndAt, selectionKey, formation, publishedAt.
• team_of_the_week_players.calcVersion vérifié: totw-v2, totw-v3.
• team_of_the_week_players.fitKind vérifié: exact, compatible, fallback.
• Champs vérifiés côté joueurs: position, positionDetailed?, selectionSlot, selectionRole, selectionPositionDetailed, candidateKey, scores bruts.
• team_of_the_week_players duplique leagueId et season depuis team_of_the_week pour les lectures indexées par saison; index vérifié: by_leagueId_season.

​

Discipline et restrictions (table sanctions)

• targetType vérifié: PERSON, CLUB (pas uniquement personne).
• sanctionType vérifiés (liste observée dans le schéma): BAN_PLAYER, SUSPENSION, BAN_CLUB, PENDING_DISCIPLINARY, POINTS_DEDUCTION, FINE, FORFAIT, PERSON_BAN, PERSON_SUSPENSION, PERSON_DISCIPLINARY_REVIEW, COMPETITION_BAN.
• effectScopes vérifiés: APP_ACCESS, SPORT_ELIGIBILITY, VISIBILITY, CONTACT.
• lifecycleState vérifiés: ACTIVE, ENDED_MANUAL, ENDED_EXPIRED, ENDED_REPLACED.
• endSource vérifiés: MANUAL, AUTO_EXPIRED, REPLACED.

​

Limites de ce document

• Les règles métier complètes d’envoi notification (priorités, cadence de retry, templates) ne sont pas détaillées dans ce modèle de données.
• Les comportements métier de certains types de sanction (par ex. interaction exacte entre banScope et l’admissibilité en compétition) sont documentés côté règles métiers, pas côté modèle.

​

Tables internes et techniques

• rate_limits : limitation applicative CEL par clé et fenêtre.
• email_verification_tokens : tokens pour la vérification des emails.
• password_reset_tokens : tokens pour la réinitialisation de mots de passe.
• league_calendar_snapshots et league_calendar_snapshot_entries : snapshots du calendrier des ligues.
• ea_cache_counters et ea_cache_purge_lock : gestion du cache EA API.
• cron_executions et system_settings : exécutions, configuration et déclenchement des jobs runtime.
• migration_runs : suivi des migrations et backfills opérés.
• stripe_webhook_log et stripe_customer_index : journal webhook et projection client Stripe.
• upload_objects : index des objets stockés dans le file storage Convex.