anonymisation/docs/spec-regles-administration.md

# Specification MVP - regles d'administration

## 1. Objet

Cette specification decrit un MVP pour administrer des regles d'anonymisation
sans modifier directement le code du moteur.

Le but n'est pas de donner un acces libre a des regex dangereuses.
Le but est de fournir un **moteur de regles gouverne**, testable et reversible.

## 2. Objectifs fonctionnels

Le MVP doit permettre de :

- creer une regle ;
- visualiser sa forme normalisee ;
- simuler son effet sur un corpus cible ;
- l'activer ou la desactiver ;
- garder une trace complete des changements ;
- lier chaque regle a des cas de test.

## 3. Hors perimetre MVP

Le MVP ne cherche pas encore a :

- couvrir tous les cas regex complexes ;
- gerer des workflows d'approbation multi-niveaux ;
- remplacer toute la configuration coeur existante ;
- editer directement les heuristiques internes du pipeline.

## 4. Types de regles supportes

### 4.1 `exact_term`

Usage :

- masquer un terme exact.

Exemples :

- `CHCB`
- `LOCAL_SIGLE`

Parametres principaux :

- `match.exact_value`
- `normalization.case_insensitive`
- `normalization.whole_word`

### 4.2 `normalized_identifier`

Usage :

- masquer une valeur canonique et ses variantes normalisees.

Exemple :

- valeur canonique : `1234567`

Variantes attendues selon la configuration :

- `1234567`
- `N°1234567`
- `N° 1234567`
- `No1234567`
- `Numero 1234567`

Parametres principaux :

- `match.canonical_value`
- `normalization.accepted_prefixes`
- `normalization.prefix_value_separators`
- `normalization.allow_bare_value`
- `normalization.multiline`

### 4.3 `contextual_identifier`

Usage :

- masquer un identifiant seulement dans un contexte structure donne.

Exemples :

- `IPP : ABC12345`
- `N° venue : 1234567`
- `N° examen : 23L35781`

Parametres principaux :

- `match.canonical_value`
- `match.context_prefixes`
- `match.context_separators`
- `normalization.multiline`

### 4.4 `preserve_phrase`

Usage :

- garantir qu'une phrase ou formulation metier ne soit jamais masquee.

Exemples :

- `classification internationale`
- `prise en charge`

Parametres principaux :

- `match.exact_value`
- `normalization.case_insensitive`

## 5. Structure des regles

Le schema de reference est fourni ici :

- [admin_rules.schema.json](/home/dom/ai/anonymisation/schemas/admin_rules.schema.json:1)

Le template versionne est ici :

- [admin_rules.default.yml](/home/dom/ai/anonymisation/config/admin_rules.default.yml:1)

## 6. Champs minimaux par regle

Chaque regle doit porter :

- `id`
- `label`
- `type`
- `action`
- `status`
- `match`
- `scope`
- `governance`

Et, si `action = mask` :

- `placeholder`

## 7. Etats de cycle de vie

### `draft`

- regle redigee ;
- jamais activee ;
- pas encore validee.

### `candidate`

- regle complete ;
- simulation en cours ;
- revue humaine a faire.

### `approved`

- regle validee fonctionnellement ;
- prete a etre activee.

### `active`

- regle exploitable en environnement autorise.

### `disabled`

- regle desactivee temporairement.

### `retired`

- regle retiree, conservee pour audit.

## 8. Portee d'une regle

Une regle ne doit pas etre globalisee par defaut.

Le MVP doit permettre de preciser :

- familles documentaires ;
- environnements ;
- zones documentaires :
  - `narrative`
  - `structured`
  - `table`
  - `header`
  - `footer`

## 9. Gouvernance minimale

Chaque regle doit indiquer :

- `owner`
- `justification`
- `created_at`
- `review_required_for_activation`
- `tests.required_case_ids`

Pour une regle active, l'absence de cas de test associe doit etre interdite.

## 10. Ecrans MVP recommandes

### 10.1 Liste des regles

Colonnes minimales :

- id ;
- label ;
- type ;
- status ;
- scope ;
- auteur ;
- date ;
- dernier test ;
- dernier verdict.

Actions :

- filtrer ;
- dupliquer ;
- desactiver ;
- ouvrir ;
- comparer deux versions.

### 10.2 Creation / edition d'une regle

Blocs de formulaire :

- identification ;
- type ;
- valeur source ;
- normalisation ;
- portee ;
- gouvernance ;
- rattachement des cas de test.

### 10.3 Simulation

Avant activation, afficher :

- variantes generees ;
- cas touches ;
- extrait avant / apres ;
- nouveaux masquages ;
- pertes de preservation ;
- verdict automatique.

### 10.4 Validation / activation

Le panneau d'activation doit afficher :

- resultat du validateur de schema ;
- resultat des tests lies ;
- resultat du corpus de simulation ;
- presence ou non d'une revue humaine ;
- bouton `Activer` ou blocage.

### 10.5 Historique

Chaque changement doit laisser une trace :

- qui ;
- quand ;
- quoi ;
- pourquoi ;
- sur quel perimetre ;
- avec quel resultat.

## 11. Garde-fous obligatoires

Le MVP doit bloquer :

- une regle active sans cas de test ;
- une regle `preserve_phrase` avec action `mask` ;
- une regle trop large sans justification ;
- une activation sans simulation ;
- une regle syntaxiquement invalide.

## 12. Commande de validation hors interface

Le depot fournit un validateur CLI :

- [validate_admin_rules.py](/home/dom/ai/anonymisation/tools/validate_admin_rules.py:1)

Exemple :

```bash
python3 tools/validate_admin_rules.py --config config/admin_rules.default.yml --show-variants
```

## 13. Recommandation d'implementation

Ordre recommande :

1. schema et validateur ;
2. stockage YAML versionne ;
3. simulation hors interface ;
4. ecran d'edition ;
5. ecran de simulation ;
6. activation gouvernee.

## 14. Point important

Ces artefacts definissent le **contrat de regles** et le **MVP d'administration**.
Ils ne branchent pas encore ces regles dans le moteur de production.

La prochaine etape technique sera :

- chargement de `admin_rules` ;
- compilation ;
- simulation ;
- puis application controlee dans le pipeline.