Nomenclature des identifiants

Ce guide explique comment configurer le systeme de nomenclature pour generer des identifiants uniques et coherents pour les differentes entites du systeme (menages, beneficiaires, paiements, plaintes, cycles).

Introduction

La nomenclature des identifiants permet de definir un format standardise pour les codes generes automatiquement. Cette fonctionnalite assure :

• Unicite : Chaque identifiant est unique dans le systeme
• Tracabilite : Les identifiants contiennent des informations contextuelles (region, annee)
• Coherence : Tous les identifiants d'un meme type suivent le meme format
• Lisibilite : Le format est comprehensible par les utilisateurs

---

Acces a la configuration

La configuration de la nomenclature est accessible aux administrateurs via :

Parametres > Systeme > Nomenclature des identifiants

Ou directement via l'URL : /parametres/nomenclature

---

Initialiser les configurations par defaut

Lors de la premiere utilisation, vous devez initialiser les configurations par defaut.

Via l'interface

1. Accedez a la page de configuration de la nomenclature
2. Cliquez sur le bouton Initialiser
3. Les configurations par defaut seront creees pour tous les types d'entites

Via la ligne de commande

# Sur le serveur
docker compose exec backend php bin/console app:nomenclature:init

# Ou via l'API (necessite un token admin)
curl -X POST https://votre-domaine.org/api/nomenclatures/init \
  -H "Authorization: Bearer <token>"

---

Types d'entites supportes

Le systeme gere la nomenclature pour 5 types d'entites :

Type	Description	Prefixe par defaut	Exemple
menage	Identifiant unique du menage	PCH	PCH-SAO-2026-000001
beneficiaire	Code beneficiaire	BEN	BEN-GAB-2026-000001
paiement	Reference de paiement	PAI	PAI-2026-00000001
plainte	Numero de plainte	PLA	PLA-2026-00001
cycle	Code du cycle de paiement	CYC	CYC-2026-001

---

Variables disponibles

Les identifiants sont generes a partir d'un pattern composable utilisant les variables suivantes :

{PREFIX}

Le prefixe configurable de l'identifiant.

Parametre	Description	Valeur par defaut
prefixe	Code alphabetique (1-10 caracteres)	PCH, BEN, PAI...

Exemples : PCH, BEN, PAI, PLA, CYC, TMC, PROG

{REGION}

Le code de la region geographique. Deux modes possibles :

Mode	Description	Exemple
Premieres lettres	Utilise les N premieres lettres du nom	SAO (Sao Domingos)
Code officiel	Utilise le code administratif officiel	01

Parametres :

• includeRegion : Inclure la region (true/false)
• useRegionCode : Utiliser le code officiel (true/false)
• regionLength : Nombre de caracteres si lettres du nom (1-10)

{SECTEUR}

Le code du secteur geographique. Memes modes que la region.

Parametres :

• includeSecteur : Inclure le secteur (true/false)
• useSecteurCode : Utiliser le code officiel (true/false)
• secteurLength : Nombre de caracteres si lettres du nom (1-10)

{YEAR}

L'annee de creation de l'entite.

Format	Description	Exemple
4 chiffres	Annee complete	2026
2 chiffres	Annee courte	26

Parametres :

• includeYear : Inclure l'annee (true/false)
• yearFormat : 2 ou 4 chiffres

{SEQ}

Le numero de sequence incremental ou aleatoire.

Mode	Description	Exemple (6 chiffres)
Sequentiel	Incremente automatiquement	000001, 000002, 000003...
Aleatoire	Nombre aleatoire unique	847293, 156832...

Parametres :

• sequencePadding : Nombre de chiffres (1-10)
• useRandomSequence : Mode aleatoire (true/false)

---

Separateurs disponibles

Le separateur permet de delimiter les differentes parties de l'identifiant.

Separateur	Caractere	Exemple
Tiret	-	PCH-SAO-2026-000001
Underscore	_	PCH_SAO_2026_000001
Slash	/	PCH/SAO/2026/000001
Point	.	PCH.SAO.2026.000001
Aucun	(vide)	PCHSAO2026000001

---

Personnaliser le format

Modifier une configuration

1. Sur la page de nomenclature, cliquez sur Modifier sur la carte du type souhaite
2. Ajustez les parametres dans la modale :
   • Prefixe : Code alphabetique (optionnel)
   • Separateur : Caractere de separation
   • Nombre de chiffres : Padding de la sequence
   • Inclure la region : Avec option code officiel ou lettres
   • Inclure le secteur : Avec option code officiel ou lettres
   • Inclure l'annee : Format 2 ou 4 chiffres
   • Numeros aleatoires : Au lieu de sequentiels
   • Configuration active : Activer/desactiver
3. L'apercu se met a jour en temps reel
4. Cliquez sur Enregistrer

Via l'API

# Mettre a jour une configuration
curl -X PATCH https://votre-domaine.org/api/nomenclatures/{id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prefixe": "TMC",
    "separateur": "-",
    "sequencePadding": 8,
    "includeRegion": true,
    "useRegionCode": false,
    "regionLength": 3,
    "includeYear": true,
    "yearFormat": 4,
    "useRandomSequence": false
  }'

---

