Omika/docs/LOT_SERVEUR_SYNC_CONNECTION.md

LOT SERVEUR — CONNEXION PHYSIQUE BASE TECHNIQUE SYNC (HFSQL)

OBJECTIF

Brancher l'implémentation moderne de synchronisation mobile existante sur la vraie base HFSQL technique de synchronisation, via le provider OLE DB PCSOFT.HFSQL.

Cette base technique est distincte de la base métier Batik/Omika (ODBC) et de la base Licence : elle héberge les files de communication mobile/service.

IMPORTANT

• aucune modification du schéma HFSQL ;
• aucune création/suppression de table ;
• aucune reprise du vieux WebService ;
• les anciennes documentations servent uniquement à connaître les tables, relations et comportements historiques ;
• les traitements modernes peuvent être différents ;
• les contrats API modernes restent la référence ;
• aucun secret historique ne doit être recopié.

TABLES TECHNIQUES UTILISÉES

Le repository de synchronisation (SyncTransferRepository) lit/écrit dans les tables techniques suivantes :

Table	Rôle	Colonnes utilisées
TOSRV	File d'entrée des opérations reçues du mobile (non transférées)	TS_PKID, TS_Date, TS_Mobile, TS_CMD, TS_Buffer, TS_Lu, TS_JSON
MobReception	File de travail des opérations transférées en attente de traitement	MR_PKID, MR_IDToSRV, MR_JSON, MR_CMD, MR_Buffer, MR_NumSerie, MR_Fait, MR_DateHeureRecep
MobLog	Journal des états terminaux (SUCCESS / REJECTED) et historique	ML_PKID, ML_DateCreat, ML_Message, ML_Niveau

Ces tables sont hébergées dans la base technique Sync, configurée séparément (section SyncConnection), jamais dans la base métier Batik/Omika.

CONFIGURATION CENTRALISÉE

