susana/Omika
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Premiere commit - Omika

Browse Source
This commit is contained in:
susana
2026-10-23 18:46:50 +02:00
commit 8ea76c1b24
2155 changed files with 984301 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+581
View File
@@ -0,0 +1,581 @@
# Omika
> **Gestion d'interventions terrain** — application .NET 10 / Avalonia, réécriture moderne de
> l'application WinDev historique **Batik**.
Omika couvre le cycle complet d'une intervention technique : agenda et rendez-vous, dossiers,
clients et sites, interventions et suivi des temps, comptes rendus, documents et photos, courriels,
rapports — sur **poste de bureau, Android et iOS**, avec un fonctionnement **hors ligne** complet et
une synchronisation vers le serveur HFSQL existant.
| | |
|---|---|
| **Langage / runtime** | C# · .NET 10 (`net10.0`) |
| **UI** | Avalonia 12.1.1 (thème Fluent, police Inter) — rendu identique desktop et mobile |
| **MVVM** | CommunityToolkit.Mvvm 8.4.2 |
| **Base locale (mobile)** | SQLite (`Microsoft.Data.Sqlite`) — `omika.db` |
| **Base serveur** | HFSQL Client/Server (PC SOFT) via ODBC / OLE DB |
| **Version** | `1.0.0` build `1` — source unique : `Directory.Build.props` |
| **Éditeur** | Applilogik — `com.applilogik.omika.app` |
---
## Sommaire
1. [Ce que fait Omika](#1-ce-que-fait-omika)
2. [Architecture](#2-architecture)
3. [Les projets](#3-les-projets)
4. [Prérequis](#4-prérequis)
5. [Démarrage rapide](#5-démarrage-rapide)
6. [Configuration](#6-configuration)
7. [Tests](#7-tests)
8. [Publier et déployer](#8-publier-et-déployer)
9. [Observabilité](#9-observabilité)
10. [Traduction hors ligne et packs de langues](#10-traduction-hors-ligne-et-packs-de-langues)
11. [Bases de données](#11-bases-de-données)
12. [Arborescence du dépôt](#12-arborescence-du-dépôt)
13. [Règles d'architecture](#13-règles-darchitecture)
14. [Documentation](#14-documentation)
15. [Dépannage](#15-dépannage)
---
## 1. Ce que fait Omika
### 1.1 Fonctionnel
| Domaine | Contenu |
|---|---|
| **Licence / activation** | Inscription au premier démarrage par code ou **scan de QR** (aperçu caméra), états « connexion requise », « licence expirée ou révoquée ». Attribution et révocation de licence mobile depuis la fiche collaborateur. |
| **Agenda** | Agenda personnel **Jour / Semaine / Mois**, agenda d'équipe avec filtres par équipe et collaborateur. Lecture 100 % locale, aucun appel réseau au chargement. |
| **Rendez-vous** | Fiche complète : contacts, saisie de temps inline, annulation (origine + motif + note), finalisation « Fait ». |
| **Interventions** | Recherche multi-critères (référence, client, site, collaborateur, état, type), onglets « Récentes » et « Épinglées », fiche complète, **création / modification / archivage offline-first**. |
| **Dossiers, clients, sites** | Listes avec recherche et épinglage local, fiches détaillées, **carte géographique** (Mapsui) et lancement d'itinéraire. |
| **Équipe** | Équipes de l'utilisateur, membres, fiches collaborateurs. |
| **Temps et comptes rendus** | Saisie de temps avec gestion de la pause déjeuner, compte rendu individuel ou groupe/journée avec anti-doublon. |
| **Documents et photos** | Téléchargement à la demande, cache hors ligne, ajout offline-first, **éditeur d'image plein écran** (annotation + signature), date réelle lue dans les métadonnées EXIF. |
| **Courriels** | Composition depuis un modèle, un rapport ou un contact, envoi SMTP, brouillons. |
| **Rapports** | Remplissage de modèles DOCX par champs/rubriques. |
| **Synchronisation** | File Outbox, badge du nombre d'opérations en attente, déclenchement manuel, reconstruction de la base locale par **snapshot**. |
| **Paramètres** | Thème clair/sombre/système, couleur principale, compte et licence, limite de poids des photos, horaires de pause, maintenance des données (purge, réinitialisation), export des journaux vers le support. |
| **Traduction hors ligne** | Traduction FR ⇄ 32 langues directement sur l'appareil (ONNX Runtime), sans réseau. |
### 1.2 Principe directeur : offline-first
Toute écriture métier part d'abord dans la **base SQLite locale** et dans l'**Outbox**, puis remonte
au serveur à la première occasion. L'utilisateur n'attend jamais le réseau.
- **Snapshot** : le serveur renvoie une photographie complète des données métier pour reconstruire
la base locale.
- **Outbox** : file locale des changements à pousser, rejouable après coupure.
- **Idempotence** : chaque opération porte un `OperationId` unique ; la rejouer ne produit pas de
doublon.
---
## 2. Architecture
```
┌──────────────────────────────────────────────────────────────────────┐
│ TÉLÉPHONE / POSTE DE BUREAU │
│ │
│ Omika.App.Desktop · Omika.App.Android · Omika.App.iOS │
│ │ hôtes plateformes │
│ ▼ │
│ Omika.App Vues + ViewModels + Navigation + Contrôles │
│ │ │
│ ▼ │
│ Omika.App.Local SQLite (omika.db) + SyncEngine + Outbox │
│ + cache documents + traduction ONNX │
└──────────────────────────────┬───────────────────────────────────────┘
│ HTTP / JSON + Bearer token
▼
┌──────────────────────────────────────────────────────────────────────┐
│ SERVEUR DU CLIENT (HFSQL) │
│ │
│ Omika.Api Web service · licence · bootstrap · snapshot │
│ │ │ sync │
│ ▼ ▼ │
│ Omika.Core (métier) Omika.Worker (application des ops) │
│ │ │ │
│ └────────► Omika.Data (HFSQL par ODBC / OLE DB) ◄───────────┘
└──────────────────────────────┬───────────────────────────────────────┘
│ forwarding HTTPS des diagnostics
▼
┌──────────────────────────────────────────────────────────────────────┐
│ SERVEUR CENTRAL OMIKA │
│ Omika.Diagnostics.Api → Omika.Diagnostics.Worker → PostgreSQL │
│ └──► Omika.Diagnostics.Web │
│ Omika.Langues.Api distribution des modèles de langue (ONNX) │
│ (optionnel) OpenTelemetry → Collector → SigNoz → ClickHouse │
└──────────────────────────────────────────────────────────────────────┘
```
**À retenir :**
- Le **mobile ne parle jamais directement à HFSQL** : il passe toujours par `Omika.Api`.
- Le **desktop** accède à HFSQL **directement** (chemin historique).
- `Omika.Api` **reçoit** les opérations ; `Omika.Worker` les **applique**.
- `Omika.Core` est le cerveau métier ; `Omika.Data` est la seule couche qui touche HFSQL.
- Tout ce qui est **hors** métier (diagnostics, observabilité, langues) est **fail-open** : l'arrêter
ne casse jamais l'application.
---
## 3. Les projets
### 3.1 Projets de la solution (`Omika.slnx`)
| Projet | TFM | Rôle |
|---|---|---|
| `src/Omika.Core` | `net10.0` | **Noyau métier**, sans dépendance UI ni base : entités de domaine, value objects, commands, DTO (`Contracts/`), interfaces, services métier — dont le **cœur serveur de la synchronisation mobile** (`Services/Mobile/` : licence, jetons, bootstrap, snapshot, documents, opérations de sync) — configuration typée, constantes, `Runtime/` (Batik vs Omika), sécurité, politiques d'observabilité. |
| `src/Omika.Data` | `net10.0` | **Accès HFSQL** : options de connexion et validation, connexion ODBC / OLE DB, repositories, mapping, **modèles physiques générés** (Batik 48 tables / Omika 58 tables), migrations Batik → Omika, détection de schéma. |
| `src/Omika.App.Local` | `net10.0` | **Cerveau local du client** : SQLite (`omika.db`), schéma, `SyncEngine`, `OutboxService`, cache documents, un service local par entité, traduction ONNX, licence de développement, diagnostics locaux. |
| `src/Omika.App` | `net10.0` | **Bibliothèque UI partagée** : 38 vues XAML, 48 ViewModels, navigation (`PageViewModelFactory`), contrôles réutilisables (dont la carte), styles, services d'interface. |
| `src/Omika.App.Desktop` | `net10.0` | Hôte **bureau** (`WinExe`, manifeste Windows 10). |
| `src/Omika.App.Android` | `net10.0-android` | Hôte **Android** — min SDK 23, `com.applilogik.omika.app`, format APK, scan QR via ZXing. |
| `src/Omika.App.iOS` | `net10.0-ios` | Hôte **iOS** — min 14.0. **La compilation d'un `.app` exige macOS + Xcode.** |
| `src/Omika.Api` | `net10.0` | **API métier et mobile**, installée chez chaque client : licence, bootstrap, snapshot, sync, documents, courriels, rapports, aide contextuelle. OpenAPI. |
| `src/Omika.Worker` | `net10.0` | **Service de synchronisation** : dépile `TOSRV`, exécute le handler métier, journalise dans `MobLog`. Service Windows. |
| `src/Omika.Observability.External` | `net10.0` | **Seul projet autorisé** à référencer OpenTelemetry : adaptateur OTLP HTTP/protobuf, `RemoteDiagnosticForwarder`, câblage DI. |
| `tests/Omika.Tests` | `net10.0` | Tests xUnit de la solution métier et du client. |
| `tools/Omika.HfSqlProbe` | `net10.0` | Sonde de connexion et d'inspection HFSQL. |
| `tools/HfSqlModelAudit` | `net10.0` | Audit des modèles physiques (attributs de mapping). |
| `tools/HfSqlOleDbAudit` | `net10.0` | Audit du schéma par OLE DB (mode `connection-test` inclus). |
| `tools/Omika.LanguesProbe` | `net10.0` | Validation hors ligne d'un couple de traduction (vocabulaire SentencePiece, paire FR⇄ES). |
### 3.2 Projets compilés hors solution
Ces projets existent, se compilent et se testent, mais **ne sont pas référencés par `Omika.slnx`** :
un `dotnet build Omika.slnx` ne les couvre pas. Les compiler explicitement par leur chemin.
| Projet | TFM | Rôle |
|---|---|---|
| `src/Omika.Diagnostics.Core` | `net10.0` | Modèles, abstractions de repository, importeur JSONL → PostgreSQL. Aucune logique métier. |
| `src/Omika.Diagnostics.Data` | `net10.0` | Persistance PostgreSQL du Diagnostic Center (base dédiée `omika_diagnostics`), Npgsql direct. |
| `src/Omika.Diagnostics.Api` | `net10.0` | API **centrale** : reçoit les lots des serveurs clients, authentifie (`ClientCode` + `ApiKey`), écrit le spool central. |
| `src/Omika.Diagnostics.Worker` | `net10.0` | Import asynchrone du spool central JSONL → PostgreSQL, déduplication par `event_id`, backoff borné. |
| `src/Omika.Diagnostics.Web` | `net10.0` | Interface support (Razor Pages) : Dashboard, Diagnostics, Erreurs, Traces, Synchronisation, Telemetry, Parc, Versions, Référentiel, Utilisateurs, Clients Diagnostics, Système, Mon compte. |
| `src/Omika.Langues.Api` | `net10.0` | Service **stateless** de distribution des modèles de langue ONNX (`/api/langues`, `/api/langues/{code}/{sens}/{fichier}`). Sans base ni authentification. |
| `tests/Omika.Diagnostics.Tests` | `net10.0` | Tests du Diagnostic Center (faux repositories, PostgreSQL simulé en panne, mappers, checkpoint, sécurité, pagination). |
| `tools/*` (21 autres) | `net10.0` | Sondes de diagnostic : `ClientSnapshotProbe`, `CollaborateurBulkProbe`, `CountProbe`, `DiagnosticHashTool`, `FileAccessProbe`, `FilePasswordProbe`, `IdempotenceProbe`, `IdentityProbe`, `LieuProbe`, `MessageExterneProbe`, `OleDbSchemaProbe`, `RdvProbeJour`, `RendezVousBulkProbe`, `RendezVousProbe`, `SiteSnapshotProbe`, `SmtpMobileConfigProbe`, `SmtpRealProbe`, `StatusProbe`, `TosrvProbe`, `Verif.Dictee`, `Verif.Langues`. |
---
## 4. Prérequis
| Besoin | Détail |
|---|---|
| **.NET SDK 10** | SDK de référence : **10.0.302** (voir `global.json.bak`). Le dépôt ne contient pas encore de `global.json` actif : renommer le `.bak` si vous voulez figer la version. |
| **Workloads mobiles** | `dotnet workload install android` pour l'APK. iOS demande **macOS + Xcode**. |
| **Serveur HFSQL** | HFSQL Client/Server (port **4900**) + pilote ODBC « HFSQL Client/Server », pour le développement local et les tests d'intégration. |
| **Windows** | Requis pour le client desktop (OLE DB, manifeste Windows) et pour les services Windows déployés. |
| **PostgreSQL** | Uniquement pour le Diagnostic Center (`omika_diagnostics`). Optionnel pour le métier. |
| **Docker** | Uniquement pour la pile d'observabilité externe (optionnelle). |
Packages : gestion **centralisée** via `Directory.Packages.props`. Les `.csproj` référencent les
packages **sans version** — ne jamais ajouter de `Version=` dans un `.csproj`.
---
## 5. Démarrage rapide
### 5.1 Tout-en-un (mode test local)
Les scripts de `docs/` compilent et lancent les trois composants (API, Worker, desktop) :
```powershell
# Compiler (arrête les processus Omika en cours pour libérer les DLL)
powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\build_omika_test.ps1
# Lancer : API (http://localhost:5097) + Worker + application de bureau
powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\start_omika_test.ps1 -NoBuild
# Arrêter
powershell -NoProfile -ExecutionPolicy Bypass -File .\docs\stop_omika_test.ps1
```
Options utiles de `start_omika_test.ps1` :
| Option | Effet |
|---|---|
| `-NoBuild` | Ne pas recompiler. |
| `-SkipDesktop` | Lancer seulement l'API et le Worker. |
| `-SkipWorker` | Lancer seulement l'API et le desktop. |
| `-Clean` | Purger `omika.db` et `omika-diagnostics.db` avant lancement (changement d'environnement). |
Le script crée automatiquement, si absent, le fichier de licence de développement
`%LOCALAPPDATA%\Omika\development-license.json` :
```json
{
"Enabled": true,
"ClientCode": "LOCAL-DEV",
"UserDisplayName": "<nom affiché>",
"ExpirationDays": 365,
"ApiUrl": "http://localhost:5097"
}
```
### 5.2 Commandes `dotnet` directes
```powershell
# Restauration
dotnet restore .\Omika.slnx
# Compiler toute la solution (client + API + Worker + bibliothèques + tests + 4 outils)
dotnet build .\Omika.slnx
# Composants pris isolément
dotnet build .\src\Omika.Api\Omika.Api.csproj
dotnet build .\src\Omika.Worker\Omika.Worker.csproj
dotnet build .\src\Omika.App.Desktop\Omika.App.Desktop.csproj
dotnet build .\src\Omika.App.Android\Omika.App.Android.csproj # APK
dotnet build .\src\Omika.App.iOS\Omika.App.iOS.csproj # macOS + Xcode requis
# Projets hors solution
dotnet build .\src\Omika.Diagnostics.Web\Omika.Diagnostics.Web.csproj
dotnet build .\src\Omika.Langues.Api\Omika.Langues.Api.csproj
# Lancer
dotnet run --project .\src\Omika.Api\Omika.Api.csproj # http://localhost:5097/health
dotnet run --project .\src\Omika.Worker\Omika.Worker.csproj
dotnet run --project .\src\Omika.App.Desktop\Omika.App.Desktop.csproj
```
### 5.3 Ports de développement
| Service | Port |
|---|---|
| `Omika.Api` | **5097** (HTTP) · 7160 (HTTPS) |
| `Omika.Diagnostics.Api` | **5098** |
| `Omika.Diagnostics.Web` | **5080** |
| `Omika.Langues.Api` | **5099** (derrière Apache sur `/langues/`) |
| HFSQL Client/Server | **4900** |
En production, Kestrel reste en **HTTP sur loopback** ; l'exposition HTTPS est assurée par un
reverse proxy **Apache**.
---
## 6. Configuration
### 6.1 `config/hfsql-test.local.json` — non versionné
Les `appsettings.json` ne contiennent que des **placeholders** (hôtes `localhost`, mots de passe
vides). Les vraies connexions de test vivent dans `config/hfsql-test.local.json`, **exclu du dépôt**
par `.gitignore` (`/config/`).
Le fichier est chargé par `HfSqlTestConfigurationLoader` **uniquement** en environnement
`Development` ou `Test`, jamais en `Production`, et les **variables d'environnement restent
prioritaires**. Il est localisé de deux façons :
1. variable d'environnement `OMIKA_HFSQL_TEST_CONFIG` = chemin explicite (fait foi) ;
2. sinon, `config/hfsql-test.local.json` en remontant jusqu'à 6 niveaux depuis le répertoire courant.
Structure attendue pour reconstituer ce fichier :
```json
{
"Server": "<serveur HFSQL>",
"Port": 4900,
"FilePasswords": { "ProtectionStd": "", "ProtectionPlus": "" },
"Batik": { "Database": "", "User": "", "Credential": "" },
"Omika": { "DatabaseVersion": "Auto", "Database": "", "User": "", "Credential": "" },
"Hfsql": {
"ConnectionName": "Business", "Server": "", "Port": 4900, "DatabaseName": "",
"Login": "", "Password": "", "Driver": "HFSQL Client/Server",
"ConnectionTimeoutSeconds": 30,
"FilePasswords": { "ProtectionStd": "", "ProtectionPlus": "" }
},
"LicenseConnection": { "Server": "", "Port": 4900, "DatabaseName": "Licence", "Login": "", "Password": "", "FilePasswords": { "ProtectionStd": "", "ProtectionPlus": "" } },
"SyncConnection": { "Server": "", "Port": 4900, "DatabaseName": "Sync", "Login": "", "Password": "", "FilePasswords": { "ProtectionStd": "", "ProtectionPlus": "" } },
"ServiceConnection": { "Server": "", "Port": 4900, "DatabaseName": "", "Login": "", "Password": "", "FilePasswords": { "ProtectionStd": "", "ProtectionPlus": "" } },
"MobileAuth": { "SigningKey": "" },
"DevelopmentAuth": { "Enabled": true, "DevCollaborateurPkId": 0, "DevCodeClient": "" },
"E2E": { "AllowHfSqlWrites": false, "ServiceDatabaseConfirmedTest": false, "WebServiceDatabaseConfirmedTest": false }
}
```
> **Garde-fou E2E** : `E2E:AllowHfSqlWrites` doit rester à `false`. Il n'est activé que
> temporairement, et explicitement, pour un test end-to-end qui écrit réellement dans HFSQL.
### 6.2 Variables d'environnement
La convention .NET `__` (double souligné) permet de surcharger n'importe quelle clé :
```powershell
$env:ASPNETCORE_ENVIRONMENT = 'Development' # charge config/hfsql-test.local.json
$env:DOTNET_ENVIRONMENT = 'Development'
$env:ASPNETCORE_URLS = 'http://localhost:5097'
$env:Omika__DatabaseVersion = 'Auto' # Auto | Batik | Omika
$env:Sync__RetryDelaySeconds = '5' # accélère le Worker en test E2E
$env:OMIKA_HFSQL_TEST_CONFIG = 'D:\chemin\vers\hfsql-test.local.json'
$env:DiagnosticsForwarding__ApiKey = '<secret>' # serveur client, jamais dans un fichier versionné
```
### 6.3 Sélection de base : Batik ou Omika
Deux notions distinctes, à ne pas confondre :
- **`DatabaseSchemaSelection`** (`Omika:DatabaseVersion`) — la sélection **demandée** :
`Auto` (détection automatique, défaut sûr), `Batik` (forcer l'ancienne base), `Omika` (forcer la
nouvelle).
- **`DatabaseSchemaVersion`** — la version **réellement détectée**. Tant que la détection n'a pas eu
lieu, elle reste `Unknown`, même si une sélection forcée est configurée. En mode forcé, une base
détectée différente provoque un échec explicite.
### 6.4 Secrets — ce qui ne doit jamais être versionné
| Fichier / clé | Statut |
|---|---|
| `config/*.local.json` | **Exclu.** Contient les identifiants HFSQL réels (dont mots de passe de fichiers). |
| `src/Omika.Diagnostics.Web/appsettings.Development.json` | **Exclu.** Contient un `PasswordHash` d'administrateur local. |
| `appsettings.*.local.json`, `secrets.json`, `.env`, `*.pfx`, `*.p12`, `*.key` | **Exclus.** |
| `DiagnosticsForwarding:ApiKey`, `MobileAuth:SigningKey`, `DiagnosticsIdentity:HmacKey`, `Diagnostics:ConnectionString` | **Vides dans les fichiers versionnés.** Injectés sur le serveur par variables d'environnement. |
---
## 7. Tests
```powershell
# Tests métier et client (~3 400 tests)
dotnet test .\tests\Omika.Tests\Omika.Tests.csproj
# Tests du Diagnostic Center (~540 tests, sans PostgreSQL réel)
dotnet test .\tests\Omika.Diagnostics.Tests\Omika.Diagnostics.Tests.csproj
# Tests internes d'un outil
dotnet test .\tools\HfSqlOleDbAudit\tests\HfSqlOleDbAudit.Tests\HfSqlOleDbAudit.Tests.csproj
```
**Échecs attendus hors environnement complet** — ce ne sont pas des régressions :
| Type | Cause |
|---|---|
| Tests HFSQL / OLE DB | Exigent un serveur HFSQL réel et `config/hfsql-test.local.json`. Ils se désactivent d'eux-mêmes si le fichier est absent. |
| Tests Avalonia headless | Peuvent échouer selon la configuration graphique de la machine. |
| `DevelopmentLicenseTests` en **Release** | Le contournement de licence de développement est compilé en `#if DEBUG` : comportement voulu. |
**Vérifications hors xUnit** — deux outils rejouent des tests sans `testhost` (contournement d'un
`Win32Exception 5` sur certains postes) :
```powershell
dotnet run --project .\tools\Omika.Verif.Dictee
dotnet run --project .\tools\Omika.Verif.Langues
```
---
## 8. Publier et déployer
Les scripts de `infra/deploy/` installent les services **Windows**. Chacun accepte une simulation
(`-WhatIf` / `-Simulation`) et s'appuie sur le module commun `Omika.Deploy.Common.psm1`.
| Script | Service Windows créé |
|---|---|
| `Install-OmikaApi.ps1` | `OmikaApi` |
| `Install-OmikaWorker.ps1` | `OmikaWorker` |
| `Install-OmikaLanguesApi.ps1` | `OmikaLanguesApi` |
| `Install-OmikaDiagnosticsApi.ps1` | `OmikaDiagnosticsApi` |
| `Install-OmikaDiagnosticsWorker.ps1` | `OmikaDiagnosticsWorker` |
| `Install-OmikaDiagnosticsWeb.ps1` | `OmikaDiagnosticsWeb` |
| `Install-OmikaServices.ps1` | Orchestration de l'ensemble |
| `Install-OmikaServerFiles.ps1` | Arborescence serveur (données, documents, journaux) |
| `Install-DatabaseSchema.ps1` | Application des migrations PostgreSQL `001` → `016` |
| `Harden-DatabaseRoles.ps1` | Rôles et droits PostgreSQL |
| `New-OmikaLanguesManifeste.ps1` | Manifeste des packs de langues à distribuer |
| `Test-PortDisponible.ps1` | Contrôle de disponibilité des ports |
Le schéma PostgreSQL vit dans `infra/postgresql/` : appliquer les migrations **dans l'ordre**
(`001_diagnostics_schema.sql` → `016_diagnostics_event_delete.sql`). Elles sont idempotentes.
Procédures détaillées :
- `docs/DEPLOIEMENT_PRODUCTION_DIAGNOSTICS.md` — déploiement du Diagnostic Center, rôles, ports,
bootstrap du premier administrateur.
- `docs/T15-RUNBOOK-DEPLOIEMENT-PRODUCTION.md` — runbook de mise en production.
- `docs/DEPLOIEMENT_API_LANGUES.md` — API de distribution des modèles de langue.
- `infra/deploy/tests/` — tests des scripts de déploiement.
---
## 9. Observabilité
Trois niveaux, **durables et fail-open** :
1. **Journaux locaux JSONL** — `logs/` côté serveur, base `omika-diagnostics.db` côté appareil.
2. **Diagnostic Center** — remontée des diagnostics vers le serveur central
(`Omika.Diagnostics.Api` → spool → `Omika.Diagnostics.Worker` → PostgreSQL →
`Omika.Diagnostics.Web`).
3. **OpenTelemetry (optionnel)** — `Observability:External:Enabled=false` par défaut. Activable vers
un Collector OTLP HTTP/protobuf (port 4318) puis SigNoz / ClickHouse.
> **Règle absolue** : *les journaux servent Omika, Omika ne dépend jamais des journaux.* Arrêter le
> Collector, SigNoz, ClickHouse ou PostgreSQL Diagnostics ne casse **jamais** le métier.
Pile de référence : `infra/observability/docker-compose.yml` + `otel-collector-config.yaml`.
Documentation : `docs/observability/` (configuration, déploiement, guide support, données exportées,
procédure de débranchement).
Le flux mobile ne passe **jamais** par OTLP : `Mobile → POST /api/diagnostics → spool JSONL serveur
→ ACK`, le forwarding externe étant asynchrone et best-effort **après** l'acquittement.
---
## 10. Traduction hors ligne et packs de langues
La traduction FR ⇄ 32 langues s'exécute **sur l'appareil** via `Microsoft.ML.OnnxRuntime`
(SentencePiece + modèles encodeur/décodeur). Le moteur n'est compilé que si le symbole
`OMIKA_ONNX_RUNTIME` est défini — il l'est dans `Omika.App.Local.csproj`. Sans lui, la traduction
répond « indisponible ».
Les modèles (`*.onnx`, `*.spm`, environ 0,5 à 1,1 Go **par langue**) sont **hors dépôt** :
| Élément | Statut |
|---|---|
| `packs/` (≈ 26 Go, 32 langues × `commun` / `versFrancais` / `depuisFrancais`) | **Non versionné.** Distribué par `Omika.Langues.Api` / GitHub Releases. |
| `packs.zip` (≈ 23 Go) | **Non versionné.** |
| `tests/fixtures/sentencepiece/*.spm`, `encoder.onnx` | **Non versionnés** — seuls les `<modele>.fixtures.json` le sont. Les tests se désactivent silencieusement en leur absence. |
Régénération des packs :
```powershell
.\scripts\Exporter-Packs-Langues.ps1 # export des packs
.\scripts\Completer-Packs-Langues.ps1 # complétion des langues manquantes
.\scripts\Generer-Fixtures-SentencePiece.ps1
```
Voir `docs/TRADUCTION_HORS_LIGNE_MOBILE.md`, `docs/LIVRAISON_MODELES_LANGUES.md` et
`docs/VALIDATION_TRADUCTION_ONNX.md`.
---
## 11. Bases de données
| Base | Technologie | Rôle |
|---|---|---|
| **HFSQL « Batik »** | HFSQL C/S (48 tables) | Ancienne base WINDEV, toujours lue et écrite. |
| **HFSQL « Omika »** | HFSQL C/S (58 tables) | Nouvelle base cible. |
| **`Licence`** | HFSQL C/S | Licences et inscriptions. |
| **`Sync`** | HFSQL C/S (`TOSRV`, `MobReception`, `MobLog`) | File d'opérations de synchronisation. |
| **`omika.db`** | SQLite | Base locale de l'appareil (offline-first). |
| **`omika-diagnostics.db`** | SQLite | Diagnostics locaux de l'appareil. |
| **`omika_diagnostics`** | PostgreSQL | Diagnostic Center central. |
> **Règle d'or** : la base HFSQL existante **n'est jamais modifiée**. Aucune table n'est créée,
> supprimée ni altérée par le nouveau code — il ne fait que lire et écrire dans le schéma existant.
> Les migrations présentes dans `Omika.Data/Migrations` concernent la **compatibilité des données**
> Batik → Omika, pas la structure.
Le dictionnaire machine-readable du schéma est `docs/schema-compatibilite-batik-omika.json`
(582 Ko) ; les 106 modèles physiques de `src/Omika.Data/HfSql/Models/` en sont générés.
---
## 12. Arborescence du dépôt
```
Omika.slnx Solution (format .slnx) — 15 projets
Directory.Build.props Version unique : OmikaVersion 1.0.0 / OmikaBuild 1
Directory.Packages.props Gestion centralisée des versions NuGet
.gitignore Exclusions (build, secrets, runtime, packs, Batik)
fix-sdk-locators.ps1 Correctif MSB4276 (poste de développement, admin)
src/ Code source (16 projets)
Omika.Core/ Métier, contrats, services (dont sync mobile)
Omika.Data/ HFSQL : connexion, repositories, mapping, migrations
Omika.App.Local/ SQLite, SyncEngine, Outbox, traduction ONNX
Omika.App/ UI Avalonia partagée (Views, ViewModels, Navigation)
Omika.App.Desktop/ Hôte bureau
Omika.App.Android/ Hôte Android
Omika.App.iOS/ Hôte iOS
Omika.Api/ API métier et mobile
Omika.Worker/ Service de synchronisation
Omika.Observability.External/ Adaptateur OpenTelemetry (isolé)
Omika.Diagnostics.*/ Diagnostic Center (Core, Data, Api, Worker, Web)
Omika.Langues.Api/ Distribution des modèles de langue
tests/
Omika.Tests/ Tests métier et client (~3 400)
Omika.Diagnostics.Tests/ Tests du Diagnostic Center (~540)
fixtures/sentencepiece/ Fixtures de traduction (LISEZMOI + *.fixtures.json)
tools/ 25 sondes console de diagnostic
docs/ Documentation (~64 documents)
infra/
deploy/ Scripts d'installation des services Windows
postgresql/ Migrations 001 → 016
observability/ Pile OTel / SigNoz / ClickHouse (optionnelle)
collector/ Exemple de configuration collector
scripts/ Export des packs de langues, seeds, publication
config/ Secrets locaux — NON versionné
packs/ Modèles de langue ONNX (≈ 26 Go) — NON versionné
Batik/ Projet WinDev historique — NON versionné
artifacts/ Sorties de publication — NON versionné
logs/ Journaux runtime — NON versionné
```
---
## 13. Règles d'architecture
Ces règles sont **vérifiées par des tests** dans `tests/Omika.Tests/Architecture/` :
1. **`Omika.Core` ne référence ni Avalonia, ni ASP.NET Core, ni `Omika.Data`.**
C'est le noyau partagé, sans dépendance technique.
2. **Le métier ne référence jamais OpenTelemetry.** Les packages OTel sont confinés à
`Omika.Observability.External` ; seules des politiques pures vivent dans `Core`.
3. **L'UI ne référence jamais `Omika.Data`.** L'application passe par l'API (HTTP) ou par
`Omika.App.Local`.
4. **Les contrats publics ne contiennent ni nom de table HFSQL, ni champ « zombie ».** Les DTO
exposés ne laissent pas fuiter le schéma physique.
5. **`Omika.Data` est la seule couche qui parle HFSQL.**
6. **Résultats d'opération** : les services renvoient `Result` / `Result<T>` plutôt que de lever des
exceptions pour les cas métier.
7. **Pas de conteneur DI dans l'UI partagée** : une composition racine manuelle unique
(`AppServices.cs`).
8. **Hors métier = fail-open.** Diagnostics, observabilité, distribution des langues : leur
indisponibilité ne doit jamais dégrader l'application.
---
## 14. Documentation
| Document | Contenu |
|---|---|
| `docs/ARCHITECTURE_PROJET.md` | **Guide complet** : rôle de chaque projet, flux, où chercher quand un bug apparaît. Le meilleur point d'entrée. |
| `docs/architecture-solution.md` | Architecture initiale de la solution, conventions, gestion de la base Batik/Omika. |
| `docs/LOT_MOBILE_0.md` | Architecture technique mobile : offline-first, SQLite, sync, identités, design system. |
| `docs/MOBILE_FUNCTIONAL_STATUS.md` | État fonctionnel réel de l'application mobile, écran par écran. |
| `docs/E2E_SYNC_VALIDATION.md` | Validation end-to-end du pipeline de synchronisation. |
| `docs/TRADUCTION_HORS_LIGNE_MOBILE.md` | Traduction ONNX embarquée. |
| `docs/DEPLOIEMENT_PRODUCTION_DIAGNOSTICS.md` | Déploiement multi-serveurs du Diagnostic Center. |
| `docs/T15-RUNBOOK-DEPLOIEMENT-PRODUCTION.md` | Runbook de mise en production. |
| `docs/dictionnaire-compatibilite-batik-omika.md` | Dictionnaire de compatibilité des schémas. |
| `docs/observability/` | Observabilité externe (configuration, déploiement, support, débranchement). |
| `docs/BATIK.md`, `docs/OMIKA.md`, `docs/Documentation_*.md` | **Exports WINDEV de l'ancien système** — référence historique uniquement. |
| `ANALYSE-OMIKA-APP.md` | Analyse technique complète de l'application (écrans, pile, limites). |
| `ANALYSE_OMIKA_BATIK/` | Études comparatives Batik / Omika. |
---
## 15. Dépannage
| Symptôme | Cause probable / solution |
|---|---|
| **MSB4276** à la compilation | Workload Android/iOS corrompu sur le poste. Contournement utilisé par les scripts : `dotnet build <projet> --no-restore -m:1`. Solution durable : `dotnet workload repair`, ou exécuter `fix-sdk-locators.ps1` **en administrateur**. |
| **MSB3027** (fichier verrouillé) | Une instance d'Omika tourne encore. `stop_omika_test.ps1`, ou `build_omika_test.ps1` sans `-NoStop`. |
| L'API démarre mais les données sont vides | `config/hfsql-test.local.json` absent ou non résolu. Vérifier `OMIKA_HFSQL_TEST_CONFIG`, et que `ASPNETCORE_ENVIRONMENT=Development`. |
| Traduction « indisponible » | Le symbole `OMIKA_ONNX_RUNTIME` n'est pas défini, ou les modèles de langue ne sont pas installés sur l'appareil. |
| `omika.db` contient des données de la mauvaise base | Relancer avec `start_omika_test.ps1 -Clean` après un changement Batik ⇄ Omika. |
| Le Worker ne traite pas les opérations | Vérifier la connexion `SyncConnection` et la table `TOSRV`. En test E2E, `Sync__RetryDelaySeconds=5` accélère la boucle. |
| Diagnostics.Web : pages « indisponible » | PostgreSQL est en panne. **Comportement attendu** (fail-open) : l'outil support ne bloque jamais le métier. |
| `dotnet build Omika.slnx` ne compile pas les Diagnostics | Normal : ces projets sont **hors solution**. Les compiler par leur chemin explicite. |
| L'application Android ne se compile pas | `dotnet workload install android`. iOS exige macOS + Xcode. |
---
## Licence
Projet propriétaire — © Applilogik. Tous droits réservés.