Aller au contenu

Composition parent/enfant

Certains enregistrements sont des parties d’un tout. Une commande porte ses lignes, un projet porte ses tâches, un employé porte ses événements de carrière. Facet modélise cela par la composition : le parent possède ses enfants, et l’enfant ne peut pas exister hors du parent. Une déclaration sur le parent et une sur l’enfant mettent la paire en place.

Utilisez la composition quand l’enfant appartient à un seul parent et disparaît avec lui. Utilisez un champ référence quand la cible existe par elle-même (voir Références et liens entrants).

  • Les deux moitiés. Le parent déclare une entrée children, et l’enfant déclare member_of en retour. Facet refuse une paire à sens unique.
  • Même domaine, nom court. Un doctype enfant vit dans le même domaine que son parent, et son nom s’écrit sans le préfixe du domaine.

La racine est l’enregistrement que les utilisateurs créent et suppriment. Déclarez-le avec aggregate_root: true.

Chaque entrée porte le nom de la relation, par exemple tasks. Ce nom devient le segment de route pour les créations imbriquées.

"children": {
"tasks": { "doctype": "Task", "collection": true }
}

collection: true porte plusieurs enfants. Une relation à enfant unique l’omet.

"member_of": "Project",
"aggregate_root": false

N’ajoutez pas sur l’enfant un champ référence qui pointerait vers le parent. Facet gère lui-même le lien vers le parent.

Envoyez un corps en deux blocsà : $content pour les champs du parent et $children pour les enfants imbriqués. Facet crée tout dans une seule transaction. Si un enfant échoue à la validation, rien n’est écrit.

Règle Effet
Suppression en cascade Supprimer le parent supprime ses enfants.
Verrouillage couplé Une écriture sur un enfant verrouille le parent, pour que l’agrégat reste cohérent.
Création directe refusée Un enfant créé hors de son parent répond 422. Passez par la route imbriquée.
Accès hérité Une permission sur le parent couvre l’enfant, car le chemin de l’enfant prolonge celui du parent.
Propagation des événements Un changement d’enfant notifie le parent, et les champs calculés du parent se mettent à jour.

Les deux définitions ci-dessous déclarent une racine projects.Project et son enfant projects.Task.

{
"domain": "projects",
"doctype": "Project",
"aggregate_root": true,
"schema_version": 1,
"display_name": "{{ name }}",
"fields": {
"name": { "type": "string", "required": true, "filters": ["equality", "text_search"] },
"status": { "type": "enum", "default": "planned", "filters": ["equality"],
"values": [ { "key": "planned", "label": "Planned" }, { "key": "active", "label": "Active" } ] }
},
"children": {
"tasks": { "doctype": "Task", "collection": true }
}
}
{
"domain": "projects",
"doctype": "Task",
"aggregate_root": false,
"member_of": "Project",
"schema_version": 1,
"display_name": "{{ title }}",
"fields": {
"title": { "type": "string", "required": true, "filters": ["equality", "text_search"] },
"done": { "type": "boolean", "default": false }
}
}

Un appel crée le projet et sa première tâcheà :

Fenêtre de terminal
curl -k -X POST "https://facet.localhost:3443/Api/projects/Project" \
-H "Authorization: Bearer $FACET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"$content": { "name": "Apollo", "status": "active" },
"$children": {
"tasks": [ { "title": "Cut the keyway" } ]
}
}'

-k ignore la vérification du certificat de l’adresse de développement locale. La réponse porte le parent et les enfants créés. La tâche reçoit done: false de sa valeur par défaut.

Une moitié de la composition manque. Ajoutez le member_of sur l’enfant ou l’entrée children sur le parent, puis publiez à nouveau.

Les enfants se créent via le parent. Utilisez la route imbriquée sur le document parent, ou le corps en deux blocs montré plus haut.

L’enfant apparaît sous un autre parent après une copie

Section intitulée « L’enfant apparaît sous un autre parent après une copie »

C’est impossible. Une copie rattache l’enfant au parent copié, jamais à l’original.

Exact. La cascade ne va que vers le basà : supprimer le parent retire ses enfants.