La connexion Sync est configurée dans la section SyncConnection des fichiers de configuration .NET (appsettings / variables d'environnement / secrets) :

"SyncConnection": {
  "Server": "localhost",
  "Port": 4900,
  "DatabaseName": "Sync",
  "Login": "",
  "Password": "",
  "FilePasswords": {
    "ProtectionStd": "",
    "ProtectionPlus": ""
  }
}

• Server / Port : serveur HFSQL Client/Serveur.
• DatabaseName : nom de la base technique Sync.
• Login / Password : compte technique serveur (jamais en clair en source).
• FilePasswords : mots de passe de fichiers HFSQL (ProtectionStd / ProtectionPlus), propres à l'installation. Optionnels.

Aucun secret historique n'est repris : les valeurs proviennent exclusivement de la configuration d'installation.

OUVERTURE DE LA CONNEXION VIA OLEDB

La connexion Sync est enregistrée comme IHfsqlConnection nommée "Sync" (SyncConnectionOptions.ConnectionName), distincte de la connexion métier ODBC par défaut et de la connexion Licence.

• SyncConnectionOptions : options de connexion (section SyncConnection).
• SyncConnectionOptionsValidator : validation minimale (règle pure, testable).
• HfSqlConnectionOptionsFactory.CreateForSync(...) : traduction vers les options OLE DB.
• SyncOleDbConnection : connexion OLE DB réutilisant le contrat IHfsqlConnection (lecture, métadonnées), alimentée par la fabrique OLE DB.

BRANCHEMENT DU REPOSITORY

AddOmikaDataSyncConnection() (dans Omika.Data) :

1. enregistre la configuration SyncConnection (section SyncConnection) ;
2. enregistre le validateur SyncConnectionOptionsValidator ;
3. enregistre la fabrique OLE DB IHfSqlOleDbConnectionFactory ;
4. enregistre la connexion IHfsqlConnection nommée "Sync" (Scoped).

⚠️ OBSOLÈTE : cette méthode ne branche plus ISyncTransferRepository sur la connexion Sync. Le repository est désormais multi-connexion (voir section "Topologie multi-connexion" ci-dessous). Cette méthode est conservée uniquement pour la compatibilité de configuration (section SyncConnection) et pour les outils de diagnostic. Sa suppression est proposée une fois toutes les références migrées.

Le repository de synchronisation lit/écrit désormais dans deux bases physiques distinctes via les connexions explicites Service et WebService. Les contrats API modernes restent la référence ; aucune donnée physique HFSQL n'est exposée (le repository ne renvoie que des entités métier).

MAPPING VERS LES CONTRATS MODERNES

Le SyncTransferRepository mappe les lignes physiques vers les contrats modernes (SyncEnvelope, SyncLogEntry, SyncStatusResponse) :

• TOSRV.TS_JSON / MobReception.MR_JSON → SyncEnvelope (JSON versionné).
• MobLog.ML_Message → SyncLogEntry (JSON versionné, schemaVersion).
• États : SyncStatus.Success / SyncStatus.Rejected / SyncStatus.Pending.

VALIDATION DE LA BASELINE

Élément	Résultat
Build solution	Vert (0 erreur)
Build Android	Vert (0 erreur)
Build Mobile (Omika.App)	Vert (0 erreur)
Tests Mobile	506/506 (0 échec)
Tests unitaires (hors HFSQL environnemental)	1683/1683 (0 échec)

Note sur le compteur 1675 → 1683

La référence historique indiquait 1675 tests unitaires hors HFSQL environnemental. Le filtre utilisé (FullyQualifiedName!~Omika.Tests.Connection.HfSqlOleDb) exclut les 19 tests HfSqlOleDb*IntegrationTests (tests environnementaux nécessitant une base HFSQL réelle, qui plantent le processus hôte sans base).

Le total actuel avec ce filtre est 1683 (0 échec), soit +19 tests par rapport au compte rendu précédent (1664) : ces 19 tests sont les nouveaux tests ajoutés pour la connexion Sync (SyncConnectionOptionsValidatorTests : 9 tests, SyncOleDbConnectionTests : 10 tests).

La différence entre 1675 (référence historique) et 1664 (compte rendu précédent) provient de l'évolution du codebase entre les deux comptes rendus (tests ajoutés / supprimés). Le point essentiel est maintenu : 0 échec sur l'ensemble des tests non environnementaux.

PROCHAINES ÉTAPES (LECTURE SEULE D'ABORD)

Avant toute écriture, prouver en lecture seule :

• connexion ouverte ;
• tables accessibles (TOSRV, MobReception, MobLog) ;
• colonnes réellement présentes ;
• opération connue / inconnue ;
• état terminal / en attente ;
• mapping JSON cohérent.

STOP si le modèle physique diffère des hypothèses du repository actuel. Dans ce cas fournir : table réelle, colonne réelle, modèle attendu, divergence, adaptation minimale proposée.

---

✅ TOPOLOGIE MULTI-CONNEXION — IMPLÉMENTÉE

Ce lot a été implémenté. Les probes de lecture réels (via OLEDB PCSOFT.HFSQL) ont révélé que la topologie physique des tables de synchronisation répartit les tables sur deux bases distinctes. Le SyncTransferRepository a été adapté pour utiliser deux connexions explicites. Aucune écriture HFSQL réelle n'a été effectuée pendant ce lot.

Topologie réelle des tables de synchronisation

Table	Base réelle	Connexion utilisée
TOSRV	BATIK.01_BLS (base Service)	IServiceHfSqlConnection
MobReception	base métier WebService	IWebServiceHfSqlConnection
MobLog	base métier WebService	IWebServiceHfSqlConnection

Architecture multi-connexion retenue

Le SyncTransferRepository reçoit désormais deux connexions explicites dans son constructeur :

public SyncTransferRepository(
    IServiceHfSqlConnection serviceConnection,      // base Service → TOSRV
    IWebServiceHfSqlConnection webServiceConnection) // base WebService → MobReception, MobLog

• IServiceHfSqlConnection : wrapper léger autour de la connexion OLE DB nommée "Service" (base Service, table TOSRV). Enregistrée par AddOmikaDataServiceConnection().
• IWebServiceHfSqlConnection : wrapper léger autour de la connexion métier ODBC par défaut (base WebService/Business, tables MobReception et MobLog). Enregistrée par AddOmikaData().

Routage des opérations

Opération	Table	Connexion
InsertToSrvAsync	TOSRV	Service
GetStatusAsync (TOSRV)	TOSRV	Service
GetStatusAsync (MobReception/MobLog)	MobReception/MobLog	WebService
GetTerminalResultAsync	MobLog	WebService
WriteLogAsync	MobLog	WebService
PurgeLogsAsync	MobLog	WebService
TransferToReceptionAsync (lecture)	TOSRV	Service
TransferToReceptionAsync (insertion)	MobReception	WebService
TransferToReceptionAsync (suppression)	TOSRV	Service
GetPendingOperationsAsync	MobReception	WebService
MarkSuccessAsync	MobReception/MobLog	WebService
MarkRejectedAsync	MobReception/MobLog	WebService
IncrementRetryAsync	MobReception	WebService

Atomicité inter-base (TransferToReception)

Le transfert TOSRV → MobReception → suppression TOSRV traverse deux bases physiques. Aucune transaction distribuée (DTC) n'est utilisée. L'atomicité est garantie au niveau logique par :

1. Ordre : lecture TOSRV → insertion MobReception → suppression TOSRV.
2. Idempotence par OperationId : si l'opération existe déjà dans MobReception ou est déjà terminale dans MobLog, on ne recrée pas MobReception (on nettoie TOSRV).
3. Non-perte : si l'insertion MobReception échoue, TOSRV n'est pas supprimé (l'opération reste dans la file Service pour un prochain cycle).

Rôle restant de la connexion Sync

AddOmikaDataSyncConnection() est obsolète : elle ne branche plus ISyncTransferRepository. Elle est conservée pour la compatibilité de configuration (section SyncConnection) et pour les outils de diagnostic. Sa suppression est proposée une fois toutes les références migrées.

Aucune modification du schéma HFSQL n'a été effectuée. Aucune table n'a été créée, modifiée ou supprimée. Aucune donnée n'a été écrite.