Repository Public
1<!--2SP Notes (macOS)3File: docs/AUDIT.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Audit de note.spboucher.ai (v2.0.0, `main` @ 2c18f85, 2026-11-18)89Source lue : `M4M64c:~/apps/note-spboucher-ai` (322 fichiers sous `src/`, schéma `src/db/schema.ts`, 96 routes `route.ts`, docs `docs/*.md`).10Ce 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.1112## 1. Architecture1314| Couche | Réalité |15|---|---|16| Frontend | Next.js 16.4 (App Router), React 19, Tailwind 4, Radix, TanStack Query ; PWA (service worker limité aux assets) |17| Éditeur | Tiptap 3 (ProseMirror) ; document stocké en **JSON ProseMirror** (`pages.content`, jsonb) — jamais en HTML ni en Markdown |18| Backend | Route handlers Next (`src/app/api/**/route.ts`) enveloppés par `handler()` : session, origine, idempotence (`Idempotency-Key`), journal |19| Données | PostgreSQL 17 + pgvector ; Drizzle ; file de travaux pg-boss (`note-worker`) : indexation, sauvegardes, agents, imports |20| Hébergement | M4M64c:8480 (PM2 `note-web`, `note-worker`), exposé par le MacLustr Tunnel (Caddy BHS64 → WireGuard) |2122## 2. Modèle de données (ce qui concerne les notes)2324- `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).25- `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).26- `tags` + `page_tags` : étiquettes en minuscules, 20 au plus par page.27- `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.28- `links` / `knowledge_edges` : liens entre pages, dérivés du contenu (nœuds `mention` et liens `/p/<id>`).29- `tasks`, `databases*`, `references`, `experiments`, `ai_*`, `chunks` / `embeddings` : fonctions du site sans équivalent demandé dans le cahier des charges natif (voir §6).3031**Il n'existe pas de table « dossiers » ni de champ « favori »** : l'organisation se fait par arborescence de pages, sections, épingle (`pinned`), archive, étiquettes.3233## 3. Format des documents3435Nœ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`.36Nœuds en ligne : `text`, `hardBreak`, `mention` (lien stable vers une page : `id`, `label`), `inlineMath`, `footnoteRef`.37Marques : `bold`, `italic`, `underline`, `strike`, `code`, `link`, `highlight`, `subscript`, `superscript`.38Chaque 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`).39Validation serveur (`assertDoc`) : 8 Mo, profondeur 60, 200 000 nœuds, URL `javascript:` / `data:text/html` refusées.4041## 4. API utilisées par un client de notes4243| Besoin | Route |44|---|---|45| Liste / arbre | `GET /api/tree`, `GET /api/pages?view=recent|pinned|trash|archived|section:…|children:…` |46| Lire / créer / modifier | `GET /api/pages/:id`, `POST /api/pages`, `PATCH /api/pages/:id` (`baseVersion` → `409 conflict` avec la copie serveur) |47| Conflit | `POST /api/pages/:id/resolve` (`mine` / `theirs` / `both` — les deux copies restent dans l'historique) |48| Corbeille | `DELETE /api/pages/:id`, `POST …?action=restore`, `DELETE …?purge=1` (passkey < 5 min), `/api/trash` |49| Dupliquer | `POST /api/pages/:id?action=duplicate` |50| Historique | `GET /api/pages/:id/versions[?v=n]`, `POST` (restaurer) |51| Étiquettes | `GET /api/tags`, `GET/PUT /api/pages/:id/tags` |52| Pièces jointes | `POST/GET/DELETE /api/attachments`, `GET /api/files/:id` |53| Recherche | `GET /api/search` (rapide par titre, ou hybride plein texte + vecteurs) |54| Capture | `POST /api/capture`, `/api/inbox` (tri réversible) |55| 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` |56| Export / import | `GET /api/export?format=md|zip|json|csv|pdf|html|bib`, `POST /api/import` |57| Compte | `/api/auth/*` (passkeys, sessions, step-up), `/api/settings` |5859**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.6061## 5. Authentification et sécurité (v2)6263Passkeys 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.6465## 6. Fonctions du site hors du périmètre natif (restent sur le web)6667Bases 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.6869## 7. Ajouts au backend pour les clients natifs (branche `native-sync`, tous additifs)7071| Ajout | Raison |72|---|---|73| 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. |74| `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. |75| `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. |76| `GET /.well-known/apple-app-site-association` | Autorise les applications natives à utiliser les passkeys du domaine. |77| Libellé d'appareil « SP Notes · Mac » | Lisibilité de la liste des sessions. |7879Rien n'est retiré ni modifié dans le comportement du site ; retour arrière : `drizzle/0002_native_sync.down.sql`.80