# T24-A — Prompt IA local + référentiel administrable ScreenCode/FeatureCode

> Statut : PRÉPROD LOCAL / recette manuelle. Aucun Git, aucune Production.

## 1. Générer le prompt IA (Partie A)

### Principe
Le centre Diagnostics génère un **prompt d'analyse local** depuis un diagnostic/erreur.
**Aucun appel IA externe** (OpenAI, ChatGPT ou autre) : le système se contente de :

```
diagnostic → construire un texte local → afficher le prompt → permettre « Copier »
```

Le prompt n'est **jamais enregistré en PostgreSQL** (génération à la demande uniquement, V1).

### Boutons
- **Détail diagnostic** (`/Diagnostics/{id}`) : bouton « Générer le prompt IA » à proximité du
  contexte technique.
- **Détail erreur** (`/Erreurs/{id}`) : bouton « Générer le prompt IA » (depuis l'occurrence la
  plus récente du groupe).

Un clic déclenche la génération **côté serveur** (handler Razor Pages `OnGetPromptAsync`), puis
affiche le prompt dans une modale dédiée avec un bouton **« Copier le prompt »** (réutilise
`OmikaCopy()`, aucune nouvelle librairie JS).

### Service partagé
La construction du prompt est centralisée dans `Omika.Diagnostics.Core` :
`DiagnosticPromptBuilder.Build(DiagnosticEventRecord, IReadOnlyList<DiagnosticEventRecord>?)`.
Le chargement des événements corrélés est partagé par
`DiagnosticsDetailModel.GetCorrelatedEventsAsync(...)` (utilisé par le détail diagnostic ET le
détail erreur). Aucune logique dupliquée.

### Informations incluses (si disponibles)
- **CONTEXTE** : ClientCode, Environment, ServerInstance, Source, Component, Platform,
  OperatingSystem, OperatingSystemVersion, Manufacturer, Model, AppVersion, AppBuild,
  ScreenCode, FeatureCode.
- **ERREUR** : EventCode, Level, Priority, ErrorCode, Timestamp, DurationMs.
- **MESSAGE** : Message (tronqué à 2000 caractères).
- **EXCEPTION** : ExceptionType, StackTrace (tronquée à 4000 caractères).
- **HTTP / MÉTADONNÉES** : uniquement les clés whitelistées (`method`, `statusCode`,
  `routeTemplate`, `retryCount`, …) et valeurs simples non interdites.
- **CORRÉLATION** : TraceId, OperationId, SessionId.
- **IDENTITÉ TECHNIQUE AUTORISÉE** : LicenseNumber (numéro fonctionnel), DeviceKey et ActorKey
  **tronqués** (pseudonymes HMAC-SHA256, jamais réversibles).
- **ÉVÉNEMENTS CORRÉLÉS** (si TraceId/OperationId) : chronologie compacte, **bornée à 25
  événements**, sans stack trace (timestamp, level, eventCode, component, message court,
  screen/feature).

### Informations exclues (jamais)
password, password_hash, ApiKey, api_key_hash, Bearer token, SigningKey, HmacKey,
ConnectionString, DeviceId brut, UserId brut, CollaborateurId brut, ClientId brut, email,
téléphone, IMEI, serial, MAC, secret de licence.

La politique **réutilise** les filtres existants : `DiagnosticForbiddenData`
(jetons interdits) et `DiagnosticMetadataPolicy` (whitelist des clés). Aucune seconde logique de
filtrage. Défense en profondeur : chaque valeur relue est re-vérifiée avant inclusion.

### Format
Le prompt commence par :
> « Analyse cette erreur Omika et aide-moi à déterminer sa cause probable. »

puis demande explicitement : cause probable, niveau de confiance, fichier/méthode à vérifier en
priorité, éléments de preuve, hypothèses alternatives, correctif recommandé, tests de
confirmation, dire si l'erreur semble volontaire/de test, distinguer faits confirmés et hypothèses.

### Exemple /dev/throw
L'événement de recette `API_HTTP_ERROR` / `InvalidOperationException` / `/dev/throw` /
`TELEMETRY_TEST_ERROR` / `Development` produit un prompt contenant naturellement ces données —
**aucune règle codée en dur** « /dev/throw ».

## 2. Référentiel administrable (Partie B)

