Initial commit

docs/ARCHITECTURE.md

@@ -0,0 +1,51 @@
+# Architecture V1
+
+## État et autorité
+
+`ShopSavedData` conserve boutiques, réputation par propriétaire et crédits. `ShopInventoryBlockEntity` conserve les objets. `ShopManager` gère les sessions en mémoire sur le thread serveur. Mode, règles et identifiant de session sont immuables ; les commandes sont tarifées à leur création. L’écran reçoit un instantané et envoie des actions de menu, jamais des montants approuvés par le client.
+
+`Delivery.consume` vérifie toutes les cases avant de modifier un objet. `ShopManager.finish` retire la commande avant le paiement : un second clic ne peut plus la valider. Cela protège les interactions normales ; il ne s’agit pas d’un journal transactionnel entre fichiers joueur, chunks et SavedData en cas d’arrêt brutal du système.
+
+## Provenance
+
+Le composant `ShopProductionData`, persistant et synchronisé, contient boutique, session, producteur, handler et famille. `ShopProductionTracker` définit le contrat commun. Les adaptateurs observent la production réelle. Un addon serveur est du code de confiance : appeler `produced` sans consommer les ingrédients violerait ce contrat.
+
+Les mixins Vanilla suivent :
+
+- Le contexte de clic, restauré par `try/finally`, et les ingrédients avant consommation.
+- Les résultats de craft, taille et forge pendant l’extraction ; les prévisualisations perdent ensuite leur marquage.
+- Les restes de fabrication lors de la consommation réelle, avant restitution dans la grille.
+- Les lots de four chargés manuellement, les entrées attendues et les opérations successives ; les anciennes sorties et les apports automatiques invalident l’accréditation.
+
+Une matière explicitement autorisée peut servir d’ingrédient externe. Un produit livrable exige un marquage de la session courante. Une nouvelle session rend les marquages précédents inutilisables.
+
+## Résolveur et stock
+
+`RecipeResolver` est indépendant de Minecraft. Il explore les alternatives sur des copies, détecte les cycles, compte les lots, restes et combustibles. Recherche bornée à 12 niveaux et 12 000 étapes par demande ; échec ou budget épuisé exclut le produit.
+
+`ShopStock` compte les conteneurs par identité : stockages, inventaire/cursor du propriétaire dans la zone, véritables entrées de menus, comptoir et stock fourni par les handlers. Les prévisualisations ne comptent pas. Les productions valides disponibles peuvent satisfaire une commande sans refabrication. Les objets à composants particuliers sont exclus du calcul par ID.
+
+L’estimation est conservatrice : elle n’optimise pas la chaleur déjà engagée ni l’ordonnancement parallèle des machines. Les durées s’additionnent. Le joueur reste libre d’utiliser toute chaîne admissible, sans recette imposée.
+
+Cache de recettes indépendant du mode ; résolveurs partagés par capacités ; quantités recalculées pour chaque commande. Scan complet à la vérification, à l’ouverture ou après invalidation, jamais à chaque tick. Rechargement : fermeture neutre et invalidation des caches.
+
+## Ajouter une intégration
+
+Enregistrer avec `ProductionRegistry.register`, à l’initialisation commune :
+
+1. `StationFamilyProvider` : IDs de familles namespacés.
+2. `StationProvider` : reconnaissance des blocs, retour `StationDefinition(id, family, handler)` ; `intrinsicStations` pour les capacités sans bloc.
+3. `RecipeProvider` : `ProductionRecipe` déterministes. Chaque ensemble d’alternatives consomme **une unité** ; répéter l’ensemble pour plusieurs unités.
+4. `ProductionHandler` : validation des entrées et éventuel stock physique des stations.
+
+L’adaptateur vérifie propriétaire, présence et station réelle ; observe les ingrédients avant consommation ; appelle `ShopProductionTracker.produced(ProductionContext, inputs, output)` uniquement à la création réelle ; consomme exactement les entrées. Il observe ou refuse les apports automatiques. `reset` abandonne les contextes techniques invalides.
+
+Exemple exécutable : `src/gameTest/java/fr/shinuwa/counterofshinuwa/test/TestProductionIntegration.java`. Station cloche, nouvelle famille, recette et handler ajoutés sans branche spécifique dans le cœur. Le mod de test est exclu du JAR distribué.
+
+## Easy NPC
+
+Le cœur connaît `NpcAdapter`. `EasyNpcAdapter` crée le type configuré, établit sa propriété et utilise les bulles Easy NPC. Un objectif personnalisé enregistré via son API suit les positions de la boutique avec une précision de chemin de zéro bloc.
+
+Core 7.12.1 présente deux particularités : les villageois exigent un objectif de voyage pour bouger ; l’action publique termine son chemin à un bloc de la cible. L’objectif propre au mod permet de suivre précisément les tapis. La navigation est réessayée ; après 600 ticks sans progrès, le client est retiré sans pénalité technique. Les anciens clients sont supprimés à leur rechargement si la session a disparu.
+
+Types testés : `easy_npc:humanoid`, `easy_npc:villager`. D’autres types peuvent avoir des dimensions ou comportements incompatibles avec les parcours et nécessitent des essais dédiés.

