Dictionnaire de données

Cette page décrit chaque table, chaque colonne et chaque énumération de la base PostgreSQL du backend. Les tableaux ne sont pas écrits à la main : ils sont générés à chaque construction de la documentation à partir de backend/prisma/schema.prisma et des fichiers SQL de backend/prisma/migrations/. Une colonne ajoutée au schéma apparaît donc ici sans intervention ; seule sa description doit être rédigée.

La vue d'ensemble des relations, avec le diagramme entité-association, est sur la page Modèle de données. La justification de chaque index et de chaque contrainte est sur la page Index et contraintes.

#Mode de lecture

Chaque modèle Prisma fait l'objet d'une section. Le nom du modèle est aussi le nom de la table PostgreSQL, entre guillemets doubles dans le SQL car il contient des majuscules : SELECT * FROM "User";. De même pour les colonnes : "walletAddress".

Les colonnes du tableau de chaque modèle se lisent ainsi :

#Champs de relation

Les lignes de type relation vers … ne correspondent à aucune colonne en base. Ce sont les champs de navigation du client Prisma : ticket.user, user.tickets. La colonne réelle est la clé étrangère qui les accompagne (userId, lotteryId…), signalée dans la colonne Contraintes par « clé étrangère » et le comportement ON DELETE quand il est précisé dans le schéma. Quand il ne l'est pas, Prisma applique Restrict pour une relation obligatoire et SetNull pour une relation facultative.

#Index et contraintes de la table

Sous chaque tableau, une liste reprend les attributs de bloc du schéma (@@index, @@unique) et les contraintes CHECK trouvées dans les migrations. Les CHECK ne sont pas exprimables dans le schéma Prisma : elles n'existent que dans le SQL, et la génération va les y chercher.

#Exemple de lecture

Dans la section Ticket, la ligne ticketIndex indique un Int non obligatoire. Avec la ligne d'unicité @@unique([lotteryId, ticketIndex]), cela se lit : en mode onchain, un numéro de ticket ne peut apparaître qu'une fois par tour ; en mode simulé, la colonne reste vide, et PostgreSQL considère deux valeurs NULL comme distinctes, si bien que les tickets simulés ne se gênent pas entre eux.

#Conventions transverses

• Identifiants : tous en String. Les UUID v7 (uuid(7)) sont triables par date de création. User.referralCode utilise un UUID v4 (uuid()), non prévisible. ChainCursor.id est fixé par le code.
• Dates : DateTime est stocké en TIMESTAMPTZ(3), au fuseau UTC, avec une précision à la milliseconde.
• Montants : les montants en wei sont en String pour rester exacts ; prizePool est en ETH flottant, pour l'affichage.
• Adresses : stockées en minuscules.
• Données sensibles : walletEncryptedKey et twoFactorSecret sont chiffrées par l'application (AES-256-GCM) ; Token.token et twoFactorBackupCodes sont des empreintes SHA-256. Aucune colonne ne contient de secret en clair. Voir Cryptographie et secrets.
• Suppression : les comptes ne sont jamais supprimés physiquement par l'application ; ils sont anonymisés et deletedAt est renseigné.

#Mise à jour de cette page

Les descriptions viennent du fichier documentation-officielle/content/_data/modele-donnees.json, organisé ainsi :

{
  "modeles": { "User": { "description": "…", "champs": { "id": "…" } } },
  "enumerations": { "Role": { "description": "…", "valeurs": { "USER": "…" } } }
}

Après une modification de schema.prisma, il faut ajouter dans ce fichier la description de chaque nouveau champ, modèle, énumération ou valeur. La construction de la documentation signale chaque description manquante, et le job CI documentation échoue tant qu'il en reste.

#Tables et colonnes

#User

Compte d'un citoyen, d'un commerçant partenaire ou d'un agent de la Mairie. Porte le portefeuille Ethereum intégré, le mot de passe facultatif, le statut de vérification d'âge, le solde d'EtherPoints, la double authentification et le parrainage. Un compte peut aussi être créé sans email par l'indexeur pour une adresse inconnue qui a acheté sur le contrat. La suppression RGPD anonymise la ligne au lieu de la supprimer.

