Premiere commit - Omika

2026-10-23 18:46:50 +02:00
commit 8ea76c1b24
2155 changed files with 984301 additions and 0 deletions
@@ -0,0 +1,175 @@
+# LOT SERVEUR — CONNEXION PHYSIQUE BASE SERVICE (HFSQL)
+
+## OBJECTIF
+
+Brancher l'implémentation moderne de synchronisation mobile existante sur la
+vraie base HFSQL **Service**, via le provider OLE DB `PCSOFT.HFSQL`.
+
+Cette base Service est **distincte** de la base métier Batik/Omika (ODBC), de la
+base Licence et de la base technique Sync : elle héberge les tables techniques
+du service de synchronisation.
+
+## 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é.
+
+## TOPOLOGIE RÉELLE CONSTATÉE (probes de lecture)
+
+Les probes de lecture réels (via OLEDB `PCSOFT.HFSQL`) ont révélé la topologie
+physique suivante sur le serveur HFSQL (`127.0.0.1:4900`) :
+
+| Base réelle | Rôle | Tables techniques |
+|-------------|------|-------------------|
+| `BATIK.01_BLS` | Base **Service** (service de synchronisation) | `TOSRV`, `TOMOB`, `MOBILES`, `PARAMETRES` |
+| `BATIK_TEST` | Base métier Batik (Business) | 44 tables métier |
+| `OMIKA_TEST` | Base technique Sync | 54 tables métier |
+| `BASE_LICENCES` | Base Licence | tables de backup système uniquement |
+
+### Matrice physique des tables de synchronisation
+
+| Table | Base réelle | Rôle |
+|-------|-------------|------|
+| `TOSRV` | **`BATIK.01_BLS`** (Service) | File d'entrée des opérations reçues du mobile |
+| `MobReception` | **base métier WebService** | File de travail des opérations transférées |
+| `MobLog` | **base métier WebService** | Journal des états terminaux |
+
+> **Divergence structurelle** : le `SyncTransferRepository` actuel est
+> **mono-connexion** et suppose que `TOSRV`, `MobReception` et `MobLog` sont dans
+> la **même** base. Or la topologie réelle répartit ces tables sur **deux** bases
+> distinctes (`TOSRV` dans la base Service, `MobReception`/`MobLog` dans la base
+> métier WebService). Le repository actuel est donc **insuffisant** pour cette
+> topologie.
+
+## CONFIGURATION CENTRALISÉE
+
+La connexion Service est configurée dans la section **`ServiceConnection`** des
+fichiers de configuration .NET (appsettings / variables d'environnement /
+secrets) :
+
+```json
+"ServiceConnection": {
+  "Server": "127.0.0.1",
+  "Port": 4900,
+  "DatabaseName": "BATIK.01_BLS",
+  "Login": "",
+  "Password": "",
+  "FilePasswords": {
+    "ProtectionStd": null,
+    "ProtectionPlus": null
+  }
+}
+```
+
+- `Server` / `Port` : serveur HFSQL Client/Serveur.
+- `DatabaseName` : nom de la base Service (`BATIK.01_BLS`).
+- `Login` / `Password` : compte technique serveur (jamais en clair en source).
+- `FilePasswords` : mots de passe de fichiers HFSQL (ProtectionStd / ProtectionPlus),
+  propres à l'installation. Optionnels.
+
+### Mot de passe optionnel
+
+Selon le client, la connexion Service peut être configurée avec un mot de passe
+**absent** (`null`), **vide** (`""`) ou **renseigné**. Le validateur et le
+constructeur OLEDB acceptent proprement les trois cas. **Aucun mot de passe
+fictif n'est jamais inventé** lorsque la valeur est absente.
+
+## OUVERTURE DE LA CONNEXION VIA OLEDB
+
+La connexion Service est enregistrée comme `IHfsqlConnection` **nommée** `"Service"`
+(`ServiceConnectionOptions.ConnectionName`), distincte de la connexion métier ODBC
+par défaut, de la connexion Licence et de la connexion Sync.
+
+- `ServiceConnectionOptions` : options de connexion (section `ServiceConnection`).
+- `ServiceConnectionOptionsValidator` : validation minimale (règle pure, testable).
+- `HfSqlConnectionOptionsFactory.CreateForService(...)` : traduction vers les options
+  OLE DB.
+- `ServiceOleDbConnection` : connexion OLE DB réutilisant le contrat `IHfsqlConnection`
+  (lecture, métadonnées), alimentée par la fabrique OLE DB.
+
+### `ServiceOleDbConnection`
+
+La connexion Service expose :
+
+- `Options` : un `HfsqlOptions` minimal dérivé des options Service (sans secret),
+  avec `ConnectionName = "Service"`, `DatabaseName`, `Login`.
+- `OpenAsync` / `CloseAsync` / `DisposeAsync` : cycle de vie de la connexion.
+- `QueryAsync` / `ExecuteScalarAsync` / `ExecuteNonQueryAsync` : lecture/écriture.
+- `GetColumnsAsync` : métadonnées des colonnes d'une table.
+
+## BRANCHEMENT DU REPOSITORY — MULTI-CONNEXION IMPLÉMENTÉ
+
+`AddOmikaDataServiceConnection()` (dans `Omika.Data`) :
+
+1. enregistre la configuration `ServiceConnection` (section `ServiceConnection`) ;
+2. enregistre le validateur `ServiceConnectionOptionsValidator` ;
+3. enregistre la fabrique OLE DB `IHfSqlOleDbConnectionFactory` ;
+4. enregistre la connexion `IHfsqlConnection` nommée `"Service"` (Scoped) ;
+5. enregistre le wrapper `IServiceHfSqlConnection` (Scoped) autour de la connexion
+   Service.
+
+> **✅ Implémenté** : le `SyncTransferRepository` est désormais **multi-connexion**.
+> Il reçoit deux connexions explicites : `IServiceHfSqlConnection` (base Service,
+> table `TOSRV`) et `IWebServiceHfSqlConnection` (base WebService/Business, tables
+> `MobReception` et `MobLog`). Le routage des opérations est documenté dans
+> `LOT_SERVEUR_SYNC_CONNECTION.md`.
+
+### Rôle de la connexion Service
+
+La connexion Service (`IServiceHfSqlConnection`) est utilisée **uniquement** pour
+les opérations sur la table `TOSRV` :
+
+- `InsertToSrvAsync` : insertion d'une opération reçue du mobile.
+- `GetStatusAsync` / `GetExistingStateAsync` : recherche d'une opération dans TOSRV.
+- `TransferToReceptionAsync` : lecture de TOSRV et suppression après transfert réussi.
+
+Aucune opération `MobReception` / `MobLog` ne passe par la connexion Service.
+
+> **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.
+
+
+## VALIDATION DE LA BASELINE
+
+| Élément | Résultat |
+|---------|----------|
+| Build solution | **Vert** (0 erreur) |
+| Build Android | **Vert** (0 erreur) |
+| Tests unitaires (hors HFSQL environnemental) | **1748/1748** (0 échec) |
+
+### Note sur les tests
+
+Les 10 tests `HfSqlOleDb*IntegrationTests` échouent car ils nécessitent un serveur
+HFSQL réel non démarré dans cet environnement (`La connexion au serveur <:0> a
+échoué`). Ces tests sont **hors baseline** (tests environnementaux).
+
+Les nouveaux tests ajoutés pour la connexion Service passent tous :
+
+- `ServiceConnectionOptionsValidatorTests` (13 tests) : validation, mot de passe
+  optionnel, `ToString` sans secret.
+- `ServiceOleDbConnectionTests` (12 tests) : cycle de vie, lecture, options,
+  `CreateForService`.
+- `HfSqlOleDbConnectionStringBuilderTests` : construction OLEDB avec mot de passe
+  optionnel.
+- `ServiceCollectionExtensionsTests` : enregistrement DI de la connexion Service.
+
+## PROCHAINES ÉTAPES (LECTURE SEULE D'ABORD)
+
+Avant toute écriture, prouver en lecture seule :
+
+- connexion Service ouverte ;
+- tables accessibles (`TOSRV`, `TOMOB`, `MOBILES`, `PARAMETRES`) ;
+- 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.