mesreleves-php/README.md

# MesRelevés

Application web de saisie et de recherche de relevés généalogiques pour associations.  
Permet la saisie collaborative de relevés d'actes (naissance, mariage, décès, etc.), la recherche plein texte et l'export au format GEDCOM 5.5.1.

---

## Installation sur hébergement mutualisé (recommandé)

### Prérequis serveur

| Composant | Version minimale |
|---|---|
| PHP | 8.2 avec extensions : `pdo_mysql`, `mbstring`, `openssl`, `tokenizer`, `xml`, `ctype`, `fileinfo`, `bcmath`, `curl` |
| MySQL / MariaDB | MySQL 8.0+ ou MariaDB 10.5+ |
| Serveur web | Apache (mod_rewrite activé) ou Nginx |
| Accès fichier | Écriture sur `storage/` et `bootstrap/cache/` |

> **PostgreSQL** est également supporté et recommandé pour les grandes bases de relevés (full-text search natif, JSONB). Voir la section [Docker](#docker) pour une installation avec PostgreSQL.

---

### Étape 1 — Télécharger et décompresser l'archive

Récupérez la dernière archive depuis la page des [releases](https://git.barbel.synology.me/CGL/mesreleves-php/releases) :

```
mesreleves-X.Y.Z.tar.gz
```

Décompressez-la dans le dossier de votre hébergement (via FTP ou le gestionnaire de fichiers du panneau de contrôle) :

```bash
tar -xzf mesreleves-X.Y.Z.tar.gz
```

Cela crée un dossier `mesreleves/` contenant toute l'application.

---

### Étape 2 — Faire pointer le site vers `public/`

Le point d'entrée de l'application est le dossier `public/`.  
**Le dossier racine de votre site (document root) doit pointer sur `public/`, pas sur la racine de l'archive.**

**Exemples de configurations :**

<details>
<summary>Apache — <code>.htaccess</code> (déjà inclus dans <code>public/</code>)</summary>

Rien à faire : le `.htaccess` livré avec l'application configure automatiquement la réécriture d'URL. Vérifiez que `mod_rewrite` est activé sur votre hébergement.

Si vous ne pouvez pas modifier le document root, vous pouvez déposer les fichiers directement dans le dossier `public_html/` de votre hébergement en copiant le contenu de `public/` à sa racine et en adaptant le chemin dans `index.php` :

```php
// public/index.php — adapter le chemin si l'arborescence est modifiée
require __DIR__.'/../mesreleves/vendor/autoload.php';
$app = require_once __DIR__.'/../mesreleves/bootstrap/app.php';
```

</details>

<details>
<summary>Nginx</summary>

```nginx
server {
    listen 80;
    server_name votre-domaine.fr;
    root /var/www/mesreleves/public;

    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }
}
```

</details>

---

### Étape 3 — Lancer l'assistant d'installation

Ouvrez votre navigateur sur `https://votre-domaine.fr/setup`.

L'assistant vous guide à travers **5 étapes** :

1. **Prérequis** — vérification automatique des extensions PHP et des droits d'écriture
2. **Base de données** — saisie des paramètres MySQL/PostgreSQL ; un bouton « Tester la connexion » valide la configuration avant de continuer
3. **Application** — nom du site, URL de base, activation des inscriptions publiques
4. **Compte administrateur** — création du premier compte admin
5. **Installation** — migrations, génération de la clé d'application, résumé

> L'assistant crée automatiquement le fichier `.env` et exécute toutes les migrations.  
> Une fois terminé, la page `/setup` est désactivée.

---

### Étape 4 — Configurer les tâches planifiées (optionnel)

Pour activer les notifications par e-mail et la vérification automatique des mises à jour, ajoutez cette ligne à votre `crontab` (via le panneau de contrôle de l'hébergement → **Tâches planifiées / Cron**) :

```
* * * * * php /chemin/absolu/vers/mesreleves/artisan schedule:run >> /dev/null 2>&1
```

Remplacez `/chemin/absolu/vers/mesreleves/` par le chemin réel sur votre serveur (visible dans le gestionnaire de fichiers, généralement `/home/user/www/mesreleves/`).

---

### Mise à jour

Dans **Administration → Paramètres du site → Version du logiciel**, le tableau de bord signale automatiquement les nouvelles versions disponibles (si la vérification n'est pas désactivée et que les tâches planifiées sont actives).

**Pour appliquer une mise à jour manuellement :**

1. Télécharger la nouvelle archive `mesreleves-X.Y.Z.tar.gz`
2. Décompresser et écraser les fichiers existants (**sauf** `.env` et `storage/`)
3. Exécuter les migrations depuis un terminal SSH :
   ```bash
   php artisan migrate --force
   php artisan optimize:clear
   ```

---

## Fonctionnalités

- **Saisie collaborative** — formulaires dynamiques pilotés par des types de sources configurables
- **Calendriers** — saisie en calendrier grégorien, julien ou républicain avec conversion automatique
- **Recherche plein texte** — filtrable par type de source, lieu (avec subdivisions récursives) et plage d'années
- **Gestion des lieux** — arbre hiérarchique (pays → région → département → commune…), types configurables
- **Workflow de validation** — statuts `à faire → en cours → à valider → terminé`, notifications mail + in-app
- **Export GEDCOM 5.5.1** — par source ou par sélection de recherche, conversion des dates vers le grégorien
- **Gestion des rôles** — administrateur, responsable de section, membre ; autorisations granulaires par source
- **Interface admin** — tableau de bord, gestion des utilisateurs, sections, dépôts d'archives, types de sources
- **Import / export CSV** — gestion en masse des utilisateurs
- **Mode sombre** — détection automatique, commutable manuellement (clair / sombre / automatique)
- **2FA par e-mail** — code PIN à 6 chiffres à la connexion, activé dès qu'un serveur SMTP est configuré

---

## Stack technique

| Composant | Technologie |
|---|---|
| Backend | PHP 8.2+ · Laravel 12 |
| Base de données | MySQL 8.0+ / MariaDB 10.5+ · ou PostgreSQL 16+ |
| Frontend | Blade · Alpine.js · Tailwind CSS |
| Auth | Laravel Breeze (sessions) |

---

## Docker

Installation avec Docker Compose : **PHP-FPM + Nginx + PostgreSQL** (pas de Redis — cache, sessions et queue utilisent la base de données).

> La stack Docker utilise exclusivement **PostgreSQL**. Pour MySQL, utilisez l'installation manuelle sur hébergement mutualisé décrite ci-dessus.

### Prérequis

- Docker Engine ≥ 24
- Docker Compose v2 (`docker compose version`)

### Première installation

**1. Extraire l'archive**

```bash
tar -xzf mesreleves-X.Y.Z.tar.gz
cd mesreleves
```

**2. Premier lancement — création du `.env`**

```bash
./install.sh
```

Le script détecte l'absence de `.env`, le crée depuis `.env.example` et s'arrête pour vous laisser le configurer.

**3. Configurer `.env`**

Ouvrez `.env` et renseignez au minimum :

```env
APP_URL=https://votre-domaine.fr

DB_PASSWORD=mot_de_passe_fort          # mot de passe PostgreSQL
DB_DATABASE=mesreleves                 # nom de la base (créée automatiquement)
DB_USERNAME=mesreleves                 # utilisateur PostgreSQL
```

> **`APP_KEY`** est généré automatiquement au premier démarrage — laissez-le vide.  
> **SMTP** peut être configuré après installation via **Administration → Paramètres du site** (le 2FA par e-mail s'active dès qu'un serveur SMTP est enregistré).

**4. Installation complète**

```bash
./install.sh
```

Le script :
1. Construit l'image Docker (php-fpm 8.5, extensions PostgreSQL)
2. Démarre les services `app`, `nginx` et `db`
3. Attend que PostgreSQL soit prêt
4. Exécute les migrations
5. Crée le lien symbolique `storage/`
6. Affiche la commande crontab à copier

L'application est accessible sur **http://votre-domaine.fr** (port 80).

### Commandes courantes

```bash
# Voir les logs en temps réel
docker compose -f docker-compose.prod.yml logs -f app

# Ouvrir un shell dans le container
docker compose -f docker-compose.prod.yml exec app sh

# Relancer après modification du .env
docker compose -f docker-compose.prod.yml restart app
```

### Tâches planifiées

Ajoutez à votre crontab (`crontab -e`) la ligne affichée à la fin de `./install.sh` :

```
* * * * * cd /chemin/vers/mesreleves && docker compose -f docker-compose.prod.yml exec -T app php artisan schedule:run >> /dev/null 2>&1
```

### Mises à jour

Vérifier la version disponible :

```bash
docker compose -f docker-compose.prod.yml exec app php artisan app:check-update
```

Appliquer une mise à jour (sauvegarde BDD → téléchargement → migrations) :

```bash
docker compose -f docker-compose.prod.yml exec app php artisan app:update
```

Lister les sauvegardes et restaurer en cas de problème :

```bash
docker compose -f docker-compose.prod.yml exec app php artisan app:rollback --list
docker compose -f docker-compose.prod.yml exec app php artisan app:rollback
```

---

## Développement

### Prérequis

- PHP 8.2+, Composer, Node.js 20+
- MySQL 8+ / MariaDB 10.5+ ou PostgreSQL 16+

### Démarrage rapide

```bash
composer install
npm install && npm run build

cp .env.example .env
php artisan key:generate

# Démarrer la base de données (Docker)
docker compose up -d

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

php artisan serve       # http://localhost:8000
npm run dev             # Vite en watch (CSS/JS)
```

Comptes de test créés par le seeder :

| E-mail | Rôle | Mot de passe |
|---|---|---|
| `admin@mesreleves.local` | Administrateur | `password` |
| `responsable@mesreleves.local` | Responsable de section | `password` |
| `membre@mesreleves.local` | Membre | `password` |

### Commandes utiles

```bash
php artisan test                        # tous les tests
php artisan test --filter=NomTest       # un test précis
./vendor/bin/pint                       # formatage PHP (Laravel Pint)
./vendor/bin/phpstan analyse            # analyse statique
```

### Créer une release

```bash
echo "1.1.0" > VERSION
git add VERSION && git commit -m "bump version 1.1.0"

bin/build-release.sh
# → mesreleves-1.1.0.tar.gz

git tag v1.1.0 && git push origin v1.1.0
```

---

## Architecture

```
app/
  Models/           Eloquent : User, Source, Releve, Lieu, Section, Depot…
  Http/
    Controllers/    Un controller par entité (+ Admin/ + Auth/)
    Middleware/     RoleMiddleware, CheckInstallation, EnsureUserIsActive
    Requests/       Form requests avec validation
  Policies/         Autorisation par modèle
  Services/         GedcomExportService, DateConversionService, UpdateService,
                    SiteSettingsService
  Enums/            SourceStatus, UserRole, CalendarType, FieldType
database/
  migrations/       Schéma complet (lieux, sections, sources, relevés…)
  seeders/          Données de démonstration
resources/views/
  layouts/          Navigation (sélecteur de thème), app layout, guest layout
  components/       lieu-picker, user-picker (recherche modale), dropdown…
  setup/            Assistant d'installation en 5 étapes
  sources/          CRUD + workflow de statut
  releves/          Formulaire dynamique par type de source
  recherche/        Recherche plein texte + filtres
  admin/            Tableau de bord, utilisateurs, sections, dépôts, paramètres
```

---

## Licence

Usage interne — association de généalogie.