Add database documentation and setup script
- Add comprehensive DATABASE_SCHEMA.md with complete SQLite schemas - Document all 3 databases: activities.db, game_library.db, test_activities.db - Include recreation methods, examples, and troubleshooting - Add scripts/create_databases.py for automated database setup - Move README.md to project root for better visibility - Ensure *.db files excluded via .gitignore are fully documented 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
307
docs/DATABASE_SCHEMA.md
Normal file
307
docs/DATABASE_SCHEMA.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user