Omika/docs/LOT_SYNC_WORKER.md

# LOT SERVEUR — Worker de Synchronisation (Omika.Worker)

## 1. Décision de conception

Le projet **`src/Omika.Worker/`** est le **nom officiel** du service de
synchronisation serveur dans cette solution. Il est **réutilisé tel quel** :
aucun nouveau projet `Omika.Sync.Worker` n'est créé, aucun renommage, aucun
déplacement, aucune duplication de `SyncProcessor`, `SyncWorker` ou des
handlers.

Le projet existant satisfait déjà le rôle attendu d'un .NET Worker Service
séparé de `Omika.Api`.

## 2. Rôle

`Omika.Worker` est un **BackgroundService** qui traite les opérations de
synchronisation mobile reçues par l'infrastructure serveur. Il est **séparé**
de l'API : l'API reçoit les opérations et les écrit dans la file de transfert
(`TOSRV`) ; le Worker les transfère vers la file de réception (`MobReception`),
les applique via les handlers métier, et journalise le résultat dans `MobLog`.

## 3. Architecture

```
API (SyncOperationService.ReceiveAsync)
  → InsertToSrvAsync() → écrit dans TOSRV
Worker (SyncWorker → SyncProcessor.ProcessAsync)
  → TransferToReceptionAsync() → TOSRV → MobReception
  → GetPendingOperationsAsync() → lit MobReception
  → Handler (Intervention / Default) → applique l'opération
  → MarkSuccessAsync / MarkRejectedAsync / IncrementRetryAsync → MobLog
```

### Chaîne TOSRV → MobReception

Le transfert **TOSRV → MobReception** est **déjà géré** par
`SyncTransferRepository.TransferToReceptionAsync()`, appelé par
`SyncProcessor.ProcessAsync()` (première étape de chaque cycle). **Aucun
chaînon manquant** : la chaîne est complète.

- **Qui écrit dans TOSRV** : `SyncOperationService.ReceiveAsync()` (côté API)
  via `ISyncTransferRepository.InsertToSrvAsync()`.
- **Ce que lit SyncProcessor** : les opérations en attente dans `MobReception`
  via `GetPendingOperationsAsync()`.
- **MobReception n'est jamais vide** : il est alimenté par le transfert
  TOSRV → MobReception à chaque cycle.

## 4. Program.cs / DI

`Program.cs` enregistre :

| Service | Lifetime | Connexion |
|---|---|---|
| `AddOmikaData()` | — | Business (ODBC métier) + WebService |
| `AddOmikaDataServiceConnection()` | — | **Service** (OLEDB, TOSRV) |
| `SyncOptions` (section `Sync`) | Options | — |
| `DefaultSyncOperationHandler` | Scoped | — |
| `IMobileEntityIdentityResolver` | Singleton | — |
| `InterventionSyncOperationHandler` | Scoped | Business |
| `SyncOperationHandlerRegistry` | Scoped | — |
| `SyncProcessor` | Scoped | — |
| `SyncWorker` (HostedService) | Singleton | — |

### Topologie multi-connexion

Le `ISyncTransferRepository` est désormais **multi-connexion** : il reçoit deux
connexions explicites via le DI.

- `IServiceHfSqlConnection` (enregistrée par `AddOmikaDataServiceConnection()`) :
  base Service, table `TOSRV`.
- `IWebServiceHfSqlConnection` (enregistrée par `AddOmikaData()`) : base
  WebService/Business, tables `MobReception` et `MobLog`.

Le Worker reçoit via DI le repository multi-connexion. Il ne recrée **aucune**
logique TOSRV/MobReception : il délègue entièrement à `SyncProcessor` →
`ISyncTransferRepository`.

## 5. Connexion Service / WebService

La connexion **Service** est configurée dans la section `ServiceConnection`
(`ServiceConnectionOptions`), via le provider OLEDB `PCSOFT.HFSQL`. Elle est
enregistrée comme `IHfsqlConnection` nommée `"Service"` et exposée via le
wrapper `IServiceHfSqlConnection`. Elle héberge la table `TOSRV`.

La connexion **WebService/Business** est la connexion métier ODBC par défaut
(`HfsqlOptions`), exposée via le wrapper `IWebServiceHfSqlConnection`. Elle
héberge les tables `MobReception` et `MobLog` ainsi que les données métier.

`ISyncTransferRepository` est branché sur ces **deux** connexions explicites.


## 6. Connexion Business

