Premiere commit - Omika
This commit is contained in:
@@ -0,0 +1,230 @@
|
||||
# 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.
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user