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