game-library/docs/DATABASE_SCHEMA.md

# DATABASE SCHEMA DOCUMENTATION

> Documentația structurii bazelor de date pentru INDEX-SISTEM-JOCURI
> 
> **IMPORTANT**: Fișierele `*.db` sunt excluse din git prin `.gitignore`. Această documentație permite recrearea structurii bazelor de date.

## Prezentare Generală

Sistemul folosește SQLite pentru stocarea datelor, cu următoarele baze de date:

- **`activities.db`** - Baza de date principală pentru activități educaționale
- **`game_library.db`** - Baza de date pentru biblioteca de jocuri (sistem legacy)
- **`test_activities.db`** - Baza de date pentru teste

## 1. ACTIVITIES.DB (Baza de Date Principală)

### Tabel: `activities`

Tabelul principal pentru stocarea activităților educaționale (conform PRD Section 5.3).

```sql
CREATE TABLE IF NOT EXISTS activities (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    file_path TEXT NOT NULL,
    file_type TEXT,
    page_number INTEGER,
    tags TEXT,
    category TEXT,
    age_group TEXT,
    participants TEXT,
    duration TEXT,
    materials TEXT,
    difficulty TEXT DEFAULT 'mediu',
    source_text TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Descrierea coloanelor:**

| Coloană | Tip | Descriere |
|---------|-----|-----------|
| `id` | INTEGER | Cheia primară, auto-increment |
| `title` | TEXT | Titlul activității (obligatoriu) |
| `description` | TEXT | Descrierea activității |
| `file_path` | TEXT | Calea către fișierul sursă (obligatoriu) |
| `file_type` | TEXT | Tipul fișierului (PDF, DOCX, etc.) |
| `page_number` | INTEGER | Numărul paginii în fișierul sursă |
| `tags` | TEXT | Tag-uri în format JSON |
| `category` | TEXT | Categoria activității |
| `age_group` | TEXT | Grupa de vârstă (ex: "8-12 ani") |
| `participants` | TEXT | Numărul de participanți (ex: "5-10 persoane") |
| `duration` | TEXT | Durata activității (ex: "15-30min") |
| `materials` | TEXT | Materialele necesare |
| `difficulty` | TEXT | Dificultatea (implicit: "mediu") |
| `source_text` | TEXT | Textul complet extras din fișier |
| `created_at` | TIMESTAMP | Data creării (implicit: now) |

### Tabel Virtual: `activities_fts`

Tabel pentru căutare full-text (FTS5) pentru performanță optimă.

```sql
CREATE VIRTUAL TABLE IF NOT EXISTS activities_fts USING fts5(
    title, description, source_text,
    content='activities'
);
```

### Tabel: `search_history`

Istoricul căutărilor pentru analiză și optimizare.

```sql
CREATE TABLE IF NOT EXISTS search_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    query TEXT NOT NULL,
    results_count INTEGER,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### Tabel: `file_processing_log`

Log-ul procesării fișierelor pentru urmărirea indexării.

