yann64
9efb6d6093
Description du projet, stack technique, instructions d'installation Docker, procédures de mise à jour (manuelle, automatique, rollback), guide de développement, commandes utiles, procédure de release et aperçu de l'architecture. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
236 lines
6.9 KiB
Markdown
236 lines
6.9 KiB
Markdown
# 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.
|
|
|
|
## Fonctionnalités
|
|
|
|
- **Saisie collaborative** — formulaires dynamiques pilotés par des types de sources configurables ; champs libres stockés en JSONB PostgreSQL
|
|
- **Calendriers** — saisie en calendrier grégorien, julien ou républicain avec conversion automatique
|
|
- **Recherche plein texte** — recherche PostgreSQL native sur les relevés, 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 de lieux configurables, recherche par picker contextuel
|
|
- **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 statistiques, gestion des utilisateurs, sections, dépôts, types de sources et de lieux
|
|
- **Mises à jour automatiques** — vérification quotidienne via l'API Gitea, application sans rebuild Docker
|
|
|
|
## Stack technique
|
|
|
|
| Composant | Technologie |
|
|
|---|---|
|
|
| Backend | PHP 8.5 · Laravel 12 |
|
|
| Base de données | PostgreSQL 18 (JSONB, full-text search, CTE récursives) |
|
|
| Cache / Sessions | Redis 7 |
|
|
| Frontend | Blade · Alpine.js · Tailwind CSS |
|
|
| Auth | Laravel Breeze (sessions) |
|
|
| Conteneurs | Docker + Docker Compose |
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Prérequis
|
|
|
|
- Docker Engine ≥ 24
|
|
- Docker Compose v2 (`docker compose version`)
|
|
|
|
### Première installation
|
|
|
|
**1. Télécharger la dernière release**
|
|
|
|
Récupérez l'archive `mesreleves-X.Y.Z.tar.gz` depuis la page des [releases](https://git.barbel.synology.me/CGL/mesreleves-php/releases) et extrayez-la :
|
|
|
|
```bash
|
|
tar -xzf mesreleves-X.Y.Z.tar.gz
|
|
cd mesreleves-X.Y.Z
|
|
```
|
|
|
|
**2. Lancer le script d'installation**
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
Le script crée un `.env` depuis `.env.example` puis s'arrête pour vous laisser le configurer.
|
|
Éditez `.env` avec vos paramètres :
|
|
|
|
```env
|
|
APP_URL=https://votre-domaine.fr
|
|
APP_KEY= # généré automatiquement au démarrage
|
|
|
|
DB_PASSWORD=mot_de_passe_fort
|
|
|
|
MAIL_MAILER=smtp
|
|
MAIL_HOST=smtp.example.com
|
|
MAIL_PORT=587
|
|
MAIL_USERNAME=...
|
|
MAIL_PASSWORD=...
|
|
MAIL_FROM_ADDRESS=mesreleves@example.com
|
|
```
|
|
|
|
**3. Relancer le script**
|
|
|
|
```bash
|
|
./install.sh
|
|
```
|
|
|
|
L'application est accessible sur le port 80 (ou la valeur de `APP_URL`).
|
|
|
|
**4. Activer les tâches planifiées** (optionnel — nécessaire pour la vérification automatique des mises à jour)
|
|
|
|
Ajoutez à votre crontab (`crontab -e`) la ligne affichée à la fin du script d'installation :
|
|
|
|
```
|
|
* * * * * 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 installée et les mises à jour disponibles
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml exec app php artisan app:check-update
|
|
```
|
|
|
|
### Appliquer une mise à jour
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml exec app php artisan app:update
|
|
```
|
|
|
|
Le processus :
|
|
1. Sauvegarde PostgreSQL dans `storage/app/backups/`
|
|
2. Téléchargement de la nouvelle archive
|
|
3. Synchronisation des fichiers (`.env` et `storage/` préservés)
|
|
4. `composer install --no-dev`
|
|
5. Migrations
|
|
6. Rechargement gracieux de php-fpm
|
|
7. L'application est disponible pendant toute l'opération (sauf la fenêtre de migration)
|
|
|
|
### Mise à jour automatique
|
|
|
|
Pour activer la mise à jour automatique lors de la vérification planifiée, ajoutez dans `.env` :
|
|
|
|
```env
|
|
AUTO_UPDATE=true
|
|
```
|
|
|
|
> Par défaut `AUTO_UPDATE=false` : la vérification quotidienne notifie uniquement dans le tableau de bord admin.
|
|
|
|
### Rollback
|
|
|
|
En cas de problème, lister les sauvegardes disponibles :
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml exec app php artisan app:rollback --list
|
|
```
|
|
|
|
Restaurer la base de données :
|
|
|
|
```bash
|
|
docker compose -f docker-compose.prod.yml exec app php artisan app:rollback
|
|
```
|
|
|
|
---
|
|
|
|
## Développement
|
|
|
|
### Prérequis
|
|
|
|
- PHP 8.2+, Composer, Node.js 20+, npm
|
|
- PostgreSQL 16+ ou Docker
|
|
|
|
### Démarrage rapide
|
|
|
|
```bash
|
|
# Cloner et installer les dépendances
|
|
composer install
|
|
npm install && npm run build
|
|
|
|
# Configuration
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
|
|
# Démarrer PostgreSQL et Redis (Docker)
|
|
docker compose up -d
|
|
|
|
# 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)
|
|
```
|
|
|
|
Compte administrateur créé par le seeder :
|
|
|
|
| Champ | Valeur |
|
|
|---|---|
|
|
| E-mail | `admin@example.com` |
|
|
| Mot de passe | `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
|
|
|
|
php artisan app:check-update # vérifier les mises à jour
|
|
php artisan app:update # appliquer une mise à jour
|
|
php artisan app:rollback --list # lister les sauvegardes
|
|
```
|
|
|
|
### Créer une release
|
|
|
|
```bash
|
|
# Modifier VERSION (ex : 1.1.0)
|
|
echo "1.1.0" > VERSION
|
|
git add VERSION && git commit -m "bump version 1.1.0"
|
|
|
|
# Construire l'archive
|
|
bin/build-release.sh
|
|
# → mesreleves-1.1.0.tar.gz + mesreleves-1.1.0.tar.gz.sha256
|
|
|
|
# Publier
|
|
git tag v1.1.0 && git push origin v1.1.0
|
|
# Créer une release sur Gitea et joindre les deux fichiers
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
app/
|
|
Models/ Eloquent : User, Source, Releve, Lieu, Section, Depot…
|
|
Http/
|
|
Controllers/ Un controller par entité (+ Admin/ pour la gestion)
|
|
Middleware/ RoleMiddleware (admin, section_manager, member)
|
|
Requests/ Form requests avec validation dynamique
|
|
Policies/ Autorisation par modèle (Gates/Policies)
|
|
Services/ GedcomExportService, DateConversionService, UpdateService
|
|
Enums/ SourceStatus, UserRole, CalendarType, FieldType
|
|
database/
|
|
migrations/ 10 migrations (lieux, sections, sources, relevés…)
|
|
seeders/ Données de démonstration
|
|
resources/views/
|
|
layouts/ Navigation, app layout
|
|
components/ lieu-picker (Alpine.js + AJAX)
|
|
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…
|
|
bin/
|
|
build-release.sh Construction de l'archive de distribution
|
|
```
|
|
|
|
## Licence
|
|
|
|
Usage interne — association de généalogie.
|