docs: réécriture complète du README
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>
This commit is contained in:
@@ -1,59 +1,235 @@
|
|||||||
<p align="center"><a href="https://laravel.com" target="_blank"><img src="https://raw.githubusercontent.com/laravel/art/master/logo-lockup/5%20SVG/2%20CMYK/1%20Full%20Color/laravel-logolockup-cmyk-red.svg" width="400" alt="Laravel Logo"></a></p>
|
# MesRelevés
|
||||||
|
|
||||||
<p align="center">
|
Application web de saisie et de recherche de relevés généalogiques pour associations.
|
||||||
<a href="https://github.com/laravel/framework/actions"><img src="https://github.com/laravel/framework/workflows/tests/badge.svg" alt="Build Status"></a>
|
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.
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/dt/laravel/framework" alt="Total Downloads"></a>
|
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/v/laravel/framework" alt="Latest Stable Version"></a>
|
|
||||||
<a href="https://packagist.org/packages/laravel/framework"><img src="https://img.shields.io/packagist/l/laravel/framework" alt="License"></a>
|
|
||||||
</p>
|
|
||||||
|
|
||||||
## About Laravel
|
## Fonctionnalités
|
||||||
|
|
||||||
Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable and creative experience to be truly fulfilling. Laravel takes the pain out of development by easing common tasks used in many web projects, such as:
|
- **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
|
||||||
|
|
||||||
- [Simple, fast routing engine](https://laravel.com/docs/routing).
|
## Stack technique
|
||||||
- [Powerful dependency injection container](https://laravel.com/docs/container).
|
|
||||||
- Multiple back-ends for [session](https://laravel.com/docs/session) and [cache](https://laravel.com/docs/cache) storage.
|
|
||||||
- Expressive, intuitive [database ORM](https://laravel.com/docs/eloquent).
|
|
||||||
- Database agnostic [schema migrations](https://laravel.com/docs/migrations).
|
|
||||||
- [Robust background job processing](https://laravel.com/docs/queues).
|
|
||||||
- [Real-time event broadcasting](https://laravel.com/docs/broadcasting).
|
|
||||||
|
|
||||||
Laravel is accessible, powerful, and provides tools required for large, robust applications.
|
| 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 |
|
||||||
|
|
||||||
## Learning Laravel
|
---
|
||||||
|
|
||||||
Laravel has the most extensive and thorough [documentation](https://laravel.com/docs) and video tutorial library of all modern web application frameworks, making it a breeze to get started with the framework. You can also check out [Laravel Learn](https://laravel.com/learn), where you will be guided through building a modern Laravel application.
|
## Installation
|
||||||
|
|
||||||
If you don't feel like reading, [Laracasts](https://laracasts.com) can help. Laracasts contains thousands of video tutorials on a range of topics including Laravel, modern PHP, unit testing, and JavaScript. Boost your skills by digging into our comprehensive video library.
|
### Prérequis
|
||||||
|
|
||||||
## Laravel Sponsors
|
- Docker Engine ≥ 24
|
||||||
|
- Docker Compose v2 (`docker compose version`)
|
||||||
|
|
||||||
We would like to extend our thanks to the following sponsors for funding Laravel development. If you are interested in becoming a sponsor, please visit the [Laravel Partners program](https://partners.laravel.com).
|
### Première installation
|
||||||
|
|
||||||
### Premium Partners
|
**1. Télécharger la dernière release**
|
||||||
|
|
||||||
- **[Vehikl](https://vehikl.com)**
|
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 :
|
||||||
- **[Tighten Co.](https://tighten.co)**
|
|
||||||
- **[Kirschbaum Development Group](https://kirschbaumdevelopment.com)**
|
|
||||||
- **[64 Robots](https://64robots.com)**
|
|
||||||
- **[Curotec](https://www.curotec.com/services/technologies/laravel)**
|
|
||||||
- **[DevSquad](https://devsquad.com/hire-laravel-developers)**
|
|
||||||
- **[Redberry](https://redberry.international/laravel-development)**
|
|
||||||
- **[Active Logic](https://activelogic.com)**
|
|
||||||
|
|
||||||
## Contributing
|
```bash
|
||||||
|
tar -xzf mesreleves-X.Y.Z.tar.gz
|
||||||
|
cd mesreleves-X.Y.Z
|
||||||
|
```
|
||||||
|
|
||||||
Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](https://laravel.com/docs/contributions).
|
**2. Lancer le script d'installation**
|
||||||
|
|
||||||
## Code of Conduct
|
```bash
|
||||||
|
./install.sh
|
||||||
|
```
|
||||||
|
|
||||||
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
|
Le script crée un `.env` depuis `.env.example` puis s'arrête pour vous laisser le configurer.
|
||||||
|
Éditez `.env` avec vos paramètres :
|
||||||
|
|
||||||
## Security Vulnerabilities
|
```env
|
||||||
|
APP_URL=https://votre-domaine.fr
|
||||||
|
APP_KEY= # généré automatiquement au démarrage
|
||||||
|
|
||||||
If you discover a security vulnerability within Laravel, please send an e-mail to Taylor Otwell via [taylor@laravel.com](mailto:taylor@laravel.com). All security vulnerabilities will be promptly addressed.
|
DB_PASSWORD=mot_de_passe_fort
|
||||||
|
|
||||||
## License
|
MAIL_MAILER=smtp
|
||||||
|
MAIL_HOST=smtp.example.com
|
||||||
|
MAIL_PORT=587
|
||||||
|
MAIL_USERNAME=...
|
||||||
|
MAIL_PASSWORD=...
|
||||||
|
MAIL_FROM_ADDRESS=mesreleves@example.com
|
||||||
|
```
|
||||||
|
|
||||||
The Laravel framework is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).
|
**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.
|
||||||
|
|||||||
Reference in New Issue
Block a user