1.1 Scop

Scopul acestui document este de a oferi o descriere detaliata a cerintelor pentru sistemul "Books on Web". Acesta va fi utilizat de catre echipa de dezvoltare pentru a implementa functionalitatile specificate si de catre echipa de testare pentru a verifica conformitatea sistemului.

2.1 Gestionarea Utilizatorilor

• Inregistrare: Utilizatorii noi trebuie sa se poata inregistra furnizand o adresa de e-mail, un nume de utilizator si o parola. Sistemul valideaza datele si previne inregistrarile duplicate pentru e-mail si nume de utilizator. (Vezi: htdocs/controllers/RegisterController.php, htdocs/models/User.php)
• Autentificare: Utilizatorii inregistrati se pot autentifica folosind e-mailul sau numele de utilizator si parola. La autentificare, un token JWT este stocat intr-un cookie pentru a mentine sesiunea activa. (Vezi: htdocs/controllers/LoginController.php, htdocs/config/utils.php)
• Deconectare: Utilizatorii autentificati se pot deconecta, actiune care va sterge cookie-ul de autentificare. (Vezi: htdocs/controllers/LogoutController.php)
• Rol de Administrator: Sistemul suporta un rol de administrator cu privilegii extinse. Rutele de administrare sunt protejate si accesibile doar utilizatorilor cu acest rol. (Vezi: htdocs/router.php)

2.2 Gestionarea Cartilor

• Vizualizare Carti: Toti utilizatorii pot vizualiza o lista de carti. Lista poate fi filtrata dupa gen si cautata dupa titlu sau autor. (Vezi: htdocs/controllers/BookController.php, htdocs/models/Book.php)
• Vizualizare Detalii Carte: Fiecare carte are o pagina de detalii care afiseaza informatii complete, inclusiv recenziile utilizatorilor. (Vezi: htdocs/controllers/BookController.php)
• Administrare Carti (Admin): Administratorii pot adauga, edita si sterge carti din sistem. (Vezi: htdocs/controllers/BookController.php)
• Import Carti (Admin): Administratorii pot importa o lista de carti dintr-un fisier CSV sau JSON, care trebuie sa contina cel putin titlul si autorul. (Vezi: htdocs/controllers/BookController.php, importCsv si importJson)

2.3 Recenzii si Evaluari

• Adaugare Recenzie: Utilizatorii autentificati pot adauga o recenzie (rating de la 1 la 5 si un comentariu) pentru o carte, dar numai o singura data per carte. (Vezi: htdocs/controllers/ReviewController.php, htdocs/models/Review.php)
• Vizualizare Recenzii: Recenziile pentru o carte sunt afisate pe pagina de detalii a cartii, impreuna cu rating-ul mediu. (Vezi: htdocs/models/Book.php, htdocs/controllers/BookController.php)

2.4 Grupuri de Discutii

• Creare si Vizualizare Grupuri: Utilizatorii autentificati pot crea grupuri de discutii noi si pot vizualiza o lista a grupurilor existente. (Vezi: htdocs/controllers/GroupController.php, htdocs/models/Group.php)
• Alaturare la Grup: Utilizatorii se pot alatura grupurilor existente. Creatorul unui grup este adaugat automat ca membru. (Vezi: htdocs/controllers/GroupController.php)
• Gestionare Continut Grup: Membrii unui grup pot adauga carti in lista grupului si pot posta comentarii in sectiunile de discutii dedicate fiecarei carti. (Vezi: htdocs/controllers/GroupController.php, htdocs/models/GroupDiscussion.php)

2.5 Functionalitati Suplimentare

• Feed RSS: Aplicatia genereaza un feed RSS cu cele mai recente carti si recenzii adaugate. (Vezi: htdocs/controllers/RssController.php)
• Statistici: O pagina de statistici afiseaza numarul de recenzii si rating-ul mediu pentru fiecare carte. Aceste date pot fi exportate in format CSV sau DocBook/XML. (Vezi: htdocs/controllers/StatisticsController.php)
• Gasire Biblioteci: Utilizatorii pot gasi biblioteci in apropierea lor, furnizand coordonatele geografice (latitudine si longitudine). Aplicatia foloseste serviciul Nominatim de la OpenStreetMap pentru aceasta functionalitate. (Vezi: htdocs/controllers/LibraryController.php, htdocs/services/LibraryService.php)

3.1 Nivel 1: Contextul Sistemului

La acest nivel, vedem aplicatia "Books on Web" ca o cutie neagra in centrul diagramei. Interrelationeaza cu urmatoarele entitati:

• Utilizator: Interationeaza cu sistemul printr-un browser web pentru a cauta carti, a se alatura grupurilor si a lasa recenzii.
• Administrator: Un tip special de utilizator care gestioneaza continutul (carti) prin interfata de administrare.
• Sistemul de E-mail: Desi nu este explicit implementat in codul furnizat (nu exista functionalitati de trimitere e-mail), un sistem real ar necesita interactiune cu un serviciu de e-mail pentru inregistrare si notificari.
• OpenStreetMap/Nominatim API: Un sistem extern utilizat pentru a oferi date despre bibliotecile din apropiere.

