Shard-API — Documentation

API du serveur Minecraft RP Tetrago (projet Shard-2). Elle stocke les comptes, la bibliothèque, les civilisations, religions, commerces, alliances, guerres, personnages, la cartographie et les statistiques du monde. Elle est utilisée par ShardUI-2 (le site) et ShardUI-2-Maps (la carte).

Version actuelle : 2.0.15 (champ version de package.json, lu par api/core/version.py).

Ce document est aussi servi en HTML par l'API sur /documentation (source brute sur /documentation.md).

Sommaire

• Vue d'ensemble
• Installation et lancement
• Configuration
• Démarrage de l'API
• Authentification et droits
• Organisation du code
• Modèle de données
• Référence des routes
• Règles métier
• Intégrations externes
• Tests
• Points d'attention

Vue d'ensemble

             ┌────────────────────┐
 ShardUI-2 ──┤                    ├── Discord (bot, OAuth)
             │     Shard-API      ├── Microsoft / Xbox / Minecraft (OAuth)
 Maps ───────┤  FastAPI + SQLite  ├── playerdb.co (pseudos)
             │                    │
 Générateur ─┘ POST /api/monde/releves (clé X-Monde-Key)
 de cartes   └────────────────────┘

Installation et lancement

Prérequis : Python 3.10 ou plus, npm (pour les scripts), pm2 pour la production.

npm run init        # crée .venv et installe requirements.txt
cp config.json.template config.json                              # puis renseigner les valeurs
cp config.development.json.template config.development.json      # facultatif, pour le développement

Depuis la racine de Shard-2, npm run api:init fait la même chose.

Les scripts interactifs start.sh (Linux/macOS) et start.ps1 (Windows) proposent aussi de créer le venv, d'installer les dépendances et de lancer l'API.

Scripts npm

Configuration

La configuration est lue par api/core/utils.py au chargement du module.

• config.json est toujours lu. S'il n'existe pas, il est créé à partir de config.json.template.
• Si API_ENV=development (npm run dev, npm run verbose), config.development.json est fusionné par-dessus : les objets sont fusionnés clé par clé, les autres valeurs sont remplacées.
• Les fichiers chargés sont affichés au démarrage (Configuration: config.json + config.development.json).

Aucun de ces deux fichiers n'est versionné : ils contiennent des secrets.

Clés

oauth2.<fournisseur>.client_secret doit être le Client Secret OAuth2 du fournisseur, pas le jeton du bot. Chaque redirect_uri pointe vers la page /auth/<fournisseur>/callback de ShardUI-2 et doit être déclarée chez le fournisseur (Discord Developer Portal, Azure).

Variables d'environnement

Démarrage de l'API

La fonction lifespan de api/main.py exécute, dans l'ordre :

1. create_db_and_tables() : crée les tables manquantes.
2. migrate_commerces_owner_to_members() : migration unique de l'ancienne colonne commerces.owner_id vers une ligne Fondateur dans commercemembers (sans effet une fois faite).
3. check_database_tables() : compare chaque table aux modèles, ajoute les colonnes manquantes et corrige une colonne dont le type ou la nullabilité diffère en reconstruisant la table, valeurs conservées (voir ci-dessous).
4. crud.loadsecurity() : crée ou met à jour le compte administrateur de security (admin, actif, masqué).
5. crud_nettoyage.nettoyer_references_orphelines() : corrige les références laissées par d'anciennes suppressions.
6. crud_personnages.seed_referentiels() : ajoute les espèces et classes de personnages par défaut.

Correction des colonnes incohérentes

Avant la première modification de structure d'un démarrage, backup_database() copie le fichier SQLite en <database.name>.backup-<AAAA-MM-JJ_hhmmss>.db. Le chemin est rappelé à la fin de la vérification.

SQLite ne sait pas changer le type ni la nullabilité d'une colonne en place : _rebuild_table() recrée donc la table d'après son modèle, y recopie les colonnes communes, supprime l'ancienne et renomme la nouvelle — la même méthode que la migration des commerces. Si la copie échoue (une valeur NULL dans une colonne devenue NOT NULL, par exemple), la transaction est annulée : la table et ses données restent intactes et un message indique la correction à faire à la main.

Les sauvegardes *.backup-*.db ne sont pas supprimées automatiquement : les purger de temps en temps.

Pages servies

Toute autre adresse renvoie une 404 : page HTML hors /api, JSON {"detail": ...} pour l'API.

