Omika/docs/niveau-3-modele-canonique.md

Niveau 3 — Modèle métier canonique et contrats API

Rôle des dossiers de Omika.Core

Domain/

Le domaine contient les entités métier canoniques, indépendantes du stockage.

Elles correspondent aux concepts fonctionnels de l'application :

• Client, Adresse, Contact, Site ;
• Societe, Collaborateur, Equipe, Utilisateur ;
• Dossier, Intervention, ActionIntervention, CompteRendu, Checklist ;
• RendezVous et ses éléments associés ;
• Document et modèles de courrier/rapport ;
• Role, Permission, DroitAcces ;
• ParametreMetier, ParametreApplication, PreferenceUtilisateur.

Elles ne portent :

• aucun attribut HFSQL ;
• aucun préfixe de rubrique physique (CL_, IN_, PL_, RDV_…) ;
• aucun champ zombie.

Les objets de valeur (ValueObjects/) représentent des valeurs sans identité :

• ReferenceValue (valeur de référentiel configurable) ;
• DateTimeRange (plage horaire validée) ;
• PostalAddress, ContactDetails ;
• ExternalReference (référence vers Batigest / base externe).

Les exceptions (Exceptions/) portent les erreurs de validation du domaine.

Contracts/

Les contrats sont utilisés entre Omika.Api et Omika.App.

Ce sont des DTO purs :