### Règle absolue
`diagnostic_event` **reste la vérité** sur ce qui a réellement été observé. Le référentiel
(`diagnostics_reference`) est un **enrichissement** (libellé / description / ordre / état) et ne
détermine **jamais** quels événements sont acceptés. Un code observé non référencé reste visible
dans les filtres.

### Table `diagnostics_reference` (migration 011)
`id`, `reference_type` (`SCREEN_CODE` / `FEATURE_CODE`), `code` (normalisé TRIM+UPPER),
`label`, `description`, `enabled`, `sort_order`, `created_at_utc`, `updated_at_utc`.

- Unicité : `(reference_type, UPPER(code))` — index unique.
- **Code immuable** après création. Pour corriger un code : créer une nouvelle entrée + archiver
  l'ancienne.
- **Archivage = `enabled=false`**, jamais de DELETE physique (V1).

### Ownership / GRANT (011)
- Propriétaire : `omika_diagnostics_owner`.
- `omika_diagnostics_web` : `SELECT`, `INSERT`, `UPDATE (label, description, enabled,
  sort_order, updated_at_utc)` + `USAGE` séquence. **Aucun DELETE.**
- `omika_diagnostics_api` et `omika_diagnostics_worker` : **aucun droit** (testé négativement).

### Initialisation (idempotente)
Les **29 ScreenCode** et **3 FeatureCode** du catalogue applicatif sont seedés par la migration
avec leurs libellés (`ON CONFLICT DO NOTHING`). Un libellé modifié par un Admin n'est **jamais
écrasé** au redémarrage.

### Pages
- `/Referentiel` : consultation (Support + Admin) — sections Codes écran / Codes fonctionnalité
  alimentées par le référentiel DB (libellé + description + état), repli catalogue statique si DB
  indisponible.
- `/Referentiel/Admin` : **Admin uniquement** — liste (Type, Code, Libellé, Description, État,
  Dernière modification, Actions), création, modification (libellé/description/état/tri),
  archivage/réactivation, et section **« Codes observés non référencés »** avec **ajout rapide**.

### Procédure : ajout d'un nouveau code
1. Un événement arrive avec un `screen_code`/`feature_code` inconnu (ex. `FACTURE_DETAIL`).
2. Le code **apparaît automatiquement** dans les filtres Diagnostics (alimentés par
   `diagnostic_event`), affiché `FACTURE_DETAIL (non référencé)`.
3. Dans `/Referentiel/Admin` → « Codes observés non référencés » → « Ajouter » (type + code
   préremplis) → Admin renseigne le libellé/la description.
4. Le filtre affiche alors `Détail de facture (FACTURE_DETAIL)` — **sans modifier les données
   historiques**. La recherche SQL utilise toujours le **code**, jamais le libellé.

### Dropdowns / filtrage
Les listes déroulantes continuent d'être alimentées par les codes **réellement observés** (jamais
`SELECT` sur `diagnostics_reference` uniquement). Si une référence existe : `Libellé (CODE)` ;
sinon : `CODE (non référencé)`. La valeur du filtre reste toujours le CODE.

## 3. Corrections UX (Partie C)
- Filtre « Acteur » → **« Acteur pseudonymisé »** + aide : « Identifiant pseudonymisé permettant
  de retrouver les événements d'un même utilisateur. »
- Page/menu « Versions » → **« Versions Omika »**.
- « Version la plus représentée » → **« Version Omika la plus observée »** + note : « Les valeurs
  correspondent aux événements observés, pas au nombre d'installations. »

## 4. Sécurité
- Prompt généré : 0 fuite de données interdites (testé — `DiagnosticPromptBuilderTests`).
- HTML : le prompt est affiché via `textContent` (aucune injection HTML).
- Aucun enregistrement du prompt (ni PostgreSQL, ni log).
- Migration 011 : aucune colonne secret, aucun mot de passe.

## 5. Tests
- `Omika.Diagnostics.Tests` : 574/574 (baseline 536 + 38 tests T24-A).
- `Omika.Tests` : 3366/3370 — 4 échecs environnementaux/préexistants (construction de vues
  Avalonia ×2, course temporelle ShellViewModel, accès HFSQL), **aucune régression** liée à T24-A
  (T24-A est isolé dans le sous-système Diagnostics, non référencé par Omika.Tests).

## 6. Migration 011
`infra/postgresql/011_diagnostics_reference.sql` — ordre final : `001 → … → 010 → 011`.
Idempotente, non destructive (aucun DROP/DELETE), aucun mot de passe.