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`
|
||||
@@ -1,134 +0,0 @@
|
||||
# 🎮 COLECȚIA JOCURI ȘI ACTIVITĂȚI TINERET
|
||||
|
||||
**200+ fișiere PDF | 2000+ activități catalogate | Sistem de căutare automatizat**
|
||||
|
||||
---
|
||||
|
||||
## 📁 STRUCTURA DIRECTORULUI
|
||||
|
||||
```
|
||||
/carti-camp-jocuri/
|
||||
├── 📚 Fișiere PDF originale (200+ fișiere)
|
||||
│ ├── Activities and Games Scouts NZ/
|
||||
│ ├── dragon.sleepdeprived.ca/
|
||||
│ ├── escape-room/
|
||||
│ ├── prim-ajutor/
|
||||
│ └── ...și multe altele
|
||||
│
|
||||
└── 📋 INDEX-SISTEM-JOCURI/ ← SISTEMUL DE CATALOGARE
|
||||
├── INDEX_MASTER_JOCURI_ACTIVITATI.md (Catalogul complet)
|
||||
├── GHID_UTILIZARE.md (Manual detaliat)
|
||||
├── README.md (Start rapid)
|
||||
├── game_library_manager.py (Script principal)
|
||||
├── search_games.py (Căutare interactivă)
|
||||
└── game_library.db (Baza de date)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 UTILIZARE RAPIDĂ
|
||||
|
||||
### 1. Căutare Manuală (Cel mai simplu)
|
||||
```bash
|
||||
# Deschideți fișierul în orice editor de text
|
||||
INDEX-SISTEM-JOCURI/INDEX_MASTER_JOCURI_ACTIVITATI.md
|
||||
|
||||
# Căutați cu Ctrl+F:
|
||||
"team building" → Activități de echipă
|
||||
"8-11 ani" → Jocuri pentru Cubs
|
||||
"fără materiale" → Jocuri care nu necesită echipament
|
||||
"orientare" → Jocuri cu busole
|
||||
```
|
||||
|
||||
### 2. Căutare Automatizată (Recomandat)
|
||||
```bash
|
||||
# Intrați în directorul sistemului
|
||||
cd INDEX-SISTEM-JOCURI
|
||||
|
||||
# Căutare interactivă (urmați instrucțiunile)
|
||||
python search_games.py
|
||||
|
||||
# Căutări rapide
|
||||
python search_games.py --category "Team Building"
|
||||
python search_games.py --age 8 --keywords "cooperare"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 STATISTICI COLECȚIE
|
||||
|
||||
- **📁 Total fișiere:** 200+
|
||||
- **🎮 Total activități:** 2,000+
|
||||
- **📂 Categorii principale:** 8
|
||||
- **🗣️ Limbi:** Română, Engleză
|
||||
- **📄 Formate:** PDF (85%), DOC (10%), HTML (5%)
|
||||
|
||||
### Distribuția pe categorii:
|
||||
- **🏕️ Jocuri Cercetășești:** 800+ activități (40%)
|
||||
- **🤝 Team Building:** 300+ activități (15%)
|
||||
- **🏞️ Camping & Exterior:** 400+ activități (20%)
|
||||
- **🧩 Escape Room & Puzzle:** 100+ activități (5%)
|
||||
- **🧭 Orientare & Busole:** 80+ activități (4%)
|
||||
- **🚑 Primul Ajutor:** 60+ activități (3%)
|
||||
- **📚 Activități Educaționale:** 200+ activități (10%)
|
||||
- **🎵 Resurse Speciale:** 60+ activități (3%)
|
||||
|
||||
---
|
||||
|
||||
## ⚡ EXEMPLE DE UTILIZARE
|
||||
|
||||
```bash
|
||||
cd INDEX-SISTEM-JOCURI
|
||||
|
||||
# Jocuri pentru copii mici (5-8 ani)
|
||||
python search_games.py --age 5
|
||||
|
||||
# Activități team building
|
||||
python search_games.py --category "Team Building"
|
||||
|
||||
# Jocuri fără materiale
|
||||
python search_games.py --keywords "fără materiale"
|
||||
|
||||
# Activități de tabără
|
||||
python search_games.py --keywords "camping,exterior"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 PENTRU DIFERITE TIPURI DE UTILIZATORI
|
||||
|
||||
### 🏕️ Organizatori de tabere:
|
||||
- **Categorii:** Camping & Exterior, Orientare
|
||||
- **Cuvinte cheie:** "tabără", "natură", "orientare", "supraviețuire"
|
||||
|
||||
### 👨🏫 Profesori și educatori:
|
||||
- **Categorii:** Activități Educaționale, Team Building
|
||||
- **Cuvinte cheie:** "științe", "biologie", "primul ajutor", "conflicte"
|
||||
|
||||
### 🏕️ Instructori Scout:
|
||||
- **Categorii:** Jocuri Cercetășești
|
||||
- **Cuvinte cheie:** "Cubs", "Scouts", "cercetași", "Baden Powell"
|
||||
|
||||
### 🎪 Animatori evenimente:
|
||||
- **Categorii:** Escape Room, Resurse Speciale
|
||||
- **Cuvinte cheie:** "puzzle", "cântece", "interior", "fără materiale"
|
||||
|
||||
---
|
||||
|
||||
## 📖 DOCUMENTAȚIA COMPLETĂ
|
||||
|
||||
Consultați subdirectorul **`INDEX-SISTEM-JOCURI/`** pentru:
|
||||
|
||||
| Fișier | Pentru ce |
|
||||
|--------|-----------|
|
||||
| **README.md** | Start rapid și exemple |
|
||||
| **INDEX_MASTER_JOCURI_ACTIVITATI.md** | Catalogul complet (300+ pagini) |
|
||||
| **GHID_UTILIZARE.md** | Manual detaliat de utilizare |
|
||||
| **search_games.py** | Căutare automată în colecție |
|
||||
|
||||
---
|
||||
|
||||
**🎉 Succese în organizarea activităților!**
|
||||
|
||||
*Pentru asistență detaliată: `INDEX-SISTEM-JOCURI/GHID_UTILIZARE.md`*
|
||||
*Sistem creat cu Claude AI - 2025-09-09*
|
||||
Reference in New Issue
Block a user