• résumés de liste ;
• détails ;
• requêtes de création / modification / recherche ;
• DTO communs (pagination, enveloppe d'erreur, référence, adresse, coordonnées).

Distinction AddressDto / AdresseDto :

• AddressDto (Contracts/Common) : adresse postale simple, sans identité (libellé, lignes, code postal, ville, pays). Réutilisée partout où une adresse postale brute est nécessaire.
• AdresseDto (Contracts/Clients) : adresse d'une entité du domaine Clients, avec identifiant, type, indicateurs (« principale », « archivée ») et une adresse postale optionnelle (AdressePostale). Il ne s'agit pas d'un doublon de AddressDto : l'un est une valeur, l'autre un conteneur d'entité.

Ils ne contiennent :

• aucun attribut HFSQL ;
• aucune propriété à préfixe physique ;
• aucune dépendance vers Omika.Data ;
• aucun champ zombie ;
• aucun mot de passe ni objet de connexion ;
• aucun graphe cyclique.

Compatibility/

Les types de compatibilité conservent la provenance des données sans exposer la structure physique :

• DatabaseSchemaVersion (Unknown / Batik / Omika) ;
• DatabaseSource (version + nom logique de base) ;
• LegacyEntityReference (référence vers l'enregistrement d'origine) ;
• SchemaCapabilities (capacités déclarées d'un schéma) ;
• CanonicalMappingResult<T> (résultat d'un mapping physique → canonique).

Interfaces/, Abstractions/, Constants/, Runtime/, Mapping/

• Interfaces/ : services métier (voir ci-dessous).
• Abstractions/ : abstractions techniques existantes, non touchées.
• Constants/ : constantes existantes.
• Runtime/ : contexte d'exécution existant, non touché.
• Mapping/ : mappers purs entité métier → DTO.

Différence entre une entité métier et un modèle physique

Modèle physique (Omika.Data)	Entité métier (Omika.Core.Domain)
Correspond aux tables HFSQL (Document.fic, Planning_RDV…)	Correspond aux concepts fonctionnels (Document, RendezVous…)
Porte des rubriques préfixées (DC_Categorie, PL_PKID…)	Porte des propriétés métier nommées sans préfixe
Marque les rubriques zombie	Ne contient jamais de champ zombie
Connaît les clés internes et la version physique	Connaît uniquement les identifiants canoniques et la provenance

La chaîne attendue :

Modèle physique Batik (Isis_BO)          Modèle physique Omika
            |                                      |
            +----------> Modèle métier canonique <-+
                                |
                                v
                          Contrat API
                                |
                                v
                        Application Avalonia

Le mapping physique → métier reste dans Omika.Data. Le mapping métier → DTO est dans Omika.Core/Mapping.

Différence entre une entité métier et un DTO

Entité métier	DTO (contrat)
Évolue dans le temps (classe)	Immutable par convention (record avec propriétés init)
Expose des collections contrôlées (Add*)	Expose des listes IReadOnlyList<T> en lecture seule
Peut contenir des objets de valeur du domaine	Ne contient que des DTO ou types primitifs
Vit dans Domain/	Vit dans Contracts/
N'est jamais sérialisé tel quel	Est la frontière de l'API

Stratégie des identifiants

Les identifiants publics des contrats sont des chaînes afin de permettre temporairement :

• le GUID Omika ;
• l'identifiant historique Batik (Isis_BO) ;
• une clé métier.

Le domaine utilise Guid Id (identifiant canonique) plus LegacyEntityReference? SourceReference pour conserver la référence d'origine sans exposer la clé physique.

LegacyEntityReference.PublicIdentifier fournit une représentation publique stable (GUID → clé métier → identifiant numérique → GUID physique → ImportId).

Un helper de représentation publique des identifiants peut être ajouté plus tard si le besoin se fait sentir côté API/mobile.

Stratégie des paramètres métier

Les paramètres métier (type de client, statut, type d'activité, priorité…) sont représentés par ReferenceValue :

• Key : clé métier stable (nouveau schéma Omika) ;
• LegacyId : identifiant historique (ancien schéma Batik) ;
• Code : code court éventuel ;
• Label : libellé d'affichage.

Ils ne sont pas transformés automatiquement en enum : ils restent configurables. Le passage en enum n'est envisagé que si un paramètre devient vraiment stable et fermé.

Stratégie des champs zombie

Les rubriques physiques obsolètes (anciens identifiants de civilité, de statut, clés internes…) sont marquées zombie dans les modèles physiques de Omika.Data.

Dans Omika.Core :

• elles n'apparaissent jamais comme propriétés publiques ;
• le mapper de Omika.Data est responsable de convertir les valeurs en propriétés métier (ReferenceValue, libellés, etc.) ;
• les tests d'architecture interdisent leur apparition dans les contrats.

Stratégie de compatibilité Batik (Isis_BO) / Omika

• Le domaine est unique pour les deux bases.
• La provenance est conservée via LegacyEntityReference / DatabaseSource.
• SchemaCapabilities permet de savoir, sans connaître la structure physique, si une fonctionnalité est disponible dans la version source (clés métier, GUID, rôles, nouveau modèle de rendez-vous…).
• CanonicalMappingResult<T> permet à un mapper physique → canonique de retourner la valeur plus les warnings, champs ignorés et erreurs non bloquantes.

Cas particulier des rendez-vous

Un agrégat métier unique RendezVous reçoit les données des deux versions :

• ancien modèle : Planning_RDV, Planning_RDV_Personne ;
• nouveau modèle : RDV_Planning, RDV_Collaborateur, RDV_Contact.

L'entité porte :

• une DateTimeRange Periode ;
• des AffectationCollaborateur (responsable, période particulière, statut, temps validé) ;
• des ParticipantRendezVous (contact, coordonnées, type, présence confirmée) ;
• une AnnulationRendezVous éventuelle ;
• des liens optionnels vers Client / Site / Dossier / Intervention.

Toute information absente dans une version est nullable.

Le contrat RendezVousDetailsDto est identique pour les deux versions et ne contient aucune notion de Planning_RDV, RDV_Planning, PL_PKID, RDP_GUID ou autre nom physique.

Liste des fichiers créés

Omika.Core/Compatibility

• DatabaseSchemaVersion.cs
• DatabaseSource.cs
• LegacyEntityReference.cs
• SchemaCapabilities.cs
• CanonicalMappingResult.cs

Omika.Core/Domain/Common

• EntityBase.cs

Omika.Core/Domain/ValueObjects

• ReferenceValue.cs
• DateTimeRange.cs
• PostalAddress.cs
• ContactDetails.cs
• ExternalReference.cs

Omika.Core/Domain/Exceptions

• DomainException.cs
• DomainValidationException.cs

Omika.Core/Domain/Entities

• Clients/Client.cs, Adresse.cs, Contact.cs, Site.cs
• Organisation/Societe.cs, Collaborateur.cs, Equipe.cs, Utilisateur.cs
• Interventions/Dossier.cs, Intervention.cs, ActionIntervention.cs, CompteRendu.cs, EtatIntervention.cs, Checklist.cs, ChecklistItem.cs
• Planning/RendezVous.cs, AffectationCollaborateur.cs, ParticipantRendezVous.cs, AnnulationRendezVous.cs, SuiviTemps.cs
• Documents/Document.cs, NoteDocument.cs, MessageInterne.cs, MessageExterne.cs, ModeleMail.cs, ModeleRapport.cs
• Security/Role.cs, Permission.cs, DroitAcces.cs
• Configuration/ParametreMetier.cs, ParametreApplication.cs, PreferenceUtilisateur.cs

Omika.Core/Contracts/Common

• ApiErrorDto.cs, ApiResult.cs, PagedRequest.cs, PagedResult.cs
• ReferenceValueDto.cs, AddressDto.cs, ContactDetailsDto.cs

Omika.Core/Contracts/Clients

• ClientSummaryDto.cs, ClientDetailsDto.cs
• CreateClientRequest.cs, UpdateClientRequest.cs, SearchClientsRequest.cs
• AdresseDto.cs, ContactDto.cs, SiteDto.cs

Omika.Core/Contracts/Organisation

• CollaborateurSummaryDto.cs, CollaborateurDetailsDto.cs
• EquipeDto.cs, SocieteDto.cs, UtilisateurDto.cs

Omika.Core/Contracts/Interventions

• DossierSummaryDto.cs, DossierDetailsDto.cs
• InterventionSummaryDto.cs, InterventionDetailsDto.cs
• CreateInterventionRequest.cs, UpdateInterventionRequest.cs, SearchInterventionsRequest.cs
• ActionInterventionDto.cs, CompteRenduDto.cs, EtatInterventionDto.cs

Omika.Core/Contracts/Planning

• RendezVousSummaryDto.cs, RendezVousDetailsDto.cs
• CreateRendezVousRequest.cs, UpdateRendezVousRequest.cs, SearchRendezVousRequest.cs
• AffectationCollaborateurDto.cs, ParticipantRendezVousDto.cs, AnnulationRendezVousDto.cs, SuiviTempsDto.cs, CreateSuiviTempsRequest.cs

Omika.Core/Contracts/Documents

• DocumentSummaryDto.cs, DocumentDetailsDto.cs, CreateDocumentRequest.cs
• ModeleMailDto.cs, ModeleRapportDto.cs

Omika.Core/Contracts/Security

• LoginRequest.cs, CurrentUserDto.cs, RoleDto.cs, PermissionDto.cs

Omika.Core/Contracts/Configuration

• ParametreMetierDto.cs, ApplicationConfigurationDto.cs, PreferenceUtilisateurDto.cs

Omika.Core/Interfaces

• IClientService.cs, IInterventionService.cs, IRendezVousService.cs, IDocumentService.cs, IReferenceDataService.cs, ICurrentUserService.cs

Omika.Core/Mapping

• ClientContractMapper.cs, InterventionContractMapper.cs, RendezVousContractMapper.cs, DocumentContractMapper.cs

Omika.Tests

• Architecture : CoreMustNotReferenceDataTests, CoreMustNotReferenceAvaloniaTests, CoreMustNotReferenceAspNetCoreTests, PublicContractsMustNotContainHfSqlNamesTests, PublicContractsMustNotContainZombieFieldsTests
• Contrats : PagedResultTests, ClientContractTests, InterventionContractTests, RendezVousContractTests
• Domaine : DateTimeRangeTests, ClientDomainTests, InterventionDomainTests, RendezVousDomainTests, RendezVousCrossSchemaTests
• Compatibilité : LegacyEntityReferenceTests, SchemaCapabilitiesTests

Décisions encore à valider

1. Identifiants publics : chaînes temporaires (GUID / legacy / clé métier). Un helper dédié ou un type valeur « PublicId » reste possible.
2. États et statuts : conservés en ReferenceValue. À confirmer si certains deviendront des enums stables.
3. DateTime vs DateTimeOffset : pas de gestion multi-fuseaux documentée pour l'instant ; DateTime est utilisé partout. À revoir si le mobile doit synchroniser sur plusieurs fuseaux.
4. Collections dans les entités : List<T> privées avec méthodes Add*. À confirmer si des collections doivent devenir remplaçables (remplacement complet lors d'une mise à jour).
5. Contrat de recherche : SearchClientsRequest hérite de PagedRequest avec des propriétés additionnelles. Les filtres seront consolidés lors de l'implémentation des services.
6. Sécurité : LoginRequest accepte un mot de passe temporaire, mais aucun service d'authentification n'est implémenté à ce niveau. Le stockage des identifiants (hash, salt) sera décidé au niveau supérieur.
7. Fichiers physiques des documents : les contrats exposent des identifiants logiques et des métadonnées ; la gestion du téléversement/téléchargement sera définie avec l'API.