Audit de note.spboucher.ai (v2.0.0, main @ 2c18f85, 2026-11-18)
Source lue : M4M64c:~/apps/note-spboucher-ai (322 fichiers sous src/, schéma src/db/schema.ts, 96 routes route.ts, docs docs/*.md).
Ce document décrit ce qui existe réellement côté web ; la colonne « natif » de FEATURE_MATRIX.md dit ce que l'application macOS en fait.
1. Architecture
| Couche | Réalité |
|---|---|
| Frontend | Next.js 16.4 (App Router), React 19, Tailwind 4, Radix, TanStack Query ; PWA (service worker limité aux assets) |
| Éditeur | Tiptap 3 (ProseMirror) ; document stocké en JSON ProseMirror (pages.content, jsonb) — jamais en HTML ni en Markdown |
| Backend | Route handlers Next (src/app/api/**/route.ts) enveloppés par handler() : session, origine, idempotence (Idempotency-Key), journal |
| Données | PostgreSQL 17 + pgvector ; Drizzle ; file de travaux pg-boss (note-worker) : indexation, sauvegardes, agents, imports |
| Hébergement | M4M64c:8480 (PM2 note-web, note-worker), exposé par le MacLustr Tunnel (Caddy BHS64 → WireGuard) |
2. Modèle de données (ce qui concerne les notes)
pages:iduuid,parent_id(arborescence),database_id(page-ligne d'une base),type(page | database | research | dashboard),section(notes | documents | databases | projects | research),title,icon,cover,content(doc ProseMirror),plain_text,properties(jsonb libre),position,pinned,archived,version(concurrence optimiste),word_count, dates,deleted_at(corbeille),inbox_at/capture_kind(boîte de capture).page_versions: instantanés (au plus 200 par page ; un instantané à la première modification, puis toutes les 20 versions ou 10 minutes ; les deux côtés d'un conflit sont toujours conservés).tags+page_tags: étiquettes en minuscules, 20 au plus par page.attachments: fichiers adressés par contenu (sha256), servis par/api/files/<id>après authentification, 200 Mo au plus, types exécutables / HTML refusés.links/knowledge_edges: liens entre pages, dérivés du contenu (nœudsmentionet liens/p/<id>).tasks,databases*,references,experiments,ai_*,chunks/embeddings: fonctions du site sans équivalent demandé dans le cahier des charges natif (voir §6).
Il n'existe pas de table « dossiers » ni de champ « favori » : l'organisation se fait par arborescence de pages, sections, épingle (pinned), archive, étiquettes.
3. Format des documents
Nœuds de bloc : paragraph, heading (niveaux 1 à 3 seulement : StarterKit.configure({ heading: { levels: [1, 2, 3] } }) — un niveau 4–6 n'est pas un nœud valide pour l'éditeur web), blockquote, codeBlock (langage, lowlight), bulletList / orderedList / listItem, taskList / taskItem (checked), table / tableRow / tableHeader / tableCell, horizontalRule, image, fileBlock (pièce jointe), blockMath (LaTeX), callout (kind, icon), details / detailsSummary / detailsContent, aiBlock (provenance IA), youtube, footnote.
Nœuds en ligne : text, hardBreak, mention (lien stable vers une page : id, label), inlineMath, footnoteRef.
Marques : bold, italic, underline, strike, code, link, highlight, subscript, superscript.
Chaque bloc porte un identifiant stable attrs.id (10 caractères) utilisé par la recherche et les citations ; le serveur en attribue aux blocs qui n'en ont pas (ensureBlockIds).
Validation serveur (assertDoc) : 8 Mo, profondeur 60, 200 000 nœuds, URL javascript: / data:text/html refusées.
4. API utilisées par un client de notes
| Besoin | Route |
|---|---|
| Liste / arbre | GET /api/tree, `GET /api/pages?view=recent |
| Lire / créer / modifier | GET /api/pages/:id, POST /api/pages, PATCH /api/pages/:id (baseVersion → 409 conflict avec la copie serveur) |
| Conflit | POST /api/pages/:id/resolve (mine / theirs / both — les deux copies restent dans l'historique) |
| Corbeille | DELETE /api/pages/:id, POST …?action=restore, DELETE …?purge=1 (passkey < 5 min), /api/trash |
| Dupliquer | POST /api/pages/:id?action=duplicate |
| Historique | GET /api/pages/:id/versions[?v=n], POST (restaurer) |
| Étiquettes | GET /api/tags, GET/PUT /api/pages/:id/tags |
| Pièces jointes | POST/GET/DELETE /api/attachments, GET /api/files/:id |
| Recherche | GET /api/search (rapide par titre, ou hybride plein texte + vecteurs) |
| Capture | POST /api/capture, /api/inbox (tri réversible) |
| IA | POST /api/ai/action (SSE : réécrire, corriger, traduire, résumer, développer, expliquer, listes, tâches, tableau…), POST /api/ai/chat (SSE, réponses fondées sur les notes avec citations), /api/ai/models |
| Export / import | `GET /api/export?format=md |
| Compte | /api/auth/* (passkeys, sessions, step-up), /api/settings |
Avant ce projet il n'existait aucun mécanisme de synchronisation pour un client qui garde une copie locale : le site lit et écrit en direct, avec un brouillon IndexedDB par page ouverte. D'où les ajouts du §7.
5. Authentification et sécurité (v2)
Passkeys uniquement (SimpleWebAuthn 14), RP ID note.spboucher.ai, vérification de l'utilisateur exigée ; session serveur révocable (jeton aléatoire, seul son SHA-256 est stocké), cookie __Host-note_session (inactivité 30 j, maximum 90 j), rotation à chaque step-up ; actions sensibles = passkey vérifiée depuis moins de 5 minutes ; mutations acceptées seulement avec Origin égal à l'origine configurée ; enrôlement sans session uniquement par une fenêtre ouverte en ligne de commande sur le nœud. Mono-utilisateur, pas de rôles. Détail : docs/security.md du dépôt web.
6. Fonctions du site hors du périmètre natif (restent sur le web)
Bases de données façon Notion (vues table / tableau / calendrier / galerie / chronologie, formules, relations), espace recherche (références, BibTeX, DOI, expériences), graphe de connaissances et suggestions de liens, agents à propositions, comparateur de modèles, tableau de bord, administration (travaux, indexation, audit, sauvegardes), import DOCX / PDF / Notion. L'application native les laisse intacts : elle synchronise les pages concernées sans les altérer et renvoie au site pour ces écrans.
7. Ajouts au backend pour les clients natifs (branche native-sync, tous additifs)
| Ajout | Raison |
|---|---|
Migration 0002_native_sync : colonne rev (pages, attachments), table sync_tombstones, déclencheurs |
Flux de changements exact : toute écriture, quel que soit le code qui la fait, reçoit le numéro suivant d'une séquence prise sous verrou (ordre des commits) ; une suppression définitive laisse une pierre tombale. Sans cela, mise à la corbeille, restauration et étiquettes n'étaient pas détectables (updated_at inchangé) et une purge était invisible. |
GET /api/sync?since=<rev> |
Tout ce qui a changé depuis un curseur : pages complètes, métadonnées des pièces jointes, pierres tombales, étiquettes. |
POST /api/pages et POST /api/attachments acceptent un id choisi par le client |
Création hors ligne : identifiants et liens internes stables avant l'envoi ; un renvoi ne crée jamais de doublon. |
GET /.well-known/apple-app-site-association |
Autorise les applications natives à utiliser les passkeys du domaine. |
| Libellé d'appareil « SP Notes · Mac » | Lisibilité de la liste des sessions. |
Rien n'est retiré ni modifié dans le comportement du site ; retour arrière : drizzle/0002_native_sync.down.sql.