218 lines
9.3 KiB
Markdown
218 lines
9.3 KiB
Markdown
# Sokko G
|
||
|
||
Webapp React locale pour préparer et accompagner des sessions gaming sur second écran.
|
||
|
||
Sokko G propose des toolboxes modulaires stockées dans le navigateur, ainsi que des pages de guides de jeu maintenues dans le dépôt. Aucune donnée utilisateur n’est envoyée côté serveur.
|
||
|
||
L'interface cible les fenêtres d'ordinateur en plein écran ou en demi-écran. Les mises en page sont validées à partir de 768 px ; le projet ne prévoit pas d'interface ni de navigation dédiées au téléphone.
|
||
|
||
## Fonctionnalités
|
||
|
||
- Toolboxes locales stockées dans IndexedDB.
|
||
- Outils disponibles : bloc notes, checklist avec quantités, images, annotation d’images, liens, compteurs et calculateur.
|
||
- Import/export d’une toolbox.
|
||
- Import/export global de toutes les toolboxes.
|
||
- Association locale entre une page jeu et une toolbox.
|
||
- Bascule Guide / Toolbox sous 1440 px et panneau latéral redimensionnable à partir de 1440 px sur les pages jeux.
|
||
- Suivi d’un budget de stockage recommandé, avec quota navigateur en information.
|
||
- Pages de guides de jeu éditables via JSON.
|
||
- Listes de jeu exportables vers les checklists.
|
||
|
||
## Démarrage
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
Par défaut, le site démarre sur `http://localhost:5173`.
|
||
|
||
Pour générer la version statique de production :
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
Le build est généré dans `website/dist`.
|
||
`npm start` sert cette version statique avec `server.mjs`.
|
||
|
||
## Configuration
|
||
|
||
Le serveur et Vite lisent automatiquement un fichier `.env` facultatif à la racine
|
||
du projet, avec le parseur natif de Node. Les variables déjà définies dans le
|
||
processus sont prioritaires, y compris lorsqu'elles sont vides.
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Exemple :
|
||
|
||
```env
|
||
PORT=5173
|
||
```
|
||
|
||
Le fichier `.env` est ignoré par git. Pour changer le port localement, modifier `PORT`.
|
||
|
||
## Vérifications
|
||
|
||
Avant un push ou une mise en ligne :
|
||
|
||
```bash
|
||
npm run check
|
||
```
|
||
|
||
Cette commande vérifie la configuration Node/Vite, lance les tests, puis exécute le build React.
|
||
|
||
Pour inclure les parcours navigateur, lancer `npm run check:full`. Le check, les
|
||
E2E de développement et les E2E de production sont exécutés successivement pour
|
||
éviter la concurrence avec le build.
|
||
La suite E2E utilise deux workers par défaut pour limiter la contention lors du
|
||
chargement initial des outils par Vite. Le parallélisme reste ajustable avec
|
||
`npm run test:e2e -- --workers=4`. Les traces des tests en échec sont conservées
|
||
dans `test-results` et consultables depuis le rapport Playwright.
|
||
|
||
`npm run test:e2e:production` reconstruit l'application puis teste les comportements
|
||
propres à la production, notamment la visibilité de la prise en main. Cette suite
|
||
utilise temporairement `127.0.0.1:4173` ; le port doit être libre, aucune instance
|
||
existante n'est réutilisée. Le navigateur est isolé des données personnelles et
|
||
le serveur est fermé à la fin. Ses diagnostics sont conservés séparément dans
|
||
`test-results/production` et `playwright-report/production`. La suite habituelle
|
||
`npm run test:e2e` reste sur Vite en développement et exclut ces scénarios.
|
||
|
||
L'application est enveloppée dans `StrictMode` : en développement (y compris les
|
||
E2E sur Vite), React rejoue certains rendus et cycles d'effets pour détecter les
|
||
effets de bord et les nettoyages manquants. Ces contrôles supplémentaires ne
|
||
s'exécutent pas en production. Les règles recommandées React Hooks, dont
|
||
`react-hooks/set-state-in-effect`, sont actives dans ESLint.
|
||
|
||
Pour mesurer le chargement local des toolboxes, lancer `npm run profile:toolboxes`
|
||
avec Chromium Playwright installé (`npx playwright install chromium`). Le script
|
||
construit la production, utilise temporairement `127.0.0.1:4173` (le port doit être
|
||
libre) et crée ses données dans des profils Chromium temporaires sur disque,
|
||
sans toucher aux toolboxes personnelles. Il supprime uniquement ses profils
|
||
temporaires et ferme le navigateur et le serveur à la fin.
|
||
|
||
Les quatre scénarios comparent une base vide, 40 toolboxes légères, une toolbox
|
||
avec 160 images WebP synthétiques et les mêmes images réparties sur 40 toolboxes.
|
||
Cinq rechargements après une navigation de chauffe mesurent l'affichage de la
|
||
liste après lecture IndexedDB, la durée de lecture, les tâches longues et le tas
|
||
JavaScript après GC. Le rapport brut est écrit dans
|
||
`.local/performance/toolbox-loading.json`, hors Git. Exécuter ce profil seul, sans
|
||
build ou tests concurrents. Ce n'est ni un budget CI, ni une mesure du démarrage
|
||
à cache froid, ni de la mémoire totale du navigateur ; les résultats dépendent
|
||
de la machine et ne couvrent pas le décodage des images dans une toolbox ouverte.
|
||
Le profil suit les lectures groupées et ciblées et vérifie que les valeurs des
|
||
outils Images restent sur disque tant qu'aucune toolbox n'est ouverte.
|
||
|
||
## Contenu éditable
|
||
|
||
Les contenus maintenus à la main sont regroupés dans `website/public/data`.
|
||
|
||
| Fichier | Rôle |
|
||
| --- | --- |
|
||
| `website/public/data/site.json` | Textes généraux du site : home, about, navigation, sidebar, page toolboxes. |
|
||
| `website/public/data/games.json` | Liste des jeux affichés sur `/games` et contenus des cards jeux. |
|
||
| `website/public/data/mhwilds/monsters.json` | Données des monstres Monster Hunter Wilds. |
|
||
| `website/public/data/mhwilds/endemic_life.json` | Données de la faune Monster Hunter Wilds. |
|
||
| `website/public/data/mhwilds/lists/*.json` | Listes de jeu MHWilds copiables ou convertibles en checklist. |
|
||
| `website/public/data/mhwilds/lists/index.json` | Index généré automatiquement des listes MHWilds. |
|
||
| `website/public/data/mhwilds/i18n/fr.json` | Traductions françaises des données MHWilds. |
|
||
| `website/public/data/mhwilds/i18n/en.json` | Traductions anglaises des données MHWilds. |
|
||
| `website/public/data/diablo4/affixes_types.json` | Données et filtres des affixes Diablo IV. |
|
||
| `website/public/data/toolbox-icons.json` | Manifeste des icônes SVG réutilisables. |
|
||
|
||
Les images publiques sont dans `website/public/static`.
|
||
|
||
Les index de listes sont générés automatiquement par :
|
||
|
||
```bash
|
||
npm run lists:index
|
||
```
|
||
|
||
Ce script est lancé avant `npm run dev`, `npm run build` et `npm run check`.
|
||
|
||
## Pages jeux
|
||
|
||
Les pages jeux sont dans `website/src/features/games`.
|
||
|
||
- `website/src/features/games/GamesPage.jsx` : liste des jeux disponibles.
|
||
- `website/src/features/games/GameRoute.jsx` : route vers la page du jeu demandé.
|
||
- `website/src/features/games/mhwilds/` : vues et composants propres à Monster Hunter Wilds.
|
||
- `website/src/features/games/diablo4/` : vues et composants propres à Diablo IV.
|
||
|
||
Pour ajouter un jeu :
|
||
|
||
- ajouter son entrée dans `website/public/data/games.json` ;
|
||
- créer son dossier dans `website/src/features/games/` si la page nécessite un rendu spécifique ;
|
||
- brancher sa route dans `website/src/features/games/GameRoute.jsx`.
|
||
|
||
## Outils de toolbox
|
||
|
||
Les outils de toolbox sont déclarés dans `website/src/features/toolboxes/modules/index.jsx`.
|
||
Chaque outil possède son propre fichier de composant :
|
||
|
||
- `website/src/features/toolboxes/modules/NotepadModule.jsx`
|
||
- `website/src/features/toolboxes/modules/ChecklistModule.jsx`
|
||
- `website/src/features/toolboxes/modules/ImagesModule.jsx`
|
||
- `website/src/features/toolboxes/modules/LinksModule.jsx`
|
||
- `website/src/features/toolboxes/modules/CountersModule.jsx`
|
||
- `website/src/features/toolboxes/modules/CalculatorModule.jsx`
|
||
- `website/src/features/toolboxes/modules/ImageAnnotationModule.jsx`
|
||
|
||
Pour ajouter ou maintenir un outil :
|
||
|
||
- créer son fichier dans `website/src/features/toolboxes/modules/` ;
|
||
- l’ajouter au registre `MODULE_COMPONENTS` dans `website/src/features/toolboxes/modules/index.jsx` ;
|
||
- garder les données persistées via le service IndexedDB `website/src/utils/indexedDbStorage.js`.
|
||
|
||
## Structure
|
||
|
||
```text
|
||
.
|
||
├── DESIGN_SYSTEM.md
|
||
├── package.json
|
||
├── server.mjs
|
||
├── vite.config.js
|
||
├── tests/
|
||
└── website/
|
||
├── index.html
|
||
├── public/
|
||
│ ├── data/
|
||
│ └── static/
|
||
└── src/
|
||
├── main.jsx
|
||
├── components/
|
||
├── features/
|
||
│ ├── games/
|
||
│ │ ├── diablo4/
|
||
│ │ └── mhwilds/
|
||
│ └── toolboxes/
|
||
│ └── modules/
|
||
└── styles/
|
||
├── _base.scss
|
||
├── _cards.scss
|
||
├── _diablo4.scss
|
||
├── _games.scss
|
||
├── _home.scss
|
||
├── _icons.scss
|
||
├── _mixins.scss
|
||
├── _mhwilds.scss
|
||
├── _nebula.scss
|
||
├── _overlays.scss
|
||
├── _responsive.scss
|
||
├── _shell.scss
|
||
├── _tokens.scss
|
||
├── _toolboxes.scss
|
||
└── main.scss
|
||
```
|
||
|
||
## Stockage local
|
||
|
||
Les données utilisateur sont stockées dans IndexedDB, dans la base `sokkog`.
|
||
|
||
Espaces principaux :
|
||
|
||
- `kv` : registre des toolboxes, associations jeu -> toolbox et réglages locaux.
|
||
- `modules` : données de chaque outil, indexées par `{toolboxId}:{moduleId}`.
|
||
|
||
La barre affichée utilise un budget recommandé de confort pour l’app. Le quota navigateur réel vient de `navigator.storage.estimate()` et peut être beaucoup plus élevé selon l’espace disque disponible. Les images et annotations restent locales et peuvent occuper beaucoup d’espace ; les exports globaux restent recommandés pour sauvegarder les données.
|