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, membres, beneficiaires, paiements, plaintes, transferts).

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 > onglet Parametres > section Nomenclature > Configuration des nomenclatures

Ou directement via l'adresse /#/parametres/nomenclature (l'application utilise un routage par ancre).

---

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 l'API

curl -X POST https://<domaine>/api/nomenclatures/init \
  -H "Authorization: Bearer <token>"

Il n'existe pas de commande console d'initialisation. L'initialisation ne crée que les types encore absents : elle ne modifie pas une configuration existante.

---

Types d'entites supportes

Le systeme gere la nomenclature pour 6 types d'entites. Les prefixes ci-dessous sont ceux crees par l'initialisation ; la configuration reelle de chaque serveur se lit dans l'ecran.

Type	Description	Prefixe par defaut	Exemple
menage	Identifiant unique du menage	PCH	PCH-SAO-2026-000001
membre	Identifiant d'un membre du menage	M	M00000001 (prefixe + sequence sur 8 chiffres au moins)
beneficiaire	Code beneficiaire	BEN	format en service : identifiant du menage + rang (0070196270201) ; le format BEN-… de l'initialisation n'est plus utilise
paiement	Reference de paiement	PAI	PAI-2026-00000001
plainte	Numero de plainte	PLA	PLA-2026-00001
cycle	Code du transfert (cycle de paiement), affiche « Transfert »	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 appelez POST /api/nomenclatures/init.

---

API Reference

Endpoints disponibles

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

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

---

Regenerer les identifiants d'un lot

Un lot integre avant un changement de nomenclature garde ses anciens identifiants. Pour le renumeroter (menages et beneficiaires), cibler le lot par son prefixe, jamais tout le registre :

docker exec -u www-data pch_backend php bin/console app:nomenclature:regenerer-menages --prefixe=<PREFIXE> --dry-run
docker exec -u www-data pch_backend php bin/console app:nomenclature:regenerer-menages --prefixe=<PREFIXE>

L'identifiant de nomenclature d'un menage est distinct de son code de collecte (code Kobo ou code du fichier source), qui est conserve tel quel.