Momento/_bmad-output/implementation-artifacts/spec-improve-note-graph-relationships.md

title, type, created, status, baseline_commit, context

title	type	created	status	baseline_commit	context
Improve Note Graph Relationships	feature	2026-05-23T08:25:00Z	done	ca0637cc6e

Intent

Problem: La vue en graphe (NoteGraphView) ne tire parti que de balayages de texte rudimentaires (mentions de titre, tags partagés et similarité Jaccard en mémoire qui est désactivée au-delà de 500 notes) pour tracer les liaisons. Elle ignore totalement :

1. Les liaisons explicites manuelles créées par l'utilisateur via des WikiLinks ([[Note]]) et enregistrées dans la table NoteLink de la base de données.
2. Les connexions sémantiques riches générées en arrière-plan par l'IA ("Memory Echo") et enregistrées dans la table MemoryEchoInsight de la base de données. Cela donne à la vue en graphe un aspect incomplet et décousu, limitant grandement la sérendipité et la découverte de connaissances.

Approach:

1. Modifier la route API /api/graph pour requêter et fusionner les liaisons manuelles (NoteLink) et les connexions sémantiques saines non rejetées (MemoryEchoInsight avec dismissed = false).
2. Introduire des types de liaisons explicites (explicit_link et semantic_echo) dans le flux de données de l'API.
3. Mettre à jour le composant de rendu React <NoteGraphView /> pour styliser et différencier visuellement ces relations clés avec des couleurs HSL premium, des épaisseurs de trait adaptées et des motifs (pleins vs. pointillés) pour enrichir l'expérience utilisateur et clarifier la structure du graphe.

Boundaries & Constraints

Always:

• Filtrer rigoureusement toutes les requêtes Prisma par userId pour garantir l'étanchéité des données utilisateur.
• Exclure toutes les liaisons (sources ou cibles) pointant vers des notes archivées ou envoyées à la corbeille (trashedAt !== null).
• Exclure les connexions sémantiques marquées comme rejetées (dismissed: true).
• Assurer un fort contraste visuel sur le graphe en harmonie avec la charte graphique premium existante (pas de couleurs agressives non maîtrisées).

Ask First:

• Faut-il plafonner le nombre total de liens sémantiques ou Jaccard affichés simultanément pour éviter de surcharger visuellement les graphes de grande taille (au-delà de 200 notes) ?

Never:

• Modifier la structure de la base de données Prisma (pas de changement de schéma).
• Lancer de commande destructive sur la base de données (prisma db push --force-reset ou équivalent).
• Supprimer ou désactiver les liaisons textuelles existantes (title_mention, shared_label, jaccard), qui restent d'excellents compléments de découverte.

I/O & Edge-Case Matrix

Scenario	Input / State	Expected Output / Behavior	Error Handling
HAPPY_PATH	L'utilisateur possède des notes connectées par WikiLinks et des Memory Echo Insights	L'API /api/graph retourne un tableau fusionné contenant des arêtes de types explicit_link, semantic_echo, title_mention, etc.	N/A
EMPTY_STATE	Aucune liaison, aucune note	L'API retourne { nodes: [], edges: [], clusters: [] } de manière propre sans planter.	Retourne des tableaux vides de manière sécurisée
TRASHED_NOTES	Des liaisons (NoteLink ou MemoryEchoInsight) pointent vers des notes supprimées	Les arêtes correspondantes sont filtrées et exclues du graphe final.	Filtrage en amont lors de la construction des listes
STUB_LINKS	Des wikilinks pointent vers des notes inexistantes (stubs)	Filtrage des arêtes orphelines (seuls les couples de notes existantes et valides sont renvoyés).	Ignorer l'arête si l'ID source ou cible n'est pas dans le set des notes chargées

Code Map

• memento-note/app/api/graph/route.ts -- Route API GET principale assemblant la liste des nœuds, des arêtes et des clusters de carnets.
• memento-note/components/note-graph-view.tsx -- Composant de rendu 2D interactif utilisant react-force-graph-2d pour dessiner les arêtes et les groupes.
• memento-note/prisma/schema.prisma -- Fichier de schéma Prisma contenant les définitions des tables NoteLink et MemoryEchoInsight.

