geo/api/CLAUDE.md

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