Aller au contenu

Carnets : modèle de données et migration mono → multi-carnets

Cette page explique pourquoi Kirexo organise les articles d'un utilisateur en carnets, comment ce modèle est passé d'un seul carnet par compte à plusieurs, et quels choix de données sous-tendent l'archivage et le devenir d'un article dont le carnet disparaît. Pour la référence du dashboard qui affiche le nom du carnet, voir Espaces utilisateur et admin ; pour la création d'un compte et de son premier carnet, voir Créer un compte utilisateur en ligne de commande.

D'un carnet unique à plusieurs

À l'origine, chaque compte portait un simple champ texte : le nom de son carnet d'écriture, stocké directement sur l'entité User. C'était suffisant tant qu'un utilisateur n'avait qu'un seul espace où déposer ses articles — mais ce n'était qu'une étiquette, sans existence propre : impossible d'en avoir plusieurs, d'en archiver un, ou de regrouper des articles autrement que par auteur.

Kirexo est passé à un modèle multi-carnets : le carnet devient une entité à part entière, Notebook (src/Entity/Notebook.php), et un utilisateur peut en posséder plusieurs. Un carnet regroupe des articles pour la frise chronologique de l'espace utilisateur, porte un nom et un sous-titre (tagline) optionnel, et appartient à un unique propriétaire.

La relation est bidirectionnelle :

  • Notebook.owner — ManyToOne vers User, non nul et immuable : le propriétaire est fixé au constructeur et n'a pas de setter. Un carnet ne change jamais de main.
  • User.notebooks — la collection inverse (OneToMany, mappedBy: 'owner'), ordonnée par createdAt croissant grâce à #[ORM\OrderBy]. Cet ordre déterministe est ce qui permet à user.notebooks|first de désigner toujours le carnet le plus ancien (le dashboard s'appuie dessus).

Le nom par défaut d'un carnet (« Le carnet de \<prénom> ») est une préoccupation du carnet, pas de l'utilisateur : la logique vit dans Notebook::defaultName(). Tout nouveau compte reçoit un carnet à sa création — que ce soit via la commande app:user:create ou via les fixtures — de sorte qu'un utilisateur possède toujours au moins un carnet.

L'archivage tient dans un seul champ

Un carnet peut être actif ou archivé. Plutôt qu'un enum d'état ou un booléen, Kirexo porte cette distinction par un unique champ nullable, archivedAt :

  • null → le carnet est actif ;
  • une date → le carnet est archivé, et l'on sait quand.

Ce choix donne l'information d'état et sa date en une seule colonne, sans redondance possible entre « est archivé » et « date d'archivage ». Le helper métier Notebook::isArchived() dérive le booléen (null !== $this->archivedAt) pour éviter de disséminer un test archivedAt is not null dans les templates. Le repository expose les deux vues correspondantes — findActiveByOwner() (les archivedAt IS NULL, du plus ancien au plus récent) et findArchivedByOwner() (les archivedAt IS NOT NULL, du plus récemment archivé au plus ancien) — qui alimenteront la frise et la vue « archives ».

C'est le même parti pris que pour la date d'entrée en corbeille d'un article (trashedAt) : un état de cycle de vie porté par un horodatage nullable plutôt que par un drapeau séparé.

Tout article appartient à un carnet, et y reste

Un Article est rattaché à un carnet par une relation notebook (ManyToOne, inverse de Notebook::$articles). Elle est obligatoire : JoinColumn(nullable: false, onDelete: 'CASCADE') sur Article::$notebook. Un article reçoit son carnet dès sa création — le controller de création (src/Controller/AppArticleNewController.php) lui affecte le carnet source de la requête, celui dont le bouton « Écrire » a été cliqué, et jamais un carnet par défaut déduit de l'auteur. Les fixtures comme les migrations rattachent, elles aussi, tout article à un carnet.

La question que cette contrainte tranche est : que devient un article si son carnet est supprimé ? Deux réponses étaient possibles.

  • ON DELETE SET NULL — supprimer le carnet détache ses articles, qui deviennent orphelins (notebook_id remis à null) au lieu d'être détruits. C'est le choix qu'avait fait le modèle multi-carnets à son introduction, pour ne pas perdre de travail.
  • ON DELETE CASCADE — supprimer le carnet supprime aussi ses articles et, en cascade, leurs révisions.

