Premiere commit - Omika

docs/hfsql-odbc-probe.md

@@ -0,0 +1,114 @@
+# HFSQL ODBC Capability Probe
+
+## ⚠ CRITICAL — pour base de test / clone uniquement
+
+Cet outil est **exclusivement réservé à une base clone ou de test**.
+Il ne doit **jamais** être lancé contre une base de production.
+
+Les probes d'écriture (`transaction`, `returning`) effectuent des INSERT temporaires
+(avec ROLLBACK), mais un auto-incrément peut être consommé même après rollback.
+
+## Pourquoi cet outil ?
+
+Avant d'implémenter la création de Client (`POST /clients`), nous devons confirmer
+expérimentalement que le driver ODBC HFSQL supporte :
+
+1. `INSERT INTO ... RETURNING <colonne_auto_id>` via `OdbcCommand.ExecuteScalar()` et `ExecuteReader()`
+2. Les transactions (BEGIN / ROLLBACK)
+3. Le format de GUID Omika (32 caractères, format `N`)
+
+Ces capacités ne peuvent pas être vérifiées sans une connexion réelle.
+
+## Commandes
+
+```
+dotnet run --project tools/Omika.HfSqlProbe -- <commande> <options>
+```
+
+### `capabilities` — lecture seule
+
+Affiche les informations du driver ODBC et teste `SELECT 1`.
+
+```
+dotnet run --project tools/Omika.HfSqlProbe -- capabilities --connection-string "<DSN>"
+```
+
+### `transaction` — écriture (exige `--allow-write-probe`)
+
+Teste BEGIN / INSERT / SELECT / ROLLBACK sur une table de test.
+
+```
+dotnet run --project tools/Omika.HfSqlProbe -- transaction `
+  --connection-string "<DSN>" `
+  --allow-write-probe `
+  --table ProbeTable `
+  --marker-column TestMarker
+```
+
+### `returning` — écriture (exige `--allow-write-probe`)
+
+Teste `INSERT ... RETURNING` via **ExecuteScalar** et **ExecuteReader**.
+
+```
+dotnet run --project tools/Omika.HfSqlProbe -- returning `
+  --connection-string "<DSN>" `
+  --allow-write-probe `
+  --table ProbeTable `
+  --id-column PKID `
+  --marker-column TestMarker
+```
+
+### `omika-guid` — lecture seule
+
+Statistiques sur les GUID de la table Client (longueur 32/36, doublons).
+
+```
+dotnet run --project tools/Omika.HfSqlProbe -- omika-guid --connection-string "<DSN>"
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--connection-string` | Chaîne ODBC HFSQL (DSN=...) — obligatoire |
+| `--allow-write-probe` | Confirme l'utilisation sur une base clone/test (obligatoire pour writes) |
+| `--table` | Table pour les probes d'écriture |
+| `--id-column` | Colonne auto-ID (défaut : PKID) |
+| `--marker-column` | Colonne recevant la valeur marqueur (défaut : Marker) |
+| `--schema` | `batik` ou `omika` (pour probes spécifiques Client) |
+| `--use-client-table` | Écriture sur la table Client (clone DB uniquement !) |
+
+## Codes de sortie
+
+| Code | Signification |
+|---|---|
+| 0 | Succès |
+| 1 | Capacité testée non supportée / échec |
+| 2 | Arguments invalides / sécurité |
+| 3 | Connexion impossible |
+
+## Ordre recommandé pour le premier test réel
+
+1. **`capabilities`** sur une clone — valider le driver et la connexion
+2. **`returning`** sur une table de test dédiée avec colonne auto-ID — prouver que RETURNING fonctionne
+3. **`transaction`** sur la même table — prouver l'isolation
+4. Si 1/2/3 sont verts : **`omika-guid`** pour les statistiques GUID
+5. Ensuite seulement : tests spécifiques Client Batik/Omika
+
+## Niveaux de validation
+
+- **Niveau 1** : capacité générique du driver (`returning`, `transaction`)
+- **Niveau 2** : INSERT Client physique (Batik ou Omika) — nécessite le niveau 1 validé
+
+## Protection anti-production
+
+- `--allow-write-probe` est obligatoire pour toute commande d'écriture
+- La connection string n'est jamais lue automatiquement (pas de appsettings.json)
+- Les credentials sont masqués dans les messages d'erreur
+- Les identifiants SQL sont strictement validés (`\A[A-Za-z_][A-Za-z0-9_]*\z`)
+
+## Limitations connues
+
+- La validation RETURNING n'a pas encore été exécutée contre un vrai driver HFSQL
+- L'outil ne prouve pas comment l'application historique Omika générait ses GUID
+- Un auto-ID peut être consommé par HFSQL même après ROLLBACK