Administration Mairie

Le module admin sert l'espace d'administration de la Mairie d'EtherBay : tableau de bord, disjoncteur du smart contract, reversement de la commission à la trésorerie, suspension des partenaires, gestion des comptes Mairie et partenaires, vérification des pièces d'identité, export de rapports et journal d'audit. Le tirage et l'annulation d'un tour, aussi réservés à l'ADMIN, sont dans le module Loterie.

#Protection

Le routeur applique router.use(authenticate, requireRoles('ADMIN')) avant toutes ses routes. Une requête sur n'importe quel chemin sous /admin, même inexistant, passe donc d'abord par ces deux contrôles : un USER reçoit 403 et non 404.

Pendant une maintenance (MAINTENANCE_MODE=true), seules les routes appelées par /api/admin/... restent accessibles ; le préfixe /api/v1/admin/... est bloqué comme le reste de l'API (voir Structure et cycle d'une requête).

#Routes

#GET /admin/dashboard

Combine les agrégats du module, ceux du tableau de bord analytique et l'état du réseau.

{
  "success": true,
  "message": "Tableau de bord central Mairie récupéré",
  "data": {
    "kpis": { "totalPrizePoolEth": 3.42, "ticketsSold": 342, "municipalityRevenueEth": 0.342, "registeredCitizens": 128, "activePartners": 2, "claimedRewards": 17 },
    "demographics": { "target18_35Validated": true, "ageBreakdown": { "18-25": 61, "26-35": 44, "36-50": 15, "50+": 6 } },
    "utmAcquisition": [ { "source": "direct", "conversions": 402 } ],
    "network": { "mode": "onchain", "chainId": 31337, "isFallback": false, "rpcUrl": "http://127.0.0.1:8545", "isPaused": false, "contractAddress": "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9", "poapContractAddress": "0x5FC8d32690cc91D4c39d9d3abcBD16989F875707" },
    "rounds": [ { "id": "019a7c41-...", "contractRoundId": 1, "status": "OPEN", "prizePool": 3.42 } ]
  }
}

La commission réellement disponible sur le contrat (accruedFees) n'est pas affichée ici. Elle est lisible sur la chaîne, voir Exploitation du contrat.

#POST /admin/circuit-breaker

Mode onchain : le compte opérateur appelle pause() ou unpause() sur BlockLucky, ce qui exige le rôle PAUSER_ROLE. Pendant la pause, le contrat refuse achats et tirages : POST /lottery/buy renvoie 503 avec circuitBreaker: true, le keeper ne fait rien. Un compte opérateur sans le rôle produit 403 Le compte opérateur du backend n'a pas le rôle requis sur le Smart Contract.

Mode simulé : la clé Redis blockchain:circuit_breaker passe à true ou false et un hachage aléatoire est renvoyé.

{
  "success": true,
  "message": "Circuit Breaker ACTIVÉ : Smart Contract mis en pause d'urgence",
  "data": { "paused": true, "txHash": "0x3c7e...b210", "timestamp": "2026-11-11T17:00:00.000Z", "reason": "Comportement anormal détecté sur les achats" }
}

L'état courant est exposé par GET /health (network.isPaused) et GET /lottery/status. Le parcours complet est dans Disjoncteur.

#POST /admin/treasury/withdraw

Mode onchain, dans lotteryGateway.withdrawFees :

1. si multisigWallet diffère de la trésorerie enregistrée dans le contrat, le compte opérateur appelle setTreasury(multisigWallet), qui exige DEFAULT_ADMIN_ROLE. L'opérateur détient ce rôle en local (sauf LOCAL_STRICT_ROLES=true), mais pas sur Sepolia, où il est réservé au multisig de la Mairie : il faut y saisir l'adresse MAIRIE_TREASURY_ADDRESS déjà en place ;
2. il lit accruedFees, puis appelle withdrawFees(), qui verse la totalité de la commission accumulée à la trésorerie.

Mode simulé : aucun fonds ne bouge, la réponse contient un hachage aléatoire et reprend amountEth.

