Tutoriel : construire un module de gestion de tâches

Statut documentaire : tutorial — voir Maturité et preuves.

Objectif

Construire un premier module métier complet avec les conventions actuelles de logiCells : package, manifeste, modèle Task, facettes conceptuelle et persistante, puis activation dans une configuration d'application.

Ce tutoriel privilégie YAML. La même structure peut être exprimée en XML lorsqu'un projet choisit cette voie ; les deux formats doivent converger vers le même contrat Runtime.

Structure cible

TaskManagement/
├── packages/
│   └── TaskManagement.package.yaml
└── meta/
    └── models/
        └── TaskManagement/
            ├── ClassItems.manifest.yaml
            ├── Task.model.yaml
            ├── Project.model.yaml
            └── TaskBelongsToProject.model.yaml

Conventions de nommage

• ClassItems est un manifest, pas un modèle métier.
• Les modèles métier utilisent *.model.yaml ou *.model.xml.
• Le format est visible dans l'extension.
• Les identifiants applicatifs utilisent un préfixe possédé par le projet. Ici nous utilisons tsk#.

1. Créer le package

package:
  name: TaskManagement
  enabled: true

Le package définit la frontière de chargement du module. Gardez-le minimal tant que le premier modèle n'est pas validé.

2. Créer le manifeste des classes

ClassItems.manifest.yaml :

classes:
  - class:
      classId: tsk#task
      name: Task
      type: entity
  - class:
      classId: tsk#project
      name: Project
      type: entity
  - class:
      classId: tsk#task_belongs_to_project
      name: TaskBelongsToProject
      type: relation

Le classId est une identité conceptuelle stable. Ne le modifiez pas arbitrairement une fois que des données, relations, services ou intégrations en dépendent.

3. Déclarer Task

Task.model.yaml :

class:
  classId: tsk#task
  name: Task
  type: entity
  concepts:
    - concept:
        name: Entity
        facets:
          - facet:
              type: hypergraph
              name: main
              fields:
                - Name: String
                - Description: String
                - Priority: Integer
                - StartDate: DateTime
                - EndDate:
                    type: DateTime
                    nullable: true

Ce premier modèle suffit pour établir la signification conceptuelle de Task. Ne commencez pas par le stockage : validez d'abord le modèle et son chargement.

4. Ajouter la projection persistante

Lorsque le modèle conceptuel est stable, ajoutez une facette de persistance correspondant au contrat supporté par votre Runtime :

facets:
  - facet:
      type: database
      name: Task
      mappingTableName: lgcTask
      fields:
        - IdTask:
            type: String
            size: 32
            rolePath: Id
        - ClassIdTask:
            type: String
            size: 32
            defaultValue: tsk#task
            rolePath: ClassId
        - Name:
            type: String
            size: 120
        - Description:
            type: String
            size: 500
        - Priority: Integer
        - StartDate: DateTime
        - EndDate:
            type: DateTime
            nullable: true

La facette persistante est une projection technique. Le sens métier reste porté par le modèle conceptuel.

5. Déclarer Project

class:
  classId: tsk#project
  name: Project
  type: entity
  concepts:
    - concept:
        name: Entity
        facets:
          - facet:
              type: hypergraph
              name: main
              fields:
                - Name: String
                - Description: String

6. Relier Task et Project

La relation est un élément du modèle, pas une simple clé étrangère technique.

class:
  classId: tsk#task_belongs_to_project
  name: TaskBelongsToProject
  type: relation

Complétez ses participants et contraintes avec les formes supportées par la version du Runtime utilisée. La règle importante est de conserver l'identité relationnelle dans le modèle conceptuel, même lorsqu'une projection relationnelle existe en base.

7. Activer le module

Ajoutez le package à la configuration d'application utilisée pour le test. Les chemins de déploiement restent de la configuration ; ils ne doivent pas être codés dans le modèle métier.

Au premier démarrage, vérifiez dans cet ordre :

1. configuration d'application ;
2. package ;
3. manifeste ;
4. classe Task ;
5. facettes ;
6. relation ;
7. persistance ;
8. vues et services ensuite seulement.

Cette méthode de diagnostic « de la frontière vers l'intérieur » évite de chercher un problème de vue lorsque le modèle n'est pas chargé.

8. Vérifier le premier succès

Le premier succès attendu n'est pas encore une application complète. Il consiste à vérifier que :

• le package est chargé ;
• les classId sont uniques et résolus ;
• Task et Project sont disponibles ;
• la relation est reconnue ;
• la configuration sélectionne correctement le mode de Runtime voulu.

9. Étape suivante

Continuez avec Construire les vues du module, puis ajoutez les services seulement lorsque le modèle et les vues sont stables.