mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-09-25 01:53:03 +02:00
docs: verify and refactor documentation to match current codebase
This commit is contained in:
Pontoporeia
+25
-196
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user