ADR 0057 – Journal de suivi d’un nœud

Statut : Accepté (2026-10-16, mode autonome)

Item 27 du backlog (jalon 3, vague 2 du document d’idées), pris par le fil « Documentation, puis capture en une ligne ». L’idée vient de Todoist et d’Alfresco : des notes horodatées sous la fiche (« appelé le fournisseur, rappel lundi »), distinctes du corps. C’est idéal pour les courriers et les tâches qui traînent, et cela s’ajoute à l’historique des modifications.

Contexte

Le corps d’un nœud est un document : on le réécrit, on le structure. Un suivi est une suite d’entrées datées, qu’on ajoute sans retoucher les précédentes. L’historique (node_event) dit ce qui a changé, pas ce qu’on a fait ou appris. Le journal concerne tous les nœuds : il appartient au moteur, sans définition dans config/.

Décision

Données

• Table node_journal (migration V13) : id, node_id (suppression en cascade à la purge du nœud), text (1 à 10 000 caractères, texte brut), created_at, updated_at (modifiée), deleted_at (retirée, récupérable), actor.
• Colonne node.journal_text : le texte des entrées non retirées, du plus ancien au plus récent, recalculé par le service à chaque écriture. Elle entre dans l’index plein texte avec le poids du corps (C) : la recherche simple, Ctrl+K et query.text des vues retrouvent « fournisseur » écrit dans un suivi.
• Chaque écriture enregistre un événement dans la même transaction : journal.added (entryId, text), journal.updated (entryId, before, after), journal.removed et journal.restored (entryId, text). Elle met aussi à jour la date de modification du nœud.
• Connecteurs (ADR 0047) : une note de suivi n’est pas une modification locale ; elle n’empêche pas d’appliquer la version reçue suivante (aucun champ synchronisé n’est touché).
• Export (ADR 0018) : clé journal de l’en-tête de chaque nœud, liste { createdAt, updatedAt?, text } du plus ancien au plus récent, entrées retirées exclues. Clé ajoutée, format inchangé (version 2) ; l’auteur n’est pas exporté, comme celui des événements.

API

• GET /api/nodes/{id}/journal : entrées non retirées, des plus récentes aux plus anciennes.
• POST /api/nodes/{id}/journal { text } : ajoute une entrée datée de maintenant (201).
• PUT /api/nodes/{id}/journal/{entryId} { text } : corrige une entrée (sa date reste, « modifiée » s’affiche).
• DELETE /api/nodes/{id}/journal/{entryId} : retire une entrée ; POST …/{entryId}/restore la remet (Annuler, ADR 0049).
• Un nœud dans la corbeille : 404, comme ses autres écritures.

Interface

• Sous l’éditeur de la fiche, une section « Journal » : un champ (« Ajouter une note de suivi… »), Ctrl+Entrée ou « Ajouter », puis les entrées, des plus récentes aux plus anciennes, avec leur date (« aujourd’hui 14:05 », « 12 oct. 09:30 »). Chaque entrée se modifie ou se retire, avec « Annuler » dans l’annonce.
• L’historique du panneau de contexte libelle les événements (« note de suivi ajoutée »…).
• Le champ garde le focus pendant l’envoi (plusieurs notes à la suite) ; « Annuler » remet l’entrée même après avoir quitté la fiche. Un brouillon non envoyé n’est pas gardé si l’on quitte la fiche.
• Texte brut, retours à la ligne gardés, sans Markdown : une note de suivi s’écrit vite et ne se met pas en forme.

Alternatives écartées

• Entrées dans le corps (liste datée en Markdown) : se mélange au document, la date n’est qu’un texte, rien ne les distingue pour la recherche ou une vue.
• Entrées comme nœuds enfants : encombrent l’arbre et les vues pour quelques mots.
• Seulement des événements node_event : le journal des modifications n’est pas modifiable, et une note de suivi doit pouvoir se corriger.

Conséquences

• Dernière entrée dans les vues (« dernier suivi »), mentions et rappels : reportés.