Marius Mutu
fd87ebca03
- 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>
415 lines
16 KiB
Markdown
415 lines
16 KiB
Markdown
# 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.** |