game-library/docs/project/PRD_v2.md

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

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

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

# 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

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