282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
---
|
|
stepsCompleted: [1]
|
|
inputDocuments:
|
|
- _bmad-output/planning-artifacts/prd.md
|
|
- _bmad-output/planning-artifacts/prd-web-app-requirements.md
|
|
- _bmad-output/analysis/brainstorming-session-2026-01-06.md
|
|
---
|
|
|
|
# Keep - Epic Breakdown
|
|
|
|
## Overview
|
|
|
|
This document provides the complete epic and story breakdown for Keep, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
|
|
|
|
## Requirements Inventory
|
|
|
|
### Functional Requirements
|
|
|
|
FR1: L'utilisateur peut créer, lire, mettre à jour et supprimer des notes (texte ou checklist).
|
|
FR2: L'utilisateur peut épingler des notes pour les maintenir en haut de la liste.
|
|
FR3: L'utilisateur peut archiver des notes pour les masquer de la vue principale.
|
|
FR4: L'utilisateur peut joindre des images aux notes.
|
|
FR5: L'utilisateur peut réorganiser l'ordre des notes manuellement (Drag-and-drop via Muuri).
|
|
FR6: Le système analyse le contenu d'une note en temps réel ou à la sauvegarde pour identifier des concepts clés.
|
|
FR7: Le système suggère des tags (labels) pertinents basés sur l'analyse du contenu.
|
|
FR8: L'utilisateur peut accepter, modifier ou rejeter les suggestions de tags de l'IA.
|
|
FR9: L'utilisateur peut créer, modifier et supprimer ses propres tags manuellement.
|
|
FR10: L'utilisateur peut filtrer et trier ses notes par tags.
|
|
FR11: L'utilisateur peut effectuer une recherche par mots-clés exacts (titre et contenu).
|
|
FR12: L'utilisateur peut effectuer une recherche sémantique en langage naturel (recherche par sens/intention).
|
|
FR13: Le système combine les résultats de recherche exacte et sémantique dans une vue unique (Recherche Hybride).
|
|
FR14: L'utilisateur peut accéder à l'application et à ses notes sans connexion internet (Mode Offline/PWA).
|
|
FR15: Le système synchronise automatiquement les modifications locales avec le serveur une fois la connexion rétablie.
|
|
FR16: L'interface utilisateur reflète instantanément les actions de l'utilisateur (Optimistic UI).
|
|
FR17: L'administrateur peut configurer le fournisseur d'IA (ex: OpenAI, Ollama) via des variables d'environnement ou une interface dédiée.
|
|
FR18: Le système supporte plusieurs adaptateurs de modèles IA interchangeables (Vercel AI SDK).
|
|
FR19: L'utilisateur peut choisir son thème (clair/sombre) et personnaliser les couleurs des notes.
|
|
|
|
### NonFunctional Requirements
|
|
|
|
NFR1: IA Responsiveness - Auto-tagging suggestions must appear within 1.5s after typing ends (debounce).
|
|
NFR2: Search Latency - Hybrid search results displayed in < 300ms for 1000 notes.
|
|
NFR3: PWA Load Time - Interactive in < 2s on average 4G network.
|
|
NFR4: API Key Isolation - AI provider keys remain server-side; never exposed to the client.
|
|
NFR5: Local-First Privacy - Full local LLM support (Ollama) ensures no note data leaves user infrastructure.
|
|
NFR6: Data at Rest - Local PWA storage secured via standard Web Storage protocols.
|
|
NFR7: Offline Resilience - 100% data integrity for offline notes during background sync.
|
|
NFR8: Vector Integrity - Automatic, background semantic index updates on every note change.
|
|
NFR9: Portability - Minimal Docker/build footprint for execution on low-resource servers.
|
|
NFR10: Compatibility - Support for current Node.js LTS versions.
|
|
|
|
### Additional Requirements
|
|
|
|
- **Stack :** Next.js 16 (App Router), TypeScript, Vercel AI SDK.
|
|
- **Layout Engine :** Muuri v0.9.5 + web-animations-js pour le Masonry robuste.
|
|
- **Synchronization :** Utilisation de `ResizeObserver` pour notifier Muuri des changements de taille des cartes sans passer par l'état React.
|
|
- **Data Persistence :** SQLite (local) / Postgres (production) avec support vectoriel.
|
|
- **AI Abstraction :** Interface `AIProvider` pour supporter plusieurs backends (OpenAI, Ollama, etc.).
|
|
- **Brownfield Context :** Extension de l'application existante avec focus sur la migration vers Muuri et l'IA.
|
|
|
|
### FR Coverage Map
|
|
|
|
FR1: Epic 1 - Gestion de base des notes (CRUD)
|
|
FR2: Epic 5 - Épinglage des notes
|
|
FR3: Epic 5 - Archivage des notes
|
|
FR4: Epic 5 - Support des images
|
|
FR5: Epic 1 - Drag-and-drop avec Muuri
|
|
FR6: Epic 2 - Analyse IA en temps réel
|
|
FR7: Epic 2 - Suggestion de tags automatique
|
|
FR8: Epic 2 - Interaction avec les suggestions (Validation)
|
|
FR9: Epic 2 - Gestion manuelle des tags
|
|
FR10: Epic 3 - Filtrage et tri par tags
|
|
FR11: Epic 3 - Recherche par mots-clés exacts
|
|
FR12: Epic 3 - Recherche sémantique par intention
|
|
FR13: Epic 3 - Moteur de recherche hybride
|
|
FR14: Epic 4 - Support Offline complet (PWA)
|
|
FR15: Epic 4 - Synchronisation automatique
|
|
FR16: Epic 1 - Optimistic UI pour le layout
|
|
FR17: Epic 5 - Configuration des providers IA
|
|
FR18: Epic 5 - Support multi-adaptateurs IA
|
|
FR19: Epic 1 - Thèmes et personnalisation visuelle
|
|
|
|
## Epic List
|
|
|
|
## Epic 1: Fondations Robustes & Nouveau Moteur de Layout (Muuri)
|
|
Remplacer le système actuel par Muuri pour garantir une base solide, un Drag-and-drop fluide et une expérience sans chevauchement.
|
|
**FRs covered:** FR1, FR5, FR16, FR19
|
|
|
|
### Story 1.1: Mise en place de l'infrastructure Muuri
|
|
As a user,
|
|
I want my notes to be displayed in a high-performance Masonry grid,
|
|
So that my dashboard is visually organized without unnecessary gaps.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** that the `muuri` and `web-animations-js` libraries are installed.
|
|
**When** I load the main page.
|
|
**Then** existing notes automatically organize themselves into a Muuri Masonry grid.
|
|
**And** the layout dynamically adapts to window resizing.
|
|
|
|
### Story 1.2: Drag-and-drop fluide et persistant
|
|
As a user,
|
|
I want to move my notes via drag-and-drop fluidly,
|
|
So that I can visually reorganize my priorities.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** an active Muuri grid.
|
|
**When** I move a note to a new position.
|
|
**Then** other notes shift with a fluid animation (web-animations-js).
|
|
**And** the new position is saved in the database via a Server Action as soon as the move is completed.
|
|
|
|
### Story 1.3: Robustesse du Layout avec ResizeObserver
|
|
As a user,
|
|
I want my grid to reorganize as soon as a note's content changes (e.g., adding text),
|
|
So that I avoid overlapping notes.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** a note with an attached `ResizeObserver`.
|
|
**When** a note's height changes (text added, image loaded).
|
|
**Then** the `ResizeObserver` notifies the Muuri instance.
|
|
**And** the grid calls `refreshItems()` and `layout()` to eliminate any overlap instantly.
|
|
|
|
## Epic 2: Assistant d'Organisation Intelligent (Auto-tagging)
|
|
Intégrer le Vercel AI SDK et mettre en place l'analyse en temps réel pour suggérer des tags automatiquement.
|
|
**FRs covered:** FR6, FR7, FR8, FR9
|
|
|
|
### Story 2.1: Infrastructure IA & Abstraction Provider
|
|
As an administrator,
|
|
I want to configure my AI provider (OpenAI or Ollama) centrally,
|
|
So that the application can use artificial intelligence securely.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** an `AIProvider` interface and the `Vercel AI SDK` installed.
|
|
**When** I provide my API key or Ollama instance URL in environment variables.
|
|
**Then** the system initializes the appropriate driver.
|
|
**And** no API keys are exposed to the client-side.
|
|
|
|
### Story 2.2: Analyse et Suggestions de Tags en temps réel
|
|
As a user,
|
|
I want to see tag suggestions appear as I write my note,
|
|
So that I can organize my thoughts without manual effort.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** an open note editor.
|
|
**When** I stop typing for more than 1.5 seconds (debounce).
|
|
**Then** the system sends the content to the AI for analysis.
|
|
**And** tag suggestions (ghost tags) are displayed discreetly under the note.
|
|
|
|
### Story 2.3: Validation des Suggestions par l'Utilisateur
|
|
As a user,
|
|
I want to be able to accept or reject a suggestion with a single click,
|
|
So that I maintain full control over my organization.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** a list of tags suggested by the AI.
|
|
**When** I click on a suggested tag.
|
|
**Then** it becomes a permanent tag for the note.
|
|
**And** if I ignore or delete it, it disappears from the current view.
|
|
|
|
## Epic 3: Moteur de Recherche Hybride & Sémantique
|
|
Déployer la recherche sémantique et hybride pour retrouver des notes par intention plutôt que par simples mots-clés.
|
|
**FRs covered:** FR10, FR11, FR12, FR13
|
|
|
|
### Story 3.1: Indexation Vectorielle Automatique
|
|
As a system,
|
|
I want to generate and store vector embeddings for every note change,
|
|
So that the notes are searchable by meaning.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** a new or updated note.
|
|
**When** the note is saved.
|
|
**Then** the system generates a vector embedding via the AI provider.
|
|
**And** the embedding is stored in the vector-enabled database (SQLite/Postgres).
|
|
|
|
### Story 3.2: Recherche Sémantique par Intention
|
|
As a user,
|
|
I want to search for notes using natural language concepts,
|
|
So that I can find information even if I don't remember the exact words.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** the search bar.
|
|
**When** I enter a conceptual query (e.g., "cooking ideas").
|
|
**Then** the system performs a cosine similarity search on the vector embeddings.
|
|
**And** relevant notes are displayed even if they don't contain the exact query words.
|
|
|
|
### Story 3.3: Vue de Recherche Hybride
|
|
As a user,
|
|
I want to see combined results from exact keyword matching and semantic search,
|
|
So that I get the most comprehensive results possible.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** a search query.
|
|
**When** the search is executed.
|
|
**Then** the system merges results from SQL `LIKE` queries and Vector similarity.
|
|
**And** results are ranked by a combination of exact match and semantic relevance.
|
|
|
|
## Epic 4: Mobilité & Résilience (PWA & Offline)
|
|
Transformer l'application en PWA complète avec support offline et synchronisation automatique.
|
|
**FRs covered:** FR14, FR15
|
|
|
|
### Story 4.1: Installation PWA et Manifeste
|
|
As a user,
|
|
I want to install Keep on my device (mobile or desktop),
|
|
So that I can access it like a native application.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** the web application.
|
|
**When** I access it via a compatible browser.
|
|
**Then** I am prompted to "Add to Home Screen".
|
|
**And** the app opens in a standalone window with its own icon.
|
|
|
|
### Story 4.2: Stockage Local et Mode Offline
|
|
As a user,
|
|
I want to view and edit my notes even without an internet connection,
|
|
So that I can remain productive in any environment.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** no active internet connection.
|
|
**When** I open the app.
|
|
**Then** the Service Worker serves the cached UI and notes from IndexedDB.
|
|
**And** I can create or edit notes which are queued for sync.
|
|
|
|
### Story 4.3: Synchronisation de Fond (Background Sync)
|
|
As a user,
|
|
I want my offline changes to be saved to the server automatically when I'm back online,
|
|
So that my data is consistent across all my devices.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** pending offline changes.
|
|
**When** an internet connection is restored.
|
|
**Then** the background sync process pushes all queued actions to the server.
|
|
**And** any conflicts are resolved (last-write-wins by default).
|
|
|
|
## Epic 5: Administration & Personnalisation (Self-Hosting Pro)
|
|
Finaliser les outils de configuration (OpenAI/Ollama) et les fonctionnalités avancées (Images, Archive).
|
|
**FRs covered:** FR2, FR3, FR4, FR17, FR18
|
|
|
|
### Story 5.1: Interface de Configuration des Modèles
|
|
As an administrator,
|
|
I want a dedicated UI to switch between AI models and providers,
|
|
So that I don't have to restart the server for configuration changes.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** the settings page.
|
|
**When** I select a new provider (e.g., switching from OpenAI to Ollama).
|
|
**Then** the application updates its internal AI driver state.
|
|
**And** the change is persisted in the database configuration table.
|
|
|
|
### Story 5.2: Gestion Avancée (Épinglage & Archivage)
|
|
As a user,
|
|
I want to pin important notes and archive old ones,
|
|
So that I can keep my main dashboard clean and focused.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** a note.
|
|
**When** I click the "Pin" icon.
|
|
**Then** the note moves to the "Pinned" section at the top.
|
|
**When** I click "Archive".
|
|
**Then** the note is moved to the Archive view and removed from the main grid.
|
|
|
|
### Story 5.3: Support Multimédia et Images
|
|
As a user,
|
|
I want to attach images to my notes,
|
|
So that I can capture visual information along with my text.
|
|
|
|
**Acceptance Criteria:**
|
|
**Given** the note editor.
|
|
**When** I upload or drag an image into the note.
|
|
**Then** the image is stored (locally or cloud) and displayed within the note card.
|
|
**And** Muuri recalculates the layout once the image is fully loaded.
|
|
|
|
### Epic 3: Moteur de Recherche Hybride & Sémantique
|
|
Déployer la recherche sémantique et hybride pour retrouver des notes par intention plutôt que par simples mots-clés.
|
|
**FRs covered:** FR10, FR11, FR12, FR13
|
|
|
|
### Epic 4: Mobilité & Résilience (PWA & Offline)
|
|
Transformer l'application en PWA complète avec support offline et synchronisation automatique.
|
|
**FRs covered:** FR14, FR15
|
|
|
|
### Epic 5: Administration & Personnalisation (Self-Hosting Pro)
|
|
Finaliser les outils de configuration (OpenAI/Ollama) et les fonctionnalités avancées (Images, Archive).
|
|
**FRs covered:** FR2, FR3, FR4, FR17, FR18
|