582 lines
33 KiB
Markdown
582 lines
33 KiB
Markdown
# 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.
|