claude code

CLAUDE.md

@@ -1,37 +1,212 @@
-# Consignes strictes — Claude Code
+# CLAUDE.md
 
-Ces consignes sont obligatoires pour toute intervention avec Claude Code.
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ---
 
-## 1. Lecture préalable obligatoire
-- Lire `a-lire.md`, `PROJECT_CONTEXT.md`, `outils_dev_pref.md`.
-- Lire `docs/ARCHITECTURE.md` avant toute décision technique.
+## Vue d'ensemble du projet
 
-## 2. Gestion des zones
-- Ne jamais supprimer `<A REMPLIR - PROJET>`.
-- Ajouter un exemple guidant avec la mention "a supprimer".
-- Utiliser `<A COMPLETER PAR AGENT>` pour les choix techniques.
+**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.
 
-## 3. Documentation avant code
-- Aucun code tant que `product/VISION.md` et `product/BACKLOG.md` ne sont pas complétés.
-- Toute décision structurante → ajouter un ADR dans `docs/adr/`.
+### Domaines couverts
+- Bricolage
+- Informatique
+- Électronique
+- Cuisine
 
-## 4. Style d’écriture
-- Français uniquement.
-- Éviter les acronymes seuls : toujours expliquer (ex: "MFA = authentification multi‑facteurs").
-- Commentaires courts et utiles.
-
-## 5. Découpage des tâches
-- Toute tâche doit être dans `tasks/`.
-- Une tâche = un objectif clair + critères d’acceptation.
-- Mentionner les fichiers autorisés.
-
-## 6. Qualité
-- Indiquer les tests attendus même si non exécutés.
-- Mettre à jour la documentation impactée.
+### 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)
 
 ---
 
-## Exemple (a supprimer)
-- "Ajouter ADR-0002 pour le choix de base de données."
+## 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 :
+
+- `<A REMPLIR - PROJET>` : À 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)"
+
+- `<A COMPLETER PAR AGENT>` : À 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 `<A REMPLIR>` 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)