{
  "success": true,
  "message": "Retrait de trésorerie vers le portefeuille multi-signatures exécuté",
  "data": { "transactionHash": "0x8e41...07cd", "amountEth": 0.004, "treasury": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8" }
}

En mode simulé, la réponse est { transactionHash, multisigWallet, amountEth, timestamp }.

#PATCH /admin/partners/:partnerId/status

Met à jour Partner.isActive. Une entreprise suspendue disparaît du catalogue avec toutes ses offres, mais ses codes déjà attribués restent valables en magasin et ses offres restent lisibles par GET /marketplace/rewards/:id. partnerId n'est pas validé : un identifiant inconnu renvoie 404 Ressource introuvable (erreur Prisma P2025). La réponse renvoie { "partner": {...} }.

Les entreprises sont actives dès leur création par POST /partners : cette route sert à suspendre puis éventuellement réactiver, pas à valider une demande en attente.

#GET /admin/reports/export

Le rapport reprend les kpis du tableau de bord.

"Metric","Value"
"Date","2026-11-11T17:30:00.000Z"
"Total_Prize_Pool_ETH","3.42"
"Municipality_Revenue_ETH","0.342"
"Tickets_Sold","342"
"Registered_Citizens","128"
"Active_Partners","2"
"Claimed_Rewards","17"

#Vérification des pièces d'identité

Ces trois routes servent la page Identités de l'espace Mairie. Elles traitent les demandes envoyées par POST /user/identity (voir Utilisateur).

#GET /admin/identity-verifications

La liste est triée par date d'envoi, la plus ancienne en premier. Chaque entrée contient id, userId, email, submittedAt et status, sans image. La réponse porte un objet meta de pagination.

#GET /admin/identity-verifications/:id

L'identifiant doit être un UUID (400 Identifiant de demande invalide) ; une demande inconnue renvoie 404. La réponse, servie avec Cache-Control: no-store, contient le compte (email, walletAddress, accountCreatedAt), le statut, les dates, l'agent qui a statué, le motif d'un refus et les deux images front et back sous forme d'URL data: déchiffrées.

Les images ne sont renvoyées que pour une demande PENDING. Après une décision, front et back valent null, puisque les images ont été effacées. Chaque consultation est tracée dans l'audit, même sans image.

#POST /admin/identity-verifications/:id/decision

La décision est écrite dans une transaction qui ne s'applique qu'à une demande encore PENDING :

L'administrateur reçoit { "decision": { "id", "userId", "status", "reviewedAt", "note" } }. Le citoyen reçoit l'email identity-decision, avec le motif en cas de refus ; il peut alors envoyer une nouvelle pièce. Un compte sans email n'est pas prévenu.

#Comptes Mairie et partenaires

Ces trois routes servent la page /mairie/comptes du web (voir Pages et espaces). Elles remplacent la promotion d'un compte par une requête SQL : seul le tout premier compte ADMIN doit encore être créé en base (voir Comptes de démonstration et connexion).

#GET /admin/accounts

Les comptes supprimés sont exclus et la liste est triée du plus récent au plus ancien. Chaque compte contient id, email, role, firstName, lastName, isTwoFactorEnabled, createdAt et, pour un partenaire, partners, la liste de ses établissements (id, name, isActive). La réponse porte un objet meta de pagination.

#POST /admin/accounts

Crée un compte Mairie ou partenaire, ou attribue ce rôle à un compte existant, puis envoie une invitation par email.

La réponse contient { "account": {...}, "created": true }, avec le compte sous la même forme que dans la liste. L'invitation utilise le modèle staff-invitation.html : elle rappelle l'identifiant de connexion, l'établissement rattaché, la façon de se connecter (« Mot de passe oublié » sur le mobile, code email sur le web) et l'obligation d'activer la 2FA pour l'espace Mairie. Un échec de mise en file est seulement journalisé.

#PATCH /admin/accounts/:id/role

1. Son propre compte est refusé : 403 Vous ne pouvez pas modifier votre propre rôle.
2. Un compte inconnu ou supprimé renvoie 404 Compte introuvable ; un rôle identique 409 Ce compte a déjà le rôle ... ; le retrait du dernier ADMIN 409 Impossible de retirer le dernier compte Mairie.
3. Le rôle est changé dans une transaction. Un compte qui quitte le rôle PARTNER est détaché de ses établissements (ownerId remis à null), qui ne sont plus gérables que par la Mairie.
4. Toutes les sessions du compte sont révoquées : le nouveau rôle s'applique à la prochaine connexion.
5. L'action est tracée : STAFF_ROLE_REVOKED pour un passage à USER, STAFF_ROLE_CHANGED sinon. Aucun email n'est envoyé.

La réponse vaut { "account": {...} }, avec le message Rôle retiré ou Rôle du compte mis à jour.

#Journal d'audit

Chaque action sensible écrit une ligne Analytics avec eventType = ADMIN_AUDIT:<action>, userId de l'administrateur, utmSource = admin-dashboard et le détail en metadata. Les clients ne peuvent pas écrire de lignes avec ce préfixe (voir Analytique).

L'audit est écrit après l'action : une action qui échoue n'est pas tracée, et un échec d'écriture de l'audit après une transaction réussie renvoie une erreur alors que l'action a eu lieu. Le tirage et l'annulation de tour (POST /lottery/draw, /refund) ne sont pas audités.

#GET /admin/audit-logs

limit est lu dans la query, défaut 100, sans borne supérieure.

{
  "success": true,
  "message": "Journal des logs d'audit récupéré",
  "data": {
    "logs": [
      { "id": "019a7c80-...", "action": "CIRCUIT_BREAKER_PAUSE", "adminId": "019a7c01-...", "adminWallet": "0x4a1e...", "metadata": { "paused": true, "reason": "Comportement anormal détecté sur les achats", "txHash": "0x3c7e...b210" }, "timestamp": "2026-11-11T17:00:00.000Z" }
    ]
  }
}

adminWallet vaut Système si la ligne n'est rattachée à aucun compte.