# 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.