3.2 Nivel 2: Containere

Aici, "marim" cutia neagra a sistemului "Books on Web" pentru a vedea principalele sale componente (containere) tehnologice:

• Aplicatia Web (Server Apache cu PHP): Acesta este containerul principal. El serveste paginile HTML utilizatorilor si expune un API pentru functionalitatile aplicatiei. Este responsabil pentru toata logica. Ruleaza pe un server web Apache si este scris in PHP.
• Baza de Date (PostgreSQL): Un container de stocare care persista toate datele aplicatiei: utilizatori, carti, recenzii, grupuri, etc. Schema este definita in init.sql si este gestionata printr-un container Docker (conform compose.yaml).
• Adminer: Un container auxiliar (definit in compose.yaml) care ofera o interfata web pentru administrarea bazei de date PostgreSQL, utila in timpul dezvoltarii.

3.3 Nivel 3: Componente

Acum ne concentram pe containerul "Aplicatia Web" si il descompunem in componentele sale principale. Acestea nu sunt neaparat clase individuale, ci grupari logice de functionalitati:

• Router (router.php): Intercepteaza toate cererile HTTP si le directioneaza catre controller-ul corespunzator. Este punctul de intrare in logica aplicatiei.
• Controlere (htdocs/controllers/): Componente care gestioneaza cererile utilizatorului. Fiecare controller este responsabil pentru o anumita resursa (ex: BookController, UserController/LoginController, GroupController). Ele orchestreaza interactiunea dintre modele si vederi.
• Models (htdocs/models/): Reprezinta interactiunea cu baza de date. Exista modele pentru fiecare entitate majora: User, Book, Review, Group.
• Views (htdocs/views/, layout.tpl): Componente responsabile cu prezentarea datelor utilizatorului. Acestea sunt fisiere PHP/HTML (sabloane) care sunt populate cu date de catre controlere.
• Services (htdocs/services/): Componente care incapsuleaza logica pentru interactiunea cu servicii externe, cum ar fi LibraryService pentru API-ul Nominatim.
• Componenta de Autentificare (utils.php, LoginController.php): Gestioneaza logica de autentificare, crearea si validarea token-urilor JWT.

3.4 Nivel 4: Cod

La acest nivel detaliem implementarea catorva componente cheie pentru a intelege cum functioneaza sistemul la nivel de cod sursa.

• Routerul (router.php)

  Punctul de intrare in aplicatie este fisierul router.php. Acesta examineaza URI-ul si metoda HTTP a fiecarei cereri primite. Folosind o structura switch, directioneaza cererea catre controller-ul si metoda corespunzatoare. De exemplu, o cerere GET catre /books va instantia BookController si va apela metoda index(). Routerul este de asemenea responsabil pentru securitatea rutelor de administrare (cele care incep cu /admin), verificand daca utilizatorul este autentificat si are rol de administrator inainte de a permite accesul. La final, rezultatul (continutul HTML) generat de controller este injectat in sablonul principal layout.tpl.

• Modelele (htdocs/models/)

  Componentele de tip Model sunt responsabile pentru toata interactiunea cu baza de date PostgreSQL. Fiecare model (ex: Book.php, User.php, Review.php) corespunde unei entitati din aplicatie. Ele folosesc un obiect PDO, obtinut printr-un singleton (Database::getInstance()), pentru a executa interogari SQL. De exemplu, metoda Book::createBook() primeste detalii despre o carte, pregateste o interogare SQL de tip INSERT si o executa, gestionand direct persistenta datelor in containerul bazei de date. Similar, User::findUserByEmailOrUsername() executa o interogare SELECT pentru a gasi un utilizator.

• Autentificarea cu JWT (htdocs/controllers/LoginController.php, htdocs/config/utils.php)

  Autentificarea se bazeaza pe JSON Web Tokens (JWT), folosind biblioteca firebase/php-jwt. Cand un utilizator se autentifica cu succes in LoginController, se creeaza un token (payload) cu datele utilizatorului (ID, username, rol). Acest payload este apoi codificat folosind metoda statica JWT::encode(), un algoritm HS256 si o cheie secreta stocata in cod. Tokenul rezultat este trimis clientului si stocat intr-un cookie HTTP-only. Pentru a verifica daca un utilizator este autentificat, aplicatia foloseste functia Utils::getLoggedInUser(), care citeste cookie-ul, decodeaza si valideaza tokenul folosind JWT::decode() si aceeasi cheie secreta.

• Integrarea cu SimplePie (htdocs/controllers/HomeController.php)

  Biblioteca simplepie/simplepie este utilizata pentru a citi si parsa feed-uri RSS. In HomeController, pagina principala a aplicatiei foloseste SimplePie pentru a se conecta la propriul feed RSS generat la adresa /rss. Metoda index() instantiaza clasa SimplePie, seteaza URL-ul feed-ului, il initializeaza (init()) si extrage item-urile (get_items()). Aceste item-uri, care reprezinta ultimele carti si recenzii adaugate, sunt apoi trimise catre sablonul home.tpl pentru a fi afisate. Acest mecanism decupleaza generarea continutului de afisarea lui pe prima pagina.