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
2. Architecture
3. Les projets
4. Prérequis
5. Démarrage rapide
6. Configuration
7. Tests
8. Publier et déployer
9. Observabilité
10. Traduction hors ligne et packs de langues
11. Bases de données
12. Arborescence du dépôt
13. Règles d'architecture
14. Documentation
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) :

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

{
  "Enabled": true,
  "ClientCode": "LOCAL-DEV",
  "UserDisplayName": "<nom affiché>",
  "ExpirationDays": 365,
  "ApiUrl": "http://localhost:5097"
}

5.2 Commandes dotnet directes

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

{
  "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é :

$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

# 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) :

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 :

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