Michael/CollectFlow
1
0 Fork 0
mirror of https://github.com/R0m1k3/CollectFlow.git synced 2026-10-20 21:48:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

feat(grid): ajout algorithme score produit avec parametrage dynamique et page d'aide

Browse Source
This commit is contained in:
Michael committed 2026-02-21 04:00:51 +01:00
1 parent f540e4f2b3
commit 3544c0c898
67 files changed
+19476 -15
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

_bmad-output/planning-artifacts/architecture.md
+190
View File
@@ -0,0 +1,190 @@
---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
workflowType: 'architecture'
lastStep: 8
status: 'complete'
completedAt: '2026-02-21'
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'
]
project_name: 'CollectFlow'
user_name: 'Michael'
---
## Project Context Analysis
### Requirements Overview
**Functional Requirements:**
L'architecture doit supporter un workflow de décision tactique en 2 magasins (plus vue globale). Les piliers fonctionnels sont :
- **Sélection de périmètre** (Magasin/Fournisseur) pilotant le chargement des données.
- **Grille de données Ultra-Dense** (10 000+ lignes) avec historique 12 mois (Heatmap).
- **Moteur d'arbitrage en ligne** (A/B/C/Z) avec recalcul immédiat des KPIs financiers (CA, Marge).
- **Intégration OpenRouter** pour les préconisations IA et justifications textuelles.
- **Persistance par Snapshots** pour permettre un export Excel différentiel (Delta).
**Non-Functional Requirements:**
- **Performance** : Rendu fluide de la grille (virtualisation) et latence < 100ms pour les interactions métier.
- **Sécurité** : Proxy API pour OpenRouter et isolation des clés côté serveur uniquement.
- **Fiabilité** : Snapshots de session persistants pour éviter les pertes de données lors des sessions d'arbitrage massives.
**Scale & Complexity:**
- **Primary domain**: Retail Analytics & Decision Support (B2B).
- **Complexity level**: Medium-High (Volume de données tabulaires + Intégration IA + Logique de Snapshot).
- **Estimated architectural components**: Frontend Grid Service, Backend AI Proxy, Database Snapshot Manager, Excel Export Engine.
### Technical Constraints & Dependencies
- **Data Layer** : Base de données PostgreSQL avec un schéma existant (`ventes_produits`, vues matérialisées).
- **Frontend Constraints** : Besoin critique de virtualisation pour gérer la densité sans perte de frames.
- **Deployment** : Environnement Docker-orchestrated.
### Cross-Cutting Concerns Identified
- **State Management** : Gestion de l'état "Draft" (arbitrages non validés) vs État permanent.
- **Performance Monitoring** : Temps de réponse des appels IA et génération d'export.
- **Data Visualization** : Rendu performant de la Heatmap 12m par ligne.
## Starter Template Evaluation
### Primary Technology Domain
Dashboard Décisionnel Haute Performance (B2B SaaS / Retail Analytics) basé sur React.
### Selected Starter: Next.js (latest)
**Rationale for Selection:**
- **Proxy API Intégré** : Facilite la sécurisation des clés OpenRouter sans infrastructure backend séparée.
- **Server-Side logic** : Possibilité de déporter le calcul massif des KPIs et la gestion des Snapshots côté serveur.
- **Ecosystème Shadcn/Radix** : Intégration native parfaite avec la stack visuelle cible.
**Initialization Command:**
```bash
npx create-next-app@latest ./ --typescript --tailwind --eslint --app --src-dir --import-alias "@/*" --turbo
```
## Core Architectural Decisions
### Decision Priority Analysis
**Critical Decisions (Block Implementation):**
- Choix de Next.js comme socle full-stack.
- Utilisation de Drizzle ORM pour l'accès aux données PostgreSQL.
- Implémentation de TanStack Table v8 avec virtualisation pour la grille 10 000 lignes.
**Important Decisions (Shape Architecture):**
- Adoption de Zustand pour la gestion d'état "Draft" (sessions d'arbitrage).
- Utilisation de Next.js Server Actions pour une communication API type-safe.
- Sécurisation via Auth.js (NextAuth) v5.
**Deferred Decisions (Post-MVP):**
- Cache global (Redis) : À évaluer si les performances de PostgreSQL/Drizzle ne suffisent pas après l'ajout de 50 000+ lignes.
### Data Architecture
- **ORM** : Drizzle ORM (v0.45.1). Rationale : Performance brute et overhead minimal.
- **Validation** : Zod (v3.x). Rationale : Typage de bout en bout.
- **Persistence Strategy** : Snapshotting des états par session Fournisseur pour calcul de différentiel.
### Authentication & Security
- **Auth Solution** : Auth.js v5 (NextAuth). Pattern de session sécurisée.
- **Security Constraints** : API Proxy Backend obligatoire pour OpenRouter (NFR-SEC-2).
### API & Communication Patterns
- **Standard interactions** : Next.js Server Actions (Typage Fort avec Zod).
- **Heavy lifting** : Route Handlers (`/api/ai/analyze`, `/api/export/excel`) pour les traitements longs.
### Frontend Architecture
- **Grid Engine** : TanStack Table v8 + `@tanstack/react-virtual`.
- **State Store** : Zustand. Pattern : Store atomique par domaine (Grid, Context, Summary).
- **Data Fetching** : TanStack Query v5.
## Implementation Patterns & Consistency Rules
### Naming Patterns
- **Database** : `snake_case`.
- **Code/API** : `camelCase` (Drizzle s'occupe du mapping).
- **Components** : `PascalCase.tsx` (ex: `HeatmapGrid.tsx`).
- **Hooks/Utils** : `kebab-case.ts` (ex: `use-arbitrage-logic.ts`).
### Structure & Process
- **Architecture** : Feature-Driven in `src/features/`.
- **State** : Store atomique par feature via Zustand.
- **API** : Server Actions avec retour `{ success, data, error }`.
- **Tests** : Co-located `[Name].test.tsx`.
## Project Structure & Boundaries
### Complete Project Directory Structure
```text
CollectFlow/
├── public/ # Assets statiques (Logos, Icons)
├── src/
│ ├── app/ # Next.js App Router (Routes & Layouts)
│ │ ├── (auth)/ # Routes d'authentification (Epic 1)
│ │ ├── (dashboard)/ # Cœur de l'application (Epic 2 & 3)
│ │ │ └── grid/ # Page principale de la grille
│ │ └── api/ # Route Handlers (IA Proxy, Export Excel)
│ ├── components/
│ │ ├── ui/ # Composants Shadcn (Boutons, Inputs, Toast)
│ │ └── shared/ # Composants transverses (Layout, Sidebar)
│ ├── features/ # Logique Métier par Domaine (Isolation Agents)
│ │ ├── grid/ # [Epic 2 & 3] Composants Heatmap, Store Zustand
│ │ ├── ai-copilot/ # [Epic 4] Intégration OpenRouter, Insights UI
│ │ ├── snapshots/ # [Epic 5] Logique de persistence et Delta
│ │ └── export/ # [Epic 5] Générateur Excel Différentiel
│ ├── db/ # Configuration Drizzle, Schéma, Migrations
│ ├── lib/ # Clients partagés (Auth.js, OpenRouter, Utils)
│ └── types/ # Definitions TypeScript globales
├── .env.local # Secrets (DB_URL, OPENROUTER_KEY)
├── package.json
└── tailwind.config.ts
```
### Architectural Boundaries
**API Boundaries:**
- Les **Server Actions** gèrent 90% des mutations métier.
- Les **Route Handlers** sont réservés aux flux externes (IA) et formats binaires (Excel).
**Data Boundaries:**
- Drizzle ORM possède la source de vérité du schéma (`src/db/schema.ts`).
- Les données "Draft" vivent exclusivement dans les stores **Zustand** avant validation.
### Requirements to Structure Mapping
**Epic/Feature Mapping:**
- **Epic 1 (Fondations)** : `src/db/`, `src/app/(auth)/`, `src/lib/auth.ts`.
- **Epic 2 (Vue Grid)** : `src/features/grid/components/`, `src/features/grid/store/`.
- **Epic 3 (Arbitrage)** : `src/features/grid/hooks/use-arbitrage.ts`.
- **Epic 4 (IA)** : `src/features/ai-copilot/`, `src/app/api/ai/`.
- **Epic 5 (Snapshots & Export)** : `src/features/snapshots/`, `src/features/export/`.
**Cross-Cutting Concerns:**
- **Authentication** : Protect via `src/middleware.ts` and `src/lib/auth.ts`.
- **Visual Theme** : Centralisé dans `tailwind.config.ts` et `src/app/globals.css`.
## Architecture Validation Results
### Coherence Validation ✅
- **Compatibilité** : Stack Next.js + Drizzle + TanStack + Auth.js 100% compatible.
- **Cohérence** : Les patterns de nommage (snake_case DB / camelCase App) sont standardisés via Drizzle mapping.
- **Alignement** : La structure feature-driven supporte l'isolation des épiques.
### Requirements Coverage Validation ✅
- **Fonctionnel** : Chaque épique (1-5) possède une zone d'implémentation définie.
- **NFR-PERF** : Virtualisation validée comme pattern critique pour la grille.
- **NFR-SEC** : Proxy IA validé pour la protection des secrets OpenRouter.
### Implementation Readiness Validation ✅
- **Statut** : READY FOR IMPLEMENTATION.
- **Confiance** : Élevée (9/10).
- **Forces** : Isolation métier, stack moderne 2026, gestion sécurisée de l'IA.
### Architecture Completeness Checklist
- [x] Analyse de contexte et complexité
- [x] Stack technologique spécifiée (Next.js 16+, Drizzle 0.45)
- [x] Patterns de nommage et structure feature-driven
- [x] Mapping des 5 Épiques vers la structure physique
- [x] Validation de la conformité NFR (Perf, Sec, Rel)
### Implementation Handoff
1. Initialiser le projet via la commande `npx create-next-app@latest`.
2. Configurer le schéma Drizzle basé sur `database-schema.sql`.
3. Démarrer l'implémentation par l'**Epic 1 (Fondations & Connectivité)**.
_bmad-output/planning-artifacts/epics.md
+371
View File
@@ -0,0 +1,371 @@
---
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).
_bmad-output/planning-artifacts/prd.md
+88 -15
View File
@@ -1,5 +1,5 @@
---
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-02b-vision', 'step-02c-executive-summary', 'step-03-success', 'step-04-journeys', 'step-05-domain', 'step-06-innovation', 'step-07-project-type']
stepsCompleted: ['step-01-init', 'step-02-discovery', 'step-02b-vision', 'step-02c-executive-summary', 'step-03-success', 'step-04-journeys', 'step-05-domain', 'step-06-innovation', 'step-07-project-type', 'step-08-scoping', 'step-09-functional', 'step-10-nonfunctional', 'step-11-polish']
inputDocuments: []
documentCounts:
briefs: 0
@@ -31,12 +31,12 @@ CollectFlow se distingue par son approche paramétrique adaptative couplée à u
- **Paramétrage Dynamique par Fournisseur :** Contrairement aux systèmes rigides, la capacité des gammes (A, B, C) n'est pas fixe. L'utilisateur définit le volume de références cibles par fournisseur et par magasin (ex: 400 références pour la Gamme A chez le Fournisseur X).
- **Intelligence du Cycle de Vie (Gamme Z) :** Au lieu de simplement supprimer les produits non performants, l'application les classe en "Gamme Z" (abandon). Cela permet de conserver l'historique d'analyse pour éviter de reproduire de mauvais choix d'achat futurs, tout en nettoyant les vues actives. Le système inclut un export natif au format Excel pour les gammes cibles, permettant la réintégration fluide et immédiate des décisions d'assortiment dans le logiciel de gestion de magasin existant.
## Project Classification
- **Project Type:** Web Application
- **Domain:** Retail Analytics & Inventory Management
- **Complexity:** Medium (Nécessite des agrégations de données poussées, vues matérialisées PostgreSQL, architecture multi-magasins/multi-fournisseurs)
- **Project Context:** Greenfield (Nouveau projet)
## Project Characteristics
- **Type:** Web Application (Single Page Application - SPA)
- **Domain:** Retail Analytics & Inventory Management (B2B Internal)
- **Environment:** Docker-orchestrated, Google Chrome (Desktop) optimized
- **Complexity:** Medium (Data aggregation via PostgreSQL materialized views, multi-store architecture, OpenRouter AI integration). *Note: The core data structure is defined in [`docs/database-schema.sql`](file:///c:/Users/Michael/Git/CollectFlow/docs/database-schema.sql).*
- **Context:** Greenfield
## Success Criteria
@@ -134,15 +134,88 @@ Pour valider cette approche, il faudra tester l'interface avec l'acheteur repré
Le risque principal d'une vue tabulaire métier est la surcharge visuelle (le syndrome de "l'usine à gaz") au fur et à mesure de l'ajout de nouvelles données (N-1, indicateurs supplémentaires).
*Mitigation :* Maintenir une discipline de conception stricte (Progressive Disclosure). Les informations secondaires doivent n'être révélées qu'à la demande (ex: clic sur une ligne pour voir le détail des 12 mois) afin de conserver un tableau principal ultra-épuré et dédié à l'action.
## Web Application Specific Requirements
### Project-Type Overview
## Project Scoping & Phased Development
CollectFlow est conçue comme une **Single Page Application (SPA)** interne. Ce format garantit une expérience analytique fluide et sans rechargement pour l'Acheteur.
### MVP Strategy & Philosophy
### Technical Architecture Considerations
**MVP Approach:** Problem-Solving MVP (Se concentrer sur la résolution du problème principal : trier rapidement l'assortiment avec des données fiables et générer un fichier d'export actionnable immédiatement, sans perturber le système existant plus que nécessaire). L'approche est minimaliste sur le front-end mais robuste sur le back-end.
- **Single Page Application (SPA) :** L'architecture front-end doit permettre la manipulation immédiate (tris, actions par lot, modifications de gammes en ligne) d'un large volume de données sans latence ni rafraîchissement global de l'écran.
- **Cible Navigateur :** Le développement et le support sont optimisés exclusivement pour **Google Chrome (Desktop)**, reflétant les standards des postes de travail des équipes d'achat.
- **Data en Temps Réel :** Contrairement aux systèmes de batching nocturnes locaux, l'application doit s'appuyer sur des bases de données de caisse "en live" ou synchronisées en temps réel pour afficher l'état instantané des encaissements lorsqu'une collection est révisée.
- **Stratégie SEO & Accessibilité :** S'agissant d'un outil fermé B2B, le référencement (SEO) est inactif. L'interface (UI/UX) doit toutefois obéir à des règles de fort contraste pour éviter la fatigue visuelle face à la densité des tableaux de bord (Accessibilité Cognitive).
**Resource Requirements:** Une petite équipe technique (1 Développeur Full-Stack maîtrisant React/PostgreSQL) avec l'Acheteur en tant qu'expert métier pour valider l'UX et les règles de gestion (1 à 2 jours par semaine d'implication).
### MVP Feature Set (Phase 1)
**Core User Journeys Supported:**
- La Revue Stratégique de Collection (Filtrage Périmètre/Fournisseur, Affichage des performances sur 6 mois, Modification en ligne des gammes (A, B, C, Z), Forçage manuel).
- Export Différentiel vers Excel (Uniquement les modifications).
**Must-Have Capabilities:**
- Interface tabulaire "Zero-Learning" avec édition "inline" des menus déroulants.
- Algorithme de tri basique (Score Volume + Marge).
- Gestion de session simple pour identifier le "Delta" (Snapshotting) lors de l'export.
- Connexion sécurisée de base (B2B).
### Post-MVP Features
**Phase 2 (Growth):**
- Historisation sur 12 mois glissants et l'ajout de la comparaison N-1.
- Actions en masse (Bulk Actions) avancées (ex: appliquer une gamme à toute une catégorie de produits d'un coup).
- Raffinement de l'algorithme de calcul des vues matérialisées pour des temps de réponse sub-secondes si le volume de données augmente.
**Phase 3 (Expansion):**
- Analyse quantitative de l'"effet de Halo" et de la cannibalisation (intelligence analytique plus poussée).
- API de synchronisation bidirectionnelle directe avec le logiciel de gestion cible (éliminer l'export Excel).
### Risk Mitigation Strategy
**Technical Risks:** La performance du rendu du grand tableau côté client (SPA) et la génération de l'export Excel complexe. Mitigation : Utiliser la virtualisation (ex: react-window) pour le front-end. Créer des Preuves de Concept (PoC) précoces pour l'export Excel.
**Market Risks:** Rejet par l'Acheteur face à une nouvelle interface, même simple. Mitigation : Tests d'utilisabilité en continu dès les premières maquettes filaires. Validation stricte du "Zero-Learning".
**Resource Risks:** Indisponibilité de l'expert métier (Acheteur) pour valider les règles de l'IA. Mitigation : Développer avec des jeux de données d'essai anonymisés massifs dès le départ pour une validation asynchrone sécurisée.
## Functional Requirements
### 1. Perimeter & Context Selection
- **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.
### 2. Performance Dashboard
- **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.
### 3. AI-Assisted Tactical Management
- **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é.**
### 4. Export & Integration
- **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.
### 5. System & Configuration (Infrastructure)
- **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).
## Non-Functional Requirements
### Performance
- **NFR-PERF-1 :** Le tableau de bord initial (liste des produits d'un fournisseur) doit s'afficher en moins de 3 secondes pour un jeu de données contenant jusqu'à 10 000 lignes.
- **NFR-PERF-2 :** Les modifications de gamme "en ligne" (inline editing) par l'Acheteur doivent être répercutées visuellement dans l'interface en moins de 100 millisecondes (ressenti immédiat).
- **NFR-PERF-3 :** Les réponses de l'IA (via OpenRouter) suite à une demande d'analyse de gamme doivent s'afficher en moins de 10 secondes.
### Security
- **NFR-SEC-1 :** L'authentification de l'Acheteur nécessite des mots de passe forts (minimum 12 caractères, incluant majuscules, minuscules, chiffres, caractères spéciaux).
- **NFR-SEC-2 :** Les clés de l'API OpenRouter et les identifiants de la base de données PostgreSQL ne doivent jamais être exposés côté client (SPA) et doivent être gardés exclusivement côté serveur via des variables d'environnement.
- **NFR-SEC-3 :** L'ensemble du trafic entre le client et le serveur doit utiliser une connexion sécurisée (HTTPS/TLS 1.2 minimum).
### Integration & Reliability
- **NFR-INT-1 :** Le fichier d'export Excel produit *doit* respecter strictement l'encodage (ex: UTF-8) et le nommage de colonnes (sans coquille) imposés par les contraintes du logiciel cible.
- **NFR-REL-1 :** Le système de `Snapshot` (FR14) doit garantir que lors d'un crash du navigateur ou d'une perte réseau, l'utilisateur ne perde que les actions de sa session active (non validées), sans altération des états historiques.
_bmad-output/planning-artifacts/ux-design-directions.html
+377
View File
@@ -0,0 +1,377 @@
<!DOCTYPE html>
<html lang="fr" class="light">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CollectFlow - UX Full Width UI (Mode Final)</title>
<script src="https://cdn.tailwindcss.com"></script>
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500;600&display=swap"
rel="stylesheet">
<style>
body {
font-family: 'Inter', sans-serif;
background-color: #f8fafc;
}
.dark body {
background-color: #0f172a;
}
.font-mono-nums {
font-family: 'JetBrains Mono', monospace;
}
/* Grid definitions for full-width fluid layout */
.data-grid {
display: grid;
grid-template-columns: 2.5fr 1fr minmax(400px, 4fr) 0.6fr 0.8fr 1fr 0.4fr 0.6fr 3fr 1.2fr;
gap: 0.5rem;
align-items: center;
}
::-webkit-scrollbar {
width: 8px;
height: 8px;
}
::-webkit-scrollbar-track {
background: transparent;
}
::-webkit-scrollbar-thumb {
background: #cbd5e1;
border-radius: 4px;
}
.dark ::-webkit-scrollbar-thumb {
background: #475569;
}
</style>
<script>
tailwind.config = {
darkMode: 'class',
theme: { extend: { colors: { brand: { 50: '#f0f9ff', 100: '#e0f2fe', 500: '#0ea5e9', 600: '#0284c7', 900: '#0c4a6e' } } } }
}
function toggleTheme() { document.documentElement.classList.toggle('dark'); }
</script>
</head>
<body class="text-slate-900 dark:text-slate-200 h-screen flex flex-col transition-colors duration-200 overflow-hidden">
<!-- Header Navigation -->
<header
class="bg-white dark:bg-slate-950 border-b border-gray-200 dark:border-slate-800 p-4 flex justify-between items-center shrink-0">
<div class="flex items-center space-x-6">
<h1 class="text-xl font-semibold tracking-tight">CollectFlow <span
class="text-slate-400 text-sm font-normal uppercase tracking-widest">Génération Assortiment</span>
</h1>
<span
class="text-xs text-brand-600 dark:text-brand-400 font-bold px-3 py-1 bg-brand-50 dark:bg-brand-900/30 rounded-full border border-brand-200 dark:border-brand-800 shadow-sm">
Direction Validée • Ultra-Dense 32"
</span>
</div>
<button onclick="toggleTheme()"
class="p-2 rounded-md hover:bg-slate-100 dark:hover:bg-slate-800 transition-colors">
<svg class="w-5 h-5 dark:hidden" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"></path>
</svg>
<svg class="w-5 h-5 hidden dark:block text-yellow-300" fill="none" stroke="currentColor"
viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z">
</path>
</svg>
</button>
</header>
<main class="flex-1 flex flex-col p-4 space-y-4 overflow-hidden">
<!-- Context Header -->
<div class="flex justify-between items-end w-full">
<div
class="flex space-x-4 bg-white dark:bg-slate-900 border border-slate-200 dark:border-slate-700 p-3 rounded-lg shadow-sm items-center w-full max-w-5xl">
<span
class="text-sm text-slate-500 uppercase tracking-widest border-r border-slate-200 dark:border-slate-700 pr-4">Fournisseur
Actif:</span>
<span
class="text-lg font-bold text-brand-700 dark:text-brand-400 border-r border-slate-200 dark:border-slate-700 pr-4">NIKE
EUROPE BV</span>
<span
class="text-sm text-slate-500 font-medium flex items-center pr-4 border-r border-slate-200 dark:border-slate-700">
<svg class="w-5 h-5 mr-2 text-slate-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2"
d="M3 4a1 1 0 011-1h16a1 1 0 011 1v2.586a1 1 0 01-.293.707l-6.414 6.414a1 1 0 00-.293.707V17l-4 4v-6.586a1 1 0 00-.293-.707L3.293 7.293A1 1 0 013 6.586V4z">
</path>
</svg>
Toutes Familles (Vue Globale)
</span>
<span class="text-sm bg-slate-100 dark:bg-slate-800 px-3 py-1 rounded-md font-mono-nums font-bold">1 240
Réf.</span>
</div>
<button
class="text-sm bg-brand-600 text-white px-5 py-2.5 rounded-lg shadow-md hover:bg-brand-500 transition font-bold active:scale-95">
+ Créer un Groupe Famille
</button>
</div>
<!-- Table Container -->
<div
class="flex-1 bg-white dark:bg-slate-950 border border-slate-200 dark:border-slate-800 rounded-lg shadow-sm flex flex-col w-full overflow-hidden">
<!-- Header Grid -->
<div
class="data-grid border-b border-slate-200 dark:border-slate-800 bg-slate-50 dark:bg-slate-900/50 p-3 text-[11px] font-bold text-slate-500 tracking-widest items-end uppercase shrink-0">
<div class="px-2 pb-1 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
Produit & Ref <span>▼</span></div>
<div
class="px-2 pb-1 border-l border-slate-200 dark:border-slate-700 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
Famille <span>▼</span></div>
<div class="px-2">
<div
class="text-center border-b border-slate-200 dark:border-slate-700 pb-1 mb-1 text-[9px] text-slate-400 font-bold uppercase tracking-[0.2em]">
Quantités Mensuelles</div>
<div class="grid grid-cols-12 gap-1 text-center text-[10px] leading-tight">
<div title="Mars 2024">Mar<br>24</div>
<div title="Avril 2024">Avr<br>24</div>
<div title="Mai 2024">Mai<br>24</div>
<div title="Juin 2024">Jui<br>24</div>
<div title="Juillet 2024">Jul<br>24</div>
<div title="Août 2024">Aoû<br>24</div>
<div title="Septembre 2024">Sep<br>24</div>
<div title="Octobre 2024">Oct<br>24</div>
<div title="Novembre 2024">Nov<br>24</div>
<div title="Décembre 2024">Déc<br>24</div>
<div title="Janvier 2025">Jan<br>25</div>
<div class="text-brand-600 dark:text-brand-400 font-black">Fév<br>25</div>
</div>
</div>
<div
class="text-center px-1 pb-1 border-l border-slate-200 dark:border-slate-700 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
Tot. 12m<span>▼</span></div>
<div
class="text-center px-1 pb-1 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
CA (€)<span>▼</span></div>
<div
class="text-center px-2 pb-1 bg-slate-100 dark:bg-slate-800/80 rounded-t pt-2 border-x border-t border-slate-200 dark:border-slate-700 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
Marge (€/%)<span>▼</span></div>
<div class="text-center px-1 pb-1 border-l border-slate-200 dark:border-slate-700">Init.</div>
<div
class="text-center px-1 pb-1 hover:text-brand-600 dark:hover:text-brand-400 cursor-pointer transition-colors">
Score<span>▼</span></div>
<div class="px-2 pb-1">Analyse IA</div>
<div
class="text-center px-2 pb-1 text-brand-700 dark:text-brand-400 font-bold border-l border-slate-200 dark:border-slate-700">
Action Arbitrage</div>
</div>
<div class="flex-1 overflow-y-auto w-full">
<!-- Row 1 -->
<div
class="data-grid border-b border-slate-100 dark:border-slate-800/50 p-2 hover:bg-slate-50 dark:hover:bg-slate-900/50 transition-colors">
<div class="px-2 min-w-0">
<div class="font-bold text-sm truncate" title="T-Shirt Essential Basic">T-Shirt Essential Basic
</div>
<div class="text-[11px] text-slate-500 font-mono-nums mt-0.5 tracking-tight">REF-892345</div>
</div>
<div class="px-2 min-w-0">
<span
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-700 dark:text-indigo-400 border border-indigo-100 dark:border-indigo-800 text-[10px] px-2 py-1 rounded truncate block text-center uppercase font-bold shadow-sm">T-Shirts
H</span>
</div>
<div class="grid grid-cols-12 gap-1 px-2 font-mono-nums">
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm">
41</div>
<div
class="bg-indigo-100 dark:bg-indigo-900/50 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm font-bold">
95</div>
<div class="bg-indigo-600 text-white text-xs text-center py-1.5 rounded-sm font-bold shadow-sm">
120</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm">
64</div>
<div
class="bg-slate-50 dark:bg-slate-800/40 text-slate-500 dark:text-slate-400 text-xs text-center py-1.5 rounded-sm">
22</div>
<div
class="bg-slate-50 dark:bg-slate-800/40 text-slate-500 dark:text-slate-400 text-xs text-center py-1.5 rounded-sm">
18</div>
<div
class="bg-slate-50 dark:bg-slate-800/40 text-slate-500 dark:text-slate-400 text-xs text-center py-1.5 rounded-sm">
15</div>
<div
class="bg-slate-50 dark:bg-slate-800/40 text-slate-500 dark:text-slate-400 text-xs text-center py-1.5 rounded-sm">
12</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm">
45</div>
<div
class="bg-indigo-100 dark:bg-indigo-900/50 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm font-bold">
88</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 dark:text-indigo-200 text-xs text-center py-1.5 rounded-sm">
54</div>
<div
class="bg-slate-50 dark:bg-slate-800/40 text-slate-600 dark:text-slate-300 text-xs text-center py-1.5 rounded-sm font-black border-2 border-brand-500/30">
30</div>
</div>
<div
class="text-center px-1 font-mono-nums text-sm font-black text-indigo-700 dark:text-indigo-300 bg-indigo-50 dark:bg-indigo-900/30 py-1.5 rounded-md border border-indigo-100 dark:border-indigo-800">
604</div>
<div class="text-center px-1 font-mono-nums text-sm font-bold tracking-tight">12 450</div>
<div
class="text-center px-2 flex flex-col items-center justify-center bg-slate-50 dark:bg-slate-800/30 rounded-md py-1 border border-slate-100 dark:border-slate-800 shadow-inner">
<span class="font-mono-nums text-xs font-black text-emerald-700 dark:text-emerald-400">5 602
€</span>
<span
class="font-mono-nums text-[11px] text-white bg-emerald-600 px-2 mt-1 rounded-full font-bold">45.0%</span>
</div>
<div class="text-center px-1 font-black text-xs text-slate-400">A</div>
<div class="text-center px-1">
<span
class="inline-flex items-center justify-center px-2 py-1.5 rounded-lg text-xs font-black bg-emerald-100 text-emerald-800 dark:bg-emerald-900/60 dark:text-emerald-300 border-2 border-emerald-200 dark:border-emerald-700 w-full shadow-sm">92</span>
</div>
<div class="px-2 text-xs text-slate-600 dark:text-slate-300 leading-snug font-medium italic">
Saisonnier été (M2-M4). Très bonne rentabilité absolue. Excellente récurrence. Maintien Fort
préconisé par l'algorithme.</div>
<div class="text-center px-2 min-w-0">
<select
class="w-full text-xs font-black border-2 border-brand-500 dark:border-brand-400 bg-white dark:bg-slate-800 rounded-lg py-2 px-2 focus:ring-4 focus:ring-brand-500/20 outline-none cursor-pointer text-brand-900 dark:text-brand-200 shadow-md">
<option selected>A - Cœur</option>
<option>B - Standard</option>
<option>C - Optionnel</option>
<option>Z - Sortie</option>
</select>
</div>
</div>
<!-- Row 2 (Alerte) -->
<div
class="data-grid border-b border-rose-100 dark:border-rose-900/30 bg-rose-50/50 dark:bg-rose-950/20 p-2 hover:bg-rose-50 dark:hover:bg-rose-900/40 transition-colors relative">
<div class="absolute left-0 top-0 bottom-0 w-1.5 bg-amber-500"></div>
<div class="px-2 pl-4 min-w-0">
<div class="font-bold text-sm truncate" title="Polo Piqué Summer Ed.">Polo Piqué Summer Ed.
</div>
<div class="text-[11px] text-slate-500 font-mono-nums mt-0.5 tracking-tight">REF-744111</div>
</div>
<div class="px-2 min-w-0">
<span
class="bg-orange-50 dark:bg-orange-900/30 text-orange-700 dark:text-orange-400 border border-orange-100 dark:border-orange-800 text-[10px] px-2 py-1 rounded truncate block text-center uppercase font-bold shadow-sm">Polos
H</span>
</div>
<div class="grid grid-cols-12 gap-1 px-2 font-mono-nums">
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
32</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
45</div>
<div
class="bg-indigo-100 dark:bg-indigo-900/50 text-indigo-900 text-xs text-center py-1.5 rounded-sm font-bold">
78</div>
<div class="bg-indigo-500 text-white text-xs text-center py-1.5 rounded-sm font-bold shadow-sm">
102</div>
<div
class="bg-indigo-100 dark:bg-indigo-900/50 text-indigo-900 text-xs text-center py-1.5 rounded-sm font-bold">
88</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
54</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
41</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
33</div>
<div
class="bg-indigo-50 dark:bg-indigo-900/30 text-indigo-900 text-xs text-center py-1.5 rounded-sm">
21</div>
<div
class="bg-amber-100 dark:bg-amber-900/60 text-amber-700 dark:text-amber-400 font-black text-xs text-center py-1.5 rounded-sm shadow-inner">
0</div>
<div
class="bg-amber-100 dark:bg-amber-900/60 text-amber-700 dark:text-amber-400 font-black text-xs text-center py-1.5 rounded-sm shadow-inner">
0</div>
<div
class="bg-amber-600 text-white font-black text-xs text-center py-1.5 rounded-sm border-2 border-amber-400 shadow-md transform scale-110 z-10">
0</div>
</div>
<div
class="text-center px-1 font-mono-nums text-sm font-black text-amber-700 dark:text-amber-400 bg-amber-50 dark:bg-amber-900/30 py-1.5 rounded-md border border-amber-200 dark:border-amber-800">
494</div>
<div class="text-center px-1 font-mono-nums text-sm font-bold tracking-tight">8 215</div>
<div
class="text-center px-2 flex flex-col items-center justify-center bg-rose-50 dark:bg-rose-900/20 rounded-md py-1 border border-rose-100 dark:border-rose-800 shadow-inner">
<span class="font-mono-nums text-xs font-black text-rose-700 dark:text-rose-400">1 478 €</span>
<span
class="font-mono-nums text-[11px] text-white bg-rose-600 px-2 mt-1 rounded-full font-bold">18.0%</span>
</div>
<div class="text-center px-1 font-black text-xs text-slate-500">B</div>
<div class="text-center px-1">
<span
class="inline-flex items-center justify-center px-2 py-1.5 rounded-lg text-xs font-black bg-amber-100 text-amber-800 dark:bg-amber-900/60 dark:text-amber-300 border-2 border-amber-200 dark:border-amber-700 w-full shadow-sm">65</span>
</div>
<div class="px-2 text-xs text-amber-800 dark:text-amber-300 font-bold leading-snug">⚠️ ALERTE :
Arrêt brutal des ventes (M11, M12, Now). Carence fournisseur ou obsolescence ? Marge
insuffisante.</div>
<div class="text-center px-2 min-w-0">
<select
class="w-full text-xs font-black border-2 border-rose-600 dark:border-rose-500 bg-rose-50 dark:bg-rose-900/50 text-rose-900 dark:text-rose-100 rounded-lg py-2 px-2 focus:ring-4 focus:ring-rose-500/20 outline-none cursor-pointer shadow-md">
<option>A - Cœur</option>
<option>B - Standard</option>
<option>C - Optionnel</option>
<option selected>Z - Sortie</option>
</select>
</div>
</div>
</div>
<!-- Summary Bar -->
<div
class="bg-slate-900 dark:bg-black text-white p-4 flex justify-between items-center shadow-2xl border-t border-slate-800 shrink-0">
<div
class="text-xs font-bold text-slate-400 bg-slate-800 px-4 py-2 rounded-full border border-slate-700">
Périmètre : <span class="text-white">NIKE EUROPE BV (Vue Globale)</span> • <span
class="text-brand-400">1 240 Réf.</span>
</div>
<div class="flex space-x-12 items-center">
<div class="flex flex-col items-center">
<span class="text-slate-500 text-[10px] uppercase font-black mb-1 tracking-tighter">Volume Total
Vendu</span>
<span class="font-mono-nums font-black text-xl text-white">12 450</span>
</div>
<div class="flex flex-col items-center">
<span class="text-slate-500 text-[10px] uppercase font-black mb-1 tracking-tighter">CA Global
Généré</span>
<span class="font-mono-nums font-black text-xl text-emerald-400">345 200 €</span>
</div>
<div class="flex flex-col items-center">
<span class="text-slate-500 text-[10px] uppercase font-black mb-1 tracking-tighter">Taux de
Marge Moyen</span>
<span class="font-mono-nums font-black text-xl text-emerald-400">41.2%</span>
</div>
</div>
<div class="flex space-x-3">
<button
class="bg-slate-700 hover:bg-slate-600 text-white px-6 py-3 rounded-xl text-sm font-bold transition-all active:scale-95 border border-slate-600">
Export Excel
</button>
<button
class="bg-brand-600 hover:bg-brand-500 text-white px-8 py-3 rounded-xl text-sm font-black transition-all shadow-lg active:scale-95">
Valider ce Fournisseur
</button>
</div>
</div>
</div>
</main>
</body>
</html>
_bmad-output/planning-artifacts/ux-design-specification.md
+428
View File
@@ -0,0 +1,428 @@
---
stepsCompleted: [step-01-discovery, step-02-strategy, step-03-core-experience, step-04-emotional-response, step-05-inspiration-analysis, step-06-design-system, step-07-defining-experience, step-08-visual-foundation, step-09-design-directions, step-10-user-journeys, step-11-component-strategy, step-12-ux-patterns, step-13-responsive-accessibility, step-14-complete]
inputDocuments: [
'c:\Users\Michael\Git\CollectFlow\_bmad-output\planning-artifacts\prd.md',
'c:\Users\Michael\Git\CollectFlow\docs\database-schema.sql'
]
---
# UX Design Specification CollectFlow
**Author:** Michael
**Date:** 2026-02-20
---
<!-- UX design content will be appended sequentially through collaborative workflow steps -->
## Executive Summary
### Project Vision
L'interface de CollectFlow doit incarner "l'Ergonomie Décisionnelle". Ce n'est pas un outil d'exploration de données complexe, mais une plateforme d'action tactique. L'UX doit masquer la complexité des calculs (jusqu'à 10 000 lignes de données croisées : Ventes, CA, Marge) derrière une interface tabulaire évidente permettant de réviser et valider des assortiments (Gammes A, B, C, Z) en quelques clics.
### Target Users
**L'Acheteur B2B (ou Responsable Réseau) :**
- **Mentalité :** Axé sur le business, le temps est une ressource critique. Privilégie la donnée quantitative pure à l'interprétation graphique abstraite.
- **Fréquence d'usage :** Épisodique (2 à 3 fois par an pour une révision de collection). C'est le point central de notre philosophie UX.
- **Besoins :** Ne veut pas réapprendre l'outil à chaque saison ("Zero-Learning UX"). D'un coup d'œil, il doit pouvoir trier, filtrer et comparer les vrais chiffres pour appliquer son instinct métier (ex: modifier une gamme pour garder un produit de "halo").
### Key Design Challenges
- **Le "Cold Start" (Zero-Learning) :** L'utilisateur doit comprendre intuitivement comment filtrer son périmètre et agir sur la grille dès la première seconde sans documentation.
- **Densité vs Lisibilité (L'enjeu Tabulaire) :** Afficher un tableau de 10 000 lignes avec des historiques de 6 à 12 mois constitués de données chiffrées pures sans provoquer de fatigue visuelle.
- **Le Split-Screen Décisionnel :** Rendre la comparaison analytique entre la *"Gamme Actuelle"* et la *"Gamme Proposée par l'IA"* parfaitement évidente ligne par ligne.
### Design Opportunities
- **Interaction "Inline" Fluide :** Utiliser des menus déroulants directement dans les lignes du tableau pour les modifications de gammes, éliminant les pop-ups ou les pages de détail.
- **Tableau Analytique Haute Performance :** Un tableau robuste présentant les chiffres bruts des ventes mensuelles (Qté), clôturé par des colonnes de Totaux (Total Qté, Total CA, Total Marge sur la période) pour une lecture directe de l'impact financier.
- **Sorting & Filtering Omniprésent :** Chaque colonne cruciale (Nomenclatures, Gammes actuelles/proposées, Totaux Quantités, Marge, CA) doit être interactive, permettant des tris ascendants/descendants et des filtrages instantanés pour isoler immédiatement les top/flops performers.
- **Totalisation Dynamique (Floating Summary Bar) :** Une ligne de totaux (CA, Qté, Marge globaux du périmètre filtré) fixée à l'écran qui se met à jour instantanément lors des modifications de gammes, validant immédiatement l'impact d'une décision.
- **Scoring Colorimétrique Subtil :** Conserver l'affichage en clair des statistiques pour le jugement métier, tout en appliquant un léger fonds de couleur (Heatmap) sur la cellule de marge/CA pour guider l'œil sans masquer la donnée chiffrée.
- **Bulk Actions (Actions en masse) Invisibles mais Accessibles :** Intégrer des fonctions de sélection multiple qui n'encombrent pas l'interface par défaut, mais qui "apparaissent" (Progressive Disclosure) dès qu'un besoin d'action à grande échelle est nécessaire.
## Core User Experience
### Defining Experience
L'action fondamentale de CollectFlow est **la décision d'assortiment ligne à ligne, guidée par un Double Filtre (Algorithme vs IA)**. L'utilisateur scrolle à travers son catalogue et dispose de deux colonnes clés juxtaposées : le **Pre-Score Algorithmique** (la réalité des ventes) et **l'Analyse IA** (la recommandation contextuelle). Si l'IA et l'Algorithme divergent, l'Acheteur arbitre instantanément et corrige la gamme en un clic via un menu déroulant "Inline", sans perdre le contexte.
### Platform Strategy
- **Plateforme Unique :** Application Web (Single Page Application).
- **Cible Matérielle :** Exclusivement Desktop/Laptop (écrans larges 1080p minimum) car la juxtaposition des colonnes de scoring et de texte d'analyse IA nécessite une grande largeur d'affichage. L'usage mobile est hors-périmètre.
- **Interaction :** Essentiellement Souris (scroll, clic sur menus déroulants, tri des en-têtes de colonnes) avec support Clavier pour accélérer. Chrome est le navigateur cible.
### Effortless Interactions
Ce qui doit paraître magique et sans effort :
- **La Comparaison Visuelle "Algo vs IA" :** L'affichage côte à côte d'une colonne "Score Algo" (calculée immédiatement sur le CA, Marge, Qté, Poids et Constance) et d'une colonne "Analyse IA". L'œil détecte immédiatement les anomalies ou les confirmations sans devoir ouvrir un panneau détaillé.
- **L'Édition "Inline" :** Changer un produit de la "Gamme B" à la "Gamme A" doit se faire directement dans la cellule du tableau, sans rechargement de page.
- **Le Recalcul Instantané :** Dès l'instant où une gamme est modifiée, la barre de "Totaux Flottante" (CA, Quantités, Marge) se met à jour en moins de 100ms.
### Critical Success Moments
- **L'Arbitrage Éclair :** Quand l'utilisateur voit qu'un produit considéré comme moyen par l'algorithme est sauvé par une analyse IA pointue (expliquant par exemple une rupture de stock passagère), lui permettant de prendre une décision éclairée en 3 secondes.
- **Le Tri Rapide des "Conflits" :** L'Acheteur peut trier son tableau pour ne voir que les lignes où le Score Algorithmique est "Bon" mais où l'IA propose de "Retirer" le produit, ciblant immédiatement son temps de cerveau disponible sur les vraies questions complexes.
- **La Validation Sans Peur :** La prévisualisation des "Deltas" récapitulant l'impact final avant la sauvegarde.
### Experience Principles
1. **La Machine et l'IA comme Conseillers, l'Acheteur comme Décideur :** L'interface présente les faits (Score Mathématique) et les opinions (Analyse Textuelle IA), mais laisse le contrôle total à l'utilisateur via une interface tabulaire.
2. **Latence Zéro :** Tout filtrage, tri ou modification en session doit être instantané. Le réseau n'est sollicité que pour requêter l'IA ou sauvegarder.
3. **Pardonner l'Erreur :** Les modifications sont conservées en local ("Draft state") jusqu'à la sauvegarde finale globale.
## Desired Emotional Response
### Primary Emotional Goals
**Maitrise et Confiance.**
L'Acheteur B2B doit se sentir en contrôle absolu. Il ne subit pas l'outil ni l'Intelligence Artificielle ; il les utilise comme des leviers pour amplifier son propre jugement métier. Le système lui donne le sentiment d'être plus rapide, d'avoir un "filet de sécurité" naturel, et une vision "Rayons X" sur sa collection.
### Emotional Journey Mapping
- **À l'ouverture (Cold Start) :** Sentiment de clarté ("Ouf, ce n'est pas une usine à gaz"). Pas d'anxiété face à l'apprentissage ; l'interface tabulaire est familière.
- **Pendant l'utilisation (The Flow) :** Sentiment d'efficacité redoutable. Le tri instantané des 10 000 lignes et l'édition "Inline" créent un rythme de travail hypnotique et fluide.
- **Lors du Nettoyage Algo ("Design de Révélation") :** Soulagement immédiat. En voyant l'interface épurer automatiquement les produits sans ventes sur 12 mois (Auto-Z) et lever des alertes claires sur les ruptures potentielles (0 vente depuis 2-3 mois), l'Acheteur se sent protégé de l'erreur d'inattention ("Le système veille sur moi").
- **Lors de l'Arbitrage Algo vs IA :** Sentiment intellectuellement stimulant ("Je suis l'expert qui tranche les anomalies complexes").
- **À la clôture session :** Sentiment de sécurité ("Mon travail est propre et je connais mon impact direct").
### Micro-Emotions
- **Confiance > Anxiété :** Le design tabulaire strict rassure l'esprit cartésien de l'Acheteur.
- **Accomplissement > Frustration :** La barre de totaux qui se met à jour instantanément offre un shoot de dopamine (accomplissement micro-tactique) à chaque validation de gamme.
- **Surprise positive :** La découverte silencieuse de fuites de CA grâce aux alertes visuelles ciblées ("Détective").
### Design Implications
- **Design pour la Confiance :** Les couleurs ("Heatmap") doivent rester subtiles. Les textes des analyses IA doivent être consultatifs (jamais prescriptifs).
- **Design de Révélation :** Utilisation de badges forts pour les épurations évidentes (ex: tag 'Z - Épuration') et d'icônes d'alerte (⚠️ orange) pour les ruptures silencieuses, réduisant radicalement la charge mentale.
- **Design pour l'Accomplissement :** Le feedback visuel lors du changement d'une gamme "Inline" doit être franc et satisfaisant (micro-animation au changement de valeur). L'écran final des "Deltas" doit raconter l'impact financier de la session (CA sauvé, Stock dormant préservé).
### Emotional Design Principles
3. **Le Conseiller, pas le Remplaçant :** L'IA adopte un ton de copilotage objectif, laissant systématiquement la place finale au libre arbitre de l'utilisateur.
## UX Pattern Analysis & Inspiration
### Inspiring Products Analysis
**Apple UI (iOS / macOS / Numbers)**
- **Ce qu'ils font bien :** Le Minimalisme Narratif. Apple ne montre que les contrôles nécessaires à l'instant T (Progressive Disclosure). Les interfaces respirent, même quand il y a beaucoup d'informations.
- **Ce qui rend l'expérience fluide :** La cohérence absolue des composants, les typographies ultra-lisibles (San Francisco), et le feedback visuel immédiat à chaque interaction microscopique.
### Transferable UX Patterns
**1. Design Système Typographique Obessionnel :**
- Utiliser une hiérarchie de textes extrêmement rigoureuse. Les chiffres financiers (CA, Marge) utilisent une police monospace (chiffres alignés verticalement) pour une scannabilité instantanée.
**2. Le "Progressive Disclosure" (Divulgation Progressive) :**
- Masquer les filtres complexes derrière un bouton "Filtres" épuré. Les actions en masse (Bulk actions) n'apparaissent que lorsqu'une ligne ou toutes les lignes sont sélectionnées.
**3. Le Feedback Visuel (Micro-interactions) :**
- Bien que sur le Web, reproduire la sensation de réactivité d'Apple. Lorsqu'une "Gamme" passe de B à A, la ligne opère une transition douce (fade-in coloré) pour valider l'action à l'œil.
### Anti-Patterns to Avoid
- **L'Esthétisme au détriment de la Densité :** L'Acheteur a besoin de voir un maximum de lignes sur son grand écran. Il faut l'épure d'Apple, mais la densité d'un outil pro (pas d'espaces blancs démesurés).
- **Les Icônes Cryptiques sans labels :** Toujours privilégier Textes clairs + Icônes standards ("Filtrer", "Trier", "Générer IA") pour le "Zero-Learning".
### Design Inspiration Strategy
**What to Adopt (Ce qu'on prend) :**
- La clarté typographique (police type Inter / San Francisco) pour les données.
- La disparition des bordures de tableaux lourdes au profit de séparations gris très clair.
- Les feedbacks de validation subtils et immédiats.
**What to Adapt (Ce qu'on adapte) :**
- La densité d'information. CollectFlow compactera l'UI Apple pour afficher le plus de lignes possibles simultanément sans scroller excessivement.
**What to Avoid (Ce qu'on rejette) :**
- Les animations gadgets ou très longues (>200ms) qui ralentiraient le "Flow" frénétique d'un acheteur validant 500 produits.
## Design System Foundation
### 1.1 Design System Choice
**Headless UI + Utility-First CSS**
Nous opterons pour une architecture front-end composable basée sur **React**, **Tailwind CSS**, et des bibliothèques de composants non-stylés ("Headless") comme **Shadcn UI** ou **Radix UI**, couplées à un moteur de tableau haute performance (**TanStack Table** avec virtualisation).
### Rationale for Selection
- **Vitesse & Indépendance Visuelle :** Tailwind CSS permet de coder rapidement une interface au pixel près, reproduisant l'élégance "façon Apple" (San Francisco/Inter, gris subtils, absence de bordures lourdes), sans subir l'esthétique générique "Google Material" d'un système comme MUI.
- **Densité Contrôlée :** Dans un workflow B2B où chaque pixel compte, une approche "Headless" nous donne un contrôle absolu de la marge et du padding, essentiel pour densifier notre tableau de 10 000 lignes tout en conservant une grande lisibilité.
- **Performance Tabulaire Critique :** L'interface repose presque exclusivement sur les manipulations de très larges volumes de données côté client. TanStack Table garantit des tris, filtres et rendus sans latence ("Zero-Latency Flow").
### Implementation Approach
- Installation d'une base React/Vite.
- Configuration stricte du thème Tailwind pour adhérer aux contraintes typographiques et colorimétriques définies (Heatmap légère pour les scores, pas de composants intempestifs).
- Mise en place d'un composant Tableau virtuel (React-Window ou équivalent) dès la fondation pour absorber la charge de données du schéma SQL sans pénaliser le navigateur.
### Customization Strategy
- **Typographie :** Utiliser des polices à haute lisibilité pour les données et une police Monospace stricte pour les données financières afin de garantir l'alignement vertical des décimales.
- **Micro-Interactions :** Standardiser une durée de transition de 100ms maximum pour les feedbacks visuels (clics, changements de gammes 'Inline') pour renforcer l'aspect dynamique et l'impact immédiat des décisions, sans jamais ralentir l'Acheteur.
## 2. Core User Experience
### 2.1 Defining Experience
**L'Arbitrage Augmenté ("The Augmented Trade-off")**
L'action fondatrice de CollectFlow est le moment où l'Acheteur regarde une ligne de produit, constate visuellement une divergence entre son intuition métier, le "Pre-Score Algorithmique" (mathématique), et la "Recommandation IA" (contextuelle). Il tranche ce désaccord en modifiant la gamme (ex: Z -> B) via un menu déroulant "Inline", et valide instantanément l'impact de son choix grâce à la mise à jour en temps réel de la barre de Totaux.
### 2.2 User Mental Model
- **Modèle Actuel :** L'Acheteur a l'habitude d'extraire des données brutes vers Excel, d'utiliser des recherches en V croisées (VLOOKUP) avec son budget, de colorier des lignes à la main et de saisir de nouvelles valeurs sans vision globale immédiate de son impact financier total.
- **Le Nouveau Paradigme :** Un tableau de bord intelligent qui a déjà mâché le travail d'extraction et de calcul (le "Pre-Score" et l'"Auto-Z" réduisent 80% du bruit). L'attente centrale est une fluidité absolue : l'Acheteur ne "navigue" pas entre des pages de détails de produits, il "pilote" une liste géante.
### 2.3 Success Criteria
1. **Confiance Visuelle (Zero ambiguity) :** Au survol (Hover), la ligne entière doit être surlignée distinctement pour éviter toute erreur de saisie sur un tableau dense de 10 000 lignes.
2. **Vitesse Pure (Action "Headless") :** L'ouverture du menu déroulant et la sélection d'une nouvelle gamme (A, B, C, Z) doivent s'effectuer sans le moindre lag de réseau.
3. **Récompense Immédiate (The Dosage of Dopamine) :** L'impact de la décision est validé par l'animation instantanée (≤ 100ms) de la barre de "Totaux Flottante" (CA, Quantités, Marge), prouvant à l'Acheteur qu'il vient de créer de la valeur.
### 2.4 Novel UX Patterns
Le format de base (Dashboard Tabulaire) est délibérément **très classique** pour minimiser la courbe d'apprentissage.
La "Nouveauté" réside dans :
- **La Juxtaposition Cognitive :** Mettre côte-à-côte, sur la même ligne, le calcul purement arithmétique (le Score) et l'inférence contextuelle textuelle (l'IA), forçant l'humain à jouer le rôle d'arbitre final.
- **La Bar de Totaux Hautement Réactive :** Un composant qui donne l'illusion de reculyler 10 000 lignes croisées à la volée dans un navigateur web, offrant une expérience "Logiciel de Bureau" (façon Apple Numbers) plutôt que "Page Web Classique".
### 2.5 Experience Mechanics
1. **Initiation :** Pendant le défilement (Scroll) de sa liste filtrée, l'œil de l'Acheteur est attiré par une alerte visuelle (tag ⚠️ orange de rupture de stock) ou un contraste entre un Score élevé et une recommandation IA "Retirer".
2. **Interaction :** L'utilisateur clique sur la cellule `Gamme` de la ligne concernée. Le menu déroulant s'ouvre, il choisit sa nouvelle sélection.
3. **Feedback :** La cellule affiche la nouvelle valeur soutenue par une légère transition de fond coloré (ex: vert clair pour `A`, rouge léger pour `Z`). De manière synchrone, les chiffres de la "Barre de Résumé Flottante" pulsent ou défilent vers leurs nouvelles valeurs.
4. **Completion :** L'action est terminée, enregistrée en local (Draft state). L'Acheteur passe avec fluidité à la ligne critique suivante, sans aucune action de confirmation requise pour cette modification unitaire.
## Visual Design Foundation
### Color System (Dual Theme)
Le système colorimétrique sera 100% sémantique et binaire (Light/Dark).
**1. Les Neutres (L'interface silencieuse) :**
- **Mode Clair :** Fond `White`, bordures `Gray-200`, texte principal `Slate-900`.
- **Mode Sombre :** Fond `Slate-950` (un gris-bleu très profond, pas de noir pur `#000` qui fatigue la rétine), bordures `Slate-800`, texte `Slate-200`.
**2. Les Sémantiques (La "Heatmap") :**
- Les couleurs ne servent *qu'à porter une information* (Jamais de décoration).
- **Succès / A / Bon Score Algo :** Vert émeraude désaturé en mode clair (`Emerald-50` fond / `Emerald-700` texte), et `Emerald-950` fond / `Emerald-400` texte en Mode Sombre.
- **Alerte / Z / Rupture :** Rouge-Orange (`Rose-50` / `Rose-900`).
- Ces couleurs sont appliquées en "Heatmap" (fond de cellule très léger) limitées aux colonnes Pre-Score et IA.
### Typography System
- **Données textuelles & UI :** `Inter` ou `San Francisco` (system-ui). Une typographie sans-serif, neutre, extrêmement lisible même en corps 12px.
- **Données financières (CA, Marge, Quantités) :** Utilisation stricte de la propriété CSS `font-variant-numeric: tabular-nums` (ou déclinaison Monospace type `JetBrains Mono`). C'est **critique** : 1000.00 et 999.00 doivent occuper exactement la même largeur en pixels pour une scannabilité verticale parfaite.
### Spacing & Layout Foundation
- **Densité Maximale ("Compact-First") :** Le padding sera réduit au strict minimum (ex: `32px` de hauteur par ligne) pour afficher un maximum de références (jusqu'à 50 lignes simultanément) sur un écran 1080p.
- **Grid de Lecture :** Retrait des bordures verticales dans le tableau. Seules de fines bordures horizontales (très claires) guideront l'œil, dans la plus pure tradition des grands logiciels d'analyse.
### Accessibility Considerations
- Le contraste entre le texte des données et le fond (même coloré par la Heatmap) devra toujours respecter la norme WCAG AA.
- Support natif du basculement instantané (Toggle) entre Mode Clair et Sombre, sans rechargement.
- Utilisation des touches fléchées du clavier (Haut/Bas) pour naviguer de ligne en ligne afin de limiter l'usage de la souris lors des longues sessions partielles.
## Design Direction Decision
### Design Directions Explored
Multiple directions were explored through an interactive HTML showcase, ranging from a "Split-Screen Analyst" approach (AI in a panel) to a "Dense Spreadsheet" and an "Extended Focus" layout. The exploration focused on balancing high data density (M1-M12 sales history) with professional tool ergonomics for 32" monitors.
### Chosen Direction
**Direction 1: The Extended Focus (Ultra-Dense)**
- **Fluid Layout**: Adapts to 100% width of large monitors (32").
- **Integrated Columns**: Nomenclature, M1-M12 history, Total 12m Quantity, and double-line Margin (€/%) are all visible in a single row.
- **Visual Hierarchy**: Centered alignment for financial data (CA, Margin) to provide breathing room between data blocks.
- **Detailed Historial View**: Explicit labels for Month/Year (e.g., "Jan 25") on the sliding 12-month window.
- **Production-Ready Formatting**: Full numerical values instead of shortened 'k' abbreviations for absolute precision in arbitrage.
### Design Rationale
This direction was chosen because it allows the Buyer to perform line-by-line arbitrage without horizontal scrolling or context switching. On a 32-inch screen, the fluid layout utilizes the full resolution to present a "panoramic" view of each product's performance. The inclusion of Nomenclature inline is critical for the initial global screening phase of the assortment process.
### Implementation Approach
The interface will be built using a robust Grid System (Tailwind CSS / Radix UI) to ensure responsive fluidity. Typography will prioritize efficiency with 'Inter' for UI and 'JetBrains Mono' for tabular data. Categorization actions (A, B, C, Z) will be handled via high-contrast select menus to ensure rapid tactile confirmation.
## User Journey Flows
### 1. Épuration & Filtrage Massif
Ce parcours permet à l'acheteur de rapidement éliminer les références sans vente ou les doublons pour réduire la charge cognitive avant l'analyse fine.
```mermaid
graph TD
A[Sélection Fournisseur] --> B[Chargement de la Vue Globale]
B --> C{Besoin de focus ?}
C -- Oui --> D[Filtrage par Nomenclature / Famille]
C -- Non --> E[Tri par Quantités ASC]
D --> E
E --> F[Identification des 'Zéros' de vente]
F --> G[Sélection Multiple]
G --> H[Action de Masse : Sortie Z]
H --> I[Mise à jour du Résumé Financier]
```
### 2. Arbitrage Fin (Ligne à Ligne)
C'est le cœur de l'application. L'acheteur utilise les indices visuels (Heatmap) et l'IA pour statuer sur chaque produit.
```mermaid
graph TD
A[Focus sur une ligne] --> B[Analyse de la Heatmap 12m]
B --> C[Lecture du Score & Commentaire IA]
C --> D{Alignement avec l'IA ?}
D -- Oui --> E[Confirmation du Choix Suggéré]
D -- Non --> F[Modification manuelle du Statut A/B/C/Z]
E --> G[Passage auto à la ligne suivante]
F --> G
G --> H[Mise à jour temps réel des totaux CA/Marge]
```
### 3. Validation & Bouclage
L'acheteur vérifie l'impact macro-économique de ses choix individuels avant de sceller l'assortiment pour le fournisseur.
```mermaid
graph TD
A[Fin de la revue des articles] --> B[Consultation de la Barre de Résumé]
B --> C{CA & Marge satisfaisants ?}
C -- Non --> D[Ajustement des arbitrages critiques]
D --> B
C -- Oui --> E[Validation Finale du Fournisseur]
E --> F[Génération de l'Assortiment Draft]
F --> G[Passage au Fournisseur Suivant]
```
### Journey Patterns
- **Pattern de Confirmation Implicite** : Le passage automatique à la ligne suivante après un arbitrage accélère considérablement le flux de travail.
- **Pattern de Feedback Financier** : Mise à jour instantanée des indicateurs globaux (CA/Marge) dans la barre flottante à chaque modification de statut (A/B/C/Z).
- **Pattern de Filtrage Progressif** : Utilisation de la Nomenclature pour passer d'une vue de survol à une vue spécialisée sans perdre le contexte financier global.
### Flow Optimization Principles
- **Minimisation du Scroll** : Utilisation de la grille fluide "Ultra-Dense" pour garder toutes les données décisionnelles dans le viewport.
- **Réduction de la Charge Cognitive** : Mise en évidence visuelle (Heatmap/Couleurs) des anomalies de vente pour attirer l'œil de l'acheteur là où son intervention est requise.
- **Feedback Immédiat** : Chaque interaction produit un résultat visible (changement de couleur de ligne, mise à jour des totaux).
## Component Strategy
### Design System Components
L'application s'appuiera sur **Tailwind CSS / Radix UI** pour les composants d'infrastructure.
- **Layout & Structure** : Sidebar, TopNav, Container Fluide.
- **Gestion des États** : Modal (Dialog), Dropdown Menu, Tooltip.
- **Formulaires** : Input text (Search), Button (Primary/Secondary), Checkbox (Multi-sélection).
### Custom Components
Ces blocs sont conçus sur mesure pour répondre aux besoins de densité et d'analyse métier de CollectFlow.
#### Heatmap Sales Grid
**Purpose:** Offrir une lecture instantanée de la saisonnalité et des ruptures de stock sur 12 mois glissants.
- **Anatomy**: Grille de 12 colonnes avec coloration conditionnelle (Bleu = Ventes, Orange = Alerte chute, Gris = Zéro).
- **Accessibility**: Tooltips détaillant les quantités exactes et le mois/année au survol de chaque cellule.
#### Financial Cell
**Purpose:** Présenter les indicateurs de performance financière (CA et Marge) de manière équilibrée.
- **Anatomy**: Cellule double ligne.
- **Variants**: Affichage du pourcentage de marge avec un badge de couleur (Vert > 40%, Orange 20-40%, Rouge < 20%).
#### AI Insights Block
**Purpose:** Synthétiser le raisonnement de l'algorithme pour justifier le score suggéré.
- **Interaction**: Texte court affiché directement, avec possibilité d'expansion pour les analyses complexes.
#### Arbitrage Select
**Purpose:** Permettre un changement de statut (A/B/C/Z) rapide et tactile.
- **States**: Bordure colorée spécifique à chaque statut (Cœur = Indigo, Sortie = Rose/Rouge).
#### Floating Summary Bar
**Purpose:** Garder l'acheteur informé de l'impact macro de ses micro-décisions.
- **Anatomy**: Barre fixe en bas d'écran calculant dynamiquement les totaux (Volume total, CA cumulé, Marge moyenne).
### Component Implementation Strategy
- Tous les composants custom seront stylisés via les **Tokens de Design** définis à l'étape 6.
- Utilisation de la police `JetBrains Mono` pour toutes les données tabulaires afin de garantir un alignement vertical parfait des chiffres.
- Support natif du **Mode Sombre** pour chaque composant.
### Implementation Roadmap
- **Phase 1 - Fondations** : Grille de données fluide et Layout global.
- **Phase 2 - Composants de Lecture** : Heatmap 12m, Cellules financières, Blocs IA.
- **Phase 3 - Composants d'Action** : Sélecteur d'arbitrage et Barre de résumé dynamique.
## UX Consistency Patterns
### Button Hierarchy
- **Action Primaire (Brand 600)** : Boutons "Valider le Fournisseur", "Confirmer l'Assortiment". Utilisés pour clore un cycle de décision. Un seul par vue principale.
- **Action Secondaire (Slate 700 / Outline)** : Boutons "Export Excel", "Détails Produit". Pour les actions non critiques.
- **Action de Danger (Rose 600)** : Boutons "Vider la sélection", "Réinitialiser". Utilisés avec une confirmation de sécurité.
### Feedback Patterns
- **Indicateurs de Performance (Marge)** :
- **Vert (Émeraude)** : Marge > 45%. Succès.
- **Orange (Amber)** : Marge entre 20% et 40%. Attention.
- **Rouge (Rose)** : Marge < 20%. Critique, nécessite une action Z ou renégociation.
- **Anomalies de Vente (Heatmap)** :
- Bordure Orange sur une cellule si la variation mensuelle est négative de plus de 50%.
- **Notifications IA** :
- Utilisation des icônes : 🤖 (Optimisation), ⚠️ (Risque), ✅ (Opportunité).
### Navigation Patterns
- **Auto-Jump Logic** : Lors d'un arbitrage manuel (A, B, C ou Z), l'application déplace automatiquement le focus visuel sur la référence suivante du tableau.
- **Sticky Headers** : Les colonnes d'en-tête et le résumé financier bas restent fixes pendant le défilement pour garantir que les totaux et les labels sont toujours visibles.
### Additional Patterns
- **Empty States** : En l'absence de données pour un fournisseur, affichage d'une vue illustrée incitant à vérifier la période de synchronisation ERP ou à changer de fournisseur.
- **Loading Pattern** : Utilisation de Skeletons (formes grises animées) respectant la structure de la grille "Ultra-Dense" pour éviter les sauts de mise en page pendant le chargement des données.
## Responsive Design & Accessibility
### Responsive Strategy
L'application adopte une approche **Desktop-First / Data-Centric**, privilégiant l'efficacité de l'analyse sur grand écran tout en maintenant une accessibilité critique sur les autres supports.
- **Desktop (32" et +)** : Affichage intégral de la grille fluide. Espace utilisé pour maximiser la visibilité des préconisations IA et des séries temporelles.
- **Laptop (13-15")** : Mode compact avec réduction des marges et masquage des colonnes de contexte non essentielles.
- **Tablette / Mobile** : Vue de consultation focalisée sur les totaux de CA/Marge et la capacité de valider un arbitrage simple déjà préparé.
### Breakpoint Strategy
- **Large Desktop (XL)** : > 1440px (Optimisé pour 32").
- **Desktop (LG)** : 1024px - 1439px.
- **Tablet (MD)** : 768px - 1023px.
- **Mobile (SM)** : < 767px.
### Accessibility Strategy (WCAG AA)
- **Contraste** : Ratio minimum de 4.5:1, même au sein de la Heatmap.
- **Typographie** : `font-variant-numeric: tabular-nums` pour un alignement décimal parfait des monnaies.
- **Focus States** : Indicateurs de focus visuels clairs lors de la navigation au clavier.
### Testing Strategy
- **Performance** : Test de réactivité de la grille jusqu'à 10 000 entrées.
- **Compatibilité** : Validation croisée sur les moteurs Blink (Chrome/Edge) et Webkit (Safari).
- **Accessibilité** : Audit automatisé (Axe/Lighthouse) complété par un test manuel de navigation au clavier.
### Implementation Guidelines
- Utilisation de `CSS Grid` et `Flexbox` pour la fluidité.
- Isolation des composants métier pour garantir que le moteur de calcul financier (Summary Bar) reste performant même en cas de scroll intensif.
- Respect strict des rôles ARIA pour le sélecteur d'arbitrage A/B/C/Z.