game-library/docs/project/PRD.md

Product Requirements Document (PRD)

Sistem de Indexare și Căutare Activități Educaționale

1. OVERVIEW

Nume Produs: INDEX-SISTEM-JOCURI
Versiune: 1.0
Data: Septembrie 2025
Obiectiv: Sistem web simplu pentru indexarea, căutarea și generarea de fișe pentru activități educaționale din diverse formate de fișiere.

2. PROBLEMA ȘI SOLUȚIA

Problema:

• Activități educaționale stocate în ~100+ fișiere de tipuri diferite (PDF, DOC, HTML, MD, TXT)
• Căutarea manuală prin fișiere este ineficientă
• Lipsește o modalitate rapidă de a genera fișe de activități

Soluția:

• Sistem de indexare automată multi-format
• Interfață web cu filtre avansate pentru căutare
• Generator de fișe HTML fără dependințe LLM

3. CERINȚE FUNCȚIONALE

3.1 Indexare Activități

• RF1: Extragerea automată de activități din fișiere PDF, DOC/DOCX, HTML, MD, TXT
• RF2: Detectarea automată a parametrilor: titlu, descriere, vârstă, durată, materiale, participanți
• RF3: Indexare inițială batch pentru toate fișierele existente
• RF4: Indexare incrementală pentru fișiere noi/modificate
• RF5: Progress tracking pentru procesul de indexare

3.2 Interfață Web de Căutare

• RF6: Layout identic cu mockup-ul furnizat (interfata-web.jpg)
• RF7: Search box pentru căutare text liberă
• RF8: 9 filtre dropdown:
  • Valori (categorie)
  • Durată (5-15min, 15-30min, 30+min)
  • Tematică (cercetășesc, team building, educativ)
  • Domeniu (sport, artă, știință)
  • Metodă (joc, poveste, atelier)
  • Materiale necesare (fără, simple, complexe)
  • Competențe (fizice, mentale, sociale)
  • Număr participanți (2-5, 5-10, 10-30, 30+)
  • Vârstă (5-8, 8-12, 12-16, 16+)
• RF9: Butoane "Aplică" și "Resetează"
• RF10: Afișare rezultate în tabel cu coloane: Titlu, Detalii, Metodă, Temă, Valori
• RF11: Link către fișierul sursă pentru fiecare rezultat

3.3 Generator Fișe Activități

• RF12: Buton "Generează fișă" pentru fiecare activitate
• RF13: Template HTML predefinit pentru fișe
• RF14: Algoritm de recomandări bazat pe similaritate (tags, categorie, vârstă)
• RF15: Fișa să conțină:
  • Informații complete activitate
  • Instrucțiuni pas cu pas
  • Lista materiale cu checklist
  • 3-5 activități similare recomandate
• RF16: Export fișă ca HTML printabil
• RF17: Funcție de copiere conținut fișă

4. CERINȚE NON-FUNCȚIONALE

4.1 Performance

• NFR1: Căutarea să returneze rezultate în <2 secunde
• NFR2: Indexarea să proceseze 100+ fișiere în <10 minute
• NFR3: Interfața să fie responsivă pe desktop/tablet

4.2 Usability

• NFR4: Interfață simplă, intuitivă, fără învățare necesară
• NFR5: Feedback vizual pentru toate acțiunile (loading, success, errors)
• NFR6: Mesaje de eroare clare și acționabile

4.3 Maintainability

• NFR7: Cod Python simplu, well-documented, <500 linii total
• NFR8: Dependințe minime (Flask + biblioteci standard)
• NFR9: Baza de date SQLite simplă, fără migrări complexe

5. ARHITECTURA TEHNICĂ

5.1 Stack Tehnologic

• Backend: Python 3.8+, Flask
• Frontend: HTML5, CSS3, JavaScript vanilla
• Database: SQLite
• Libraries: PyPDF2, python-docx, BeautifulSoup4, markdown

5.2 Structura Fișiere

INDEX-SISTEM-JOCURI/
├── app.py              # Flask server principal (~200 linii)
├── indexer.py          # Script indexare multi-format (~150 linii)
├── database.py         # Helper SQLite (~50 linii)
├── templates/
│   ├── index.html      # Pagina căutare (~100 linii)
│   ├── results.html    # Afișare rezultate (~50 linii)
│   └── fisa.html       # Template fișă activitate (~50 linii)
├── static/
│   └── style.css       # CSS minimal (~50 linii)
├── activities.db       # Baza de date SQLite
├── PRD.md              # Acest document
└── PM_PROMPT.md        # Prompt pentru project manager