Tasks & Acceptance

Execution:

• memento-note/app/api/graph/route.ts -- Modifier la route pour interroger en parallèle prisma.noteLink et prisma.memoryEchoInsight, filtrer les éléments invalides/corrompus/supprimés, et les injecter avec les types explicit_link et semantic_echo.
• memento-note/components/note-graph-view.tsx -- Enrichir la logique de mappage des arêtes du graphe pour attribuer des styles visuels premium à chaque type de lien (WikiLinks en vert émeraude épais et plein, Échos sémantiques IA en violet pointillés, etc.).
• memento-note/components/note-graph-view.tsx -- Rendre la légende des carnets (clusters) interactive : ajouter un état selectedNotebookId pour filtrer à la volée les nœuds et arêtes du graphe. Styliser les boutons actifs/inactifs de manière premium avec des micro-animations.
• memento-note/components/note-graph-view.tsx -- Afficher le nom du carnet dans le panneau latéral de détail de la note sous forme de tag interactif cliquable pour isoler instantanément le carnet sélectionné.

Acceptance Criteria:

• Given une note A contenant un WikiLink vers une note B (NoteLink enregistré) et une note C sémantiquement proche de la note A (MemoryEchoInsight enregistré)
• When l'utilisateur charge la vue en graphe
• Then l'API renvoie les relations avec les types explicit_link et semantic_echo
• And le visualiseur dessine le lien A-B en trait vert plein et le lien A-C en trait violet pointillé.

Design Notes

Configuration Visuelle des Liens dans note-graph-view.tsx

Nous utiliserons les associations de couleurs et d'épaisseurs suivantes pour offrir une lisibilité optimale sur fond clair/sombre :

// Exemple de configuration stylistique
const LINK_STYLES = {
  explicit_link: { color: '#10b981', width: 2.2, dash: false },  // Vert émeraude (WikiLink manuel)
  semantic_echo: { color: '#a78bfa', width: 1.8, dash: true },   // Violet pastel (Écho sémantique IA)
  title_mention: { color: '#f59e0b', width: 1.6, dash: false },  // Orange ambré (Mention de titre automatique)
  shared_label:  { color: '#3b82f6', width: 1.2, dash: false },  // Bleu vif (Tags partagés)
  jaccard:       { color: '#cbd5e1', width: 0.8, dash: false }   // Gris clair (Similarité sémantique simple)
}

Pour les pointillés (dash) dans react-force-graph-2d, nous adapterons l'objet du graphe ou appliquerons la configuration de rendu des lignes Canvas via l'API Native si nécessaire, ou plus simplement en les configurant élégamment dans le dessin.

Verification

Commands:

• npx tsc --noEmit -- Vérification de l'absence totale d'erreurs de typage TypeScript dans le projet après modification.

Suggested Review Order

Backend API & Relationships Integration

• Requête Prisma sécurisée pour charger en parallèle les liaisons WikiLinks (NoteLink) et les échos sémantiques IA (MemoryEchoInsight). route.ts:66

• Priorisation des liaisons qualitatives sur les mentions textuelles et assemblage des arêtes du graphe. route.ts:161

Frontend Visualizations & Legend

• Mappage des arêtes vers les nouvelles couleurs de liaison et gestion de la propriété de pointillés. note-graph-view.tsx:112

• Configuration de la propriété de rendu en pointillés linkLineDash sur le composant ForceGraph2D. note-graph-view.tsx:278

• Rendu du panneau de légende des liaisons dans le coin inférieur gauche pour une expérience utilisateur premium. note-graph-view.tsx:340

Interactive Filtering & Notebook Navigation

• Boutons de légende interactifs pour isoler ou réinitialiser le filtre par carnet à la volée. note-graph-view.tsx:342

• Tag cliquable dans le panneau latéral de détails pour isoler instantanément le carnet associé. note-graph-view.tsx:421