SPB Git

Repository Public

AUDIT.md 7.7 KB

# 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 : id uuid, 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œuds mention et 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.

Files main
Menu

Theme