# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Directives importantes
- **Langue** : Toujours répondre en français
- **Approche de travail** : 
  - Travailler par étapes claires et structurées
  - TOUJOURS présenter et proposer les modifications avant de les implémenter
  - Attendre la validation de l'utilisateur avant de modifier le code
  - Expliquer le problème identifié et la solution proposée
- **Vérification du schéma** : TOUJOURS vérifier `docs/geo_app.sql` avant de faire des modifications sur les tables de la base de données

## Build Commands
- Install dependencies: `composer install` - install PHP dependencies
- Update dependencies: `composer update` - update PHP dependencies to latest versions
- Deploy to DEV: `./deploy-api.sh` - deploy local code to dva-geo on IN3 (195.154.80.116)
- Deploy to REC: `./deploy-api.sh rca` - deploy from dva-geo to rca-geo on IN3
- Deploy to PROD: `./deploy-api.sh pra` - deploy from rca-geo (IN3) to pra-geo (IN4)
- Export operations: `php export_operation.php` - export operations data

## Development Environment
- **DEV Container**: dva-geo on IN3 server (195.154.80.116)
- **DEV API URL Public**: https://dapp.geosector.fr/api/
- **DEV API URL Internal**: http://13.23.33.43/api/
- **Access**: Via Incus container on IN3 server

## Code Architecture
This is a PHP 8.3 API without framework, using a custom MVC-like architecture:

- **Entry point**: `index.php` handles all requests through custom Router
- **Core components**:
  - `Router`: Maps URLs to controller methods, handles HTTP methods
  - `Database`: PDO wrapper for MariaDB connections
  - `Session`: Secure session management
  - `Request/Response`: HTTP request/response handling
- **Controllers**: Located in `src/Controllers/`, handle business logic
- **Services**: Located in `src/Services/`, provide reusable functionality (logging, email, exports)
- **Configuration**: `src/Config/AppConfig.php` - singleton configuration management

## Key Patterns
- No framework dependency - pure PHP 8.3 with composer autoloading
- PDO for database access with prepared statements
- RESTful API design with JSON responses
- CORS handling for cross-origin requests
- Session-based authentication
- File uploads handled in `uploads/` directory
- Logs stored in `logs/` directory

## Database
- MariaDB 10.11 with InnoDB tables
- Migration scripts in `scripts/php/migrate_*.php`
- Schema comparison tool: `scripts/python/compare_schemas.py`
- Database sync: `scripts/cron/sync_databases.php`

## Security Considerations
- Session cookies with httponly, secure flags
- CORS configured for specific origins
- XSS, clickjacking protection headers
- PDO prepared statements for SQL injection prevention
- File upload validation in FileService

## Bonnes pratiques spécifiques

### Gestion des transactions PDO
- Toujours vérifier `$db->inTransaction()` avant d'appeler `rollBack()`
- Encadrer les opérations critiques dans des try/catch avec transaction

### Paramètres SQL
- Utiliser des noms de paramètres uniques dans les requêtes SQL
- Ne jamais réutiliser le même nom de paramètre plusieurs fois dans une requête
- Exemple : `:sector_polygon1`, `:sector_polygon2` au lieu de `:sector_polygon` répété

### Format des réponses API
- Les données doivent être placées à la racine de la réponse JSON, pas dans un groupe "data"
- Suivre le modèle de `LoginController` pour la structure des réponses
- Retourner des objets complets, pas seulement des IDs (ex: sector complet, pas sector_id)

### Gestion des sessions
- La session stocke `entity_id` depuis `fk_entite` lors du login
- Utiliser `Session::getEntityId()` pour récupérer l'ID de l'entité
- L'authentification utilise des Bearer tokens contenant le session_id