PostERG/xamxam
1
0
Fork 0
mirror of https://codeberg.org/PostERG/xamxam.git synced 2026-05-06 19:19:19 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite admin panel README

Browse Source
This commit is contained in:
Théophile Gervreau-Mercier
2026-02-06 14:31:23 +01:00
parent df611b0333
commit 94d110438f
1 changed files with 108 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

353
public/admin/README.md
View File

@@ -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
- 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
## Directory Structure
```
formulaire/
├── assets/ # CSS et ressources
│ ├── normalize.css
│ ├── simple.css
│ ├── posterg.css
│ └── icon.svg
├── data/ # Données (gitignored)
│ ├── theses/ # Fichiers TFE uploadés
│ ├── covers/ # Images de couverture
│ └── yaml/ # Legacy YAML (migration)
├── Database.php # Classe helper pour DB
├── index.php # Formulaire de soumission
├── formulaire.php # Traitement de soumission
├── thanks.php # Page de confirmation
├── justfile # Tâches de développement
├── .gitignore # Fichiers ignorés
├── MIGRATION.md # Guide de migration YAML → SQLite
├── SECURITY.md # Documentation sécurité
└── README.md # Ce fichier
public/admin/
├── index.php # List all theses (main page)
├── add.php # Add new thesis form
├── edit.php # Edit existing thesis form
├── import.php # CSV import form
├── thanks.php # Thank you page after submission
├── actions/ # Backend processing scripts (no HTML output)
│ ├── formulaire.php # Process thesis submission from add.php
│ └── publish.php # Toggle publish/unpublish status
├── inc/ # Shared templates
│ ├── head.php # HTML head, CSS, navigation
│ └── footer.php # HTML footer
└── data/ # Upload directory (not in git)
├── theses/ # PDF files
└── covers/ # Cover images
```
## Workflow de soumission
## File Types
1. **Étudiant remplit le formulaire** (index.php)
- Informations de base (nom, année, titre)
- Détails académiques (orientation, AP, finalité)
- Contenu (synopsis, mots-clés, langues, formats)
- Upload fichiers (TFE + annexes)
### User-Facing Templates (Root Directory)
Files that display HTML to users:
- **index.php** - Lists all theses with filters and bulk actions
- **add.php** - Form to add a new thesis
- **edit.php** - Form to edit an existing thesis
- **import.php** - CSV import interface
- **thanks.php** - Success confirmation page
2. **Validation et traitement** (formulaire.php)
- Validation CSRF token
- Sanitization des entrées
- Transaction DB (all-or-nothing)
- Création/liaison entités (auteur, superviseurs, mots-clés)
- Upload sécurisé avec noms aléatoires
- Génération identifiant unique (YYYY-NNN)
### Backend Scripts (actions/)
Files that process forms and redirect (no HTML output):
- **formulaire.php** - Processes thesis submission from add.php
- **publish.php** - Handles publish/unpublish actions
3. **Confirmation** (thanks.php)
- Affichage récapitulatif
- Statut: "En attente de publication"
- Liste des fichiers uploadés
### Shared Templates (inc/)
Reusable HTML components:
- **head.php** - HTML head, CSS links, navigation menu
- **footer.php** - HTML footer
4. **Publication** (admin - à venir)
- Après soutenance
- Ajout note contextuelle du jury (optionnel)
- Points du jury
- Publication publique
## Workflow
## 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
- **Normalized 3NF** avec clés étrangères
- **Timestamps automatiques** via triggers
- **Cascade deletes** pour intégrité référentielle
## Security
### 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
- `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
## Templates
### 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
- `v_theses_public` - Vue filtrée pour public
Voir `../db/README.md` pour documentation complète.
## 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
Usage:
```php
<?php include "inc/head.php" ?>
<!-- Page content here -->
<?php include "inc/footer.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:**
```bash
rsync -av --exclude='test.db' --exclude='data/' \
formulaire/ user@server:/var/www/posterg/
```
## Development
2. **Créer DB production:**
```bash
cd /var/www/posterg/db
sqlite3 posterg.db < schema.sql
```
### Adding a New Page
3. **Permissions:**
```bash
chown -R www-data:www-data /var/www/posterg
chmod 644 db/posterg.db
chmod 755 data/theses data/covers
```
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" ?>
4. **Configuration nginx:**
```nginx
location /formulaire {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
<!-- Your content here -->
try_files $uri $uri/ /index.php?$query_string;
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
include fastcgi_params;
}
}
```
### Backup
```bash
# Backup automatique quotidien
0 2 * * * sqlite3 /var/www/posterg/db/posterg.db \
.dump > /backups/posterg_$(date +\%Y\%m\%d).sql
<?php include "inc/footer.php" ?>
```
## Support
2. Add navigation link in `inc/head.php` if needed
- **Schema DB:** `../db/README.md`
- **Setup DB:** `../db/SETUP.md`
- **Sécurité:** `SECURITY.md`
- **Migration:** `MIGRATION.md`
- **Specs techniques:** `../db/posterg_fiche-technique.md`
### Adding a New Action
## Changelog
1. Create the script in `/admin/actions/youraction.php`:
```php
<?php
require_once __DIR__ . "/../../config/bootstrap.php";
session_start();
### 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
// Verify CSRF token
if (!hash_equals($_SESSION['csrf_token'], $_POST['csrf_token'])) {
$_SESSION['error'] = "Security error";
header('Location: ../index.php');
exit;
}
### v1.0 - Précédent
- Stockage YAML
- Formulaire basique
// Process action...
// Redirect
header('Location: ../yourpage.php');
exit;
```
2. Create form in template that posts to `actions/youraction.php`
## Notes
- Bootstrap path from actions/: `__DIR__ . "/../../config/bootstrap.php"`
- Redirects from actions/: use `../` prefix (e.g., `../index.php`)
- Database class: `require_once __DIR__ . '/../../lib/Database.php'`
- All forms must include CSRF token from `$_SESSION['csrf_token']`