mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-06 11:09:18 +02:00
feat: extract MediaController, wire into Dispatcher, delete media.php
This commit is contained in:
Pontoporeia
222
app/storage/README.md
Normal file
222
app/storage/README.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# Database Documentation
|
||||
|
||||
Complete documentation for the Post-ERG thesis database.
|
||||
|
||||
## 📚 Available Documentation
|
||||
|
||||
### 1. **[DATABASE_SPECIFICATION.md](DATABASE_SPECIFICATION.md)** ⭐
|
||||
**Complete technical specification** - 25KB comprehensive document
|
||||
|
||||
**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
|
||||
```
|
||||
|
||||
### Initialize Database
|
||||
```bash
|
||||
# Create test database from schema
|
||||
just init-test-db
|
||||
|
||||
# Create with sample data
|
||||
just create-fixtures
|
||||
```
|
||||
|
||||
### Query Database
|
||||
```bash
|
||||
# Open SQLite prompt
|
||||
just query-db
|
||||
|
||||
# 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 `test.db` for development
|
||||
2. Create via `just init-test-db`
|
||||
3. Populate with `just create-fixtures`
|
||||
4. Test queries before deployment
|
||||
|
||||
### Schema Changes
|
||||
1. Update `schema.sql`
|
||||
2. Update `DATABASE_SPECIFICATION.md`
|
||||
3. Test on `test.db`
|
||||
4. Deploy to production (manual migration)
|
||||
|
||||
### Testing
|
||||
```bash
|
||||
# Run tests on local database
|
||||
just test-public-all
|
||||
|
||||
# Check database stats
|
||||
just stats-public
|
||||
```
|
||||
|
||||
## 📞 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)
|
||||
Reference in New Issue
Block a user