claude code

backend/CONTEXT.md

@@ -12,38 +12,33 @@ Tout ce qui est indiqué ici est la référence pour les agents backend.
 ---
 
 ## Objectif du backend
-- Problème métier couvert : <A REMPLIR - PROJET> (exemple: suivi manuel sur tableur — a supprimer)
-- Responsabilités principales : <A COMPLETER PAR AGENT>
-- Hors périmètre : <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer)
+- Problème métier couvert : Centraliser et structurer les données d'inventaire domestique avec recherche efficace et gestion de fichiers <!-- complété par codex -->
+- Responsabilités principales : API REST CRUD (items, locations, categories), upload/stockage fichiers, recherche full-text, validation données, génération OpenAPI <!-- complété par codex -->
+- Hors périmètre : Rendu frontend (SPA indépendante), authentification complexe (MVP mono-utilisateur), analytics avancées <!-- complété par codex -->
 
 ## Interfaces
-- API publique (API = Interface de Programmation) : <A COMPLETER PAR AGENT>
-- Authentification/autorisation : <A COMPLETER PAR AGENT>
-- Intégrations externes : <A REMPLIR - PROJET> (exemple: ERP existant — a supprimer)
+- API publique : REST JSON à `/api/v1/`, OpenAPI 3.0 auto-générée à `/docs`, endpoints principaux = items, locations, categories, documents, search <!-- complété par codex -->
+- Authentification/autorisation : Optionnelle pour MVP (déploiement local), si activée = session cookie basique, pas de rôles complexes (mono-utilisateur) <!-- complété par codex -->
+- Intégrations externes : Aucune intégration externe, système autonome <!-- complété par codex -->
 
 ## Données
-- Base(s) utilisée(s) : <A COMPLETER PAR AGENT>
-- Modèle de données clé : <A COMPLETER PAR AGENT>
-- Stratégie de migration : <A COMPLETER PAR AGENT>
+- Base(s) utilisée(s) : SQLite (fichier homestock.db) avec extension FTS5 pour recherche full-text <!-- complété par codex -->
+- Modèle de données clé : Item (objet principal), Location (hiérarchie lieu/meuble/tiroir), Category (domaine), Document (fichier), relations Many-to-One et Many-to-Many <!-- complété par codex -->
+- Stratégie de migration : Alembic pour migrations versionnées, auto-génération à partir des modèles SQLAlchemy, migrations réversibles up/down <!-- complété par codex -->
 
 ## Architecture interne
-- Style (monolithe modulaire, hexagonal, etc.) : <A COMPLETER PAR AGENT>
-- Modules principaux : <A COMPLETER PAR AGENT>
-- Couche d’accès aux données : <A COMPLETER PAR AGENT>
+- Style : Monolithe modulaire avec séparation claire routers → services → repositories (3-layer architecture) <!-- complété par codex -->
+- Modules principaux : `routers/` (endpoints FastAPI), `services/` (logique métier), `models/` (ORM SQLAlchemy), `schemas/` (Pydantic validation), `repositories/` (accès BDD) <!-- complété par codex -->
+- Couche d'accès aux données : Repository pattern avec SQLAlchemy async sessions, abstraction BDD pour faciliter tests et évolution <!-- complété par codex -->
 
 ## Qualité & exploitation
-- Observabilité (logs/metrics/traces = journaux/mesures/traces) : <A COMPLETER PAR AGENT>
-- Tests (unitaires/intégration) : <A COMPLETER PAR AGENT>
-- Performance attendue : <A REMPLIR - PROJET> (exemple: à personnaliser — a supprimer)
+- Observabilité : Logs structurés avec loguru (format JSON), endpoint `/health` pour healthcheck, pas de tracing distribué (monolithe) <!-- complété par codex -->
+- Tests : pytest avec tests unitaires (services/), tests intégration (routers/ avec TestClient), fixtures pour BDD test, couverture 70%+ sur logique métier <!-- complété par codex -->
+- Performance attendue : Réponse API <200ms pour GET simple, <500ms pour recherche full-text, upload fichiers <5s pour 10MB, pas de contrainte scalabilité (mono-utilisateur) <!-- complété par codex -->
 
 ## Conventions
-- Organisation du code : <A COMPLETER PAR AGENT>
-- Nommage : <A COMPLETER PAR AGENT>
-- Gestion erreurs : <A COMPLETER PAR AGENT>
+- Organisation du code : `backend/app/` racine, sous-dossiers par responsabilité (routers/, services/, models/, schemas/, repositories/), un fichier par entité <!-- complété par codex -->
+- Nommage : snake_case pour tout (variables, fonctions, fichiers), préfixes get_/create_/update_/delete_ pour CRUD, suffixes _service/_repository selon couche <!-- complété par codex -->
+- Gestion erreurs : HTTPException FastAPI pour erreurs API avec codes standards (400/404/500), exceptions métier custom héritant de BaseException, logging erreurs avec contexte <!-- complété par codex -->
 
----
-
-## Exemple (a supprimer)
-- Style : monolithe modulaire avec modules `users`, `billing`, `catalog`.
-- API : REST `/api/v1` + JWT (Jeton d’authentification).
-- DB : PostgreSQL, migrations via outils natifs.
+---