# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. --- ## Vue d'ensemble du projet **HomeStock** est une webapp de gestion d'inventaire domestique (style Homebox) permettant de cataloguer et gérer les équipements, matériels et consommables présents au domicile. ### Domaines couverts - Bricolage - Informatique - Électronique - Cuisine ### Fonctionnalités principales - Catalogue d'objets avec caractéristiques détaillées - Gestion des photos, notices et factures - Suivi des prix et du stock - Gestion de l'état (en utilisation / en stock) - Localisation précise (lieu, meuble, tiroir, boîte) --- ## Architecture du projet ### Structure globale Le projet suit une architecture **monolithe modulaire** avec séparation frontend/backend : ``` / ├── backend/ # API et logique métier ├── frontend/ # Interface utilisateur ├── contracts/ # Contrats d'API (OpenAPI) et modèles de données ├── docs/ # Documentation technique et ADR ├── product/ # Documentation produit (vision, backlog, roadmap) ├── tasks/ # Fichiers de tâches pour le découpage du travail └── scripts/ # Scripts de développement et maintenance ``` ### Fichiers de contexte clés - [a-lire.md](a-lire.md) : Instructions d'initialisation du projet - [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) : Contexte global et contraintes - [outils_dev_pref.md](outils_dev_pref.md) : Environnement et préférences de développement - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) : **À lire avant toute décision technique** - [backend/CONTEXT.md](backend/CONTEXT.md) : Contexte spécifique au backend - [frontend/CONTEXT.md](frontend/CONTEXT.md) : Contexte spécifique au frontend --- ## Workflow de développement ### 1. Documentation d'abord **IMPORTANT** : Aucun code ne doit être écrit tant que la documentation n'est pas complétée : - [product/VISION.md](product/VISION.md) doit être rempli - [product/BACKLOG.md](product/BACKLOG.md) doit contenir les exigences (REQ-XXX) - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) doit être lu et compris ### 2. Gestion des zones à remplir Le projet utilise un système de marqueurs pour identifier les sections à compléter : - `` : À compléter par l'utilisateur selon le contexte du projet - **Ne jamais supprimer** ce marqueur sans le remplacer - Ajouter un exemple guidant avec la mention "(exemple: ... — a supprimer)" - `` : À compléter par Claude Code lors des décisions techniques - Remplacer par le contenu approprié - Ajouter "complété par codex" en commentaire après remplissage ### 3. Décisions architecturales (ADR) Toute décision structurante doit être documentée dans un ADR (Architecture Decision Record) : - Créer un nouveau fichier dans [docs/adr/](docs/adr/) - Utiliser le template [docs/adr/TEMPLATE.md](docs/adr/TEMPLATE.md) - Exemples : choix de base de données, framework, pattern d'authentification, etc. ### 4. Découpage des tâches - Toute tâche de développement doit avoir un fichier dans [tasks/](tasks/) - Utiliser le template [tasks/TEMPLATE.md](tasks/TEMPLATE.md) - Une tâche = un objectif clair + critères d'acceptation + fichiers concernés --- ## Commandes de développement ### Démarrage ```bash make dev # Lancer l'environnement de développement docker-compose up # Alternative avec Docker ``` ### Tests et qualité ```bash ./scripts/test.sh # Exécuter les tests ./scripts/lint.sh # Linter le code ./scripts/fmt.sh # Formater le code ``` ### Base de données ```bash ./scripts/db/backup.sh # Sauvegarder la base de données ./scripts/db/restore.sh # Restaurer une sauvegarde ``` **Note** : Ces scripts sont actuellement vides et doivent être complétés lors de l'implémentation. --- ## Conventions de code ### Langue - **Français uniquement** pour toute la documentation et les commentaires - Toujours expliquer les acronymes : "JWT = jeton d'authentification", "RGPD = Règlement Général sur la Protection des Données" - Les noms de variables/fonctions peuvent être en anglais selon les conventions du langage ### Style de documentation - Commentaires courts et utiles uniquement - Éviter les répétitions entre code et documentation - Privilégier la clarté à la concision ### Organisation du code - Suivre l'organisation définie dans [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Respecter les conventions du [docs/STYLEGUIDE.md](docs/STYLEGUIDE.md) - Maintenir la séparation frontend/backend stricte --- ## Contrats d'API Le répertoire [contracts/](contracts/) contient les spécifications d'API : - [contracts/openapi.yaml](contracts/openapi.yaml) : Spécification OpenAPI - [contracts/data_model.md](contracts/data_model.md) : Modèle de données - [contracts/errors.md](contracts/errors.md) : Gestion des erreurs - [contracts/pagination.md](contracts/pagination.md) : Convention de pagination - [contracts/import/](contracts/import/) : Schémas d'import/export **Important** : Toute modification d'API doit mettre à jour ces contrats. --- ## Environnement technique ### Configuration - OS : Debian 13 - IDE : VS Code - Conteneurs : Docker 29.1.5+ - Git : Gitea (https://gitea.maison43.duckdns.org/) - Timezone : Europe/Paris - Réseau local : 10.0.0.0/22 ### Stack technique (à finaliser) - **Frontend** : À définir dans [frontend/CONTEXT.md](frontend/CONTEXT.md) - **Backend** : Python ou Go (préférence indiquée dans [outils_dev_pref.md](outils_dev_pref.md)) - **Base de données** : À définir via ADR - **Stockage fichiers** : À définir (photos, notices, factures) ### Thème UI - Préférences : Gruvbox, Dark, Vintage - Monokai Dark - À définir : couleurs dominantes, style UI, accessibilité --- ## Processus de contribution ### Pull Requests - Consulter [docs/PR_CHECKLIST.md](docs/PR_CHECKLIST.md) avant de créer une PR - Suivre le workflow défini dans [docs/WORKFLOW.md](docs/WORKFLOW.md) - Une PR = une fonctionnalité / un fix ### Qualité - Indiquer les tests attendus même si non implémentés - Mettre à jour toute documentation impactée - Vérifier que les marqueurs `` ne sont pas supprimés par erreur ### Sécurité - Consulter [docs/SECURITY.md](docs/SECURITY.md) - Pas de secrets en clair dans le code - Respecter les contraintes RGPD si applicable --- ## Ordre des opérations pour démarrer 1. **Compléter la documentation de base** - Remplir [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) - Compléter [product/VISION.md](product/VISION.md) - Définir les premières exigences dans [product/BACKLOG.md](product/BACKLOG.md) 2. **Définir l'architecture technique** - Compléter [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Créer les ADR pour les choix techniques majeurs - Finaliser [backend/CONTEXT.md](backend/CONTEXT.md) et [frontend/CONTEXT.md](frontend/CONTEXT.md) 3. **Configurer l'environnement** - Compléter [outils_dev_pref.md](outils_dev_pref.md) - Configurer les scripts de développement - Mettre en place Docker et docker-compose 4. **Démarrer l'implémentation** - Créer les tâches dans [tasks/](tasks/) - Suivre le workflow défini - Documenter les décisions au fur et à mesure --- ## Références - **Documentation produit** : [product/](product/) - **Documentation technique** : [docs/](docs/) - **Tâches** : [tasks/](tasks/) - **Opérations** : [docs/OPERATIONS.md](docs/OPERATIONS.md) - **Déploiement** : [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)