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).

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ă.

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.

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.

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.

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

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)

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

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

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

4. POPULAREA CU DATE

Indexarea Automată

# 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

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

5. EXEMPLE DE DATE

Exemplu Activitate

{
    "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

# 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

-- 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

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

7. PERFORMANȚĂ

Indexuri Recomandate

-- 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

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

8. TROUBLESHOOTING

Probleme Comune

1. "Database is locked"

   # Verifică procesele care folosesc DB
   lsof data/activities.db
   

2. "No such table"

   # Recreează schema
   from src.database import DatabaseManager
   db = DatabaseManager("data/activities.db")
   

3. FTS nu funcționează

   -- 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