--- stepsCompleted: [step-01-validate-prerequisites] inputDocuments: [ 'c:\Users\Michael\Git\CollectFlow\_bmad-output\planning-artifacts\prd.md', 'c:\Users\Michael\Git\CollectFlow\_bmad-output\planning-artifacts\ux-design-specification.md' ] --- # CollectFlow - Epic Breakdown ## Overview This document provides the complete epic and story breakdown for CollectFlow, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories. ## Requirements Inventory ### Functional Requirements FR1: L'Acheteur peut sélectionner le périmètre d'analyse (Magasin 1, Magasin 2, ou Global). FR2: L'Acheteur peut sélectionner le fournisseur à analyser. FR3: L'Acheteur peut consulter la liste complète des produits actifs pour le périmètre et fournisseur sélectionnés, issue de la base PostgreSQL. FR4: L'Acheteur peut visualiser la quantité vendue, le Chiffre d'Affaires et la marge générée par mois (jusqu'à 6 mois d'historique) pour chaque produit. FR5: L'Acheteur peut identifier visuellement un premier score de performance "Basique" (Volume vs Marge) pré-calculé sans IA. FR6: L'Acheteur peut définir la capacité cible (nombre d'articles) pour chaque gamme (A, B, C) par fournisseur et magasin. FR7: L'Acheteur peut déclencher manuellement une analyse IA via un bouton d'action dédié. FR8: L'Application soumet les KPIs (Quantité, CA, Marge) au modèle IA (via OpenRouter) suite à ce déclenchement, et affiche la proposition de gamme (A, B, C, Z) pour chaque produit. FR9: L'Acheteur peut visualiser de façon comparative la gamme actuelle et la proposition algorithmique/IA pour chaque produit. FR10: L'Acheteur peut attribuer manuellement de façon individuelle (surcharge) la gamme finale d'un produit (A, B, C, Z). FR11: L'Acheteur peut attribuer une gamme spécifique en masse (Bulk Action) à une sélection de produits. FR12: L'Acheteur peut annuler les modifications non sauvegardées de sa session en cours et revenir au dernier état validé. FR13: L'Acheteur peut prévisualiser un résumé global des changements de gammes (le delta) avant de confirmer. FR14: L'Acheteur peut enregistrer et valider définitivement les choix de gammes effectués. (Création d'un Snapshot persistant en base). FR15: L'Acheteur peut générer un fichier d'export au format Excel des données validées. Ce fichier contient uniquement le delta par rapport à la session précédente. FR16: Le système formate techniquement l'export Excel selon la structure syntaxique attendue par le logiciel de gestion de magasin cible. FR17: L'Application peut être déployée et exécutée dans un environnement Docker. FR18: L'Administrateur peut configurer les paramètres de connexion à la base de données PostgreSQL via des variables d'environnement. FR19: L'Administrateur peut configurer la connexion à l'IA (Clé API OpenRouter, Modèle) via des variables d'environnement. FR20: L'Utilisateur peut s'authentifier de manière sécurisée (connexion B2B). ### NonFunctional Requirements NFR-PERF-1: Le tableau de bord initial (liste des produits) s'affiche en moins de 3s pour 10 000 lignes. NFR-PERF-2: Les modifications de gamme "en ligne" sont répercutées visuellement en moins de 100ms. NFR-PERF-3: Les réponses de l'IA (OpenRouter) s'affichent en moins de 10s. NFR-SEC-1: Authentification avec mots de passe forts (min 12 car., complexité). NFR-SEC-2: Clés API et identifiants DB jamais exposés côté client (Backend uniquement via env vars). NFR-SEC-3: Trafic HTTPS/TLS 1.2 minimum. NFR-INT-1: Export Excel strictement conforme à l'encodage et au nommage du logiciel cible. NFR-REL-1: Système de Snapshot garantissant la non-altération des états historiques si crash. ### Additional Requirements (from UX Specification) - **Layout 32" Fluide** : Le design s'adapte à 100% de la largeur des écrans larges (XL > 1440px). - **Grille "Ultra-Dense"** : Nomenclature, Historique M1-M12, Total Qté 12m, et Marge (€/%) visibles sur une seule ligne. - **Heatmap Intelligence** : Coloration conditionnelle des cellules de vente (M1-M12) et badge couleur pour la marge. - **Auto-Jump Logic** : Passage automatique à la référence suivante après un arbitrage manuel. - **Sticky Headers** : Colonnes d'en-tête et résumé financier (Summary Bar) fixes au scroll. - **Tabular Numbers** : Utilisation de polices à espacement fixe (`JetBrains Mono`) pour l'alignement décimal des données financières. - **Zero-Learning UX** : Interface tabulaire épurée sans pop-ups intrusifs, édition "Inline" privilégiée. ### FR Coverage Map - **FR1 (Sélection Périmètre)**: Epic 2 - **FR2 (Sélection Fournisseur)**: Epic 2 - **FR3 (Liste Produits)**: Epic 2 - **FR4 (KPIs Mensuels)**: Epic 2 - **FR5 (Pre-score Basique)**: Epic 2 - **FR6 (Capacité Cible)**: Epic 3 - **FR7 (Déclenchement IA)**: Epic 4 - **FR8 (Analyse IA)**: Epic 4 - **FR9 (Vue Comparative)**: Epic 4 - **FR10 (Surcharge Individuelle)**: Epic 3 - **FR11 (Actions Bulk)**: Epic 3 - **FR12 (Annulation)**: Epic 3 - **FR13 (Prévisualisation Delta)**: Epic 3 - **FR14 (Snapshot & Validation)**: Epic 5 - **FR15 (Génération Export)**: Epic 5 - **FR16 (Formatage ERP)**: Epic 5 - **FR17 (Dockerization)**: Epic 1 - **FR18 (Config PostgreSQL)**: Epic 1 - **FR19 (Config AI/OpenRouter)**: Epic 1 - **FR20 (Authentification B2B)**: Epic 1 **NFR Mapping:** - **Performance (Grid)**: Epic 2 - **Réactivité (Inline)**: Epic 3 - **Sécurité & API**: Epic 1 - **Fidélité Export**: Epic 5 - **Fiabilité (Snapshot)**: Epic 5 ## Epic List ## Epic 1: Fondations & Connectivité Mise en place de l'environnement technique, de la base de données et de l'accès sécurisé pour permettre le démarrage du projet. ### Story 1.1: Environnement Docker & Orchestration As an Administrator, I want to manage the application architecture within Docker containers, So that I can ensure a reproducible and isolated environment for development and production. **Acceptance Criteria:** **Given** a project directory with a Docker configuration **When** I run `docker-compose up` **Then** three containers (Frontend, Backend, PostgreSQL) start successfully **And** they can communicate internally through a dedicated Docker network. ### Story 1.2: Configuration Base de Données & Environnement As a Developer, I want to connect the application to a PostgreSQL database using environment variables, So that I can secure credentials and separate configuration from code. **Acceptance Criteria:** **Given** the database container is running **When** the backend initializes with the provided DB_URL variable **Then** it successfully retrieves data from the 'configuration' table **And** the initial schema from `docs/database-schema.sql` is applied. ### Story 1.3: Authentification B2B Sécurisée As an Buyer, I want to log in to the application with my credentials, So that my professional data and decision-making environment are secured. **Acceptance Criteria:** **Given** the application is running on its domain **When** I enter a valid email and a strong password (>12 characters) **Then** I am redirected to the Dashboard **And** session tokens are managed securely according to NFR-SEC-1. ### Story 1.4: Services IA (OpenRouter) As a Developer, I want a dedicated backend service to communicate with the OpenRouter API, So that AI requests are centralized and the API key is never exposed to the client. **Acceptance Criteria:** **Given** the OpenRouter API key is set in environment variables **When** the backend service sends a test prompt to a specified model **Then** it receives a valid JSON response from the AI **And** no API tokens are leaked in the client-side SPA bundle (NFR-SEC-2). ## Epic 2: Exploration de Performance (Vue Grid) Permettre à l'acheteur de sélectionner un périmètre et de visualiser les performances réelles (ventes, CA, marge) via la grille ultra-dense. ### Story 2.1: Sélecteur de Contexte (Magasin/Fournisseur) As a Buyer, I want to select a specific store and provider from a sidebar, So that I can focus my analysis on a precise subset of my collection. **Acceptance Criteria:** **Given** the application is loaded **When** I select "Magasin 1" and provider "Fournisseur X" in the sidebar **Then** the dashboard triggers a data fetch for this specific context **And** the UI displays the currently active filters clearly. ### Story 2.2: Grille de Performance Ultra-Dense (Fondation) As a Buyer, I want to scroll through thousands of product lines without lag on my 32" screen, So that I can maintain a high-speed professional workflow. **Acceptance Criteria:** **Given** a dataset of 10,000 product references **When** I scroll the main data grid **Then** the rendering remains fluid (using virtualization) **And** the column headers remain fixed to the top (Sticky Headers). ### Story 2.3: Historique de Ventes & Heatmap 12m As a Buyer, I want to see a 12-month rolling sales history visualized as a heatmap, So that I can immediately identify seasonality or recent stockouts. **Acceptance Criteria:** **Given** historical sales data in the database **When** the grid renders a product line **Then** it displays 12 columns with Month/Year labels (e.g., "Jan 25") **And** the background color of each cell varies from gray (0) to deep blue based on quantity sold. ### Story 2.4: Cellules Financières & Pre-scoring (Marge & CA) As a Buyer, I want to see precise financial KPIs (Turnover, Margin) in a highly readable format, So that I can make arbitrage decisions based on real profitability. **Acceptance Criteria:** **Given** calculated financial metrics **When** the grid displays the Margin and Turnover columns **Then** it uses `JetBrains Mono` for perfect vertical decimal alignment **And** the margin percentage is highlighted (e.g., Emerald badge for >45%, Rose for <20%). ## Epic 3: Arbitrage Tactique & Supervision Humaine Permettre à l'acheteur d'ajuster manuellement l'assortiment, d'utiliser le bulk-editing et de voir l'impact financier en temps réel. ### Story 3.1: Définition des Capacités Cibles As a Buyer, I want to set the target number of items for categories A, B, and C, So that I can align my assortment decisions with my shelf capacity and budget. **Acceptance Criteria:** **Given** the provider analysis page is open **When** I enter target quantities for Gamme A, B, and C in the configuration header **Then** the values are saved for the current session **And** the summary bar uses these targets to calculate the current "fill rate" (e.g., 80/100 items allocated). ### Story 3.2: Arbitrage "Inline" & Auto-Jump As a Buyer, I want to change a product's status (A, B, C, Z) directly in the table row and move to the next item automatically, So that I can process hundreds of products at high speed without interruption. **Acceptance Criteria:** **Given** a list of products in the grid **When** I select a new status (e.g., "Gamme Z") from the dropdown menu in a row **Then** the status is updated instantly with a visual highlight **And** the focus (or active row indicator) automatically moves to the next product line. ### Story 3.3: Barre de Résumé Flottante & Recalcul Temps Réel As a Buyer, I want to see the cumulative impact of my choices on Turnover and Margin updated in real-time, So that I can ensure my final collection meets my financial performance goals. **Acceptance Criteria:** **Given** the floating summary bar is visible at the bottom of the screen **When** I modify a product's category (A/B/C/Z) **Then** the totals for Quantity, Turnover, and Margin in the bar update in less than 100ms **And** the numbers pulse or animate slightly to acknowledge the change. ### Story 3.4: Actions en Masse (Bulk Actions) & Annulation As a Buyer, I want to apply a status to multiple selected products or reset all unconfirmed changes, So that I can quickly handle large batches of items and recover from mistakes. **Acceptance Criteria:** **Given** multiple products are selected via checkboxes **When** I choose "Assign to Gamme A" from the bulk action menu **Then** all selected products are updated simultaneously **And** clicking "Reset Session" reverts all products to their state at the start of the session. ## Epic 4: Assistance IA & Aide à la Décision Déclencher l'intelligence algorithmique pour obtenir des recommandations de gammes basées sur OpenRouter. ### Story 4.1: Génération de Prompt & Envoi des KPIs As a Buyer, I want to trigger an AI analysis manually for a specific provider, So that I can receive intelligent sorting suggestions based on the most recent sales performance data. **Acceptance Criteria:** **Given** the provider's grid is loaded with product KPIs **When** I click the "Trigger AI Analysis" button **Then** the system packages the Turnover, Margin, and Quantity data for all products in the filtered view **And** sends this payload to the backend for prompt generation. ### Story 4.2: Traitement IA & Réception des Suggestions (OpenRouter) As a Developer, I want the system to parse and map the AI response from OpenRouter back to the product list, So that recommandations are correctly associated with their respective references. **Acceptance Criteria:** **Given** the backend has received an AI response (JSON) from OpenRouter **When** the response is returned to the frontend **Then** each product ID is mapped to its proposed category (A, B, C, or Z) **And** the entire process completes in less than 10 seconds (NFR-PERF-3). ### Story 4.3: Vue Comparative "Actuel vs IA" As a Buyer, I want to see the AI's proposed category right next to the current category, So that I can immediately spot and audit the recommended changes. **Acceptance Criteria:** **Given** AI recommendations have been received **When** the grid renders **Then** a new column "Proposition IA" is displayed **And** cells where the AI suggestion differs from the current status are visually highlighted. ### Story 4.4: Affichage des "AI Insights" (Commentaire Contextuel) As a Buyer, I want to read a short justification for each AI recommendation, So that I can understand the context (e.g., stockouts, margin trends) before approving a category change. **Acceptance Criteria:** **Given** the AI has provided textual justifications (insights) **When** I hover over an AI recommendation or view the product details **Then** a compact text block is displayed explaining the reasoning (e.g., "High volume but declining margin, downgrade to B") **And** the insight is clearly legible and contextually relevant. ## Epic 5: Clôture, Snapshots & Export Sécuriser les décisions via des snapshots de session et générer l'export Excel différentiel pour l'ERP. ### Story 5.1: Résumé Final & Prévisualisation du Delta As a Buyer, I want to see a global summary of my assortment changes before finalizing the session, So that I can verify the financial impact and the number of products categorised as 'Z' (Removed). **Acceptance Criteria:** **Given** I have completed my arbitrage for a provider **When** I click "Finalize Session" **Then** a summary screen appears showing the total count of items in categories A, B, C, and Z **And** it highlights the total Turnover and Margin impact of the session's diff (delta). ### Story 5.2: Validation de Session & Snapshot Persistant As a Developer, I want the system to save the current state of the assortment as a permanent Snapshot in the database, So that I can use it as a reference for calculating deltas in future sessions. **Acceptance Criteria:** **Given** the user confirms the final summary **When** the "Save Assortment" action is triggered **Then** a new record is created in the database with the current category status for all products **And** the current session is marked as "Validated". ### Story 5.3: Génération de l'Export Excel Différentiel As a Buyer, I want to download an Excel file containing only the products whose category has changed compared to the previous season, So that I can import it directly into my ERP without manual filtering. **Acceptance Criteria:** **Given** a validated session with recorded snapshots **When** I click "Generate Export" **Then** the system identifies lines where the current category differs from the last Snapshot **And** it generates an Excel file only containing these specific rows. ### Story 5.4: Formatage ERP & Encodage (UTF-8) As an Administrator, I want the exported Excel file to strictly follow the ERP's required syntax and encoding, So that it can be imported without syntax errors or data corruption. **Acceptance Criteria:** **Given** the differential data is ready for export **When** the Excel file is generated **Then** it uses UTF-8 encoding **And** the column headers and data types match exactly the skeleton provided in the target ERP requirements (NFR-INT-1).