mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 11:09:18 +02:00
docs: rewrite admin panel README
This commit is contained in:
Théophile Gervreau-Mercier
@@ -1,277 +1,140 @@
|
|||||||
# PostERG - Formulaire d'ajout de mémoires
|
# Admin Panel Structure
|
||||||
|
|
||||||
Le formulaire permet aux étudiant.e.s sortant de l'ERG en cursus de Master de soumettre leurs mémoires et travaux de fin d'études.
|
This directory contains the admin panel for managing Post-ERG thesis database.
|
||||||
|
|
||||||
## Fonctionnalités
|
## Directory Structure
|
||||||
|
|
||||||
- Soumission de mémoires avec métadonnées complètes
|
|
||||||
- Stockage structuré dans base de données SQLite
|
|
||||||
- Support multi-auteurs, multi-superviseurs, multi-langues
|
|
||||||
- Gestion des mots-clés (max 10 par TFE)
|
|
||||||
- Téléversement sécurisé des fichiers
|
|
||||||
- Protection CSRF et validation complète
|
|
||||||
- Workflow de publication (soumission → soutenance → publication)
|
|
||||||
|
|
||||||
## Technologies
|
|
||||||
|
|
||||||
- PHP 7.4+ avec PDO SQLite
|
|
||||||
- SQLite 3.8+
|
|
||||||
- CSS fait-main + [Simple.css](https://simplecss.org/)
|
|
||||||
- [Symfony YAML](https://symfony.com/doc/current/components/yaml.html) (pour migration legacy)
|
|
||||||
- [Just](https://github.com/casey/just) pour les tâches de développement
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Prérequis
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# PHP avec SQLite
|
|
||||||
php -v # 7.4 ou supérieur
|
|
||||||
php -m | grep sqlite # Vérifier extension SQLite
|
|
||||||
|
|
||||||
# Composer
|
|
||||||
composer install
|
|
||||||
|
|
||||||
# Just (optionnel mais recommandé)
|
|
||||||
# macOS: brew install just
|
|
||||||
# Linux: cargo install just
|
|
||||||
```
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
|
|
||||||
1. **Base de données production:**
|
|
||||||
```bash
|
|
||||||
cd ../db
|
|
||||||
sqlite3 posterg.db < schema.sql
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Base de données de test:**
|
|
||||||
```bash
|
|
||||||
just init-test-db
|
|
||||||
```
|
|
||||||
|
|
||||||
## Développement local
|
|
||||||
|
|
||||||
### Avec Just (recommandé)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Configuration complète et lancement du serveur
|
|
||||||
just dev
|
|
||||||
|
|
||||||
# Ou étape par étape:
|
|
||||||
just init-test-db # Créer la base de test
|
|
||||||
just serve # Lancer le serveur (réinitialise la DB)
|
|
||||||
just serve-only # Lancer sans réinitialiser
|
|
||||||
|
|
||||||
# Nettoyage
|
|
||||||
just cleanup # Supprimer test.db et fichiers uploadés
|
|
||||||
just reset # Cleanup + réinitialisation
|
|
||||||
|
|
||||||
# Statistiques
|
|
||||||
just stats # Voir les stats de la DB
|
|
||||||
just recent # Voir les soumissions récentes
|
|
||||||
just show 1 # Voir le TFE #1
|
|
||||||
|
|
||||||
# Autres commandes
|
|
||||||
just query # Shell SQLite interactif
|
|
||||||
just dump # Backup de la DB
|
|
||||||
```
|
|
||||||
|
|
||||||
### Sans Just
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Créer la base de test
|
|
||||||
sqlite3 test.db < ../db/schema.sql
|
|
||||||
|
|
||||||
# Lancer le serveur
|
|
||||||
php -S 127.0.0.1:3000
|
|
||||||
|
|
||||||
# Ouvrir dans le navigateur
|
|
||||||
open http://127.0.0.1:3000
|
|
||||||
```
|
|
||||||
|
|
||||||
## Structure du projet
|
|
||||||
|
|
||||||
```
|
```
|
||||||
formulaire/
|
public/admin/
|
||||||
├── assets/ # CSS et ressources
|
├── index.php # List all theses (main page)
|
||||||
│ ├── normalize.css
|
├── add.php # Add new thesis form
|
||||||
│ ├── simple.css
|
├── edit.php # Edit existing thesis form
|
||||||
│ ├── posterg.css
|
├── import.php # CSV import form
|
||||||
│ └── icon.svg
|
├── thanks.php # Thank you page after submission
|
||||||
├── data/ # Données (gitignored)
|
├── actions/ # Backend processing scripts (no HTML output)
|
||||||
│ ├── theses/ # Fichiers TFE uploadés
|
│ ├── formulaire.php # Process thesis submission from add.php
|
||||||
│ ├── covers/ # Images de couverture
|
│ └── publish.php # Toggle publish/unpublish status
|
||||||
│ └── yaml/ # Legacy YAML (migration)
|
├── inc/ # Shared templates
|
||||||
├── Database.php # Classe helper pour DB
|
│ ├── head.php # HTML head, CSS, navigation
|
||||||
├── index.php # Formulaire de soumission
|
│ └── footer.php # HTML footer
|
||||||
├── formulaire.php # Traitement de soumission
|
└── data/ # Upload directory (not in git)
|
||||||
├── thanks.php # Page de confirmation
|
├── theses/ # PDF files
|
||||||
├── justfile # Tâches de développement
|
└── covers/ # Cover images
|
||||||
├── .gitignore # Fichiers ignorés
|
|
||||||
├── MIGRATION.md # Guide de migration YAML → SQLite
|
|
||||||
├── SECURITY.md # Documentation sécurité
|
|
||||||
└── README.md # Ce fichier
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Workflow de soumission
|
## File Types
|
||||||
|
|
||||||
1. **Étudiant remplit le formulaire** (index.php)
|
### User-Facing Templates (Root Directory)
|
||||||
- Informations de base (nom, année, titre)
|
Files that display HTML to users:
|
||||||
- Détails académiques (orientation, AP, finalité)
|
- **index.php** - Lists all theses with filters and bulk actions
|
||||||
- Contenu (synopsis, mots-clés, langues, formats)
|
- **add.php** - Form to add a new thesis
|
||||||
- Upload fichiers (TFE + annexes)
|
- **edit.php** - Form to edit an existing thesis
|
||||||
|
- **import.php** - CSV import interface
|
||||||
|
- **thanks.php** - Success confirmation page
|
||||||
|
|
||||||
2. **Validation et traitement** (formulaire.php)
|
### Backend Scripts (actions/)
|
||||||
- Validation CSRF token
|
Files that process forms and redirect (no HTML output):
|
||||||
- Sanitization des entrées
|
- **formulaire.php** - Processes thesis submission from add.php
|
||||||
- Transaction DB (all-or-nothing)
|
- **publish.php** - Handles publish/unpublish actions
|
||||||
- Création/liaison entités (auteur, superviseurs, mots-clés)
|
|
||||||
- Upload sécurisé avec noms aléatoires
|
|
||||||
- Génération identifiant unique (YYYY-NNN)
|
|
||||||
|
|
||||||
3. **Confirmation** (thanks.php)
|
### Shared Templates (inc/)
|
||||||
- Affichage récapitulatif
|
Reusable HTML components:
|
||||||
- Statut: "En attente de publication"
|
- **head.php** - HTML head, CSS links, navigation menu
|
||||||
- Liste des fichiers uploadés
|
- **footer.php** - HTML footer
|
||||||
|
|
||||||
4. **Publication** (admin - à venir)
|
## Workflow
|
||||||
- Après soutenance
|
|
||||||
- Ajout note contextuelle du jury (optionnel)
|
|
||||||
- Points du jury
|
|
||||||
- Publication publique
|
|
||||||
|
|
||||||
## Base de données
|
### Adding a Thesis
|
||||||
|
1. User visits `add.php` (displays form)
|
||||||
|
2. User submits form to `actions/formulaire.php` (processes data)
|
||||||
|
3. On success, redirects to `thanks.php?id=123`
|
||||||
|
4. On error, redirects back to `add.php` with error message
|
||||||
|
|
||||||
### Structure
|
### Publishing/Unpublishing
|
||||||
|
1. User clicks publish/unpublish button in `index.php`
|
||||||
|
2. Form submits to `actions/publish.php` (processes action)
|
||||||
|
3. Redirects back to `index.php` with success/error message
|
||||||
|
|
||||||
- **19 tables** incluant tables de jonction et vues
|
## Security
|
||||||
- **Normalized 3NF** avec clés étrangères
|
|
||||||
- **Timestamps automatiques** via triggers
|
|
||||||
- **Cascade deletes** pour intégrité référentielle
|
|
||||||
|
|
||||||
### Tables principales
|
- All pages require HTTP Basic Auth (configured in nginx)
|
||||||
|
- CSRF tokens protect all forms
|
||||||
|
- File uploads validated and sanitized
|
||||||
|
- Database queries use prepared statements
|
||||||
|
- Upload directory outside public/ in production
|
||||||
|
|
||||||
- `theses` - TFE avec métadonnées
|
## Templates
|
||||||
- `authors` - Auteurs (réutilisables)
|
|
||||||
- `supervisors` - Promoteurs
|
|
||||||
- `thesis_files` - Métadonnées fichiers
|
|
||||||
- `keywords` - Mots-clés (extensible)
|
|
||||||
- Plus tables de référence et jonctions
|
|
||||||
|
|
||||||
### Vues
|
The `inc/` folder contains shared templates:
|
||||||
|
- `head.php` - Included at the top of each page (DOCTYPE, CSS, nav)
|
||||||
|
- `footer.php` - Included at the bottom of each page (closing tags)
|
||||||
|
|
||||||
- `v_theses_full` - Vue complète pour admin
|
Usage:
|
||||||
- `v_theses_public` - Vue filtrée pour public
|
```php
|
||||||
|
<?php include "inc/head.php" ?>
|
||||||
Voir `../db/README.md` pour documentation complète.
|
<!-- Page content here -->
|
||||||
|
<?php include "inc/footer.php" ?>
|
||||||
## Sécurité
|
|
||||||
|
|
||||||
✅ **Protection CSRF** - Tokens de session
|
|
||||||
✅ **SQL Injection** - Prepared statements PDO
|
|
||||||
✅ **Path Traversal** - Validation stricte des chemins
|
|
||||||
✅ **File Upload** - Noms aléatoires, validation MIME
|
|
||||||
✅ **Input Validation** - Sanitization + validation typage
|
|
||||||
✅ **Error Handling** - Pas d'exposition de chemins système
|
|
||||||
|
|
||||||
Voir `SECURITY.md` pour détails complets.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
### Test manuel
|
|
||||||
|
|
||||||
1. Lancer serveur: `just dev`
|
|
||||||
2. Ouvrir http://127.0.0.1:3000
|
|
||||||
3. Remplir formulaire avec données test
|
|
||||||
4. Vérifier confirmation
|
|
||||||
5. Vérifier DB: `just stats` et `just recent`
|
|
||||||
|
|
||||||
### Checklist
|
|
||||||
|
|
||||||
- [ ] Form se charge sans erreurs
|
|
||||||
- [ ] Dropdowns peuplés depuis DB
|
|
||||||
- [ ] Validation champs requis fonctionne
|
|
||||||
- [ ] Upload fichiers réussit
|
|
||||||
- [ ] Transaction rollback sur erreur
|
|
||||||
- [ ] Page confirmation affiche données
|
|
||||||
- [ ] Identifiant unique généré (YYYY-NNN)
|
|
||||||
- [ ] Fichiers stockés avec noms aléatoires
|
|
||||||
|
|
||||||
## Migration données legacy
|
|
||||||
|
|
||||||
Si vous avez des fichiers YAML existants:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Script de migration à créer
|
|
||||||
php migrate_yaml_to_sqlite.php
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Voir `MIGRATION.md` pour guide complet.
|
## URL Structure
|
||||||
|
|
||||||
## Production
|
- `/admin/` - List theses (index.php)
|
||||||
|
- `/admin/add.php` - Add new thesis
|
||||||
|
- `/admin/edit.php?id=123` - Edit thesis #123
|
||||||
|
- `/admin/import.php` - Import CSV
|
||||||
|
- `/admin/thanks.php?id=123` - Thank you page
|
||||||
|
|
||||||
### Déploiement
|
Backend actions (not directly accessed):
|
||||||
|
- `/admin/actions/formulaire.php` - Form processor
|
||||||
|
- `/admin/actions/publish.php` - Publish toggle
|
||||||
|
|
||||||
1. **Copier fichiers:**
|
## Development
|
||||||
```bash
|
|
||||||
rsync -av --exclude='test.db' --exclude='data/' \
|
### Adding a New Page
|
||||||
formulaire/ user@server:/var/www/posterg/
|
|
||||||
|
1. Create the template in `/admin/yourpage.php`:
|
||||||
|
```php
|
||||||
|
<?php
|
||||||
|
require_once __DIR__ . "/../../config/bootstrap.php";
|
||||||
|
session_start();
|
||||||
|
$pageTitle = "Your Page Title";
|
||||||
|
?>
|
||||||
|
<?php include "inc/head.php" ?>
|
||||||
|
|
||||||
|
<!-- Your content here -->
|
||||||
|
|
||||||
|
<?php include "inc/footer.php" ?>
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Créer DB production:**
|
2. Add navigation link in `inc/head.php` if needed
|
||||||
```bash
|
|
||||||
cd /var/www/posterg/db
|
|
||||||
sqlite3 posterg.db < schema.sql
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Permissions:**
|
### Adding a New Action
|
||||||
```bash
|
|
||||||
chown -R www-data:www-data /var/www/posterg
|
|
||||||
chmod 644 db/posterg.db
|
|
||||||
chmod 755 data/theses data/covers
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Configuration nginx:**
|
1. Create the script in `/admin/actions/youraction.php`:
|
||||||
```nginx
|
```php
|
||||||
location /formulaire {
|
<?php
|
||||||
auth_basic "Restricted";
|
require_once __DIR__ . "/../../config/bootstrap.php";
|
||||||
auth_basic_user_file /etc/nginx/.htpasswd;
|
session_start();
|
||||||
|
|
||||||
try_files $uri $uri/ /index.php?$query_string;
|
// Verify CSRF token
|
||||||
|
if (!hash_equals($_SESSION['csrf_token'], $_POST['csrf_token'])) {
|
||||||
location ~ \.php$ {
|
$_SESSION['error'] = "Security error";
|
||||||
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
|
header('Location: ../index.php');
|
||||||
include fastcgi_params;
|
exit;
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Process action...
|
||||||
|
|
||||||
|
// Redirect
|
||||||
|
header('Location: ../yourpage.php');
|
||||||
|
exit;
|
||||||
```
|
```
|
||||||
|
|
||||||
### Backup
|
2. Create form in template that posts to `actions/youraction.php`
|
||||||
|
|
||||||
```bash
|
## Notes
|
||||||
# Backup automatique quotidien
|
|
||||||
0 2 * * * sqlite3 /var/www/posterg/db/posterg.db \
|
|
||||||
.dump > /backups/posterg_$(date +\%Y\%m\%d).sql
|
|
||||||
```
|
|
||||||
|
|
||||||
## Support
|
- Bootstrap path from actions/: `__DIR__ . "/../../config/bootstrap.php"`
|
||||||
|
- Redirects from actions/: use `../` prefix (e.g., `../index.php`)
|
||||||
- **Schema DB:** `../db/README.md`
|
- Database class: `require_once __DIR__ . '/../../lib/Database.php'`
|
||||||
- **Setup DB:** `../db/SETUP.md`
|
- All forms must include CSRF token from `$_SESSION['csrf_token']`
|
||||||
- **Sécurité:** `SECURITY.md`
|
|
||||||
- **Migration:** `MIGRATION.md`
|
|
||||||
- **Specs techniques:** `../db/posterg_fiche-technique.md`
|
|
||||||
|
|
||||||
## Changelog
|
|
||||||
|
|
||||||
### v2.0 - 2026-01-27
|
|
||||||
- Migration vers SQLite
|
|
||||||
- Support multi-entités (auteurs, superviseurs, etc.)
|
|
||||||
- Sécurité renforcée
|
|
||||||
- Workflow de publication
|
|
||||||
- Justfile pour développement
|
|
||||||
|
|
||||||
### v1.0 - Précédent
|
|
||||||
- Stockage YAML
|
|
||||||
- Formulaire basique
|
|
||||||
|
|||||||
Reference in New Issue
Block a user