What's your best IA Rules to generate TopModel files ? #541
gideruette
started this conversation in
General
Replies: 3 comments
|
First proposal, generated by Cursor from the documentation : description: Règles pour écrire des fichiers TopModel (.tmd) conformes au schéma JSON
|
| Type | Identifiant | Usage |
|---|---|---|
| Standard | name |
Champ primitif avec domaine |
| Association | association |
Clé étrangère vers autre classe |
| Composition | composition |
Instance(s) d'autre classe |
| Alias | alias |
Réutilisation de propriétés existantes |
Validation du schéma
Avant de sauvegarder un fichier .tmd :
- ✅ Vérifier la structure YAML (documents séparés par
---) - ✅ Vérifier que le frontmatter est présent et valide
- ✅ Vérifier que les champs obligatoires sont présents
- ✅ Vérifier que les types correspondent au schéma JSON
- ✅ Vérifier que les classes/endpoints/décorateurs référencés sont dans
uses - ✅ Vérifier l'ordre des propriétés dans les définitions
- ✅ Vérifier que tous les commentaires obligatoires sont présents
Exemples complets
Exemple 1 : Classe persistée avec associations
---
module: Restaurant
tags:
- back
uses:
- Restaurant/Entities/Client
---
class:
name: Commande
trigram: CMD
comment: Commande d'un client dans un restaurant
properties:
- name: Id
domain: DO_ID
primaryKey: true
comment: Identifiant unique de la commande
- name: DateCommande
domain: DO_DATE_HEURE
required: true
comment: Date et heure de la commande
- name: MontantTotal
domain: DO_PRIX
required: true
comment: Montant total de la commande
- association: Client
required: true
withReverse:
comment: Commandes du client
comment: Client ayant passé la commande
unique:
- [ClientId, DateCommande]Exemple 2 : DTO avec alias et mapper
---
module: Restaurant
tags:
- front
- back
uses:
- Restaurant/Entities/Commande
---
class:
name: CommandeRead
comment: Commande en lecture pour l'API
properties:
- alias:
class: Commande
mappers:
from:
- params:
- class: CommandeExemple 3 : Endpoint complet
---
module: Restaurant
tags:
- api-client
- back
uses:
- Restaurant/Dtos/CommandeWrite
- Restaurant/Dtos/CommandeRead
- Restaurant/Entities/Commande
options:
endpoints:
prefix: api/commandes
---
endpoint:
name: CreateCommande
method: POST
route: /
description: Crée une nouvelle commande
params:
- composition: CommandeWrite
name: commande
comment: Données de la commande à créer
returns:
composition: CommandeRead
name: result
comment: Commande créée avec son IDExemple 4 : Classe de référence (enum)
---
module: Common
tags:
- back
- front
---
class:
name: StatutCommande
trigram: STC
reference: true
comment: Statuts possibles pour une commande
properties:
- name: Code
domain: DO_CODE
primaryKey: true
comment: Code du statut
- name: Libelle
domain: DO_LIBELLE
required: true
comment: Libellé du statut
values:
EnAttente: { Code: EN_ATT, Libelle: "En attente" }
EnPreparation: { Code: EN_PREP, Libelle: "En préparation" }
Terminee: { Code: TERM, Libelle: "Terminée" }Anti-patterns à éviter
❌ Oublier le frontmatter
class: # ❌ Manque le frontmatter avec module/tags
name: Test✅ Correct
---
module: Test
tags: []
---
class:
name: Test❌ Mauvais ordre des propriétés
properties:
- domain: DO_ID # ❌ domain avant name
name: Id
comment: ID✅ Correct
properties:
- name: Id # ✅ name en premier
domain: DO_ID
comment: ID❌ Référence sans uses
---
module: Test
tags: []
---
class:
name: MaClasse
properties:
- association: AutreClasse # ❌ AutreClasse pas dans uses
comment: Association✅ Correct
---
module: Test
tags: []
uses:
- chemin/vers/AutreClasse
---
class:
name: MaClasse
properties:
- association: AutreClasse # ✅ AutreClasse dans uses
comment: Association❌ Commentaires manquants
class:
name: Test
properties: # ❌ Manque class.comment
- name: Prop
domain: DO_CODE # ❌ Manque property.comment✅ Correct
class:
name: Test
comment: Description de la classe # ✅
properties:
- name: Prop
domain: DO_CODE
comment: Description de la propriété # ✅
0 replies
|
Proposal for Topmodel X Focus4 generated by Copilot using both docs + Some prompt exemple Project — AI Rules v1 (Focus v4 × TopModel)0) Objectifs & principes (rappel)
1) Périmètre & versions
2) Modélisation TopModel — règles renforcées2.1 Domaines
2.2 Propriétés
2.3 Classes
2.4 Endpoints
2.5 Mappers & converters
2.6 Annotations / Décorateurs
3) Configuration & génération
4) Front Focus v4 — règles complémentaires
5) Qualité & sécurité5.1 Checklists Dev
5.2 Checklists Review (Lead Tech)
5.3 Garde‑fous recommandés
6) Mesure & capitalisation
Prompts :
1) Modélisation TopModel (
|
0 replies
Guide TopModel - DosiTL📖 À propos de TopModelTopModel est un outil open-source de modélisation et de génération de code développé par Klee Contrib.
Principe fondamentalTopModel suit une approche Model-First :
Avantages✅ Single Source of Truth - Le modèle est la source unique de vérité 🏗️ Architecture TopModel dans DosiTLStructure des fichiers⚙️ Configuration TopModel (topmodel.config)Configuration actuelle de DosiTLapp: DosiTL
# Générateur JPA (Backend Java)
jpa:
- tags: [Entity, Dto]
outputDirectory: ../backend/
apiPath: "{modelRootPath}:fr/irsn/dositl/controllers/{module}"
entitiesPath: "{modelRootPath}:fr/irsn/dositl/entity/{module}"
dtosPath: "{modelRootPath}:fr/irsn/dositl/dto/{module}"
daosPath: "{modelRootPath}:fr/irsn/dositl/dao/{module}"
enumsPath: "{modelRootPath}:fr/irsn/dositl/enums/{module}"
apiGeneration: Server
persistenceMode: jakarta # Jakarta EE (Spring Boot 3+)
translateReferences: false
identity:
mode: sequence # Séquences PostgreSQL
start: 1
increment: 1
# Générateur JavaScript/TypeScript (Frontend Angular)
javascript:
- tags: [Api, Dto, Reference]
outputDirectory: ../frontend/src/appgenerated
apiMode: angular # Services Angular
entityMode: typed # Interfaces TypeScript typées
entityTypesPath: "ngx-focus-entities"
referenceMode: values # Tableaux de valeurs pour les refs
domainPath: "@root/domains"
resourceRootPath: ../assets
translateReferences: false
# Générateur SQL (Migrations)
sql:
- tags: [Entity]
outputDirectory: ../backend/src/main/resources/db
targetDBMS: postgre # PostgreSQL
procedural:
crebasFile: 01_crebase.sql # CREATE TABLE
indexFKFile: 02_index-fk.sql # Index et FK
uniqueKeysFile: 03_uniq.sql # Contraintes UNIQUE
initListFile: 04_references.sql # Données de référence
commentFile: 05_comments.sql # COMMENT ON
resourceFile: 06_resources.sql # Autres ressources
# Générateur i18n (Traductions)
i18n:
defaultLang: fr_FR
rootPath: i18n/{lang}/inTags et leur significationLes tags contrôlent ce qui est généré pour chaque classe :
📝 Syntaxe des fichiers .tmdStructure d'un fichier .tmd---
module: NomDuModule # Nom du module (correspond au dossier)
uses: # Imports d'autres modules
- Meta/Domain
- Common/01_Entities
tags: # Tags de génération
- Entity
- Dto
---
# Définitions de classes (voir sections suivantes)1. Domaines (Domain.tmd)Les domaines définissent les types de données réutilisables. domain:
name: DO_LIBELLE
label: Libelle
ts:
type: string
java:
type: String
sql:
type: varchar
length: 100Domaines avec validation : domain:
name: DO_MOT_DE_PASSE
label: Mot de passe
ts:
type: string
java:
type: String
annotations:
- text: '@Pattern(
regexp = "^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%&*]).{12,}$",
message = "Le mot de passe doit comporter au moins 12 caractères..."
)'
imports:
- jakarta.validation.constraints.Pattern
sql:
type: varchar
length: 300Domaines avec formatage de date : domain:
name: DO_DATE_TIME
label: DateTime
ts:
type: string
java:
type: LocalDateTime
imports:
- java.time.LocalDateTime
annotations:
- text: '@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd/MM/yyyy - hh:mm")'
imports:
- com.fasterxml.jackson.annotation.JsonFormat
sql:
type: timestampDomaines génériques : domain:
name: DO_PAGE
ts:
type: Page
genericType: "Page<{T}>" # {T} sera remplacé par le type réel
imports:
- "@app/services/api-types/Page"
java:
type: Page
genericType: Page<{T}>
imports:
- org.springframework.data.domain.PageDomaines avec fichiers : domain:
name: DO_FILE_EXCEL_RESPONSE_ENTITY
mediaType: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
ts:
type: File
java:
type: ResponseEntity<Resource>
imports:
- org.springframework.http.ResponseEntity
- org.springframework.core.io.Resource2. Décorateurs (decorators.tmd)Propriétés communes réutilisables : decorator:
name: DateCreation
decorators:
- property:
name: DateCreation
comment: Date de création
domain: DO_DATE_CREATION
label: Date de création
required: true3. Références / Énumérations (00_References.tmd)class:
name: Profil
reference: true # Marque comme énumération
trigram: PRO
comment: Profil utilisateur
properties:
- name: Code
primaryKey: true
domain: DO_CODE
- name: Libelle
domain: DO_LIBELLE
values: # Valeurs de l'énumération
- Code: ADMIN
Libelle: Administrateur
- Code: TECH
Libelle: Technicien
- Code: EXPERT
Libelle: Expert🔍 Fonctionnalités avancées de TopModelRequêtes personnalisées dans les DAOs# model/Utilisateur/01_Entities.tmd
class:
name: Utilisateur
# ... propriétés ...
queries:
- name: searchUtilisateurs
type: query
returns: list
params:
- name: nom
domain: DO_LIBELLE_LONG
- name: email
domain: DO_EMAIL
- name: profil
class: ProfilCode
- name: pageable
domain: DO_PAGEABLE
sql: |
SELECT u FROM Utilisateur u
WHERE (:nom IS NULL OR :nom = '' OR LOWER(u.nom) LIKE LOWER(CONCAT('%', :nom, '%')))
AND (:email IS NULL OR :email = '' OR LOWER(u.email) LIKE LOWER(CONCAT('%', :email, '%')))
AND (:profil IS NULL OR u.profil.code = :profil)
AND u.isActif = trueGénère : public interface UtilisateurDAO extends JpaRepository<Utilisateur, Long> {
@Query("SELECT u FROM Utilisateur u WHERE ...")
@EntityGraph(attributePaths = {"profil"})
Page<Utilisateur> searchUtilisateurs(
String nom,
String email,
ProfilCode profil,
Pageable pageable
);
}Mappers complexesclass:
name: UtilisateurRechercheDto
mappers:
from:
- params:
- class: Utilisateur
- class: Profil
name: fromUtilisateurAndProfilGénère : public class UtilisateurMappers {
public static UtilisateurRechercheDto fromUtilisateurAndProfil(
Utilisateur utilisateur,
Profil profil
) {
// ... mapping automatique
}
}Relations entre entités# Association simple (Many-to-One)
- association: Profil
comment: Profil de l'utilisateur
required: true
# Association avec nom personnalisé
- association: Utilisateur
name: Createur
comment: Créateur de l'enregistrement
required: true
# Liste (One-to-Many)
- association: Permission
as: list
comment: Liste des permissionsPropriétés calculées (non persistées)class:
name: UtilisateurDto
properties:
- alias:
class: Utilisateur
- name: NomComplet # Propriété calculée
domain: DO_LIBELLE_LONG
comment: Nom complet (nom + prénom)
# Pas de mapping -> doit être rempli manuellement⚡ Extension VSCode TopModelInstallation
Fonctionnalités✅ Autocomplétion - Suggestions contextuelles Commandes VSCode
🚨 Erreurs fréquentes et solutions❌ Erreur : Circular dependency dans les uses# Module A uses Module B
# Module B uses Module ASolution : Créer un module commun ❌ Erreur : Propriété inconnue après générationProblème : Nouvelle propriété ajoutée mais pas visible en Java/TS Solutions :
❌ Erreur : Type incompatible entre Java et TypeScriptProblème : Le type Java ne correspond pas au type TS Solution : Vérifier la définition du domaine dans domain:
name: DO_PROBLEMATIQUE
ts:
type: number # ✅ Cohérent
java:
type: Long # ✅ Cohérent❌ Erreur : Mapper ne se génère pasProblème : Pas de méthode Solution : Vérifier la section class:
name: MonDto
mappers:
to: # ✅ to = générer toEntity()
- class: MonEntity
from: # ✅ from = générer fromEntity()
- params:
- class: MonEntity❌ Erreur : Endpoint ne génère pas le bon verbe HTTPProblème : Solution : Vérifier la casse exacte : endpoint:
method: POST # ✅ Majuscules
# method: post # ❌ Ne fonctionne pas📋 Checklist avant de générer✅ Les fichiers 🎓 Best Practices TopModel1. Organisation des modules2. Nommage
3. Domaines réutilisables❌ Mauvais - Domaines spécifiques : domain:
name: DO_EMAIL_UTILISATEUR # Trop spécifique
name: DO_NOM_CLIENT # Trop spécifique✅ Bon - Domaines génériques : domain:
name: DO_EMAIL # Réutilisable partout
name: DO_NOM_PRENOM # Réutilisable partout4. DTOs vs Entities
# ✅ Bon : DTO allégé
class:
name: UtilisateurListeDto
properties:
- alias:
class: Utilisateur
include: [Id, Nom, Prenom, Email] # Pas de mot de passe !
# ❌ Mauvais : Exposer toute l'entité
class:
name: UtilisateurDto
properties:
- alias:
class: Utilisateur # Inclut TOUT, même MotDePasse5. Versionnement des fichiers .tmd✅ Committer les fichiers 6. Documentation dans les modèlesclass:
name: Utilisateur
comment: Utilisateur de l'application avec ses droits et profil # ✅ Descriptif
endpoint:
name: CreateUtilisateur
description: | # ✅ Détaillé
Créé un nouvel utilisateur dans le système.
Envoie un email de confirmation avec un lien d'activation.
params:
- composition: UtilisateurCreationDto
comment: Les données du nouvel utilisateur # ✅ Utile🔄 Migration / Évolution du modèleAjout d'une colonne# Avant
class:
name: Utilisateur
properties:
- name: Email
domain: DO_EMAIL
# Après
class:
name: Utilisateur
properties:
- name: Email
domain: DO_EMAIL
- name: Telephone # ✅ Nouvelle colonne
domain: DO_TELEPHONE
required: false # NULL autorisé en BDDImpact :
Action manuelle :
Renommage d'une propriété# Avant
- name: NomComplet
domain: DO_LIBELLE
# Après
- name: NomEtPrenom # ✅ Nouveau nom
domain: DO_LIBELLEAttention : Renommage = suppression + ajout pour la BDD Action manuelle :
Suppression d'une entité
🛠️ Débogage TopModelVoir ce qui sera généré sans écraser# Utiliser l'option dry-run (si disponible dans votre version)
modgen --dry-runLogs de générationL'extension VSCode TopModel affiche les logs dans :
Validation du modèle# Vérifier la syntaxe sans générer
# (Dépend de la version de TopModel installée)
modgen --validate📚 Ressources complémentaires
🤖 Instructions pour l'IAEn tant qu'IA de développement travaillant sur DosiTL :
Workflow recommandé pour l'IA
|
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
AI Rules for .tmd files
We've been working with AI assistants (Cursor, GitHub Copilot) on TopModel projects and noticed they could benefit from clearer guidelines when generating
.tmdfiles.Proposal: Establish community rules to help AI tools:
Open questions:
.cursorrules, docs, repo root)?We'd like to gather feedback from the community before formalizing anything.
All reactions