# 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