mesreleves-php/CLAUDE.md

CLAUDE.md

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

Project Overview

MesRelevés — Application web PHP/PostgreSQL pour une association de généalogie. Elle permet la saisie systématique de relevés d'actes (naissance, mariage, décès, etc.), la recherche dans ces relevés, et l'export au format GEDCOM.

Tech Stack

• Backend : PHP 8.2+, framework Laravel 11
• Base de données : PostgreSQL 16 (JSONB pour les champs variables des relevés, full-text search natif)
• Frontend : Blade templates + Alpine.js (interactivité légère) + Tailwind CSS
• Auth : Laravel Breeze (sessions, middleware de rôles custom)
• Cache : Redis (Laravel Cache) pour les listes de lieux et requêtes fréquentes

Development Commands

# Installation
composer install
npm install && npm run build
cp .env.example .env && php artisan key:generate

# Base de données
php artisan migrate
php artisan migrate:fresh --seed   # reset + données de test

# Serveur de développement
php artisan serve                  # http://localhost:8000
npm run dev                        # Vite en watch (CSS/JS)

# Tests
php artisan test                   # tous les tests
php artisan test --filter=NomTest  # un test précis
php artisan test --testsuite=Feature

# Qualité de code
./vendor/bin/pint                  # formatage PHP (Laravel Pint)
./vendor/bin/phpstan analyse       # analyse statique

Architecture

app/
  Models/          # Eloquent models
  Http/
    Controllers/   # un controller par entité métier
    Middleware/    # RoleMiddleware (admin, section_manager, member)
    Requests/      # Form requests avec validation
  Policies/        # Autorisation par modèle (Laravel Gates/Policies)
  Services/        # Logique métier complexe (ex: GedcomExportService, DateConversionService)
  Enums/           # SourceStatus, UserRole, CalendarType
database/
  migrations/
  seeders/
resources/
  views/
    layouts/
    sections/
    sources/
    releves/       # formulaires dynamiques pilotés par source_type
    lieux/
    admin/
routes/
  web.php          # routes principales
  admin.php        # routes admin (prefix /admin, middleware admin)

Domain Model (entités clés)

Utilisateurs et rôles

• users : id, name, email, role (admin | section_manager | member)
• section_user (pivot) : user_id, section_id, role_in_section
• Un utilisateur peut appartenir à plusieurs sections locales.

Sections locales

• Champs : nom, lieu_id (FK), adresse, email_contact, url

Dépôts d'archives

• Champs : nom, description, adresse_postale, url

Lieux

• Champs : nom, code, lieu_parent_id (FK self-référentiel), nom_long (calculé), latitude, longitude, note
• nom_long est généré automatiquement en concaténant les noms des ancêtres (ex. "Bordeaux, Gironde, France").

Types de sources (SourceType)

• Définissent les champs dynamiques du formulaire de saisie.
• Stocké comme : source_types (id, nom, description) + source_type_fields (id, source_type_id, name, label, type, required, order, options JSON)
• Types de champ possibles : text, date, boolean, select, textarea, number
• L'ajout/modification d'un type de source ne doit pas casser les relevés existants (les champs JSONB contiennent toujours l'ancienne structure).

Sources

• Champs : nom, description, source_type_id, depot_id, cote, auteur, status
• Status (enum) : a_faire → en_cours → a_valider → termine
• Une source est créée uniquement par admin ou responsable de section, avec status initial a_faire.
• Table pivot source_user : assignation des membres à une source.
• Visibilité des relevés : status termine → visible par tous les membres ; sinon → visible uniquement par admin et membres de section assignés.

Relevés (releves)

• Schéma : id, source_id, data (JSONB — champs variables selon le source_type), created_by, created_at, updated_by, updated_at
• Le JSONB est la solution retenue pour la flexibilité et la performance (pas de colonnes dynamiques, pas d'ALTER TABLE).
• Les colonnes les plus recherchées (nom, prénom, date) sont extraites dans des colonnes indexées générées : ALTER TABLE releves ADD COLUMN nom TEXT GENERATED ALWAYS AS (data->>'nom') STORED; + index GIN sur data pour la recherche fulltext.
• Pagination obligatoire (25 par page minimum), jamais de SELECT * sans LIMIT.

Dates

• Chaque date stocke : { "valeur": "1792-09-22", "calendrier": "republicain" }
• Calendriers supportés : gregorien, julien, republicain
• Service DateConversionService gère la conversion vers/depuis le calendrier républicain (An I = 22 sept 1792).

Règles d'autorisation

Action	Admin	Resp. Section	Membre assigné	Membre	Visiteur
Créer une source	✓	✓ (sa section)
Assigner un membre à une source	✓	✓ (sa section)
Saisir/modifier un relevé	✓	✓	✓
Voir relevés (status termine)	✓	✓	✓	✓
Voir relevés (autres status)	✓	✓ (sa section)	✓ (assigné)
Passer status → a_valider	✓	✓	✓ (assigné)
Passer status → termine	✓	✓ (sa section)
Gérer utilisateurs / sections	✓

Workflow de statut d'une source

a_faire → en_cours → a_valider → termine
                   ↑____________| (rejet possible par admin/resp.)

Lors du passage en a_valider, une notification (mail + notification interne) est envoyée à l'admin et au(x) responsable(s) de la section.

Performance

• Index GIN sur releves.data (recherche JSONB).
• Colonnes générées stockées + index B-tree pour les champs les plus filtrés (nom, date_evenement).
• Eager loading systématique (with()) pour éviter les requêtes N+1.
• Cache Redis (TTL 1h) sur la liste des lieux (arbre hiérarchique).
• Pagination curseur (keyset) plutôt qu'offset pour les listes de relevés volumineuses.

Export GEDCOM

• GedcomExportService : génère un fichier .ged à partir d'une source ou d'une sélection de relevés.
• Format GEDCOM 5.5.1.
• Conversion des dates : toujours en grégorien dans le GEDCOM (les calendriers julien/républicain sont convertis).

Étapes de construction (ordre suggéré)

1. Scaffold Laravel + config PostgreSQL + auth Breeze + middleware rôles
2. Migrations et modèles : lieux, sections, users, depots, source_types, source_type_fields, sources, source_user, releves
3. CRUD Lieux (avec arbre hiérarchique et calcul nom_long)
4. CRUD Sections, Dépôts, Types de sources (admin)
5. CRUD Sources + assignation de membres
6. Formulaire de saisie dynamique des relevés (piloté par source_type_fields)
7. Workflow de statut + notifications
8. Recherche dans les relevés (fulltext PostgreSQL)
9. Export GEDCOM
10. Interface admin (gestion utilisateurs, statistiques)