Aller au contenu

Identifiants et contraintes d’unicité

Par défaut, Facet nomme chaque document avec un ULIDà: un identifiant long, triable et opaque. Beaucoup d’enregistrements se lisent mieux avec un numéro que l’on peut prononcer à voix haute, comme INV-2026-0001. Un bloc identifier sur le doctype génère de tels numéros. Les règles d’unicité sur les champs servent un second butà : deux documents ne peuvent pas porter la même valeur.

Ajoutez un identifiant quand les utilisateurs citent des numéros de document de vive voix, dans un courriel ou sur un document imprimé. Ajoutez unique quand une valeur dupliquée serait une erreur de données, comme deux employés avec la même adresse de courriel.

  • L’identifiant devient l’id du document. Il est généré à la création et ne change jamais.
  • Un compteur par doctype. Facet tient un compteur par doctype, partagé entre tous les écrivains.
Jeton Signification
# Un chiffre du compteur, complété par des zéros. Quatre chiffres comptent à partir de 0001.
{year} L’année en cours, par exemple 2026.
{month} Le mois en cours, par exemple 06.
{day} Le jour en cours, par exemple 15.
autre texte Texte littéral, copié tel quelà : INV-, -, TKT-.

Le modèle exige au moins un groupe #, et un groupe compte au plus 18 chiffres. Quand l’année ou le mois change, le compteur repart à zéro et la numérotation redémarre à 1.

"identifier": {
"template": "INV-{year}-####",
"genonly": true
}

genonly: true interdit aux appelants de fournir leur propre id à la création. Sans lui, le modèle génère quand même l’id quand l’appelant n’en fournit pas.

Mettez unique: true sur tout champ dont la valeur doit différer d’un document à l’autre. Facet vérifie la règle à chaque create et updateà : une valeur vide sur un document et une valeur absente sur un autre n’entrent pas en collision.

"email": {
"type": "string",
"required": true,
"unique": true,
"filters": ["equality", "text_search"]
}
{
"domain": "crm",
"doctype": "Invoice",
"aggregate_root": true,
"schema_version": 1,
"identifier": { "template": "INV-{year}-####", "genonly": true },
"fields": {
"customer": { "type": "reference", "doctype": "crm.Company", "required": true },
"total": { "type": "money", "currency": "EUR", "filters": ["comparison"] }
}
}

Les trois premières créations produisent les ids INV-2026-0001, INV-2026-0002 et INV-2026-0003. Le 1er janvier, la numérotation repart de INV-2027-0001. Le numéro est l’id du documentà : les pages l’affichent et les utilisateurs peuvent retrouver un document par son numéro (le filtre id__match).

Une écriture répond 422 avec une erreur d’unicité

Section intitulée « Une écriture répond 422 avec une erreur d’unicité »

Un autre document du même doctype porte déj à cette valeur. Trouvez-le en filtrant la liste sur le champ, puis changez la valeur ou corrigez le doublon.

Le doctype déclare genonly: true. Les appelants omettent l’id et laissent Facet le générer.

Le compteur a débordé, ou le document a été créé avant l’ajout du bloc identifier. Les identifiants s’appliquent aux documents créés une fois le bloc en place.

Deux doctypes remettent leur compteur à zéro à des moments différents

Section intitulée « Deux doctypes remettent leur compteur à zéro à des moments différents »

Chaque modèle porte ses propres variables de temps. Un modèle avec {month} repart chaque moisà ; un modèle avec seulement {year} repart chaque année.