docs/IMPLEMENTATION.md

@@ -0,0 +1,56 @@
+# Réalisation et validation V1
+
+Cible : Minecraft 1.21.1 / NeoForge 21.1.235 / Java 21 / Easy NPC Core 7.12.1.
+
+## Implémentation
+
+- [x] Identité du mod, configurations, intégration obligatoire Easy NPC.
+- [x] Boutique persistante, cinq objets de construction, inventaires et outil de liaison.
+- [x] Validation des zones, parcours, spécialisations et chunks, contours côté client.
+- [x] Framework extensible et production Vanilla : 2×2, 3×3, four, haut fourneau, fumoir, taille de pierre, forge.
+- [x] Provenance par boutique/session/propriétaire, lots manuels, exclusion des anciens résultats et des apports automatiques.
+- [x] Graphe de recettes, alternatives, cycles, quantités, restes, combustible et stock sans doublons.
+- [x] Sessions STANDARD/CHILL, commandes jusqu’à trois lignes, livraison atomique pour les interactions normales, paiement et crédit persistant.
+- [x] Clients Easy NPC, file, navigation, dialogues, sortie, récupération des blocages, réputation et fermetures.
+- [x] Écrans, modèles utilisant les textures Vanilla, recettes d’obtention, traductions FR/EN, documentation et scripts d’installation/validation.
+- [x] Extension de test ajoutant famille, station, recette et handler sans modifier le cœur.
+
+## Contrôles exécutés — 17 septembre 2026
+
+**14 tests unitaires**, sans échec :
+
+- Règles des deux modes, réputation CHILL à 500, progression STANDARD.
+- Prix multi-produit et arrondi unique après multiplicateur.
+- Recettes récursives, tailles de lots, restes, ressources partagées, alternatives, cycles, combustible, budget de recherche et absence de mutation lors d’un échec.
+
+**21 GameTests**, sans échec sur serveur Minecraft/NeoForge avec Easy NPC :
+
+- Sérialisation de boutique, modes et invalidation des anciens marquages.
+- Livraison exacte sur plusieurs piles, surplus et refus sans consommation partielle.
+- Craft 2×2, 3×3 et shift-craft ; rejet des intermédiaires externes et fabrications hors zone.
+- Fours manuels, haut fourneau, fumoir ; rejet du chargement automatique, des anciennes sorties et des mélanges par entonnoir.
+- Tailleur de pierre, transformation netherite, restes de fabrication marqués.
+- Permissions des stockages, limitation des sessions, inventaire plein et crédit restant.
+- Transfert stockage → grille → curseur sans duplication du stock.
+- Humanoïde et villageois Easy NPC : apparition, navigation et suppression.
+- Cycle client → commande → fabrication → livraison → paiement → départ ; double validation sans double paiement.
+- Fermeture neutre après obstruction du parcours.
+- Extension indépendante de production ; entonnoir incapable de retirer le stock sécurisé.
+
+Les joueurs simulés des GameTests ne négocient pas les canaux réseau Easy NPC : son API peut journaliser un refus de bulle de dialogue vers ces connexions simulées. La synchronisation avec un vrai client est couverte séparément.
+
+**Test graphique automatisé réussi**, dans un affichage Xvfb isolé : chargement des mods, connexion au serveur intégré, création d’une boutique, arrivée du PNJ au comptoir, réception de la commande et affichage de l’écran français. Capture inspectée : `run/clientSmoke/counter-smoke.png`. Témoin d’exécution : `run/clientSmoke/counter-smoke.ok`.
+
+**Construction du JAR réussie.** Rapports unitaires : `build/reports/tests/test/index.html`. Bilan serveur : `build/reports/gametest.log`. Le script de vérification exige un bilan non vide de tests réussis, en plus du code de sortie Gradle.
+
+## Limites des preuves et recette manuelle
+
+Les tests automatiques ne remplacent pas une partie prolongée. Les points suivants restent à éprouver avant de qualifier une version publique de stable :
+
+- Deux vrais joueurs sur un serveur dédié : réapprovisionnement par un ami, reconnexion, échanges rapides et inventaires pleins.
+- Arrêt puis redémarrage complet d’un serveur avec boutiques et crédits, récupération des anciens PNJ dans des chunks chargés ultérieurement. La sérialisation et l’invalidation par session sont testées ; cette séquence disque/processus complète n’est pas automatisée.
+- Déchargement réel des chunks, rechargement de datapacks et reconfiguration en cours de jeu.
+- Parcours avec relief, obstacles mobiles et autres types d’entités Easy NPC configurés.
+- Équilibrage des prix, de la patience et des quantités ; performances avec un modpack volumineux et de nombreuses boutiques actives.
+
+La V1 utilise des recettes à résultat déterministe. Les objets à composants particuliers et mécanismes non pris en charge sont exclus. L’estimation de combustible/durée est conservatrice pour les machines déjà en cours de cuisson. Farmer’s Delight, automatisation admissible, assistants, feu de camp et recettes spéciales sont prévus après cette version.