# LOT SERVEUR — Connexion physique base Licence HFSQL

## Objectif

Brancher l'implémentation moderne Licence existante sur la vraie base HFSQL
Licence, via le provider OLEDB pour HFSQL (`PCSOFT.HFSQL`).

## Principes respectés

- **Aucune modification du schéma HFSQL** : aucune table/colonne créée, modifiée ou supprimée.
- **Aucune création/suppression de table** : le repository lit/écrit dans les tables existantes.
- **Aucune reprise du vieux WebService** : les traitements modernes restent la référence.
- **Les anciennes documentations** servent uniquement à connaître les tables, relations et comportements historiques.
- **Les contrats API modernes restent la référence** : le repository ne renvoie que des entités métier.
- **Aucun secret historique recopié** : les valeurs de connexion proviennent exclusivement de la configuration d'installation.

## Modèle physique réel (confirmé)

La base Licence héberge les tables techniques suivantes, utilisées par le repository :

| Table | Rôle | Colonnes utilisées |
|-------|------|--------------------|
| `ClientBase` | Clients de la base licence | `CL_PKID`, `CL_Code`, `CL_Nom` |
| `Licence` | Licences attribuées | `LI_PKID`, `LI_IDClient`, `LI_IDCollaborateur`, `LI_IDUser`, `LI_Numero`, `LI_IDMobile`, `LI_DateAttribution`, `LI_DateExpiration`, `LI_Active`, `LI_UserNom`, `LI_UserPrenom`, `LI_Type`, `LI_InfoSupMob`, `LI_VersionMajeur` |
| `LicenceHisto` | Historique des opérations de licence | `LH_Date`, `LH_Auteur`, `LH_Operation`, `LH_GUIDLicence`, `LH_CodeClient`, `LH_IdMobile`, `LH_Note` |

> **Aucune divergence** entre le modèle physique réel et les hypothèses du repository actuel.
> Le mapping est direct et conforme.

## Mapping vers les contrats modernes

Le `LicenceRepository` (`src/Omika.Data/Repositories/Technical/LicenceRepository.cs`)
mappe les lignes physiques HFSQL vers les entités métier modernes :

| Table physique | Entité métier | Contrat |
|----------------|---------------|---------|
| `ClientBase` | `ClientBase` | `Omika.Core.Domain.Entities.Mobile.ClientBase` |
| `Licence` | `Licence` | `Omika.Core.Domain.Entities.Mobile.Licence` |
| `LicenceHisto` | `LicenceHistoEntry` | `Omika.Core.Domain.Entities.Mobile.LicenceHistoEntry` |

Aucune donnée physique HFSQL n'est exposée dans l'API : le repository ne renvoie
que des entités métier, et les endpoints API ne manipulent que des contrats modernes.

## Fonctionnalités couvertes

| # | Fonctionnalité | Implémentation |
|---|----------------|----------------|
| 1 | Configuration centralisée de connexion Licence | `LicenseConnectionOptions` + `LicenseConnectionOptionsValidator` (section `LicenseConnection`) |
| 2 | Ouverture de la connexion HFSQL via OLEDB | `LicenseOleDbConnection` + `HfSqlOleDbConnectionFactory` (provider `PCSOFT.HFSQL`) |
| 3 | Ouverture/lecture des tables réellement utilisées | `LicenceRepository` branché sur la connexion nommée `"License"` |
| 4 | Mapping vers les contrats modernes | `LicenceRepository` (mapping `ClientBaseRow`/`LicenceRow` → entités métier) |
| 5 | Recherche CodeClient | `GetClientByCodeAsync` |
| 6 | Recherche NumeroLicence | `GetByNumeroAsync`, `GetByNumeroAndClientAsync` |
| 7 | Vérification licence active | `Licence.Active` |
| 8 | Vérification DateExpiration | `Licence.DateExpiration` |
| 9 | Vérification attribution DeviceId | `Licence.DeviceId` |
| 10 | Résolution UserId | `Licence.UserId` |
| 11 | Résolution CollaborateurId | `Licence.CollaborateurId` |
| 12 | Activation réelle | `AssignDeviceAsync` + `AddHistoAsync` |
| 13 | Validation réelle | via `LicenseService` (contrats API modernes) |
| 14 | Aucune donnée physique exposée | le repository ne renvoie que des entités métier |