La connexion **Business** (base métier Batik/Omika) est configurée dans la
section `Hfsql` (`HfsqlOptions`), via le driver ODBC HFSQL. Les services métier
(`IInterventionService`, etc.) et les repositories adaptatifs Batik/Omika
restent sur cette connexion.

## 7. Rôle TOSRV

`TOSRV` est la file de transfert **mobile → serveur**. L'API y écrit les
opérations reçues via `InsertToSrvAsync()`. Le Worker les transfère ensuite
vers `MobReception`.

## 8. Rôle MobReception

`MobReception` est la file de réception **serveur**. `SyncProcessor` y lit les
opérations en attente de traitement via `GetPendingOperationsAsync()`.

## 9. Rôle MobLog

`MobLog` est le journal terminal de synchronisation. `SyncProcessor` y écrit
les résultats terminaux (`SUCCESS` / `REJECTED`) et les tentatives
(`IncrementRetryAsync`). Le Worker purge périodiquement les journaux terminaux
au-delà de la rétention configurée (`LogRetentionDays`).

## 10. SyncProcessor

`SyncProcessor` est la logique de traitement testable, réutilisée telle quelle.
`SyncWorker` (le BackgroundService) délègue entièrement à `SyncProcessor` :
il ne contient **aucun SQL métier**. Le BackgroundService gère uniquement la
boucle, le `CancellationToken`, l'intervalle de polling et la gestion des
erreurs de cycle.

## 11. SyncWorker

`SyncWorker` est le `BackgroundService` qui orchestre les cycles :

- boucle tant que le `CancellationToken` n'est pas annulé ;
- à chaque cycle : `SyncProcessor.ProcessAsync()` puis purge légère de `MobLog` ;
- délai entre deux cycles : `SyncOptions.RetryDelaySeconds` (configurable) ;
- arrêt propre sur annulation.

## 12. Polling

L'intervalle de polling est **configurable** via la section `Sync`
(`SyncOptions.RetryDelaySeconds`, défaut 120 s). Aucun refactoring nécessaire :
le Worker utilise déjà cette option comme intervalle de cycle.

## 13. CancellationToken

Le `CancellationToken` est passé à `SyncProcessor.ProcessAsync()` et à la purge.
Une annulation pendant le délai lève `OperationCanceledException`, capturée et
transformée en arrêt propre (`break`).

## 14. Gestion des erreurs

