generated from gilles/template-webapp
213 lines
7.5 KiB
Markdown
213 lines
7.5 KiB
Markdown
# 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 :
|
|
|
|
- `<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)
|