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) :

```json
"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 :

```csharp
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.