17 KiB
stepsCompleted, inputDocuments
| stepsCompleted | inputDocuments | |||
|---|---|---|---|---|
|
|
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).