home_stock/frontend/CONTEXT.md

Contexte frontend

Ce document décrit le rôle du frontend, ses responsabilités et ses choix techniques. Tout ce qui est indiqué ici est la référence pour les agents frontend.

---

Légende des zones

• <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer) : à compléter par toi selon le projet.
• <A COMPLETER PAR AGENT> : à compléter par un agent spécialisé frontend.

---

Objectif du frontend

• Parcours utilisateur principaux : Lister/rechercher items, consulter détails item avec documents, ajouter/éditer item avec upload fichiers, naviguer hiérarchie locations
• Responsabilités principales : Interface utilisateur responsive, formulaires validation, gestion état local/serveur, upload fichiers, recherche temps réel, affichage photos/documents
• Hors périmètre : Logique métier (déléguée au backend), stockage local complexe (cache géré par React Query), authentification (gérée par backend)

Interfaces

• API consommées : Backend REST à /api/v1/ (items, locations, categories, documents, search), client généré depuis OpenAPI ou fetch/axios manuel
• Authentification/autorisation : Optionnelle, si activée = gestion session cookie automatique par navigateur, redirection login si 401
• Intégrations externes : Aucune intégration externe, consomme uniquement le backend HomeStock

Architecture UI

• Framework : React 18+ avec TypeScript, Vite comme bundler et dev server
• Structure des pages : / dashboard, /items liste items, /items/:id détail item, /items/new création, /locations gestion locations, routing avec React Router v6
• Gestion d'état : TanStack Query (React Query) pour état serveur + cache, Context API pour état UI global (theme, navigation), useState/useReducer pour état local
• Design system / UI kit : TailwindCSS pour styling, composants custom inspirés de shadcn/ui (pas de dépendance lourde), palette Gruvbox dark

Qualité & accessibilité

• Performance attendue : FCP (First Contentful Paint) <1.5s, TTI (Time To Interactive) <3s sur réseau local, bundle JS <500KB gzippé
• Accessibilité : Accessibilité de base (ARIA labels, navigation clavier, contraste WCAG AA), pas de certification stricte WCAG AAA (usage personnel)
• Tests : Vitest pour tests unitaires (hooks, utils), Playwright optionnel pour tests E2E critiques (création item, upload fichier), pas de couverture exhaustive

Conventions

• Organisation du code : frontend/src/ racine, sous-dossiers components/ (composants réutilisables), pages/ (vues complètes), hooks/ (custom hooks), api/ (clients API), utils/ (helpers)
• Nommage : PascalCase pour composants/fichiers React, camelCase pour variables/fonctions, préfixes use pour hooks custom, suffixes Page pour pages complètes
• Gestion erreurs : Error boundaries React pour erreurs render, gestion erreurs API via React Query (onError callbacks), toast notifications pour erreurs utilisateur, fallback UI gracieux

---