```sql
CREATE TABLE IF NOT EXISTS file_processing_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    file_path TEXT NOT NULL,
    file_type TEXT,
    status TEXT,
    activities_extracted INTEGER DEFAULT 0,
    error_message TEXT,
    processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Status-uri posibile:**
- `processing` - în procesare
- `completed` - finalizat cu succes
- `error` - eroare în procesare
- `skipped` - omis (ex: fișier deja procesat)

## 2. GAME_LIBRARY.DB (Sistem Legacy)

### Tabel: `activities`

Varianta legacy a tabelului de activități.

```sql
CREATE TABLE IF NOT EXISTS activities (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    file_path TEXT NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT,
    age_group TEXT,
    participants TEXT,
    duration TEXT,
    materials TEXT,
    description TEXT,
    tags TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

**Diferențe față de tabelul principal:**
- `id` este TEXT (nu INTEGER)
- Lipsesc câmpurile: `file_type`, `page_number`, `difficulty`, `source_text`
- `subcategory` este prezentă doar aici

### Tabel: `search_history`

```sql
CREATE TABLE IF NOT EXISTS search_history (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    query TEXT NOT NULL,
    results_count INTEGER,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

## 3. RECREAREA BAZELOR DE DATE

### Metoda 1: Folosind DatabaseManager (Recomandat)

```python
from src.database import DatabaseManager

# Crearea bazei de date principale
db = DatabaseManager("data/activities.db")
print("✅ Baza de date activities.db creată")

# Crearea bazei de date de test
test_db = DatabaseManager("data/test_activities.db")
print("✅ Baza de date test_activities.db creată")
```

### Metoda 2: Folosind game_library_manager

```python
from src.game_library_manager import GameLibraryManager

# Crearea bazei legacy
manager = GameLibraryManager("data/game_library.db")
print("✅ Baza de date game_library.db creată")
```

### Metoda 3: SQL Direct

```bash
# Crearea manuală cu sqlite3
sqlite3 data/activities.db < scripts/create_activities_db.sql
```

## 4. POPULAREA CU DATE

### Indexarea Automată

```bash
# Rulează din directorul src/
cd src/
python indexer.py --clear-db
```

**Parametri disponibili:**
- `--clear-db` - șterge și recreează baza de date
- `--base-path` - calea către fișierele de indexat
- `--db-path` - calea către baza de date

### Testarea Funcționalității

```bash
# Testează baza de date
cd src/
python -c "from database import test_database; test_database()"
```

## 5. EXEMPLE DE DATE

### Exemplu Activitate

```json
{
    "id": 1,
    "title": "Jocul Celor 5 Simțuri",
    "description": "Activitate pentru dezvoltarea percepției senzoriale",
    "file_path": "/path/to/file.pdf",
    "file_type": "PDF",
    "page_number": 23,
    "tags": "[\"senzorial\", \"educativ\", \"interior\"]",
    "category": "educativ",
    "age_group": "8-12 ani",
    "participants": "5-10 persoane",
    "duration": "15-30min",
    "materials": "Materiale simple",
    "difficulty": "mediu",
    "source_text": "Textul complet din PDF...",
    "created_at": "2025-09-09 12:00:00"
}
```

## 6. ÎNTREȚINERE

### Backup-ul Bazelor de Date

```bash
# Backup
cp data/activities.db backups/activities_$(date +%Y%m%d_%H%M%S).db

# Restaurare
cp backups/activities_20250909_120000.db data/activities.db
```

### Verificarea Integrității

```sql
-- Verifică integritatea bazei de date
PRAGMA integrity_check;

-- Statistici
SELECT 
    COUNT(*) as total_activities,
    COUNT(DISTINCT category) as categories,
    COUNT(DISTINCT age_group) as age_groups
FROM activities;
```

### Rebuilding FTS Index

```sql
-- Recreează indexul FTS în caz de probleme
INSERT INTO activities_fts(activities_fts) VALUES('rebuild');
```

## 7. PERFORMANȚĂ

### Indexuri Recomandate

```sql
-- Indexuri pentru performanță
CREATE INDEX IF NOT EXISTS idx_activities_category ON activities(category);
CREATE INDEX IF NOT EXISTS idx_activities_age_group ON activities(age_group);
CREATE INDEX IF NOT EXISTS idx_activities_duration ON activities(duration);
CREATE INDEX IF NOT EXISTS idx_activities_file_path ON activities(file_path);
CREATE INDEX IF NOT EXISTS idx_search_history_timestamp ON search_history(timestamp);
```

### Optimizări

```sql
-- Analizează și optimizează
ANALYZE;
VACUUM;
```

## 8. TROUBLESHOOTING

### Probleme Comune

1. **"Database is locked"**
   ```bash
   # Verifică procesele care folosesc DB
   lsof data/activities.db
   ```

2. **"No such table"**
   ```python
   # Recreează schema
   from src.database import DatabaseManager
   db = DatabaseManager("data/activities.db")
   ```

3. **FTS nu funcționează**
   ```sql
   -- Verifică dacă FTS5 este disponibil
   SELECT sqlite_version(), sqlite_compileoption_used('ENABLE_FTS5');
   ```

### Log-uri

- Logurile aplicației: vezi console output
- Loguri indexer: vezi tabelul `file_processing_log`
- Loguri căutări: vezi tabelul `search_history`