C'est le second qui a été retenu, et le renversement mérite d'être expliqué plutôt que constaté. Un article orphelin est un état qu'aucun écran ne sait montrer : il n'appartient à aucune frise, ne se range dans aucune archive, et n'apparaît que dans les requêtes qui pensent à le chercher. Autrement dit, le « filet » ne rattrapait rien — il produisait des données invisibles, à la charge d'un futur écran qui n'a jamais eu de raison d'être écrit.

Ce que la cascade suppose, en échange, c'est que la suppression d'un carnet ne puisse pas être un geste distrait. C'est la fonction de la précondition d'état portée par src/Controller/AppNotebookDeleteController.php : on ne supprime qu'un carnet déjà archivé. L'archivage devient le point d'arrêt réversible — il masque sans rien détruire — et la suppression, un second geste explicite, sur un carnet que l'auteur a déjà mis de côté. Le message rendu après l'opération nomme d'ailleurs sa portée sans détour : « Carnet supprimé, ainsi que ses articles ».

La direction de la contrainte suit donc la dépendance métier telle qu'elle est vécue : une révision n'a pas de sens sans son article (voir Contenu de travail, révisions et corbeille), et un article n'en a pas davantage sans son carnet.

Des identifiants UUIDv7 générés au constructeur

Comme toutes les entités de Kirexo, Notebook porte une clé primaire UUIDv7 générée au constructeur ($this->id = $id ?? Uuid::v7()), jamais un entier auto-incrémenté ni un #[ORM\GeneratedValue]. L'identifiant existe donc avant tout passage en base : on peut construire un carnet, l'associer à son propriétaire et le manipuler en mémoire sans dépendre d'un flush.

Le choix d'UUIDv7 plutôt qu'UUIDv4 n'est pas anodin : l'UUIDv7 est ordonnable dans le temps (son préfixe encode l'instant de génération), ce qui donne des insertions ordonnées côté index et évite la fragmentation d'un identifiant purement aléatoire, tout en conservant le bénéfice anti-énumération d'un identifiant non devinable. Ce même invariant vaut jusque dans la migration de données : les carnets créés lors du backfill reçoivent un Uuid::v7() généré en PHP, jamais un gen_random_uuid() PostgreSQL (qui produirait de l'UUIDv4).

La migration mono → multi préserve les données

Le passage de l'ancien champ texte à l'entité Notebook s'accompagne d'une migration de données, et non d'un simple changement de schéma. Supprimer d'emblée l'ancienne colonne aurait perdu le nom que chaque utilisateur avait choisi, et laissé ses articles sans carnet. La migration procède donc en trois temps, dans une seule transaction (PostgreSQL est transactionnel sur le DDL) :

  1. lecture de l'état existant — le contenu de l'ancienne colonne est lu avant toute modification de schéma, tant que la table le porte encore ;
  2. création du nouveau schéma puis backfill — la table notebook et la colonne article.notebook_id (nullable) sont créées, puis, pour chaque utilisateur, un carnet est inséré (nom = ancienne valeur, id UUIDv7 généré en PHP) et tous ses articles y sont rattachés ;
  3. finalisation — la clé étrangère ON DELETE SET NULL et son index sont posés, puis l'ancienne colonne est retirée.

À l'issue, chaque compte possède exactement un carnet reprenant son ancien nom, et aucun article n'est laissé sans carnet. Sur une base fraîche (en intégration continue, migrations jouées avant les fixtures), la boucle de backfill itère sur zéro utilisateur : c'est un no-op sûr, le schéma est simplement créé dans son état cible. Par convention projet, cette migration n'a pas de méthode down() : la réversibilité passe par la restauration d'un dump, pas par un retour arrière automatique.

C'est cette migration qui a introduit article.notebook_id en colonne nullable, avec la clé étrangère ON DELETE SET NULL de l'époque. Une migration ultérieure l'a passée en NOT NULL et a remplacé la clé étrangère par ON DELETE CASCADE — la bascule décrite plus haut. L'ordre compte : on ne peut resserrer une colonne en NOT NULL qu'une fois le backfill garanti, ce qui est exactement pourquoi les deux étapes n'ont pas pu être une seule.

Voir aussi