5.3 Schema Baza de Date

CREATE TABLE activities (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    file_path TEXT NOT NULL,
    file_type TEXT,         -- pdf, doc, html, md, txt
    page_number INTEGER,
    tags TEXT,              -- JSON array cu tags
    category TEXT,
    age_group TEXT,
    participants TEXT,
    duration TEXT,
    materials TEXT,
    difficulty TEXT DEFAULT 'mediu',
    source_text TEXT,       -- full text pentru căutare FTS
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE VIRTUAL TABLE activities_fts USING fts5(
    title, description, source_text,
    content='activities'
);

6. FLUXUL UTILIZATORULUI

6.1 Indexare Inițială

1. Admin rulează python indexer.py --full
2. Scriptul scanează toate fișierele din directoare
3. Extrage activități folosind parsere specializate
4. Salvează în baza de date cu progress feedback
5. Creează indexul full-text pentru căutare rapidă

6.2 Căutare Activități

1. Utilizatorul accesează http://localhost:5000
2. Setează filtre din dropdown-uri (opțional)
3. Introduce termeni în search box (opțional)
4. Apasă "Aplică" sau Enter
5. Vezi rezultatele în tabel
6. Click pe titlu pentru a vedea fișierul sursă

6.3 Generare Fișă

1. Din rezultate, click "Generează fișă" la o activitate
2. Sistemul creează fișă HTML cu template predefinit
3. Algoritm găsește 3-5 activități similare
4. Afișează fișa completă în pagină nouă
5. Opțiune printare sau copiere conținut

7. CRITERII DE ACCEPTANȚĂ

7.1 MVP (Minimum Viable Product)

• ✅ Indexează activități din PDF, DOC, HTML, MD, TXT
• ✅ Interfață web cu search și 9 filtre
• ✅ Afișare rezultate cu link la sursă
• ✅ Generare fișe HTML simple

7.2 Success Metrics

• Indexează >90% din activitățile existente corect
• Timpul de căutare <2 secunde pentru orice query
• Interfața funcționează pe Chrome, Firefox, Safari
• Fișele generate sunt printabile și utile

8. RISCURI ȘI MITIGĂRI

Risc	Probabilitate	Impact	Mitigare
Parsarea PDF-urilor eșuează	Medie	Mare	Folosire PyPDF2 + pdfplumber ca backup
Detectarea automată parametri inexactă	Mare	Medie	Pattern-uri regex + validare manuală opțională
Performance slab la căutare	Mică	Mare	Index FTS SQLite + limitare rezultate
Interfața nu seamănă cu mockup	Mică	Mică	Review iterativ cu feedback vizual

9. TIMELINE ESTIMAT

Fază	Durata	Deliverables
Sprint 1	2-3 zile	Indexer funcțional pentru toate formatele
Sprint 2	2-3 zile	Interfață web cu căutare și filtre
Sprint 3	1-2 zile	Generator fișe HTML cu recomandări
Sprint 4	1 zi	Testing, bug fixes, documentație

Total: 6-9 zile lucru

10. DEPENDENCIES

10.1 Externe

• Python 3.8+ instalat
• Acces la fișierele existente în /mnt/d/GoogleDrive/Cercetasi/carti-camp-jocuri/
• Browser modern pentru testare

10.2 Interne

• Baza de date SQLite existentă (game_library.db) ca referință
• Mockup interfață (interfata-web.jpg) pentru design
• Colecția existentă de activități ca date de test

11. SUCCESS CRITERIA

Produs finalizat când:

1. ✅ Indexer poate procesa toate tipurile de fișiere fără erori
2. ✅ Interfața web arată identic cu mockup-ul
3. ✅ Căutarea returnează rezultate relevante rapid
4. ✅ Fișele generate sunt complete și utile
5. ✅ Sistemul poate fi rulat local fără configurare complexă
6. ✅ Documentația permite unei terțe părți să înțeleagă și să folosească sistemul

---

Autor: Claude AI Assistant
Review: [To be completed by stakeholders]
Approval: [To be completed by product owner]