CORS : toutes les origines, méthodes et en-têtes sont acceptés, sans cookies (allow_credentials=False).

Authentification et droits

Jetons

L'authentification suit le schéma OAuth2 « password » de FastAPI, avec des jetons opaques stockés en base.

1. POST /api/users/token (formulaire username, password, paramètre expiry_hours, 24 par défaut).
2. L'API vérifie le mot de passe, supprime les sessions précédentes de l'utilisateur et crée une ActiveSession avec un jeton aléatoire de 64 caractères hexadécimaux.
3. Réponse : { "access_token": "...", "token_type": "bearer" }.
4. Les appels protégés envoient Authorization: Bearer <jeton>.

Une nouvelle connexion invalide donc les jetons précédents du même utilisateur (y compris celui de l'éditeur de carte, qui en redemande un au site).

Mots de passe

Les mots de passe sont stockés en scrypt salé, via hashlib (aucune dépendance externe). Le format en base est scrypt$<n>$<r>$<p>$<sel hex>$<clé hex> ; les paramètres de coût sont les constantes SCRYPT_* de api/services/crud.py (n = 2¹⁴, r = 8, p = 1, clé de 32 octets, sel de 16 octets).

crud.verify_password accepte aussi les empreintes de l'ancien schéma (SHA-256 sans sel, 64 caractères hexadécimaux) et signale qu'elles doivent être renouvelées ; crud.check_password s'en charge alors dans la foulée. Une empreinte héritée est donc remplacée par une empreinte scrypt à la connexion suivante de son utilisateur, sans intervention ni migration de la base. Relever les paramètres de coût provoque le même renouvellement progressif.

POST /api/users/login vérifie seulement les identifiants (par nom, par e-mail ou les deux) et renvoie le profil dans { code, user } ; il ne délivre pas de jeton. ShardUI-2 appelle /login puis /token.

Dépendances FastAPI

secu_get_current_user_optional sert aux routes publiques dont la réponse dépend du demandeur : /api/users/id/{id} et /api/users/name/{username} ne joignent l'e-mail du profil que pour son propriétaire ou un administrateur (crud.viewer_sees_private). Les autres appelants reçoivent email: null.

Rôles

Règle générale : agir au nom d'une entité demande d'en être Fondateur ou Admin, ou d'être administrateur du site. La même règle est appliquée côté site par checkMemberAuth (ShardUI-2), mais c'est l'API qui fait foi.

Organisation du code

Shard-API/
├── api/
│   ├── main.py                  # Application, démarrage (lifespan), fichiers statiques, 404, inclusion des routeurs
│   ├── core/                    # Socle commun
│   │   ├── utils.py             # Lecture et fusion de la configuration, ROOT_DIR
│   │   ├── version.py           # Version, lue dans package.json
│   │   └── documentation.py     # Rendu HTML de DOCUMENTATION.md
│   ├── db/                      # Données
│   │   ├── database.py          # Moteur SQLite, session, création/vérification des tables, migration commerces
│   │   ├── models.py            # Tables SQLModel
│   │   └── schemas.py           # Corps de requête et réponses (Pydantic)
│   ├── services/                # Logique métier
│   │   ├── crud.py              # Sécurité, utilisateurs, bibliothèque, civilisations, villes, quartiers,
│   │   │                        # religions, commerces, magasins, dimensions, cartographie, annonces Discord
│   │   ├── crud_conflits.py     # Alliances et guerres
│   │   ├── crud_personnages.py  # Personnages, espèces, classes, messages attribués
│   │   ├── crud_monde.py        # Statistiques du monde
│   │   └── crud_nettoyage.py    # Cohérence des suppressions et références orphelines
│   ├── integrations/            # Services externes
│   │   ├── oauth.py             # Discord et Microsoft (liaison et connexion)
│   │   └── discord_handler.py   # Bot Discord (salons, messages)
│   └── routes/                  # Routeurs FastAPI
│       ├── pages.py             # /, /documentation, /docs, /redoc, /api/version/, robots, sitemap, favicon
│       ├── users.py             # /api/users
│       ├── bibliotheque.py      # /api/bibliotheque
│       ├── civilisations.py     # /api/civilisations (+ gouvernements, villes, quartiers)
│       ├── religions.py         # /api/religions
│       ├── commerces.py         # /api/commerces (+ magasins)
│       ├── alliances.py         # /api/alliances
│       ├── guerres.py           # /api/guerres
│       ├── personnages.py       # /api/personnages
│       ├── cartographie.py      # /api/cartographie (+ dimensions)
│       ├── monde.py             # /api/monde
│       └── _template.py         # Modèle vide pour un nouveau routeur (non inclus)
├── templates/                   # Pages Jinja2 (accueil, documentation, docs, redoc, 404, version)
├── assets/                      # CSS (dont documentation.css), images
├── DOCUMENTATION.md             # Ce document (servi sur /documentation)
├── config.json(.template)       # Configuration
├── config.development.json(.template)
├── requirements.txt
├── start.sh / start.ps1         # Menus interactifs
└── ShardDB.db                   # Base de production (non versionnée)

Ajouter un domaine

1. Déclarer les tables dans db/models.py (elles sont créées au démarrage suivant).
2. Déclarer les corps de requête dans db/schemas.py.
3. Écrire la logique dans un module services/crud_<domaine>.py : lever des HTTPException avec un message en français, lisible tel quel par le site.
4. Créer routes/<domaine>.py à partir de routes/_template.py et l'inclure dans main.py.
5. Si des entités en référencent d'autres, compléter services/crud_nettoyage.py.

Les imports restent relatifs : depuis un sous-paquet, from ..db import models, schemas, from ..services import crud, from ..core import utils.

Modèle de données

Toutes les tables ont une clé id entière. Les dates de création sont remplies par l'API.

Comptes

Bibliothèque

Géopolitique

Alliances et guerres

Personnages

Carte

Statistiques du monde

Les 104 derniers relevés sont conservés (deux ans à raison d'un par semaine).

Référence des routes

Légende des droits : — public ; U utilisateur connecté ; A administrateur ; règle : voir Règles métier. Le détail des corps de requête est visible sur /docs.

Les réponses n'ont pas toutes le même format : selon les routes, le statut est dans code ou error (avec la valeur HTTP : 200, 404…), ou seule l'erreur HTTP est levée avec detail.

Utilisateurs — /api/users

Bibliothèque — /api/bibliotheque

Règle livre : pour un livre rattaché à une civilisation, Fondateur/Admin de cette civilisation ; sinon son auteur. L'administrateur du site a toujours accès.

| GET | /livres/contents/read/{livreID} | — | { livre, contents } | | GET | /livres/content/read/{contenuID} | — | Un contenu |

Civilisations — /api/civilisations

Religions — /api/religions

« civ. de la ville » : Fondateur/Admin de la civilisation à laquelle appartient la ville (ou la ville du quartier), ou administrateur du site. La religion elle-même n'a pas à donner son accord.

Commerces — /api/commerces

Alliances — /api/alliances

Guerres — /api/guerres

Personnages — /api/personnages

Cartographie — /api/cartographie

Droits de la cartographie : Fondateur/Admin de la civilisation propriétaire (celle de la ville ou du quartier), ou administrateur ; pour guerre, chefs de camp et modérateurs RP d'une guerre en cours.

Monde — /api/monde

Règles métier

Membres (civilisations, religions, commerces)

• Le créateur devient Fondateur. Ce rôle ne s'obtient que par transfert (/members/{id}/transfer), qui donne à l'ancien fondateur le rôle former_role (Admin par défaut).
• Les rôles ajoutables sont Admin et Membre. Un utilisateur n'est membre qu'une fois.
• Gérer les membres demande d'être Fondateur ou Admin de l'entité, ou administrateur du site.

Alliances

• Types : Militaire ou Diplomatique. Rôles : Chef de file (un seul), Membre, Observateur.
• On entre par invitation de l'alliance ou par demande de la civilisation, acceptée par l'autre partie.
• La gestion de l'alliance revient au Fondateur et aux Admins de la civilisation chef de file.

Guerres

• Militaire : entre civilisations. Religion : entre religions, que des civilisations peuvent rejoindre.

• Cycle de vie :

  déclarer ──► en_attente ──valider──► en_cours ──terminer──► terminee
                   │
                   └──refuser──► refusee
  

• Une déclaration reste privée tant qu'un modérateur RP ne l'a pas validée. Deux guerres ouvertes ne peuvent pas opposer les mêmes chefs de camp.

• Une guerre validée est archivée, jamais supprimée ; seule une déclaration en attente ou refusée peut être retirée.

• Appel aux armes : le chef de camp appelle une civilisation ou tous les membres (hors observateurs) d'une alliance dont il fait partie ; chaque appelé accepte ou décline. Un chef de camp ne peut pas se retirer.

• La chronologie s'écrit automatiquement (déclaration, validation, refus, ralliement, retrait, fin). Les chefs de camp (guerre en cours) et les modérateurs RP y ajoutent batailles, sièges, traités et autres faits ; les étapes automatiques ne peuvent pas être retirées.

• Annonces Discord (salon platforms.discord.channels.guerres) : début, batailles, sièges, traités et fin.

Personnages

• Nombre illimité, sans validation. Seuls le joueur et les administrateurs les modifient.
• Résidence cohérente : le quartier appartient à la ville, la ville à la civilisation ; les niveaux supérieurs sont complétés automatiquement.
• Skin minecraft : l'UUID du compte Microsoft lié est copié à l'enregistrement.
• Attribution d'un message : l'utilisateur doit être l'auteur Discord du message (compte Discord lié). Seul ce message est relu sur Discord et un extrait de 280 caractères est conservé.

Statistiques du monde

• Le calcul est fait par le générateur de cartes (ShardUI-2-Maps/scripts/map-generator/world_stats.py) ; l'API reçoit, complète et conserve.
• À l'arrivée : totaux recalculés à partir des dimensions, population actuelle des villes et quartiers conservée dans population_declaree, personnages domiciliés ajoutés, joueurs reliés à leur compte par l'UUID Minecraft.
• La population mesurée remplace celle des villes et quartiers. Les lieux d'une dimension absente du relevé ne sont pas modifiés.
• Pseudos : compte Minecraft lié, sinon celui fourni par le relevé, sinon playerdb.co (en tâche de fond après l'envoi, ou à la demande).

Cohérence des suppressions

Implémentée dans services/crud_nettoyage.py, et rejouée au démarrage pour les références orphelines.

Intégrations externes

Discord (bot)

integrations/discord_handler.py démarre un bot discord.py (intents par défaut + contenu des messages) à la première utilisation, avec platforms.discord.token et guild_id.

Comptes externes (OAuth)

integrations/oauth.py gère Discord (scope identify) et Microsoft. Aucun compte n'est créé depuis un fournisseur : l'utilisateur crée d'abord un compte Tetrago, lie son compte externe depuis son profil, puis peut s'en servir pour se connecter. Les jetons des fournisseurs ne sont jamais conservés.

Site                         Shard-API                      Fournisseur
 │ GET /oauth/discord/link ──►│ crée OAuthStates (10 min)     │
 │◄── { url } ────────────────│                               │
 │ redirection ───────────────┼──────────────────────────────►│
 │◄── /auth/discord/callback?code&state ──────────────────────│
 │ GET /oauth/discord/callback ►│ échange le code, lit l'identité ─►│
 │◄── { mode, ... } ──────────│                               │

Microsoft suit la chaîne Microsoft → Xbox Live → XSTS → profil Minecraft Java et renvoie un message clair pour un compte sans Xbox, un compte enfant ou un compte sans le jeu. L'application Azure doit être approuvée par Mojang (formulaire sur https://aka.ms/AppRegInfo) ; en attendant, la liaison indique que la validation est en attente.

playerdb.co

Utilisé par crud_monde pour convertir en pseudo les UUID des joueurs (10 s de délai maximal par appel).

Tests

Il n'y a pas de tests unitaires dans ce dépôt. Les parcours de bout en bout sont couverts par les tests Playwright de ShardUI-2 (npm run test:ux), qui lancent cette API sur une copie jetable de ShardDB.db avec les variables de simulation (faux Discord, faux Microsoft, faux playerdb.co, clé du monde).

Points d'attention

Les cinq constats relevés lors de la rédaction de ce document ont été traités :

Restent ouverts, sans urgence :

• Empreintes SHA-256 encore en base : elles ne disparaissent qu'au fur et à mesure des connexions. Un compte jamais reconnecté conserve son ancienne empreinte, vérifiable mais sans sel.
• oauth2.client_id / client_secret ne sont pas vérifiés par /api/users/token (code commenté).
• Format des réponses inégal : selon les routes, le statut est dans code, dans error, ou seulement dans l'erreur HTTP detail (voir Référence des routes).
• Sauvegardes *.backup-*.db jamais purgées automatiquement.