## Branchement effectué

### `src/Omika.Data/ServiceCollectionExtensions.cs`

Dans `AddOmikaDataLicenseConnection()`, le `ILicenceRepository` est désormais
branché sur la connexion OLEDB nommée `"License"` (base Licence réelle), en
remplacement de l'enregistrement ODBC métier par défaut de `AddOmikaData()` :

```csharp
services.AddScoped<ILicenceRepository>(sp =>
    new LicenceRepository(
        sp.GetRequiredKeyedService<IHfsqlConnection>(LicenseConnectionOptions.ConnectionName)));
```

Le dernier enregistrement remplace le précédent (connexion ODBC métier) : le
repository de licence lit/écrit désormais dans la base HFSQL Licence réelle via
le provider OLEDB, jamais dans la base métier.

### `src/Omika.Api/Program.cs`

Appel de `AddOmikaDataLicenseConnection()` après `AddOmikaData()` pour activer le
branchement :

```csharp
builder.Services.AddOmikaData();
builder.Services.AddOmikaDataLicenseConnection();
```

### `src/Omika.Api/appsettings.json`

Ajout de la section `LicenseConnection` (valeurs d'exemple, sans secrets) :

```json
"LicenseConnection": {
  "Server": "localhost",
  "Port": 4900,
  "DatabaseName": "Licence",
  "Login": "",
  "Password": "",
  "FilePasswords": {
    "ProtectionStd": "",
    "ProtectionPlus": ""
  }
}
```

> Les valeurs `Login`, `Password`, `FilePasswords` doivent être fournies via
> configuration sécurisée (variables d'environnement, User Secrets), jamais en
> clair dans le code source.

## Configuration de connexion

La connexion à la base Licence est centralisée dans la section `LicenseConnection` :

| Clé | Description | Exemple |
|-----|-------------|---------|
| `LicenseConnection:Server` | Hôte du serveur HFSQL Client/Serveur | `localhost` |
| `LicenseConnection:Port` | Port du serveur HFSQL | `4900` |
| `LicenseConnection:DatabaseName` | Nom de la base Licence | `Licence` |
| `LicenseConnection:Login` | Compte technique serveur (secret) | *(via env/secret)* |
| `LicenseConnection:Password` | Mot de passe du compte technique (secret) | *(via env/secret)* |
| `LicenseConnection:FilePasswords:ProtectionStd` | Mot de passe ProtectionStd (optionnel) | *(via env/secret)* |
| `LicenseConnection:FilePasswords:ProtectionPlus` | Mot de passe ProtectionPlus (optionnel) | *(via env/secret)* |

## Validation de la baseline

| Baseline | Résultat |
|----------|----------|
| Mobile | **506/506** ✓ |
| Unitaires hors HFSQL environnemental | **1748/1748** ✓ (0 échec) |
| Build solution | **vert** ✓ |
| Android | **vert** ✓ |


## Tests à faire en lecture (prochaine étape)

Une fois la base Licence réelle accessible, exécuter les tests de lecture suivants
avant toute écriture :

- [ ] Connexion ouverte (via `LicenseOleDbConnection`)
- [ ] Tables accessibles (`ClientBase`, `Licence`, `LicenceHisto`)
- [ ] Colonnes réellement présentes (comparer avec le mapping ci-dessus)
- [ ] Client connu / inconnu (`GetClientByCodeAsync`)
- [ ] Licence connue / inconnue (`GetByNumeroAsync`)
- [ ] Licence active / inactive (`Licence.Active`)
- [ ] Licence expirée (`Licence.DateExpiration`)
- [ ] Attribution existante (`Licence.DeviceId`)
- [ ] Utilisateur / collaborateur réellement résolus (`Licence.UserId`, `Licence.CollaborateurId`)

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

---

## ⛔ ÉTAT RÉEL — DIVERGENCE CONSTATÉE (STOP)

> **Ce lot est en état de STOP.** Les probes de lecture réels (via OLEDB `PCSOFT.HFSQL`)
> ont révélé que le modèle physique de la base Licence **diffère** des hypothèses du
> repository. Aucune écriture n'a été effectuée. Aucune donnée n'a été modifiée.

### Probes de lecture effectués (lecture seule, aucun secret exposé)

| Base configurée | Base réelle sur le serveur | Connexion | Tables |
|-----------------|----------------------------|-----------|--------|
| `BATIK_TEST` (Business) | `BATIK_TEST` | ✅ Ouverte | 44 tables métier |
| `BASE_LICENSES` (License) | **`BASE_LICENCES`** (orthographe différente) | ✅ Ouverte | **2 tables de backup système uniquement** |
| `SYNC_TEST` (Sync) | **`OMIKA_TEST`** (nom différent) | ✅ Ouverte | 54 tables métier |

Le serveur HFSQL (`127.0.0.1:4900`) expose 16 bases, dont `BASE_LICENCES`, `BATIK_TEST`,
`OMIKA_TEST`, `GestionUser`, etc.

### Divergence 1 — Nom de la base Licence

| Élément | Valeur |
|---------|--------|
| **Base configurée** (`LicenseConnection:DatabaseName`) | `BASE_LICENSES` |
| **Base réelle sur le serveur** | `BASE_LICENCES` |
| **Divergence** | Orthographe : `LICENSES` (config) vs `LICENCES` (réel) |

### Divergence 2 — Tables de licence absentes (critique)

La base Licence réelle (`BASE_LICENCES`) ne contient **que** les tables de backup
système suivantes :

| Table réelle | Type |
|--------------|------|
| `_Backup_20260813_080833_Integrity` | TABLE |
| `_Backup_20260813_080833_Views` | TABLE |

Les tables attendues par le repository **n'existent pas** dans cette base :

| Table attendue (modèle) | Présence réelle |
|-------------------------|-----------------|
| `ClientBase` | ❌ Absente |
| `Licence` | ❌ Absente |
| `LicenceHisto` | ❌ Absente |

### Divergence 3 — Nom de la base Sync

| Élément | Valeur |
|---------|--------|
| **Base configurée** (`SyncConnection:DatabaseName`) | `SYNC_TEST` |
| **Base réelle sur le serveur** | `OMIKA_TEST` |
| **Divergence** | Nom différent |

### Conséquence

Le `LicenceRepository` ne peut pas être branché sur la base Licence réelle tant que
les tables `ClientBase`, `Licence`, `LicenceHisto` n'existent pas dans `BASE_LICENCES`
(ou dans une base Licence dédiée). Le mapping vers les contrats modernes ne peut pas
être validé en lecture.

### Adaptation minimale proposée (à valider avant toute implémentation)

1. **Corriger le nom de la base** dans la configuration locale :
   `LicenseConnection:DatabaseName` = `BASE_LICENCES` (au lieu de `BASE_LICENSES`).
2. **Restaurer / créer les tables de licence** (`ClientBase`, `Licence`, `LicenceHisto`)
   dans la base `BASE_LICENCES` (ou fournir une base Licence de test contenant ces tables).
   → Sans ces tables, aucun test de lecture/mapping/activation n'est possible.
3. **Corriger le nom de la base Sync** : `SyncConnection:DatabaseName` = `OMIKA_TEST`
   (au lieu de `SYNC_TEST`), si `OMIKA_TEST` est bien la base technique Sync de test.
4. **Re-exécuter les probes de lecture** (connexion, tables, colonnes) une fois les
   tables de licence présentes, avant toute écriture.

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