PostERG/xamxam
1
0
Fork 0
mirror of https://codeberg.org/PostERG/xamxam.git synced 2026-09-25 01:53:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: verify and refactor documentation to match current codebase

Browse Source
This commit is contained in:
Pontoporeia
2026-08-24 11:31:38 +02:00
parent b2cdbd0174
commit e9747edce0
17 changed files with 1006 additions and 1442 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/public/admin/README.md
+68 -124
View File
@@ -1,145 +1,89 @@
# Admin Panel Structure
This directory contains the admin panel for managing XAMXAM thesis database.
This directory and `app/templates/admin/` contain the admin panel for managing
the XAMXAM TFE database.
## Directory Structure
## Entry points (`app/public/admin/`)
```
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
├── recapitulatif.php # Recap 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
```
| File | Purpose |
|------|---------|
| `index.php` | List all theses (main page; hosts the inline CSV import + tabs for list/trash) |
| `add.php` | Add new thesis form |
| `edit.php` | Existing thesis form |
| `recapitulatif.php` | Post-submission recap |
| `cleanup.php` | Orphaned-draft / storage cleanup |
| `system.php` | System dashboard (logs, SMTP/PeerTube status) |
| `contenus.php` | Editable content (pages, contacts) |
| `contenus-edit.php` | Edit a content page |
| `acces.php` | Share-link management |
| `file-access.php` | Restricted-file access requests |
| `account.php` | Admin account / password |
| `login.php` | Login (session) |
| `import.php` | Redirects to `/admin/` (CSV import is inline in `index.php`) |
| `status.php`, `markdown-cheatsheet-fragment.php`, `*fragment.php` | HTMX fragments / helpers |
## File Types
### Backend actions (`app/public/admin/actions/`)
### 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
- **recapitulatif.php** - Success confirmation page
Process forms and redirect (no HTML output):
### 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
### Shared Templates (inc/)
Reusable HTML components:
- **head.php** - HTML head, CSS links, navigation menu
- **footer.php** - HTML footer
## Workflow
### 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 `recapitulatif.php?id=123`
4. On error, redirects back to `add.php` with error message
### 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
## Security
- All pages require HTTP Basic Auth (configured in nginx) — primary layer
- All pages require PHP session auth (`AdminAuth::requireLogin()`) — defence-in-depth
- CSRF tokens protect all forms
- File uploads validated and sanitized
- Database queries use prepared statements
- Upload directory outside public/ in production
See `nginx/PHP_AUTH_LAYER.md` for details on the dual-auth architecture.
- `formulaire.php` — thesis create submission (`ThesisCreateController::submit()`)
- `edit.php` — thesis edit submission (`ThesisEditController::save()`)
- `export-csv.php`, `export-db.php`, `export-files.php` — see `docs/export.md`
- `filepond/` — FilePond async upload endpoints
- many others: `publish`, `delete`, `corbeille` (trash), `draft`, `visibility`,
`tag`, `language`, `form-help*`, `page`, `apropos`, `smtp-test`,
`peertube-*`, `maintenance`, `settings`, `account`, `access-request`,
`acces-etudiante`, `cleanup-*`
## Templates
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)
View templates live under `app/templates/admin/` (not in `public/`):
- `app/templates/admin/*.php` — page layouts
- `app/templates/admin/partials/` — shared fragments (toasts, dialogs, toc, …)
The public/partage and form partials live in `app/templates/partials/` and
`app/templates/partage/`.
## Auth
- **PHP session auth** (`src/AdminAuth.php`) via `AdminAuth::requireLogin()` is
the only authentication layer. The old nginx `auth_basic` layer has been
removed — see `docs/security.md` and `nginx/docs/PHP_AUTH_LAYER.md`.
- All forms include a CSRF token from `$_SESSION['csrf_token']`.
- Inputs use PDO prepared statements; uploads validated and stored outside the
webroot (`app/storage/`).
## Bootstrap / routing
Entry pages bootstrap the app and set up the environment:
Usage:
```php
<?php include "inc/head.php" ?>
<!-- Page content here -->
<?php include "inc/footer.php" ?>
```
## URL Structure
- `/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/recapitulatif.php?id=123` - Recap page
Backend actions (not directly accessed):
- `/admin/actions/formulaire.php` - Form processor
- `/admin/actions/publish.php` - Publish toggle
## Development
### Adding a New Page
1. Create the template in `/admin/yourpage.php`:
```php
<?php
require_once __DIR__ . "/../../config/bootstrap.php";
require_once __DIR__ . '/../../lib/AdminAuth.php';
require_once __DIR__ . '/../../bootstrap.php'; // defines APP_ROOT, autoload, config
require_once APP_ROOT . '/src/AdminAuth.php';
AdminAuth::requireLogin();
$pageTitle = "Your Page Title";
?>
<?php include "inc/head.php" ?>
<!-- Your content here -->
<?php include "inc/footer.php" ?>
```
2. Add navigation link in `inc/head.php` if needed
`APP_ROOT` is the `app/` directory. Database access is via
`app/src/Database.php`; form logic lives in `app/src/Controllers/` and
`app/src/Form/`.
### Adding a New Action
## URL structure
1. Create the script in `/admin/actions/youraction.php`:
```php
<?php
require_once __DIR__ . "/../../config/bootstrap.php";
require_once __DIR__ . '/../../lib/AdminAuth.php';
AdminAuth::requireLogin();
- `/admin/` — list theses (index.php)
- `/admin/add.php` — add thesis
- `/admin/edit.php?id=N` — edit thesis
- `/admin/cleanup.php`, `/admin/system.php`, `/admin/acces.php`, etc.
- `/admin/actions/…` — backend processors
// Verify CSRF token
if (!hash_equals($_SESSION['csrf_token'], $_POST['csrf_token'])) {
$_SESSION['error'] = "Security error";
header('Location: ../index.php');
exit;
}
## Development guide
// Process action...
**Add a page:** create `app/templates/admin/yourpage.php`, add a thin
`app/public/admin/yourpage.php` entry that bootstraps + requires the template,
and add navigation in `app/templates/admin/partials/admin-toc.php`.
// Redirect
header('Location: ../yourpage.php');
exit;
```
**Add an action:** create `app/public/admin/actions/youraction.php` that
bootstraps, requires login, verifies the CSRF token, performs the work, and
redirects back to the referring admin page.
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']`
See `docs/development.md` for the general workflow (dev server, builds,
tests, linting).
app/storage/README.md
+25 -196
View File
@@ -1,206 +1,35 @@
# Database Documentation
# Database documentation
Complete documentation for the XAMXAM thesis database.
XAMXAM stores its data in a SQLite database. See also the top-level
[`docs/database.md`](../../docs/database.md).
## 📚 Available Documentation
## Quick start
### 1. **[DATABASE_SPECIFICATION.md](DATABASE_SPECIFICATION.md)** ⭐
**Complete technical specification** - 25KB comprehensive document
- **Database file:** `xamxam.db`
- **Schema (baseline + seed):** `schema.sql`
- **Migrations:** applied set under `app/migrations/applied/` (run via `just migrate`)
**Contents:**
- Complete table definitions with all columns
- Entity relationship diagrams
- Junction table specifications
- Lookup table values
- Business rules and workflows
- Sample queries and use cases
- Instructions for requesting schema changes
**Use when:** You need complete technical details about the database structure.
---
### 2. **[QUICK_SCHEMA_REFERENCE.md](QUICK_SCHEMA_REFERENCE.md)** 🚀
**Quick reference guide** - 5KB at-a-glance reference
**Contents:**
- Table summary
- Key relationships diagram
- Core fields reference
- Predefined lookup values
- Common SQL queries
- Constraint summary
**Use when:** You need quick lookup or common query examples.
---
### 3. **[schema.sql](schema.sql)** 💾
**The actual SQL schema** - Executable SQL file
**Contents:**
- Complete CREATE TABLE statements
- Indexes and triggers
- Predefined data (orientations, AP programs, etc.)
- Views for common queries
**Use when:** Setting up or resetting the database.
---
## 🚀 Quick Start
### View Database Schema
```bash
# Read the quick reference
cat database/QUICK_SCHEMA_REFERENCE.md
# Or full specification
cat database/DATABASE_SPECIFICATION.md
just query # open an interactive sqlite3 shell on xamxam.db
just init-db # (re)create xamxam.db from schema.sql
just reset-db # rm xamxam.db + init-db
just migrate # run pending migrations
```
### Initialize Database
```bash
# Create test database from schema
just init-test-db
## Files here
# Create with sample data
just create-fixtures
```
| Path | Purpose |
|------|---------|
| `xamxam.db` | The live SQLite database |
| `schema.sql` | Full, fully-migrated schema + seed data (regenerated from the local DB) |
| `backups/` | `just backup-snapshot` hot-backups (`*.db.gz`) |
| `cache/` | Runtime cache (rate limits, etc.) |
| `logs/` | Runtime logs (admin, audit) — **outside the webroot** |
| `covers/` | Cover images |
| `theses/`, `tfe/`, `tmp/` | Uploaded files / staging |
### Query Database
```bash
# Open SQLite prompt
just query-db
## See also
# Show specific thesis
just show-thesis 42
```
## 📝 Making Schema Changes
### Step 1: Document Your Request
Format:
```
**Table:** [table_name]
**Change Type:** [add/modify/remove]
**What:** [description]
**Why:** [reason/use case]
**Example Data:** [samples]
```
### Step 2: Specify Details
For **new columns**:
- Column name
- Data type (TEXT, INTEGER, BOOLEAN, DATETIME)
- NULL/NOT NULL
- Default value
- Indexes needed?
For **new tables**:
- Table name
- All columns
- Relationships to existing tables
- Sample data
### Step 3: Provide Context
Include:
- Use case scenario
- Who will use it?
- How will it be displayed?
- Any constraints?
### Example Request
```
**Table:** theses
**Change Type:** add column
**What:** Add column to track if thesis won an award
**Why:** Need to highlight award-winning theses on homepage
**Column Name:** has_award
**Data Type:** BOOLEAN
**Default:** 0 (false)
**Example:** 1 for "Prix du Jury 2025" winner
```
## 🗂️ Database Structure Overview
```
┌─────────────┐
│ theses │ ◄── Main table (500+ records/year)
└──────┬──────┘
│
├──► authors (via thesis_authors)
├──► supervisors (via thesis_supervisors)
├──► keywords (via thesis_keywords)
├──► languages (via thesis_languages)
├──► formats (via thesis_formats)
├──► thesis_files (attachments)
│
└──► Lookup tables:
• orientations
• ap_programs
• finality_types
• access_types
• license_types
```
## 📊 Key Statistics
- **Core tables:** 3 (theses, authors, supervisors)
- **Junction tables:** 5 (many-to-many relationships)
- **Lookup tables:** 7 (predefined values)
- **Support tables:** 2 (files, pages)
- **Views:** 2 (full data, public only)
- **Indexes:** 11 (for performance)
- **Triggers:** 4 (auto-update timestamps)
## 🔍 Common Scenarios
### Scenario 1: Student Submits Thesis
1. Create record in `theses` (is_published=0)
2. Add author to `authors`, link via `thesis_authors`
3. Add supervisor(s) to `supervisors`, link via `thesis_supervisors`
4. Set `orientation_id`, `ap_program_id`, `finality_id`
5. Upload file to `thesis_files`
6. Add keywords via `thesis_keywords`
7. Set `submitted_at` timestamp
### Scenario 2: Admin Publishes Thesis
1. Verify all required fields present
2. Set `defense_date`
3. Set `jury_points`
4. Optional: add `context_note`
5. Set `is_published = 1`
6. Set `published_at = CURRENT_TIMESTAMP`
### Scenario 3: Public User Searches
Query `v_theses_public` view with filters:
- By year
- By orientation
- By keyword
- By author name
- Full-text search in title/synopsis
## 🛠️ Development Workflow
### Local Development
1. Use `xamxam.db` for development
2. Create via `just init-db`
3. Test queries before deployment
## 📞 Need Help?
1. **Quick lookup** → Read `QUICK_SCHEMA_REFERENCE.md`
2. **Complete details** → Read `DATABASE_SPECIFICATION.md`
3. **Schema changes** → Follow format in this README
4. **SQL examples** → Check `QUICK_SCHEMA_REFERENCE.md`
## 🔗 Related Documentation
- [Deployment Guide](../nginx/DEPLOYMENT_COMPLETE.md)
- [Repository Structure](../REPOSITORY_STRUCTURE_ANALYSIS.md)
- [Test Database Guide](../nginx/TEST_DATABASE_SETUP.md)
- [`docs/database.md`](../../docs/database.md) — schema reference, tables, common SQL
- [`docs/import.md`](../../docs/import.md) — CSV import format
- [`docs/export.md`](../../docs/export.md) — CSV / DB / files export + restore