Add human review protocol and admin rules contract
This commit is contained in:
307
docs/spec-regles-administration.md
Normal file
307
docs/spec-regles-administration.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user