Index et contraintes de la table :

• Index : @@index([referredById])
• Contrainte CHECK RewardCatalog_remainingStock_non_negative : "remainingStock" >= 0

#IdentityDocument

Pièce d'identité envoyée par un citoyen pour la vérification d'âge. Une seule ligne par compte : un nouvel envoi remplace le précédent. Le recto et le verso sont chiffrés en AES-256-GCM et effacés dès que la Mairie statue ; la ligne est supprimée avec l'anonymisation RGPD du compte.

Index et contraintes de la table :

• Index : @@index([status, submittedAt])
• Index : @@index([reviewerId])

#Token

Jeton à usage unique et à durée limitée envoyé par email. Seule l'empreinte SHA-256 du jeton est stockée. Utilisé aujourd'hui pour confirmer une suppression de compte (validité 24 h).

Index et contraintes de la table :

• Index : @@index([userId])

#LotteryRound

Tour de loterie. En mode onchain, projection d'un tour du contrat BlockLucky, identifié par contractRoundId et alimenté par l'indexeur et la lecture du contrat. En mode simulé, tour créé et piloté par le backend.

Index et contraintes de la table :

• Index : @@index([status])

#Ticket

Ticket de loterie. En mode onchain, une ligne par ticket émis par l'événement TicketsPurchased, identifiée par le couple tour et numéro de ticket. Un achat de plusieurs tickets produit plusieurs lignes partageant le même hachage de transaction.

Index et contraintes de la table :

• Unicité : @@unique([lotteryId, ticketIndex])
• Index : @@index([userId, purchasedAt])
• Index : @@index([lotteryId])
• Index : @@index([transactionHash])

#ChainCursor

Curseur de l'indexeur blockchain. Une seule ligne, d'identifiant BlockLucky, contient le dernier bloc entièrement indexé. La remettre à zéro ou la supprimer fait relire la chaîne depuis CHAIN_START_BLOCK.

#PointTransaction

Journal des mouvements d'EtherPoints. Chaque crédit ou débit écrit une ligne et met à jour User.pointsBalance dans la même transaction. Les montants sont positifs pour un crédit et négatifs pour un débit.

Index et contraintes de la table :

• Index : @@index([userId, createdAt])

#Partner

Commerce partenaire d'EtherBay qui propose des récompenses en échange d'EtherPoints.

Index et contraintes de la table :

• Index : @@index([ownerId])

#RewardCatalog

Offre de récompense d'un partenaire, échangeable contre des EtherPoints, avec un stock limité.

Index et contraintes de la table :

• Index : @@index([partnerId])
• Contrainte CHECK RewardCatalog_totalStock_non_negative : "totalStock" >= 0
• Contrainte CHECK RewardCatalog_costInPoints_positive : "costInPoints" > 0
• Contrainte CHECK LotteryRound_prizePool_non_negative : "prizePool" >= 0

#ClaimedReward

Récompense obtenue par un citoyen : un code promo unique à présenter chez le partenaire, qui le valide une seule fois.

Index et contraintes de la table :

• Index : @@index([userId, claimedAt])
• Index : @@index([rewardId])

#Analytics

Événement d'analytique (parcours, sources UTM) ou entrée du journal d'audit d'administration. Les entrées d'audit ont un eventType préfixé ADMIN_AUDIT:.

Index et contraintes de la table :

• Index : @@index([eventType, timestamp])
• Index : @@index([userId])
• Contrainte CHECK User_pointsBalance_non_negative : "pointsBalance" >= 0

#Énumérations

#Role

Rôle d'autorisation d'un compte, vérifié par le middleware RBAC.

#TwoFactorMethod

Méthode de double authentification d'un compte.

#AgeVerificationStatus

Statut de la vérification d'âge, porté par User.ageVerificationStatus et IdentityDocument.status.

#TokenType

Usage d'un jeton à usage unique de la table Token.

#Status

Statut d'un tour de loterie, aligné sur l'énumération Solidity RoundStatus du contrat.