romfast/game-library
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Organize project structure

Browse Source 
- Create organized directory structure (src/, docs/, data/, static/, templates/)
- Add comprehensive .gitignore for Python projects
- Move Python source files to src/
- Move documentation files to docs/ with project/ and user/ subdirectories
- Move database files to data/
- Update all database path references in Python code
- Maintain Flask static/ and templates/ directories

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Marius Mutu
2025-09-10 00:40:39 +03:00
commit fd87ebca03
23 changed files with 7317 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

415
docs/project/PRD_v2.md Normal file
View File

@@ -0,0 +1,415 @@
# Product Requirements Document (PRD) v2.0
## Sistem de Indexare și Căutare Activități Educaționale - FAZA 2
### 1. OVERVIEW
**Nume Produs:** INDEX-SISTEM-JOCURI v2.0
**Versiune:** 2.0 (Production-Ready)
**Data:** Septembrie 2025
**Obiectiv:** Sistem web production-ready cu containerizare Docker pentru indexarea și căutarea activităților educaționale din date reale.
**Context Faza 2:**
- Migrarea de la datele mock la datele reale din INDEX_MASTER_JOCURI_ACTIVITATI.md
- Implementare containerizare Docker și gestiune dependențe Pipenv
- Interfață minimalistă, profesională, fără branding extern
- Filtre dinamice populate din baza de date reală
### 2. PROBLEMA ȘI SOLUȚIA
**Probleme identificate în Faza 1:**
- Sistem cu date mock (doar 5 activități superficiale)
- Instalare manuală a dependențelor (pip install)
- Extracție superficială din fișiere (doar metadate)
- Filtre hardcodate în cod
- Interfață cu branding nepotrivit și emoji excesiv
- Lipsa containerizare pentru deployment
**Soluția Faza 2:**
- Indexare reală din catalogul de 2000+ activități documentate
- Containerizare Docker completă cu Pipenv
- Parser avansat pentru extracție detaliată a jocurilor individuale
- Filtre dinamice din baza de date
- Interfață minimalistă, profesională
- Deployment production-ready
### 3. CERINȚE FUNCȚIONALE
#### 3.1 Indexare Activități Reale (PRIORITATE CRITICĂ)
- **RF2.1:** Import complet din INDEX_MASTER_JOCURI_ACTIVITATI.md (1156 linii)
- **RF2.2:** Extracție detaliată pentru fiecare joc individual: nume, descriere completă, reguli, materiale specifice, durată exactă
- **RF2.3:** Parsarea structurată a următoarelor categorii:
- [A] Jocuri Cercetășești și Scout (15+ fișiere, 200+ jocuri)
- [B] Team Building și Comunicare (300+ activități)
- [C] Camping și Activități Exterior (400+ activități)
- [D] Escape Room și Puzzle-uri (100+ activități)
- [E] Orientare și Busole (80+ activități)
- [F] Primul Ajutor și Siguranță (60+ activități)
- [G] Activități Educaționale (200+ activități)
- [H] Resurse Speciale (60+ activități)
- **RF2.4:** Minimum 500 activități reale în baza de date (nu mock data)
- **RF2.5:** Validarea calității datelor - verificare automată că activitățile au descrieri complete
#### 3.2 Containerizare și Deployment
- **RF2.6:** Dockerfile pentru containerizarea aplicației Python Flask
- **RF2.7:** docker-compose.yml pentru orchestrarea serviciilor (app + database)
- **RF2.8:** Pipfile și Pipfile.lock pentru gestiunea dependențelor Python
- **RF2.9:** Volume mapping pentru persistența bazei de date
- **RF2.10:** Environment variables pentru configurare
- **RF2.11:** Health checks pentru monitoring container
#### 3.3 Interfață Web Minimalistă
- **RF2.12:** Eliminarea completă a brandingului extern:
- Eliminare logo-uri "Noi Orizonturi" și "Telekom"
- Eliminare referințe la organizații externe
- **RF2.13:** Design minimalist și profesional:
- Eliminare emoji din interfață
- Tipografie clasică, sobră
- Layout curat, modern
- Focus pe funcționalitate
- **RF2.14:** Păstrarea paletei de culori existente (gradienți orange/purple)
- **RF2.15:** Interfață responsive optimizată pentru desktop-first
#### 3.4 Filtre Dinamice din Baza de Date
- **RF2.16:** Eliminarea filtrelor hardcodate din cod
- **RF2.17:** Generarea dinamică a opțiunilor pentru dropdown-uri:
- Categorii (din datele reale indexate)
- Grupe de vârstă (din activitățile parsate)
- Tipuri de materiale (din catalogul real)
- Durate activități (din datele reale)
- Număr participanți (din specificațiile reale)
- **RF2.18:** Auto-refresh al filtrelor când se adaugă noi activități
- **RF2.19:** Filtrarea multiplă și combinată funcțională
#### 3.5 Căutare Avansată și Performance
- **RF2.20:** Full-text search optimizat pentru 500+ activități
- **RF2.21:** Indexare FTS (Full-Text Search) pentru performanță
- **RF2.22:** Căutare în multiple câmpuri: nume, descriere, reguli, materiale
- **RF2.23:** Autocomplete pentru termeni frecvenți
- **RF2.24:** Sortare după relevanță, popularitate, dată
### 4. CERINȚE NON-FUNCȚIONALE
#### 4.1 Performance
- **NFR2.1:** Indexarea completă în <30 minute pentru toate categoriile
- **NFR2.2:** Căutarea în <1 secundă pentru orice query pe 500+ activități
- **NFR2.3:** Startup container în <60 secunde
- **NFR2.4:** Memory footprint <512MB pentru container
#### 4.2 Reliability și Availability
- **NFR2.5:** Container restart policy pentru recovery automat
- **NFR2.6:** Graceful shutdown pentru Flask app
- **NFR2.7:** Database backup automată
- **NFR2.8:** Error logging comprehensiv
#### 4.3 Maintainability
- **NFR2.9:** Cod Python cu type hints și docstrings complete
- **NFR2.10:** Test coverage >80% pentru functionalități core
- **NFR2.11:** Separarea configurației de cod (12-factor app)
- **NFR2.12:** Documentație dezvoltatori cu setup în <5 minute
#### 4.4 Security
- **NFR2.13:** No hard-coded secrets în container
- **NFR2.14:** Limited container privileges
- **NFR2.15:** Input validation pentru toate form fields
- **NFR2.16:** SQL injection protection
### 5. ARHITECTURA TEHNICĂ v2.0
#### 5.1 Stack Tehnologic
- **Backend:** Python 3.11+, Flask 2.3+
- **Frontend:** HTML5, CSS3, JavaScript ES6+ (vanilla)
- **Database:** SQLite cu FTS5 extensions
- **Containerization:** Docker 24+, Docker Compose
- **Dependencies:** Pipenv pentru Python package management
- **Testing:** pytest pentru unit tests
#### 5.2 Structura Proiect v2.0
```
INDEX-SISTEM-JOCURI-v2/
├── docker-compose.yml # Orchestrarea serviciilor
├── Dockerfile # Container definition
├── Pipfile # Python dependencies
├── Pipfile.lock # Locked dependencies versions
├── .dockerignore # Docker ignore rules
├── .env.example # Environment variables template
├── app/
│ ├── __init__.py # Flask app factory
│ ├── main.py # Application entry point
│ ├── config.py # Configuration management
│ ├── models/
│ │ ├── __init__.py
│ │ ├── activity.py # Activity data model
│ │ └── database.py # Database management
│ ├── services/
│ │ ├── __init__.py
│ │ ├── indexer.py # Advanced indexing service
│ │ ├── search.py # Search service
│ │ └── parser.py # INDEX_MASTER parser
│ ├── web/
│ │ ├── __init__.py
│ │ ├── routes.py # Flask routes
│ │ └── forms.py # WTForms definitions
│ ├── templates/
│ │ ├── base.html # Base template (minimal design)
│ │ ├── index.html # Search interface
│ │ ├── results.html # Results display
│ │ └── activity.html # Activity detail sheet
│ └── static/
│ ├── css/
│ │ └── main.css # Minimal, professional styles
│ ├── js/
│ │ └── app.js # Frontend interactions
│ └── images/ # (only necessary images)
├── data/
│ └── INDEX_MASTER_JOCURI_ACTIVITATI.md # Source data
├── tests/
│ ├── __init__.py
│ ├── test_indexer.py # Indexing tests
│ ├── test_search.py # Search functionality tests
│ └── test_web.py # Web interface tests
├── scripts/
│ ├── setup.sh # Initial setup script
│ ├── index_data.py # Data indexing script
│ └── backup.sh # Backup script
├── docs/
│ ├── SETUP.md # Docker setup guide
│ ├── API.md # API documentation
│ └── DEVELOPMENT.md # Development guide
└── README.md # Main documentation
```
#### 5.3 Schema Baza de Date v2.0
```sql
-- Activități cu structură îmbunătățită
CREATE TABLE activities (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL, -- Numele jocului
description TEXT NOT NULL, -- Descrierea completă
rules TEXT, -- Regulile detaliate
variations TEXT, -- Variațiile jocului
category TEXT NOT NULL, -- Categoria principală
subcategory TEXT, -- Subcategoria
source_file TEXT NOT NULL, -- Fișierul sursă
page_reference TEXT, -- Referința la pagină
-- Parametri structurați
age_group_min INTEGER, -- Vârsta minimă
age_group_max INTEGER, -- Vârsta maximă
participants_min INTEGER, -- Participanți minim
participants_max INTEGER, -- Participanți maxim
duration_min INTEGER, -- Durata minimă (minute)
duration_max INTEGER, -- Durata maximă (minute)
-- Categorii pentru filtrare
materials_category TEXT, -- Categoria materialelor
materials_list TEXT, -- Lista detaliată materiale
skills_developed TEXT, -- Competențele dezvoltate
difficulty_level TEXT, -- Nivelul de dificultate
-- Metadata
keywords TEXT, -- Keywords pentru căutare
tags TEXT, -- Tags structurate (JSON)
popularity_score INTEGER DEFAULT 0, -- Scoring pentru relevanță
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
-- Full-text search optimizat
CREATE VIRTUAL TABLE activities_fts USING fts5(
name, description, rules, variations, keywords,
content='activities',
content_rowid='id'
);
-- Categorii dinamice pentru filtre
CREATE TABLE categories (
id INTEGER PRIMARY KEY AUTOINCREMENT,
type TEXT NOT NULL, -- 'category', 'age_group', 'materials', etc.
value TEXT NOT NULL, -- Valoarea categoriei
display_name TEXT, -- Numele pentru afișare
usage_count INTEGER DEFAULT 0, -- Numărul de utilizări
UNIQUE(type, value)
);
-- Indexuri pentru performance
CREATE INDEX idx_activities_category ON activities(category);
CREATE INDEX idx_activities_age ON activities(age_group_min, age_group_max);
CREATE INDEX idx_activities_participants ON activities(participants_min, participants_max);
CREATE INDEX idx_activities_duration ON activities(duration_min, duration_max);
CREATE INDEX idx_categories_type ON categories(type);
```
### 6. SPECIFICAȚII IMPLEMENTARE
#### 6.1 Parser INDEX_MASTER v2.0
```python
class IndexMasterParser:
"""Parser avansat pentru INDEX_MASTER_JOCURI_ACTIVITATI.md"""
def parse_categories(self) -> Dict[str, List[Activity]]:
"""Parsează toate categoriile și returnează activități structurate"""
def extract_individual_games(self, section: str) -> List[Activity]:
"""Extrage jocuri individuale din fiecare secțiune"""
def parse_game_details(self, text: str) -> Activity:
"""Parsează detaliile unui joc individual"""
def validate_activity_completeness(self, activity: Activity) -> bool:
"""Validează că activitatea are toate câmpurile necesare"""
```
#### 6.2 Docker Configuration
```yaml
# docker-compose.yml
version: '3.8'
services:
web:
build: .
ports:
- "5000:5000"
environment:
- FLASK_ENV=production
- DATABASE_URL=/app/data/activities.db
volumes:
- ./data:/app/data:rw
depends_on:
- setup
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
interval: 30s
timeout: 10s
retries: 3
setup:
build: .
command: python scripts/index_data.py
volumes:
- ./data:/app/data:rw
restart: "no"
```
#### 6.3 Pipenv Dependencies
```toml
# Pipfile
[packages]
flask = "~=2.3.0"
flask-wtf = "~=1.1.0"
flask-sqlalchemy = "~=3.0.0"
pypdf2 = "~=3.0.0"
python-docx = "~=0.8.11"
beautifulsoup4 = "~=4.12.0"
markdown = "~=3.4.0"
pdfplumber = "~=0.9.0"
gunicorn = "~=21.2.0"
python-dotenv = "~=1.0.0"
[dev-packages]
pytest = "~=7.4.0"
pytest-cov = "~=4.1.0"
black = "~=23.7.0"
flake8 = "~=6.0.0"
mypy = "~=1.5.0"
[requires]
python_version = "3.11"
```
### 7. CRITERII DE ACCEPTANȚĂ v2.0
#### 7.1 MVP Faza 2 (Minimum Viable Product)
- ✅ Minimum 500 activități reale indexate din INDEX_MASTER
- ✅ Container Docker functional cu o singură comandă: `docker-compose up`
- ✅ Interfață minimalistă fără branding extern
- ✅ Filtre dinamice populate din baza de date reală
- ✅ Căutare funcțională în datele reale
- ✅ Deployment production-ready
#### 7.2 Success Metrics v2.0
- **Data Quality:** >95% din activitățile din INDEX_MASTER indexate corect
- **Performance:** Căutare <1 secundă pe 500+ activități
- **Deployment:** Setup complet în <5 minute cu Docker
- **Reliability:** Container restart fără loss de date
- **Usability:** Interfață profesională, curată, responsivă
#### 7.3 Quality Gates
1. **Indexare completă:** Toate categoriile [A] - [H] procesate
2. **Validare date:** Fiecare activitate cu nume, descriere, categorie
3. **Container health:** Healthcheck passing, graceful shutdown
4. **Interface quality:** Zero branding extern, design minimalist
5. **Performance benchmarks:** <1s search, <60s container startup
### 8. RISCURI ȘI MITIGĂRI v2.0
| Risc | Probabilitate | Impact | Mitigare |
|------|---------------|--------|----------|
| Parsing incomplet INDEX_MASTER | Mare | Critic | Parser incremental cu validare pe fiecare categorie |
| Container build failures | Medie | Mare | Multi-stage build, cached layers, test CI/CD |
| Performance degradation cu date reale | Medie | Mare | Indexare FTS, query optimization, benchmarking |
| Design inconsistencies | Mică | Medie | Design system cu variabile CSS, review iterativ |
| Database migration issues | Medie | Mare | Backup automată, rollback procedures |
### 9. TIMELINE ESTIMAT v2.0
| Fază | Durata | Deliverables |
|------|--------|--------------|
| **Faza 2.1** | 2-3 zile | Parser INDEX_MASTER + Docker setup |
| **Faza 2.2** | 2-3 zile | Interfață minimalistă + filtre dinamice |
| **Faza 2.3** | 1-2 zile | Testing + performance optimization |
| **Faza 2.4** | 1 zi | Documentation + handover |
**Total:** 6-9 zile lucru
### 10. DEPENDENCIES v2.0
#### 10.1 Externe
- Docker 24+ și Docker Compose instalat
- Python 3.11+ pentru development local
- Acces la INDEX_MASTER_JOCURI_ACTIVITATI.md
#### 10.2 Interne
- INDEX_MASTER_JOCURI_ACTIVITATI.md ca sursă de date
- Arhitectura existentă ca bază pentru refactoring
- Design patterns din implementarea v1.0
### 11. SUCCESS CRITERIA v2.0
**Produs v2.0 finalizat când:**
1. ✅ Container Docker pornește cu `docker-compose up`
2. ✅ Minimum 500 activități reale în baza de date
3. ✅ Interfața web este curată, minimalistă, fără branding extern
4. ✅ Toate filtrele sunt populate dinamic din date reale
5. ✅ Căutarea funcționează rapid pe datele complete
6. ✅ Documentația permite setup în <5 minute
7. ✅ Testele automatizate rulează cu succes
8. ✅ System este production-ready
### 12. HANDOVER REQUIREMENTS
#### 12.1 Documentație Obligatorie
- **README.md** cu setup Docker în 3 pași
- **SETUP.md** pentru dezvoltatori
- **API.md** pentru integrări viitoare
- **DEVELOPMENT.md** pentru contribuții
#### 12.2 Testing Requirements
- Unit tests pentru parser și indexer
- Integration tests pentru web interface
- Performance tests pentru căutare
- Container health tests
#### 12.3 Production Readiness
- Environment variables configurabile
- Logging comprehensiv
- Error handling robust
- Monitoring și alerting ready
---
**Autor:** Claude AI Assistant
**Versiune PRD:** 2.0
**Data:** Septembrie 2025
**Status:** READY FOR IMPLEMENTATION
**Această versiune 2.0 transformă sistemul dintr-un prototip cu date mock într-o aplicație production-ready cu containerizare Docker și date reale din catalogul de 2000+ activități.**