Datamodel + Appv2 migration, WIP

DATAMODELS_GUIDE.md

@@ -0,0 +1,223 @@
+# Guide d'utilisation des DataModels BoL
+
+## Exemples d'utilisation
+
+### Accès aux données d'un acteur
+
+```javascript
+// Character
+const character = game.actors.getName("Mon Héros");
+console.log(character.system.attributes.vigor.value);
+console.log(character.system.resources.hp.value);
+console.log(character.system.xp.total);
+
+// Encounter
+const npc = game.actors.getName("Gobelin");
+console.log(npc.system.chartype); // "tough"
+console.log(npc.system.isundead);
+
+// Horde
+const horde = game.actors.getName("Horde de Zombies");
+console.log(horde.system.hordesize);
+console.log(horde.system.hasdamagerule);
+
+// Vehicle
+const ship = game.actors.getName("Navire Pirate");
+console.log(ship.system.attributes.hull.value);
+console.log(ship.system.vehicletype); // "boat"
+```
+
+### Accès aux données d'un item
+
+```javascript
+// Item (équipement)
+const sword = game.items.getName("Épée");
+console.log(sword.system.properties.weapon);
+console.log(sword.system.quantity);
+console.log(sword.system.worn);
+
+// Feature (capacité)
+const trait = game.items.getName("Vision nocturne");
+console.log(trait.system.rank);
+console.log(trait.system.description);
+```
+
+### Modification des données
+
+```javascript
+// Modifier les HP d'un personnage
+await actor.update({
+  "system.resources.hp.value": 10
+});
+
+// Modifier plusieurs valeurs en une fois
+await actor.update({
+  "system.attributes.vigor.value": 3,
+  "system.attributes.agility.value": 2,
+  "system.resources.hp.max": 15
+});
+
+// Modifier la quantité d'un item
+await item.update({
+  "system.quantity": 5,
+  "system.worn": true
+});
+```
+
+### Création d'acteurs avec DataModels
+
+```javascript
+// Créer un personnage
+await Actor.create({
+  name: "Nouveau Héros",
+  type: "character",
+  system: {
+    chartype: "player",
+    attributes: {
+      vigor: { value: 2 },
+      agility: { value: 1 },
+      mind: { value: 0 },
+      appeal: { value: 1 }
+    },
+    resources: {
+      hp: { value: 10, max: 10 },
+      hero: { value: 5, max: 5 }
+    }
+  }
+});
+
+// Créer une horde
+await Actor.create({
+  name: "Horde d'Orcs",
+  type: "horde",
+  system: {
+    hordesize: 20,
+    hordebasehp: 5,
+    attributes: {
+      vigor: { value: 2 },
+      agility: { value: 1 }
+    }
+  }
+});
+```
+
+### Création d'items avec DataModels
+
+```javascript
+// Créer une arme
+await Item.create({
+  name: "Hache de bataille",
+  type: "item",
+  system: {
+    category: "weapon",
+    quantity: 1,
+    properties: {
+      weapon: true,
+      melee: true,
+      "2H": true
+    }
+  }
+});
+
+// Créer un trait
+await Item.create({
+  name: "Berserker",
+  type: "feature",
+  system: {
+    rank: 2,
+    category: "trait",
+    description: "<p>Rage au combat...</p>"
+  }
+});
+```
+
+## Ajout de méthodes personnalisées (Évolution future)
+
+Les DataModels permettent d'ajouter des méthodes personnalisées. Exemple à ajouter dans `character.mjs` :
+
+```javascript
+export default class BoLCharacterDataModel extends foundry.abstract.TypeDataModel {
+  // ... defineSchema ...
+  
+  /**
+   * Calcul automatique des données dérivées
+   */
+  prepareDerivedData() {
+    super.prepareDerivedData();
+    
+    // Calculer HP max basé sur Vigor
+    const hpMax = 10 + (this.attributes.vigor.value * 2);
+    if (this.resources.hp.max !== hpMax) {
+      this.resources.hp.max = hpMax;
+    }
+    
+    // Calculer la défense
+    const def = this.attributes.agility.value + this.aptitudes.def.value;
+    if (this.aptitudes.def.value !== def) {
+      this.aptitudes.def.value = def;
+    }
+  }
+  
+  /**
+   * Vérifier si le personnage est KO
+   */
+  isKnockedOut() {
+    return this.resources.hp.value <= 0;
+  }
+  
+  /**
+   * Appliquer des dégâts
+   */
+  async applyDamage(amount) {
+    const newHP = Math.max(0, this.resources.hp.value - amount);
+    await this.parent.update({
+      "system.resources.hp.value": newHP
+    });
+  }
+}
+```
+
+## Validation des données
+
+Les DataModels valident automatiquement les données :
+
+```javascript
+// ❌ Cette tentative échouera (vigor.value doit être un integer)
+await actor.update({
+  "system.attributes.vigor.value": "trois" // Erreur !
+});
+
+// ✅ Valide
+await actor.update({
+  "system.attributes.vigor.value": 3
+});
+
+// ❌ Cette tentative échouera (vigor.value max: 5)
+await actor.update({
+  "system.attributes.vigor.value": 10 // Erreur si max est 5 !
+});
+```
+
+## Migration des données existantes
+
+Les données existantes (créées avec template.json) restent compatibles car la structure est identique. Aucune migration de données n'est nécessaire.
+
+## Debugging
+
+Pour inspecter la structure d'un DataModel :
+
+```javascript
+// Afficher le schéma du DataModel
+console.log(game.bol.models.BoLCharacter.defineSchema());
+
+// Afficher les données d'un acteur
+const actor = game.actors.getName("Mon Héros");
+console.log(actor.system); // Instance du DataModel
+console.log(actor.system.toObject()); // Données brutes
+```
+
+## Ressources
+
+- [Foundry DataModel Documentation](https://foundryvtt.com/api/classes/foundry.abstract.DataModel.html)
+- [Data Fields Reference](https://foundryvtt.com/api/modules/foundry.data.fields.html)
+- Exemples dans `fvtt-cthulhu-eternal` et `fvtt-mournblade`