Exemples de formats

Format standard avec region

Prefixe: PCH
Region: 3 lettres du nom
Annee: 4 chiffres
Sequence: 6 chiffres
Separateur: -

Resultat: PCH-SAO-2026-000001

Format compact

Prefixe: B
Region: Code officiel (01)
Annee: 2 chiffres
Sequence: 4 chiffres
Separateur: (aucun)

Resultat: B01260001

Format avec secteur

Prefixe: MEN
Region: Code officiel (01)
Secteur: Code officiel (005)
Annee: 4 chiffres
Sequence: 5 chiffres
Separateur: -

Resultat: MEN-01-005-2026-00001

Format aleatoire (anti-fraude)

Prefixe: PAY
Region: Non incluse
Annee: 4 chiffres
Sequence: 8 chiffres aleatoires
Separateur: -

Resultat: PAY-2026-84729361

---

Gestion des sequences

Sequences par prefixe

Le systeme maintient un compteur de sequence distinct pour chaque combinaison prefixe+region+annee. Par exemple :

• PCH-SAO-2026 → Sequence 1, 2, 3...
• PCH-GAB-2026 → Sequence 1, 2, 3... (independante)
• PCH-SAO-2027 → Sequence 1, 2, 3... (reset en debut d'annee)

Reinitialiser les sequences

Attention

La reinitialisation des sequences peut creer des doublons si des entites existent deja avec les anciens identifiants. Utilisez avec precaution.

1. Sur la carte de configuration, cliquez sur l'icone de reinitialisation
2. Confirmez l'action dans la boite de dialogue

Via l'API :

curl -X POST https://votre-domaine.org/api/nomenclatures/{id}/reset-sequences \
  -H "Authorization: Bearer <token>"

---

Bonnes pratiques

Planification

• Definissez le format avant la mise en production : Changer le format apres creation d'entites cree une inconsistance
• Documentez vos choix : Notez pourquoi vous avez choisi tel ou tel format
• Testez en preprod : Verifiez que le format genere correspond a vos attentes

Lisibilite

• Prefixe court mais explicite : PCH, BEN, PAI sont preferes a P, B, P
• Utilisez des separateurs : PCH-SAO-2026-000001 est plus lisible que PCHSAO2026000001
• Padding suffisant : Prevoyez assez de chiffres pour la croissance (6 chiffres = 999 999 entites max par prefixe)

Securite

• Mode aleatoire pour les paiements : Empeche de deviner les references
• Ne partagez pas les sequences : Les dernieres sequences sont des informations sensibles

Performance

• Evitez les sequences trop longues : Plus de 10 chiffres est rarement necessaire
• Le mode aleatoire est plus couteux : Le systeme doit verifier l'unicite

---

Depannage

L'identifiant genere ne correspond pas au format

Cause possible : L'entite n'a pas de region associee.

Solution : Si includeRegion est active, assurez-vous que le menage a une region definie. Sinon, le systeme utilise "XXX" comme placeholder.

Sequence qui saute des numeros

Cause possible : Des entites ont ete supprimees ou la transaction a ete annulee.

Solution : C'est un comportement normal. La sequence garantit l'unicite, pas la continuite.

Erreur "Configuration non trouvee"

Cause possible : Les configurations par defaut n'ont pas ete initialisees.

Solution : Cliquez sur "Initialiser" ou executez la commande d'initialisation.

---

API Reference

Endpoints disponibles

Methode	Endpoint	Description	Permission
GET	/api/nomenclatures	Liste toutes les configurations	ROLE_USER
GET	/api/nomenclatures/{id}	Detail d'une configuration	ROLE_USER
GET	/api/nomenclatures/type/{type}	Configuration par type	ROLE_USER
POST	/api/nomenclatures	Creer une configuration	ROLE_ADMIN
PATCH	/api/nomenclatures/{id}	Modifier une configuration	ROLE_ADMIN
GET	/api/nomenclatures/{id}/preview	Previsualiser un identifiant	ROLE_USER
POST	/api/nomenclatures/init	Initialiser les defauts	ROLE_ADMIN
POST	/api/nomenclatures/{id}/reset-sequences	Reinitialiser les sequences	ROLE_ADMIN

Structure d'une configuration

{
  "id": "uuid",
  "type": "menage",
  "libelle": "Identifiant Menage",
  "prefixe": "PCH",
  "pattern": "{'{PREFIX}'}-{'{REGION}'}-{'{YEAR}'}-{'{SEQ}'}",
  "separateur": "-",
  "sequencePadding": 6,
  "includeRegion": true,
  "useRegionCode": false,
  "regionLength": 3,
  "includeSecteur": false,
  "useSecteurCode": true,
  "secteurLength": 3,
  "includeYear": true,
  "yearFormat": 4,
  "useRandomSequence": false,
  "exemple": "PCH-XXX-2026-000001",
  "lastSequences": {
    "PCH-SAO-2026": 42,
    "PCH-GAB-2026": 15
  },
  "actif": true,
  "createdAt": "2026-01-15T10:30:00+00:00",
  "updatedAt": "2026-05-10T14:22:00+00:00"
}

---

Prochaines etapes

• Utilisateurs
• Roles et Permissions
• Configuration