Une exception de cycle est capturée par `SyncWorker` (log d'erreur) et le cycle
suivant reprend normalement : **pas de boucle agressive**, le délai est
respecté entre les cycles.

## 15. Retries / max 30

`SyncOptions.MaxRetryCount` (défaut **30**) borne le nombre de tentatives.
`SyncProcessor` incrémente `RetryCount` à chaque échec transitoire
(`TRANSIENT_FAILURE`). Au-delà du max, l'opération est **REJECTED** (terminal).
Un échec définitif (`PERMANENT_FAILURE`) est rejeté immédiatement sans
consommer les 30 retries. **Aucun retry infini** n'est réintroduit.

## 16. OperationId

`OperationId` est conservé tout au long du cycle et sert à l'idempotence : un
doublon d'`OperationId` (déjà `SUCCESS` ou `REJECTED`) n'est pas réappliqué par
le handler.

## 17. RequestedEntityGuid / CanonicalEntityGuid

Le handler Intervention retourne `RequestedEntityGuid` (GUID mobile) et
`CanonicalEntityGuid` (GUID canonique stable) lorsqu'ils diffèrent. Le log
terminal reconstitué conserve le `CanonicalEntityGuid` d'origine pour
l'idempotence par `OperationId`. La réconciliation CREATE est gérée par le
handler (vérification d'existence avant recréation).

## 18. Handlers

Handlers actuellement enregistrés :

- **Intervention** (`InterventionSyncOperationHandler`) : CREATE, UPDATE,
  ARCHIVE.
- **DELETE** : non supporté → `PERMANENT_FAILURE` (archivage logique uniquement).
- **Autres EntityTypes sans handler** : `DefaultSyncOperationHandler` →
  `PERMANENT_FAILURE` / `NO_HANDLER` (jamais de faux SUCCESS).

Aucun nouveau handler n'est créé dans ce lot.

## 19. Concurrence / claim

**VERSION ACTUELLE : UN SEUL `Omika.Worker` actif par file Sync.** Le
repository/processor ne possède pas de mécanisme fiable de claim. Aucun verrou
HFSQL improvisé n'est créé. La concurrence multi-instance est documentée comme
limite restante (futur lot de déploiement).

## 20. Nombre de Workers autorisé actuellement

**Un seul** `Omika.Worker` actif par file Sync (pas de claim distribué).

## 21. Fonctionnement console

`Omika.Worker` est un exécutable .NET Worker Service : il fonctionne en
**console** via `dotnet run` / l'exécutable produit. Le `Host.CreateApplicationBuilder`
fournit le support console standard.

## 22. Support Windows Service

Le Host .NET standard (`Host.CreateApplicationBuilder`) est compatible avec
l'hébergement Windows Service via `UseWindowsService()`. Ce support n'est pas
encore activé dans `Program.cs` : il est documenté comme **futur lot de
déploiement** (aucune restructuration nécessaire pour l'ajouter).

## 23. Configuration / secrets

Le Worker dispose des sections nécessaires dans `appsettings.json` :

- `Hfsql` (Business / WebService) ;
- `ServiceConnection` (Service, table `TOSRV`) ;
- `Sync` (options : MaxRetryCount, RetryDelaySeconds, LogRetentionDays) ;
- `Omika` (DatabaseVersion) ;
- `Logging`.

Aucun secret n'est versionné : les valeurs de connexion sont des exemples non
sensibles, à surcharger par la configuration d'installation (variables
d'environnement / secrets). Aucune nouvelle convention de secrets n'est créée.

## 24. Fichiers réellement modifiés

- `src/Omika.Worker/Program.cs` : ajout de `AddOmikaDataServiceConnection()`
  (connexion Service pour TOSRV) en plus de `AddOmikaData()` (WebService pour
  MobReception/MobLog).
- `src/Omika.Worker/appsettings.json` : **créé** (configuration Worker).
- `tests/Omika.Tests/Mobile/SyncWorkerTests.cs` : **créé** (tests du
  BackgroundService).


## 25. Tests ajoutés / modifiés

- **Créé** : `tests/Omika.Tests/Mobile/SyncWorkerTests.cs` (5 tests) :
  1. Worker appelle SyncProcessor et s'arrête sur annulation ;
  2. absence de travail ne crée pas de boucle CPU ;
  3. exception de cycle ne provoque pas de boucle agressive ;
  4. intervalle de polling configurable respecté ;
  5. arrêt propre sur annulation.

Aucun test existant n'est dupliqué (`SyncProcessorTests`,
`InterventionSyncOperationHandlerTests` déjà présents).

## 26. Tests Worker

`SyncWorkerTests` : **5/5** (fakes/mocks, aucune base HFSQL réelle requise).

## 27. Tests Mobile

Référence : **506/506** (à confirmer après validation).

## 28. Suite unitaire

Référence : **1683/1683** hors HFSQL environnemental (à confirmer après
validation).

## 29. Build solution

Référence : **VERT** (à confirmer après validation).

## 30. Build Worker

`Omika.Worker` : **VERT**.

## 31. Build Android

Référence : **VERT** (à confirmer après validation).

## 32. Test HFSQL réel

**Non effectué** dans ce lot : les tests unitaires du Worker utilisent des
fakes/mocks. Les tests HFSQL réels restent environnementaux (nécessitent un
serveur HFSQL de test). Une absence de serveur HFSQL de test ne constitue pas
un échec unitaire.

## 33. Documentation

- `docs/LOT_SYNC_WORKER.md` (ce document).

## 34. Limites restantes

- **Concurrence** : un seul Worker actif par file Sync (pas de claim distribué).
- **Windows Service** : support non activé (futur lot de déploiement).
- **Test HFSQL réel** : non effectué (environnemental).
- **Handlers** : seul Intervention est branché ; les autres EntityTypes passent
  par le fallback `NO_HANDLER`.

## 35. Confirmation aucun schéma HFSQL modifié

**Aucun schéma HFSQL n'est modifié** : aucune création/suppression de table,
aucune modification de colonne. Le Worker lit/écrit dans les tables techniques
existantes (TOSRV, MobReception, MobLog) via le repository existant.

## 36. Confirmation aucun protocole historique réintroduit

**Aucun protocole historique n'est réintroduit** : ni `CB_Ajout_TOSRV`, ni le
protocole WINDEV historique. Le transfert TOSRV → MobReception est assuré par
le repository moderne (`SyncTransferRepository.TransferToReceptionAsync`).