mirror of
https://codeberg.org/PostERG/xamxam.git
synced 2026-05-07 11:39:18 +02:00
7fca85d1c1
More semantically accurate: contains SQLite files, schema, fixtures, test data. Updated all references in code, scripts, docs.
223 lines
5.2 KiB
Markdown
223 lines
5.2 KiB
Markdown
# 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)
|