diff --git a/AI_USAGE.md b/AI_USAGE.md deleted file mode 100644 index 749a743..0000000 --- a/AI_USAGE.md +++ /dev/null @@ -1,30 +0,0 @@ -# Use of AI in the Development of PCMod - -## AI Usage #1 - -* Date: 03/07/2026 - -* Phase: 1 – Definition of features and user interfaces. - -* Objective: Generate logos for the application. - -* Tool: Microsoft Copilot. - -* Specific Version: Microsoft 365 Copilot. - -* Tool Configuration: - - * Model: GPT-5 Chat. - * Reasoning level: Automatic. - * Mode: Chat. - -* How it was used: - - **Prompt:** - ``` - Generate logos for an e-commerce platform dedicated to buying and selling PC components. You may take inspiration from websites such as PCComponentes or Coolmod. Provide both an icon and a logo including the application name, PCMod. - ``` - -* Tool Extensions: Image generation. - -* Context Files Related to AI Usage in the Project: N/A. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c601a3..e6c55c2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.0.1] - 2026-08-18 + +### Added + +- Basic Workflow (Unit Tests + SonarCloud Analysis). +- Complete Workflow (Unit, Integration and System Tests + SonarCloud Analysis). +- Minimum configuration for the backend, frontend, and database. +- Class Component. +- Load components endpoint, function, and interface (RestController, Service, Repository, and Page). +- REST API documentation. +- Full test suite (Unit, Integration and System Tests for backend and frontend). + +### Changed + +- Updated `CHANGELOG.md`. +- Updated `AI_USAGE.md` and moved to /docs. +- Split documentation into separate files: `README.md`, `ANALYSIS.md`, `AUTHORS.md`, `DETAILED-FEATURES.md`, `DEVELOPMENT-GUIDE.md`, `METHODOLOGY.md`, `OBJECTIVES.md` and `PROJECT-TRACKING.md`. + +--- + ## [0.0.1] - 2026-07-09 ### Added diff --git a/README.md b/README.md index 5e43843..381455b 100644 --- a/README.md +++ b/README.md @@ -6,317 +6,71 @@ PCMod is a web-based application designed for buying or selling PC components online. -Its primary functionality is to facilitate the purchase and sale of computer hardware, including CPUs, GPUs, RAM modules, and other components. Additionally, the platform allows users to submit reviews for the products. The application provides a searchable and filterable product catalog, detailed product pages, secure payment processing, an AI-powered chatbot that acts as a virtual assistant, automated email notifications for user registration and purchase confirmation, and the generation of PDF invoices for completed transactions ([see the section "Basic, intermediate and advanced features"](#️-basic-intermediate-and-advanced-features)). +Its primary functionality is to facilitate the purchase and sale of computer hardware, including CPUs, GPUs, RAM modules, and other components. Additionally, the platform allows users to submit reviews for the products. The application provides a searchable and filterable product catalog, detailed product pages, secure payment processing, an AI-powered chatbot that acts as a virtual assistant, automated email notifications for user registration and purchase confirmation, and the generation of PDF invoices for completed transactions. -The functionalities available within the application depend on the user's assigned role, with each role having access to a specific set of features ([see the section "Features available by user role"](#-features-available-by-user-role)). +The functionalities available within the application depend on the user's assigned role, with each role having access to a specific set of features. -## 🎯 Objectives +⚠️ **NOTE:** *At this stage, the functional and technical objectives of the application have been defined, and development has begun; however, the implementation is not yet functional.* -This section outlines the functional and technical objectives to be achieved during the development of the PCMod application. +## πŸ“„ Documentation of the project -### Functional Objectives +* [Objectives](/docs/OBJECTIVES.md): Functional and technical objectives of the project. +* [Methodology](/docs/METHODOLOGY.md): Development methodology, phases and planned delivery scheduled. +* [Features](/docs/DETAILED-FEATURES.md): Feature classification by complexity (basic, intermediate, and advanced) and availability across user roles. +* [Analysis](/docs/ANALYSIS.md): Pages and navigation, entities, user permissions and ownership, images and charts, additional technologies, and advanced query. +* [Project Tracking](/docs/PROJECT-TRACKING.md): Links to Medium blog and GitHub Project. +* [Authors](/docs/AUTHORS.md): Thesis author and supervisor information. +* [Development Guide](/docs/DEVELOPMENT-GUIDE.md): Architecture, technology stack, development tools, quality assurance, deployment, development workflow, CI/CD, testing, and application execution. -The primary functional objectives of PCMod are the implementation of CRUD (Create, Read, Update, Delete) operations for PC components, reviews, and users. The application aims to provide users with an easy and efficient way to browse and filter PC components, as well as complete purchases. +## πŸ“ Wireframes -To meet the authorization requirements based on user roles and resource ownership, it is necessary to implement an user authentication and management system (e.g., access to the administration panel). +* **Main page:** -As advanced objectives, the application will integrate services capable of sending emails, generating PDF invoices, and assisting users through an AI-powered chatbot. - -* Enable administrators to perform complete CRUD operations for PC components. -* Provide users with efficient search and filtering capabilities for PC components. -* Implement an user authentication and management system supporting multiple user roles with different privilege levels. -* Enable complete CRUD operations for reviews. -* Enable complete CRUD operations for users. -* Provide a complete purchasing workflow (shopping cart β†’ secure payment using Stripe β†’ email confirmation). -* Send automated email notifications when a new user registers or a purchase is completed. -* Automatically generate and send purchase invoices in PDF format via email. -* Provide administrators with a dashboard containing statistics, a user list, and a purchase history. -* Integrate an AI-powered chatbot to assist users. - -### Technical Objectives - -PCMod follows a client–server architecture, using React and TypeScript for the frontend, Spring Boot and Java for the backend, and MySQL as the relational database management system. The application is deployed over HTTPS on port 443. - -Postman will be used to design, document, and test the REST API endpoints provided by the backend. In addition, SpringDoc and Swagger/OpenAPI will be used to generate and maintain the API documentation. - -To ensure software quality, automated testing will be implemented using tools such as Mockito, Selenium, and JUnit. In addition, static code quality analysis will be performed using SonarQube. - -Finally, the application packaging and publishing process will be carried out using Docker and GitHub Actions workflows. - -* Develop a web application based on a client–server architecture, separating the frontend, backend, and database layers. -* Develop the frontend using React and TypeScript. -* Develop the backend using Spring Boot and Java. -* Manage application data through a MySQL relational database. -* Design, document, and test the available REST API endpoints using Postman, SpringDoc, and Swagger/OpenAPI. -* Integrate external APIs to support secure payment processing and the AI chatbot. -* Use additional technologies for email delivery, chart generation, and PDF generation. -* Ensure software quality through automated testing, GitHub Actions workflows, and static code analysis using SonarQube. -* Containerize the application and publish the Docker image to Docker Hub using GitHub Actions workflows. - -⚠️ **NOTE:** *At this stage, the functional and technical objectives of the application have been defined; however, the implementation has not yet begun.* - -## πŸ› οΈ Methodology - -This project follows an iterative and incremental development methodology based on the principles of Extreme Programming (XP). - -GitHub Projects and GitHub Issues are used to manage tasks through a Kanban board. GitHub Flow is adopted as the version control workflow. GitHub Actions is used to automate testing, code quality checks, and the publication of Docker images to Docker Hub. - -The project is divided into the following phases: - -* πŸ“„ **Phase 1: Definition of features and user interfaces:** Definition of the functional and technical objectives, classification of features into basic, intermediate, and advanced levels, definition of permissions for each user role, design of application pages using *wireframes*, selection of charts to be displayed, design of the application's class structure, selection of additional technologies, and design of the advanced search algorithm. -* πŸ“ **Phase 2: Repository, testing and continuous integration:** Creation of the backend and frontend projects, configuration of testing workflows in the repository, implementation of the minimum functionality required to verify communication between application layers, testing of the initial functionality, and configuration of static code analysis with SonarQube. -* πŸ–₯️ **Phase 3: Version 0.1 – Basic functionality and Docker:** Implementation of the application's basic functionality, release of version 0.1, creation of the required Dockerfile and Docker Compose files, and publication of version 0.1 to Docker Hub. -* πŸ–₯️ **Phase 4: Version 0.2 – Intermediate functionality:** Implementation of the application's intermediate functionality, release of version 0.2, and publication of version 0.2 to Docker Hub. -* πŸ–₯️ **Phase 5: Version 1.0 – Advanced functionality:** Implementation of the application's advanced functionality, release of version 1.0, and publication of version 1.0 to Docker Hub. -* πŸ“ **Phase 6: Thesis report:** Preparation of the project's final report. -* πŸ§‘β€πŸ« **Phase 7: Thesis defense:** Preparation and defense of the project before the evaluation committee. - -The planned start and delivery dates for each phase are shown below: - -| Phase | Start Date | Planned Delivery Date | Actual Delivery Date | -| ----- | :--------: | :-------------------: | :------------------: | -| Phase 1: Definition of features and user interfaces | 30/06/2026 | 15/09/2026 | 13/07/2026 | -| Phase 2: Repository, testing and continuous integration | - | 15/10/2026 | - | -| Phase 3: Version 0.1 – Basic functionality and Docker | - | 15/12/2026 | - | -| Phase 4: Version 0.2 – Intermediate functionality | - | 01/03/2027 | - | -| Phase 5: Version 1.0 – Advanced functionality | - | 15/04/2027 | - | -| Phase 6: Thesis report | - | 15/05/2027 | - | -| Phase 7: Thesis defense | - | 15/06/2027 | - | - -### πŸ“Š Gantt chart: - -![Gantt chart](/docs/img/gantt_chart.png) - -## πŸ–₯️ Basic, intermediate and advanced features - -The functionalities available in the application are divided into basic, intermediate, and advanced features as follows: - -### πŸ”§ Basic features: - -* Component creation -* Component editing -* Component deletion -* Component listing -* Displaying component detail pages -* Adding components to the shopping cart -* Removing components from the shopping cart -* Viewing components in the shopping cart -* Completing purchases -* Review creation -* Review modification -* Review deletion -* Listing component reviews -* User registration -* User login -* Editing personal information -* User account deletion -* Accessing the user profile page -* Listing all user purchases -* Listing all users -* Listing all PCMod purchases - -### πŸ› οΈ Intermediate features: - -* Email sending (user registration and purchase completion notifications) -* PDF generation (purchase invoice sent by email) -* Advanced search filtering (component name, type, brand, and price) -* Displaying non-graphical statistics -* Displaying graphical statistics - -### βš™οΈ Advanced features: - -* Stripe payment gateway integration -* AI-powered chatbot integration - -## πŸ‘€ Features Available by User Role - -PCMod users will have access to different functionalities depending on their assigned role: - -| Feature | Anonymous User | Registered Non-Administrator User | Registered Administrator User | -|---------|:------:|:------:|:------:| -| Component creation | ❌ | ❌ | βœ… | -| Component editing | ❌ | ❌ | βœ… | -| Component deletion | ❌ | ❌ | βœ… | -| Component listing | βœ… | βœ… | βœ… | -| Component filtering | βœ… | βœ… | βœ… | -| Displaying component detail pages | βœ… | βœ… | βœ… | -| Adding components to the shopping cart | ❌ | βœ… | βœ… | -| Removing components from the shopping cart | ❌ | βœ… | βœ… | -| Viewing components in the shopping cart | ❌ | βœ… | βœ… | -| Completing purchases (Stripe integration) | ❌ | βœ… | βœ… | -| Review creation | ❌ | βœ… | βœ… | -| Review modification (controlled by owner or administrator) | ❌ | βœ… | βœ… | -| Review deletion (controlled by owner or administrator) | ❌ | βœ… | βœ… | -| Listing component reviews | βœ… | βœ… | βœ… | -| User registration | βœ… | ❌ | ❌ | -| User login | ❌ | βœ… | βœ… | -| Editing personal information (controlled by owner or administrator) | ❌ | βœ… | βœ… | -| User account deletion (controlled by owner or administrator) | ❌ | βœ… | βœ… | -| Accessing the user profile page (controlled by owner or administrator) | ❌ | βœ… | βœ… | -| Listing total user purchases | ❌ | βœ… | βœ… | -| Listing users | ❌ | ❌ | βœ… | -| Listing total PCMod purchases | ❌ | ❌ | βœ… | -| Displaying non-graphical statistics | ❌ | ❌ | βœ… | -| Displaying graphical statistics | ❌ | ❌ | βœ… | -| Email service usage | βœ… | βœ… | βœ… | -| PDF generation service usage | ❌ | βœ… | βœ… | -| AI-powered chatbot usage | βœ… | βœ… | βœ… | - -## 🧩 Analysis - -### πŸ–₯️ Pages and navigation - -This section describes the content of each designed page and presents the corresponding *wireframe* for each one. - -* **Main page:** The initial page of the web application. It provides access to the component listing page, user registration, login, AI-powered chatbot, and the user dropdown menu. ![Wireframe Main Page](/docs/img/wireframes/wireframe-main-page.png) -* **Available components listing:** Page containing all available components in the store, allowing users to apply filters. It provides access to the component creation page (administrators only). - ![Wireframe Products Page](/docs/img/wireframes/wirefreme-products-page.png) - -* **Component detail page:** Page displaying the attributes of a component. It provides access to review creation, editing, and deletion (registered non-administrator users and administrators, with ownership control), as well as component editing and deletion (administrators only). - ![Wireframe Detail Product Page](/docs/img/wireframes/wireframe-detail-product-page.png) - -* **Component creation / editing form:** Page containing a form with the required fields to store a component in the database. - ![Wireframe Add / Modify Component Form](/docs/img/wireframes/wireframe-add-modify-form.png) - -* **Shopping cart page:** Page displaying the products added to the user's shopping cart and providing access to the payment process. - ![Wireframe Cart Page](/docs/img/wireframes/wireframe-cart-page.png) - -* **Login page:** Page containing a form to authenticate users using their email address and password. It provides access to the registration page. - ![Wireframe LogIn Page](/docs/img/wireframes/wireframe-login-page.png) - -* **Registration page:** Page containing a form to register new users and store their information in the database. It provides access to the login page. - ![Wireframe Register Page](/docs/img/wireframes/wireframe-register-form.png) - -* **Administration panel:** Page displaying statistics, the list of users, and the list of sales (administrators only). It provides access to the user profile page. - ![Wireframe Admin Page](/docs/img/wireframes/wireframe-admin-page.png) - -* **User profile page:** Page displaying the personal information of the registered user and a list of their completed purchases. It allows profile editing and account deletion. - ![Wireframe User Profile Page](/docs/img/wireframes/wireframe-profile-page.png) - -* **User menu:** Menu accessible from the website header after login. It provides access to the user profile page, the administration panel (administrators only), and the logout option. - ![Wireframe Dropdown User Menu](/docs/img/wireframes/wireframe-user-dropdown.png) - -* **AI chatbot prototype:** Page/component that enables users to interact through a chat interface with an artificial intelligence model. - ![Wireframe AI Chatbot](/docs/img/wireframes/wireframe-chatbot-AI.png) +* **Available components listing:** -* **Error page:** Error page following the visual style of the rest of the application, displaying the error code and message. It provides access to the main page. - ![Wireframe Error Page](/docs/img/wireframes/wireframe-error-page.png) - -#### Navigation Diagram: -![Wireframe Screens](/docs/img/wireframes/Wireframes%20Screens.png) - -### πŸ“¦ Entities - -This section describes the entities present in the PCMod application, along with their corresponding attributes. They are represented in the following class diagram: - -![Class Diagram](/docs/img/class_diagram.png) - -| Class | Attributes | -|:------:|------------------| -| User | ID, name, surname, username, email, encodedPassword, address, purchaseList, reviewList, image | -| Review | ID, title, content, rating, component, author, date | -| Component | ID, name, description, type, brand, price, stock, reviewList, image | -| Purchase | ID, price, date, status, PurchaseItemList, customer | -| PurchaseItem | ID, unitPrice, quantity, component | - -Two enumerated types have been added in order to improve maintainability and facilitate future extensions if required: - -| Enum | Values | -|:----:|---------| -| PurchaseStatus | ACTIVE, FINISHED | -| ComponentType | CPU, GPU, RAM, STORAGE, MOTHERBOARD, PSU, CASE | - -### πŸ”’ User Permissions - -#### πŸ‘€ Anonymous Users: - -**Available functionalities:** -* Viewing the component listing. - * **NOTE:** *Search filters are available.* -* Viewing a component detail page. -* Viewing the reviews associated with a component. -* User registration. - * **NOTE:** *Email service usage is included.* -* Using the AI-powered chatbot. - -**Ownership:** An anonymous user does not own any other element within the application. - -#### πŸ§‘ Registered Non-Administrator Users: - -**Available functionalities:** -* Viewing the component listing. - * **NOTE:** *Search filters are available.* -* Viewing a component detail page. -* CRUD operations for reviews. - * **NOTE:** *A registered non-administrator user can only edit or delete their own reviews.* -* CRUD operations for users. - * **NOTE:** *A registered non-administrator user can only edit or delete their own user account.* -* Purchasing process: Adding/removing products from the shopping cart, viewing cart contents, and completing purchases. - * **NOTE:** *Email service usage and Stripe integration are included.* -* User login. -* Using the AI-powered chatbot. + ![Wireframe Products Page](/docs/img/wireframes/wirefreme-products-page.png) -**Ownership:** A registered non-administrator user owns their completed purchases and created reviews. +* **Component detail page:** -#### πŸ‘¨β€πŸ’Ό Registered Administrator Users: + ![Wireframe Detail Product Page](/docs/img/wireframes/wireframe-detail-product-page.png) -**Available functionalities:** -* CRUD operations for components. - * **NOTE:** *Search filters are available.* -* CRUD operations for reviews. - * **NOTE:** *Administrator users can edit and delete reviews created by any user.* -* CRUD operations for users. - * **NOTE:** *Administrator users can edit and delete any user's account.* -* Purchasing process: Adding/removing products from the shopping cart, viewing cart contents, and completing purchases. - * **NOTE:** *Email service usage and Stripe integration are included.* -* User login. -* Using the AI-powered chatbot. -* Accessing statistics: Viewing graphical and non-graphical statistics. +* **Component creation / editing form:** -**Ownership:** A registered administrator user owns the available components. + ![Wireframe Add / Modify Component Form](/docs/img/wireframes/wireframe-add-modify-form.png) -### πŸ–ΌοΈ Images +* **Shopping cart page:** -The images associated with the entities are the following: + ![Wireframe Cart Page](/docs/img/wireframes/wireframe-cart-page.png) -* **User:** User profile image. -* **Component:** Product image. +* **Login page:** -### πŸ“Š Charts + ![Wireframe LogIn Page](/docs/img/wireframes/wireframe-login-page.png) -The PCMod application includes two charts: +* **Registration page:** -* **Bar chart:** Best-selling products. -* **Pie chart:** Best-selling product types. + ![Wireframe Register Page](/docs/img/wireframes/wireframe-register-form.png) -### βš™οΈ Additional Technologies +* **Administration panel:** -The following additional technologies are used: + ![Wireframe Admin Page](/docs/img/wireframes/wireframe-admin-page.png) -* βœ‰οΈ **JavaMailSender:** Sending emails when registering an account and completing a purchase. -* πŸ“„ **PDF generation:** Generation of PDF files after completing a purchase as an invoice. -* πŸ€– **Generative AI API:** AI-powered chatbot available in the application, communicating with an AI API. -* πŸ’΅ **Stripe API:** Communication with a secure payment gateway to complete purchases. +* **User profile page:** -### πŸ”Ž Advanced Algorithm or Query + ![Wireframe User Profile Page](/docs/img/wireframes/wireframe-profile-page.png) -The advanced query algorithm consists of searching for components within the database catalog using filters such as name, price, brand, and/or type. +* **User menu:** -## πŸ“° Project Tracking + ![Wireframe Dropdown User Menu](/docs/img/wireframes/wireframe-user-dropdown.png) -* πŸ“° **Medium blog**: [Medium link](https://medium.com/@jaimeeg5) -* πŸ—ƒοΈ **GitHub Project**: [GitHub Project link](https://github.com/orgs/codeurjc-students/projects/43/views/2) +* **AI chatbot prototype:** -## πŸ‘¨β€πŸŽ“ Author + ![Wireframe AI Chatbot](/docs/img/wireframes/wireframe-chatbot-AI.png) -The development of the PCMod application is carried out as a Bachelor's Thesis in Software Engineering at the ETSII of the URJC. +* **Error page:** -| Name | Role | Email | GitHub | -|------|------|-------|--------| -| Jaime Esteban GarcΓ­a | Author | j.esteban.2023@alumnos.urjc.es | [jaimeeg5](https://github.com/jaimeeg5) | -| IvΓ‘n Chicano Capelo | Supervisor | ivan.chicano@urjc.es | [ivchicano](https://github.com/ivchicano) | + ![Wireframe Error Page](/docs/img/wireframes/wireframe-error-page.png) ## πŸ€– Use of AI Tools @@ -325,7 +79,7 @@ The following section outlines the AI tools used during the different stages of | Phase | Tools | Goals | |-------|-------|-------| | 1 - Definition of features and user interfaces | Microsoft Copilot | #1 Logo generation for PCMod | -| 2 - Repository, testing and continuous integration| - | - | +| 2 - Repository, testing and continuous integration| Google Gemini | #2 Testing Tools Assistant | | 3 - Version 0.1: Basic functionality and Docker| - | - | | 4 - Version 0.2: Intermediate functionality | - | - | | 5 - Version 1.0: Advanced functionality | - | - | diff --git a/docs/AI_USAGE.md b/docs/AI_USAGE.md new file mode 100644 index 0000000..f7b9869 --- /dev/null +++ b/docs/AI_USAGE.md @@ -0,0 +1,64 @@ +# Use of AI in the Development of PCMod + +## AI Usage #1 Logo generation for PCMod + +* Date: 03/07/2026 + +* Phase: 1 – Definition of features and user interfaces. + +* Objective: Generate logos for the application. + +* Tool: Microsoft Copilot. + +* Specific Version: Microsoft 365 Copilot. + +* Tool Configuration: + + * Model: GPT-5 Chat. + * Reasoning level: Automatic. + * Mode: Chat. + +* How it was used: + + **Prompt:** + ``` + Generate logos for an e-commerce platform dedicated to buying and selling PC components. You may take inspiration from websites such as PCComponentes or Coolmod. Provide both an icon and a logo including the application name, PCMod. + ``` + +* Tool Extensions: Image generation. + +* Context Files Related to AI Usage in the Project: N/A. + +* Tools using Repository Files: N/A. + +## AI Usage #2 Testing Tools Assistant + +* Date: 27/07/2026 and 01/08/2026 + +* Phase: 2 – Repository, testing and continuous integration. + +* Objective: Assist the developer with testing tools and tests implementation. + +* Tool: Google Gemini. + +* Specific Version: Google Gemini. + +* Tool Configuration: + + * Model: 3.6 Flash. + * Reasoning level: Automatic. + * Mode: Chat. + +* How it was used: + + **Prompt:** + ``` + I'm developing a Spring Boot (Java) + React (TypeScript) + MySQL project, and I'm implementing the unit, integration and system tests. + Explain to me what [testing_tool_name] is, how it works, and show me how to integrate this tool into my project and some basic examples. + ``` + +* Tool Extensions: N/A. + +* Context Files Related to AI Usage in the Project: N/A. + +* Tools using Repository Files: N/A. \ No newline at end of file diff --git a/docs/ANALYSIS.md b/docs/ANALYSIS.md new file mode 100644 index 0000000..9c5448c --- /dev/null +++ b/docs/ANALYSIS.md @@ -0,0 +1,141 @@ +# 🧩 Analysis + +## πŸ–₯️ Pages and navigation + +This section describes the content of each designed page and presents the corresponding *wireframe* for each one. + +* **Main page:** The initial page of the web application. It provides access to the component listing page, user registration, login, AI-powered chatbot, and the user dropdown menu. + ![Wireframe Main Page](/docs/img/wireframes/wireframe-main-page.png) + +* **Available components listing:** Page containing all available components in the store, allowing users to apply filters. It provides access to the component creation page (administrators only). + ![Wireframe Products Page](/docs/img/wireframes/wirefreme-products-page.png) + +* **Component detail page:** Page displaying the attributes of a component. It provides access to review creation, editing, and deletion (registered non-administrator users and administrators, with ownership control), as well as component editing and deletion (administrators only). + ![Wireframe Detail Product Page](/docs/img/wireframes/wireframe-detail-product-page.png) + +* **Component creation / editing form:** Page containing a form with the required fields to store a component in the database. + ![Wireframe Add / Modify Component Form](/docs/img/wireframes/wireframe-add-modify-form.png) + +* **Shopping cart page:** Page displaying the products added to the user's shopping cart and providing access to the payment process. + ![Wireframe Cart Page](/docs/img/wireframes/wireframe-cart-page.png) + +* **Login page:** Page containing a form to authenticate users using their email address and password. It provides access to the registration page. + ![Wireframe LogIn Page](/docs/img/wireframes/wireframe-login-page.png) + +* **Registration page:** Page containing a form to register new users and store their information in the database. It provides access to the login page. + ![Wireframe Register Page](/docs/img/wireframes/wireframe-register-form.png) + +* **Administration panel:** Page displaying statistics, the list of users, and the list of sales (administrators only). It provides access to the user profile page. + ![Wireframe Admin Page](/docs/img/wireframes/wireframe-admin-page.png) + +* **User profile page:** Page displaying the personal information of the registered user and a list of their completed purchases. It allows profile editing and account deletion. + ![Wireframe User Profile Page](/docs/img/wireframes/wireframe-profile-page.png) + +* **User menu:** Menu accessible from the website header after login. It provides access to the user profile page, the administration panel (administrators only), and the logout option. + ![Wireframe Dropdown User Menu](/docs/img/wireframes/wireframe-user-dropdown.png) + +* **AI chatbot prototype:** Page/component that enables users to interact through a chat interface with an artificial intelligence model. + ![Wireframe AI Chatbot](/docs/img/wireframes/wireframe-chatbot-AI.png) + +* **Error page:** Error page following the visual style of the rest of the application, displaying the error code and message. It provides access to the main page. + ![Wireframe Error Page](/docs/img/wireframes/wireframe-error-page.png) + +### Navigation Diagram: +![Wireframe Screens](/docs/img/wireframes/Wireframes%20Screens.png) + +## πŸ“¦ Entities + +This section describes the entities present in the PCMod application, along with their corresponding attributes. They are represented in the following class diagram: + +![Class Diagram](/docs/img/class_diagram.png) + +| Class | Attributes | +|:------:|------------------| +| User | ID, name, surname, username, email, encodedPassword, address, purchaseList, reviewList, image | +| Review | ID, title, content, rating, component, author, date | +| Component | ID, name, description, type, brand, price, stock, reviewList, image | +| Purchase | ID, price, date, status, PurchaseItemList, customer | +| PurchaseItem | ID, unitPrice, quantity, component | + +Two enumerated types have been added in order to improve maintainability and facilitate future extensions if required: + +| Enum | Values | +|:----:|---------| +| PurchaseStatus | ACTIVE, FINISHED | +| ComponentType | CPU, GPU, RAM, STORAGE, MOTHERBOARD, PSU, CASE | + +## πŸ”’ User Permissions + +### πŸ‘€ Anonymous Users: + +**Available functionalities:** +* Viewing the component listing. + * **NOTE:** *Search filters are available.* +* Viewing a component detail page. +* Viewing the reviews associated with a component. +* User registration. + * **NOTE:** *Email service usage is included.* +* Using the AI-powered chatbot. + +**Ownership:** An anonymous user does not own any other element within the application. + +### πŸ§‘ Registered Non-Administrator Users: + +**Available functionalities:** +* Viewing the component listing. + * **NOTE:** *Search filters are available.* +* Viewing a component detail page. +* CRUD operations for reviews. + * **NOTE:** *A registered non-administrator user can only edit or delete their own reviews.* +* CRUD operations for users. + * **NOTE:** *A registered non-administrator user can only edit or delete their own user account.* +* Purchasing process: Adding/removing products from the shopping cart, viewing cart contents, and completing purchases. + * **NOTE:** *Email service usage and Stripe integration are included.* +* User login. +* Using the AI-powered chatbot. + +**Ownership:** A registered non-administrator user owns their completed purchases and created reviews. + +### πŸ‘¨β€πŸ’Ό Registered Administrator Users: + +**Available functionalities:** +* CRUD operations for components. + * **NOTE:** *Search filters are available.* +* CRUD operations for reviews. + * **NOTE:** *Administrator users can edit and delete reviews created by any user.* +* CRUD operations for users. + * **NOTE:** *Administrator users can edit and delete any user's account.* +* Purchasing process: Adding/removing products from the shopping cart, viewing cart contents, and completing purchases. + * **NOTE:** *Email service usage and Stripe integration are included.* +* User login. +* Using the AI-powered chatbot. +* Accessing statistics: Viewing graphical and non-graphical statistics. + +**Ownership:** A registered administrator user owns the available components. + +## πŸ–ΌοΈ Images + +The images associated with the entities are the following: + +* **User:** User profile image. +* **Component:** Product image. + +## πŸ“Š Charts + +The PCMod application includes two charts: + +* **Bar chart:** Best-selling products. +* **Pie chart:** Best-selling product types. + +## βš™οΈ Additional Technologies + +The following additional technologies are used: + +* βœ‰οΈ **JavaMailSender:** Sending emails when registering an account and completing a purchase. +* πŸ“„ **PDF generation:** Generation of PDF files after completing a purchase as an invoice. +* πŸ€– **Generative AI API:** AI-powered chatbot available in the application, communicating with an AI API. +* πŸ’΅ **Stripe API:** Communication with a secure payment gateway to complete purchases. + +## πŸ”Ž Advanced Algorithm or Query + +The advanced query algorithm consists of searching for components within the database catalog using filters such as name, price, brand, and/or type. \ No newline at end of file diff --git a/docs/AUTHORS.md b/docs/AUTHORS.md new file mode 100644 index 0000000..c72121e --- /dev/null +++ b/docs/AUTHORS.md @@ -0,0 +1,8 @@ +# πŸ‘¨β€πŸŽ“ Author + +The development of the PCMod application is carried out as a Bachelor's Thesis in Software Engineering at the ETSII of the URJC. + +| Name | Role | Email | GitHub | +|------|------|-------|--------| +| Jaime Esteban GarcΓ­a | Author | j.esteban.2023@alumnos.urjc.es | [jaimeeg5](https://github.com/jaimeeg5) | +| IvΓ‘n Chicano Capelo | Supervisor | ivan.chicano@urjc.es | [ivchicano](https://github.com/ivchicano) | diff --git a/docs/DETAILED-FEATURES.md b/docs/DETAILED-FEATURES.md new file mode 100644 index 0000000..9835594 --- /dev/null +++ b/docs/DETAILED-FEATURES.md @@ -0,0 +1,74 @@ +# πŸ–₯️ Basic, intermediate and advanced features + +The functionalities available in the application are divided into basic, intermediate, and advanced features as follows: + +## πŸ”§ Basic features: + +* Component creation +* Component editing +* Component deletion +* Component listing +* Displaying component detail pages +* Adding components to the shopping cart +* Removing components from the shopping cart +* Viewing components in the shopping cart +* Completing purchases +* Review creation +* Review modification +* Review deletion +* Listing component reviews +* User registration +* User login +* Editing personal information +* User account deletion +* Accessing the user profile page +* Listing all user purchases +* Listing all users +* Listing all PCMod purchases + +## πŸ› οΈ Intermediate features: + +* Email sending (user registration and purchase completion notifications) +* PDF generation (purchase invoice sent by email) +* Advanced search filtering (component name, type, brand, and price) +* Displaying non-graphical statistics +* Displaying graphical statistics + +## βš™οΈ Advanced features: + +* Stripe payment gateway integration +* AI-powered chatbot integration + +# πŸ‘€ Features Available by User Role + +PCMod users will have access to different functionalities depending on their assigned role: + +| Feature | Anonymous User | Registered Non-Administrator User | Registered Administrator User | +|---------|:------:|:------:|:------:| +| Component creation | ❌ | ❌ | βœ… | +| Component editing | ❌ | ❌ | βœ… | +| Component deletion | ❌ | ❌ | βœ… | +| Component listing | βœ… | βœ… | βœ… | +| Component filtering | βœ… | βœ… | βœ… | +| Displaying component detail pages | βœ… | βœ… | βœ… | +| Adding components to the shopping cart | ❌ | βœ… | βœ… | +| Removing components from the shopping cart | ❌ | βœ… | βœ… | +| Viewing components in the shopping cart | ❌ | βœ… | βœ… | +| Completing purchases (Stripe integration) | ❌ | βœ… | βœ… | +| Review creation | ❌ | βœ… | βœ… | +| Review modification (controlled by owner or administrator) | ❌ | βœ… | βœ… | +| Review deletion (controlled by owner or administrator) | ❌ | βœ… | βœ… | +| Listing component reviews | βœ… | βœ… | βœ… | +| User registration | βœ… | ❌ | ❌ | +| User login | ❌ | βœ… | βœ… | +| Editing personal information (controlled by owner or administrator) | ❌ | βœ… | βœ… | +| User account deletion (controlled by owner or administrator) | ❌ | βœ… | βœ… | +| Accessing the user profile page (controlled by owner or administrator) | ❌ | βœ… | βœ… | +| Listing total user purchases | ❌ | βœ… | βœ… | +| Listing users | ❌ | ❌ | βœ… | +| Listing total PCMod purchases | ❌ | ❌ | βœ… | +| Displaying non-graphical statistics | ❌ | ❌ | βœ… | +| Displaying graphical statistics | ❌ | ❌ | βœ… | +| Email service usage | βœ… | βœ… | βœ… | +| PDF generation service usage | ❌ | βœ… | βœ… | +| AI-powered chatbot usage | βœ… | βœ… | βœ… | \ No newline at end of file diff --git a/docs/DEVELOPMENT-GUIDE.md b/docs/DEVELOPMENT-GUIDE.md new file mode 100644 index 0000000..7d40520 --- /dev/null +++ b/docs/DEVELOPMENT-GUIDE.md @@ -0,0 +1,740 @@ +# πŸ–₯️ Development Guide + +## πŸ“„ Table of contents +* [Introduction](#-introduction) +* [Technologies](#️-technologies) +* [Tools](#️-tools) +* [Architecture](#️-architecture) +* [Quality Control](#-quality-control) +* [Development Process](#-development-process) +* [Application Execution and Code Edition](#-application-execution-and-code-edition) + +## πŸ—’οΈ Introduction + +This project is based on a Single-Page Application (SPA) architecture, in which the interface only updates the components that change, rather than reloading the entire page. This makes the web application faster and improves the user experience. The server exposes a REST API from which the frontend retrieves the data to display. + +PCMod follows a Client-Server model, clearly separating the frontend, backend, and database: + +* Client (Frontend): A React (TypeScript) SPA that communicates with the server's REST API. + +* Server (Backend): A Spring Boot (Java) application that provides the REST API. It isolates controllers, services, and repositories. It uses Spring Security, JWT and Spring Data JPA. + +* Database: A MySQL database managed by the server via Spring Data JPA. + +This project includes a full suite of unit, integration, and system tests for both frontend and backend. + +The REST API is documented using the OpenAPI Specification and Swagger UI. + +CI/CD workflows are configured via GitHub Actions to run tests and perform SonarCloud analysis. + +### Summary + +| Element | Description | +|---------|-------------| +| Architecture | Web SPA with REST API | +| Technologies | React 19, React Router 8, TypeScript, Java 25, Spring Boot 4, Spring Security (JWT), Spring Data JPA, MapStruct, MySQL 8+| +| Tools | VS Code, Postman, MySQL Workbench, Maven 3.9+, Node.js 24.X.X+, npm 11.X.X+, Vite, OpenAPI Specification, Swagger UI | +| Quality Control | JUnit, Mockito, Testcontainers, REST Assured, Selenium, Vitest, JSDOM, SonarCloud, JaCoCo | +| Deployment | - | +| Development Process | Iterative and incremental using Git, GitHub, GitHub Flow, GitHub Projects, and GitHub Actions | + +## βš™οΈ Technologies + +This section describes the technologies powering the PCMod application. + +### πŸ–₯️ Frontend: + +* ### React + + React is a library for building dynamic user interfaces. It bases interfaces on components instead of pages, and only updates the parts of the DOM that have changed. It was chosen because it enables building a SPA and integrates seamlessly with Spring Boot. + + [React Official Site](https://react.dev/) + +* ### React Router + + React Router is a React-based routing framework that enables routing in a SPA. It manages data loading, generates the layout, and integrates with Vite for hot reloading. + + [React Router Official Site](https://reactrouter.com/) + +* ### TypeScript + + TypeScript is a typed superset of JavaScript. It was chosen to implement the frontend along with React Router. + + [TypeScript Official Site](https://www.typescriptlang.org/) + +### βš™οΈ Backend: + +* ### Java + + Java 25 (LTS) is the selected programming language for implementing the backend of PCMod. It provides an object-oriented foundation, strong typing, and JVM-based platform independence, offering high performance and security for the system's core business logic. + + [Java Official Site](https://www.java.com/) + +* ### Spring Boot + + Spring Boot is a Spring-based framework that simplifies web application development. It includes an embedded web server, makes configuration easier, and accelerates development. + + [Spring Boot Official Site](https://spring.io/projects/spring-boot) + +* ### Spring Security + JWT + + Spring Security is a framework that provides authentication and authorization for Spring-based applications. It uses JWTs for stateless sessions and offers HTTPS support. + + [Spring Security Official Site](https://spring.io/projects/spring-security) + +* ### Spring Data JPA + + Spring Data JPA is part of the Spring ecosystem and enables the implementation of a data access layer by simplifying queries and providing supporting pagination. + + [Spring Data JPA Official Site](https://spring.io/projects/spring-data-jpa) + +* ### MapStruct + + MapStruct is an automatic code generator that simplifies the mapping between Java classes and DTOs. + + [MapStruct Official Site](https://mapstruct.org/) + +### πŸ—„οΈ Database: + +* ### MySQL + + MySQL is the open-source relational database management system chosen to store PCMod's data. It use benefits the application through Spring Data JPA mapping while ensuring data integrity and fast queries. + + [MySQL Official Site](https://www.mysql.com/) + +## πŸ› οΈ Tools + +This section describes the tools used to develop the PCMod application. + +### πŸ§‘β€πŸ’» Code Development: + +* ### VS Code + + VS Code is the code editor chosen for developing this project. It supports multiple programming languages, such as Java (Backend) and TypeScript (Frontend), and Git integration. It also offers a large collection of extensions that simplifies the development process. + + [VS Code Official Site](https://code.visualstudio.com/) + +* ### Postman + + Postman is the platform used to design, test and document PCMod's REST API. It allows sending requests to the application server and receiving the corresponding responses, as well as exporting the REST API endpoint collection. + + [Postman Official Site](https://www.postman.com/) + +* ### MySQL Workbench + + MySQL Workbench is a visual tool that simplifies MySQL database management and querying while allowing users to create and visualize database diagrams. + + [MySQL Workbench Official Site](https://www.mysql.com/products/workbench/) + +### πŸ“¦ Build and Package Management: + +* ### Maven + + Maven is a build automation tool for Java projects. It is used to compile code, manage dependencies, run tests, and generate distribution files. + + [Maven Official Site](https://maven.apache.org/) + +* ### Node.js + + Node.js is a runtime environment that allows executing JavaScript outside the browser. + + [Node.js Official Site](https://nodejs.org/) + +* ### npm + + npm is the package manager for Node.js. It allows installing, managing, updating, and sharing JavaScript packages and dependencies. + + [npm Official Site](https://www.npmjs.com/) + +* ### Vite + + Vite is a fast frontend build tool. It simplifies the configuration of React projects, handles paths resolution, runs the local development server, and enables instant hot module reloading in the browser. + + [Vite Official Site](https://vite.dev/) + +### πŸ“ Version Control and Repository: + +* ### Git + + Git is the distributed version control system selected for this project. It is used to track, manage, and collaborate on code changes throughout development. + + [Git Official Site](https://git-scm.com/) + +* ### GitHub + + GitHub is the platform chosen to host this project's Git repository. It provides an intuitive interface for creating, reviewing and merging pull requests, as well as managing and publishing project releases. + + [GitHub Official Site](https://github.com/) + +* ### GitHub Projects + + GitHub Projects is a project management tool integrated with GitHub for tracking issues. In this project, it is used as a Kanban board with three stages: To Do, In Progress, and Done. + + [GitHub Projects Official Site](https://docs.github.com/es/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) + +### πŸ§ͺ Testing: + +* ### JUnit + + JUnit 6 is a testing framework for Java code. In this project, it is used for backend unit testing. + + [JUnit Official Site](https://junit.org/) + +* ### Mockito + + Mockito is a Java mocking framework used to create stubs, mocks, and spies for unit testing. In PCMod, it is used to isolate database-related dependencies in backend unit tests. + + [Mockito Official Site](https://site.mockito.org/) + +* ### Testcontainers + + Testcontainers is an open-source library used to create and manage Docker containers during tests. PCMod uses it to run a MySQL container during backend integration tests. + + [Testcontainers Official Site](https://testcontainers.com/) + +* ### REST Assured + + REST Assured is a library that simplifies testing REST APIs. This dependency is used for backend system tests. + + [REST Assured Official Site](https://rest-assured.io/) + +* ### Selenium + + Selenium is a framework used to automate browser-based testing. It is used to verify frontend functionality during system end-to-end tests. + + [Selenium Official Site](https://www.selenium.dev/) + +* ### Vitest + + Vitest is a testing framework for JavaScript and TypeScript projects, designed to implement unit, integration, and component tests. It offers fast execution and Vite integration. PCMod uses it for frontend unit and integration testing. + + [Vitest Official Site](https://vitest.dev/) + +* ### JSDOM + + JSDOM is a JavaScript-based tool for Node.js that emulates a browser environment without a graphical interface. It allows manipulating and testing HTML documents. + + [JSDOM Official Site](https://github.com/jsdom/jsdom) + +### βœ… CI/CD and Quality Reports: + +* ### GitHub Actions + + GitHub Actions is a tool that allows developers to run automated workflows, which can include build, test, and deployment jobs. In this project, it is also used to run jobs that analyze code quality and test coverage, and upload the results to SonarCloud. + + [GitHub Actions Official Site](https://github.com/features/actions) + +* ### SonarCloud + + SonarCloud is a cloud-based static code analysis tool used to detect code smells, security vulnerabilities, and maintainability issues, as well as to track test coverage. + + [SonarCloud Official Site](https://www.sonarsource.com/products/sonarqube/cloud/) + +* ### JaCoCo + + JaCoCo is a Java code coverage tool used to measure how many lines of code, methods, branches, and classes are covered by tests. In PCMod, it generates coverage reports during backend testing to be uploaded to SonarCloud. + + [JaCoCo Official Site](https://www.jacoco.org/jacoco/) + +### πŸ“„ API Documentation: + +* ### OpenAPI Specification + + OpenAPI Specification is a standard for describing and documenting REST APIs. It defines endpoints, request and response formats, parameters, authentication methods, and other contract details. + + [OpenAPI Specification Official Site](https://www.openapis.org/) + +* ### Swagger UI + + Swagger UI is a tool that allows users to visualize and interact with APIs based on their OpenAPI specification. + + [Swagger UI Official Site](https://swagger.io/open-source/swagger-ui/) + +## πŸ—οΈ Architecture + +### βš™οΈ Deployment + +PCMod is divided into three processes: + +* Client (Frontend): A React SPA available on port 5173 that communicates with the REST API through HTTP requests. It allows users to interact with the application. +* Server (Backend): A Spring Boot REST API available on port 8443 that communicates with the frontend via HTTP and with the database via TCP. It contains the business logic and operate with the database. +* Database: A MySQL database available on port 3306, that communicates with the backend via TCP. It is a relational database that ensures data integrity and persistence. + +Communication between the frontend and backend is carried out using JSON format. + +### 🌐 REST API + +The REST API is documented using the OpenAPI Specification and Swagger UI. It can be accessed at [PCMod API Documentation](https://raw.githack.com/codeurjc-students/2026-PCMod/main/docs/api/api-docs.html). + +## βœ… Quality Control + +In this project, there is a complete test suite for both the frontend and backend. + +### πŸ–₯️ Frontend Tests + +#### Frontend Unit Tests + +Frontend unit tests are implemented with Vitest. + +* `renders all components`: Checks if calling the getComponents method in components-service returns the components from the database (mocked with sample data). + +#### Frontend Integration Tests + +Frontend integration tests are implemented with Vitest. + +* `check communication between frontend and backend`: Checks the rendering of the list of PC components by calling the REST API. + +#### Frontend System Tests + +Frontend system tests are implemented with Selenium and JUnit. + +* `loadComponentsTest`: Verifies that when opening the web application in a browser, the list of PC components loads correctly from the REST API. + +### βš™οΈ Backend Tests + +#### Backend Unit + +Backend unit tests are implemented with JUnit and Mockito. + +* `testComponentsLoad`: Verifies that ComponentsService correctly retrieves the list of PC components from the ComponentsRepository (which is mocked). + +#### Backend Integration Tests + +Backend integration tests are implemented with JUnit and Testcontainers. + +* `loadComponents`: Verifies that findAll method in ComponentService returns the correct PC components values when using a real database container. + +#### Backend System Tests + +Backend system tests are implemented with JUnit and REST Assured. + +* `getComponents`: Verifies that the REST API response when requesting "/components/" matches the expected values previously loaded into the database. + +--- + + A summary of these tests can be found in the table below: + +| Test | Quantity | Technologies and tools | +|------|:--------:|------------------------| +| Frontend Unit Tests | 1 | Vitest | +| Frontend Integration Tests | 1 | Vitest | +| Frontend System Tests | 1 | Selenium, JUnit | +| Backend Unit Tests | 1 | JUnit, Mockito | +| Backend Integration Tests | 1 | JUnit, Testcontainers | +| Backend System Tests | 1 | JUnit, REST Assured | + +The images below are the results of executing the complete test suite with the coverage reports: + +* Frontend Tests: + + ![Frontend Tests Execution and Coverage](/docs/img/testing/frontend_tests_execution_and_coverage.png) + + ![Frontend System Tests Execution](/docs/img/testing/frontend_system_tests_execution.png) + + **Note:** Frontend system tests are executed from the backend folder. + +* Backend Tests: + + ![Backend Tests Execution](/docs/img/testing/backend_tests_execution.png) + + ![Backend Tests Coverage](/docs/img/testing/backend_tests_coverage.png) + +--- + +### ☁️ SonarCloud Analysis + +To execute a quality analysis with SonarCloud, the GitHub Actions workflows generate JaCoCo and a LCOV reports after passing the tests. + +The metrics reported by SonarCloud after merging all feature and test branches into main are shown below: + +![Sonar Analysis Results](/docs/img/sonar_results.png) + +The analysis done has reviewed the quality of: +* Lines of code: 486 (Java: 326 | TypeScript: 147) +* Functions: 38 (Backend: 27 | Frontend: 11) +* Classes: 11 +* Files: 18 (Backend: 11 | Frontend: 7) + +## πŸ§‘β€πŸ’» Development Process + +This project is based on an iterative and incremental process, following the Agile Manifesto principles and good practices of Extreme Programming (XP). + +### πŸ“ Issues Management + +GitHub Issues and GitHub Projects are used to manage issues, using a Kanban board with three columns: To Do, In Progress, and Done. Issues are classified into "Task", "Feature", and "Documentation". Once a feature and its corresponding tests are completed, the issue can be moved to the Done column. + +![Project Kanban Board](/docs/img/kanban_github_projects.png) + +### πŸ—‚οΈ Repository and Version Control System + +As a version control system, PCMod uses Git to track and manage changes. The Git repository is hosted on GitHub to take advantage of its features (Github Issues, GitHub Projects, GitHub Actions). + +Development follows GitHub Flow strategy, using the branches main and feature/fix: + +* `main`: Stable branch, ready for deployment. +* `feature/*`: Branch for new functionalities. It is merged into main once the feature is completed and all tests pass. +* `fix/*`: Branch for bug fixes. It is merged to main once the bug is resolved and all corresponding tests pass. + +Metrics: + +| Element | Metric | +|---------|:--------:| +| Commits | ~30 | +| Branches | 7 | +| Issues | 22 | + +### πŸ”„ Continuous Integration (CI) + +In the PCMod repository, two CI/CD workflows are active: + +* Basic Workflow: Triggered on every push to a feature or fix branch. + + * Frontend unit tests. + * Backend unit tests. + * Sonar Cloud branch analysis. + +* Complete Workflow: Triggered when a pull request to main is opened, reopened, or synchronized. It blocks merging into main if any test fails. + + * Backend unit tests. + * Backend integration tests. + * Backend system tests. + * Frontend unit tests. + * Frontend integration tests. + * Frontend system tests. + * Sonar Cloud analysis. + +Both workflows contain the workflow_dispatch trigger, allowing the developer to run them manually without pushing commits or opening a PR. + +Additionally, these workflows ignore changes in .md files or the /docs directory. + +## 🌐 Application Execution and Code Edition + +This section provides the steps to clone the repository, run the PCMod application and execute the full test suite locally. + +### ⬇️ Clone the repository + +Requirements: +* Git + +You can check if Git is installed by running the following command in a terminal: +``` +git --version +``` +If the output shows a message like `git version X.XX.X`, Git is installed. +If not, please download and install it from [Git Official Installation Site](https://git-scm.com/install/) + +Once Git is installed, clone the repository by running the following command in a terminal: + +``` +git clone https://github.com/codeurjc-students/2026-PCMod.git +``` + +The application can be run in two different modes: development and production. + +### πŸ§‘β€πŸ’» Run in development mode + +#### βš™οΈ Backend and database + +Requirements: + +* MySQL Server 8.0+ +* Java 25 +* Maven 3.9+ +* Docker + +Verify that Java and Maven are installed by running the following commands in a terminal: +``` +java -version +mvn -version +``` +If the output shows `java version 25.X.X` for Java and `Apache Maven 3.9.X` for Maven, they are installed. +If not, please download Java from [Java Official Site](https://www.oracle.com/java/technologies/javase/jdk25-archive-downloads.html) and Maven from [Maven Official Site](https://maven.apache.org/download.cgi). + +To run the database, ensure that Docker Engine is installed and running. You can check this with: +``` +docker --version +docker info +``` +If the first command returns an error, please download and install Docker from [Docker Official Site](https://www.docker.com/products/docker-desktop/). If the second command returns an error, make sure the Docker daemon is running. + +Once Docker is installed and running, execute: +``` +docker run --rm -e MYSQL_ROOT_PASSWORD=password \ +-e MYSQL_DATABASE=pcmod -p 3306:3306 -d mysql:8.0 +``` + +Then, open a terminal in the cloned repository's directory and run the following commands to start the backend: +``` +cd backend/pcmod +mvn spring-boot:run +``` + +#### πŸ–₯️ Frontend + +Requirements: + +* Node.js 24.X.X+ +* npm 11.X.X+ + +You can check if Node.js and npm are installed with: +``` +node -v +npm -v +``` +If the output displays `v.24.XX.X` for Node.js and `11.XX.X` for npm, they are installed. +If not, please download both from [Node + npm Official Site](https://nodejs.org/en/download). + +Open a terminal on the cloned repository's directory and execute: +``` +cd frontend +npm install +npm run dev +``` + +Finally, open a browser and navigate to https://localhost:5173/. + +#### πŸ›‘ Stop application + +To stop running PCMod, terminate the terminal tasks or press `Ctrl + C` in both backend and frontend terminals. + +To stop the MySQL Docker container execute in a terminal: +``` +docker ps # Locate the CONTAINER ID for MySQL +docker stop +``` + +### 🌐 Run in production mode + +#### βš™οΈ Build and run + +Requirements: + +* MySQL Server 8.0+ +* Java 25 +* Maven 3.9+ +* Node.js 24.X.X+ +* npm 11.X.X+ +* Docker + +Verify that Java and Maven are installed by running the following commands in a terminal: +``` +java -version +mvn -version +``` +If the output shows `java version 25.X.X` for Java and `Apache Maven 3.9.X` for Maven, they are installed. +If not, please download Java from [Java Official Site](https://www.oracle.com/java/technologies/javase/jdk25-archive-downloads.html) and Maven from [Maven Official Site](https://maven.apache.org/download.cgi). + +Verify that Node.js and npm are installed with: +``` +node -v +npm -v +``` +If the output displays `v.24.XX.X` for Node.js and `11.XX.X` for npm, they are installed. +If not, please download both from [Node + npm Official Site](https://nodejs.org/en/download). + +Open a terminal in the cloned repository's directory and execute the following commands to build the frontend: +``` +cd frontend +npm install +npm run build +``` +Then, copy the files generated in `/frontend/build/client/` to `/backend/pcmod/src/main/resources/static/`. + +To run the database, ensure that Docker Engine is installed and running. You can check this with: +``` +docker --version +docker info +``` +If the first command returns an error, please download and install Docker from [Docker Official Site](https://www.docker.com/products/docker-desktop/). If the second command returns an error, make sure the Docker daemon is running. + +Once Docker is installed and running, execute: +``` +docker run --rm -e MYSQL_ROOT_PASSWORD=password \ +-e MYSQL_DATABASE=pcmod -p 3306:3306 -d mysql:8.0 +``` + +Finally, in a terminal on the cloned repository's directory, execute the following commands to run the application: +``` +cd backend/pcmod +mvn spring-boot:run +``` + +Open a browser and navigate to https://localhost:8443/. + +#### πŸ›‘ Stop application + +To stop running PCMod, terminate the terminal task or press `Ctrl + C` in the backend terminal. + +To stop the MySQL Docker container execute in a terminal: +``` +docker ps # Locate the CONTAINER ID for MySQL +docker stop +``` + +### πŸ› οΈ Development tools + +#### Code + +To view and edit the code, use VS Code: [VS Official Site](https://code.visualstudio.com/Download). + +It is recommended to install "Extension Pack for Java" and "Spring Boot Extension Pack" extensions in VS Code. + +If you have already cloned the repository, open the folder where it is saved. +If not, execute in a terminal: +``` +git clone https://github.com/codeurjc-students/2026-PCMod.git +``` +The project is organized as follows: + +* `/backend/pcmod`: Contains the source files for the REST API (server side). + +* `/frontend`: Contains the source files for the client side. + +* `/docs`: Contains REST API specifications and project documentation. + +* `/.github`: Contains GitHub Actions workflows files. + +You can navigate and open source files using the file explorer in the left sidebar. + +#### REST API + +To test and interact with the REST API, download Postman from [Postman Official Site](https://www.postman.com/downloads/) if you haven't already. + +First, navigate to the backend directory in your terminal and start the server: +``` +cd backend/pcmod +mvn spring-boot:run +``` + +Then, import the Postman collection included in the repository (File > Import): +[Postman PCMod Collection](/docs/api/postman/PCMod.postman_collection.json) + +Select an endpoint from the left sidebar. You can customize request parameters in the "Params" tab. Click the "Send" button in the top right corner to view the server response. + +### πŸ§ͺ Run Tests + +> [!NOTE] +> Before executing tests, execute the following commands in a terminal from the cloned repository's directory to make the Maven wrapper executable: +> ``` +> cd backend/pcmod +> chmod +x mvnw +> ``` + +To run all backend tests: +> [!NOTE] +> Before executing these commands, verify that the Docker daemon is running. +``` +# Unit + Integration + System + +cd backend/pcmod +./mvnw verify '-Dtest=!es.codeurjcstudents.pcmod.e2e.ui.**' +``` + +To run all frontend tests: +``` +# Unit + Integration + +cd frontend +npm install +cd ../backend/pcmod +./mvnw spring-boot:run > /dev/null 2>&1 < /dev/null & +npx wait-on https-get://localhost:8443/api/v1/components/ +cd ../../frontend +npm run test +``` +``` +# System (requires both frontend and backend to be running) + +cd frontend +npm run dev > /dev/null 2>&1 < /dev/null & +cd ../backend/pcmod +./mvnw spring-boot:run > /dev/null 2>&1 < /dev/null & +npx wait-on http-get://localhost:5173 https-get://localhost:8443/api/v1/components/ +./mvnw test -Dgroups="client-system" +``` + +#### Backend Unit Tests + +From the root directory of the cloned repository: +``` +cd backend/pcmod +./mvnw clean test -Dgroups="server-unit" +``` + +#### Backend Integration Tests + +To run integration tests, ensure Docker Engine is installed and running: +``` +docker --version +docker info +``` +If the first command returns an error, please download and install Docker from [Docker Official Site](https://www.docker.com/products/docker-desktop/). If the second command returns an error, make sure the Docker daemon is running. + +From the root directory of the cloned repository: +``` +cd backend/pcmod +./mvnw clean test -Dgroups="server-integration" +``` + +#### Backend System Tests + +From the root directory of the cloned repository: +``` +cd backend/pcmod +./mvnw clean test -Dgroups="server-system" +``` + +#### Frontend Unit Tests + +From the root directory of the cloned repository: +``` +cd frontend +npm run test:unit +``` + +#### Frontend Integration Tests + +> [!NOTE] +> The backend must be running before executing integration tests. + +First, start the backend: +``` +cd backend/pcmod +./mvnw spring-boot:run +``` +In a new terminal, run: +``` +cd frontend +npm run test:integration +``` + +#### Frontend System Tests + +> [!NOTE] +> The backend and the frontend must be running before executing system tests. + +First, start the frontend: +``` +cd frontend +npm run dev +``` +In a second terminal, start the backend: +``` +cd backend/pcmod +./mvnw spring-boot:run +``` +In a third terminal, run the system tests: +``` +cd backend/pcmod +./mvnw test -Dgroups="client-system" +``` + +### πŸ“¦ Publish a Release + +To publish a release you must follow these steps: + +1. Ensure all tests pass. +2. Verify that the SonarCloud quality gate passes. +3. On GitHub, navigate to "Releases" and click "Draft a new release" +4. Specify the release title, description, and tag version, and click "Publish release". +5. Update the version of the app in pom.xml, package.json, and docker-compose.yml. \ No newline at end of file diff --git a/docs/METHODOLOGY.md b/docs/METHODOLOGY.md new file mode 100644 index 0000000..73e688d --- /dev/null +++ b/docs/METHODOLOGY.md @@ -0,0 +1,31 @@ +# πŸ› οΈ Methodology + +This project follows an iterative and incremental development methodology based on the principles of Extreme Programming (XP). + +GitHub Projects and GitHub Issues are used to manage tasks through a Kanban board. GitHub Flow is adopted as the version control workflow. GitHub Actions is used to automate testing, code quality checks, and the publication of Docker images to Docker Hub. + +The project is divided into the following phases: + +* πŸ“„ **Phase 1: Definition of features and user interfaces:** Definition of the functional and technical objectives, classification of features into basic, intermediate, and advanced levels, definition of permissions for each user role, design of application pages using *wireframes*, selection of charts to be displayed, design of the application's class structure, selection of additional technologies, and design of the advanced search algorithm. +* πŸ“ **Phase 2: Repository, testing and continuous integration:** Creation of the backend and frontend projects, configuration of testing workflows in the repository, implementation of the minimum functionality required to verify communication between application layers, testing of the initial functionality, and configuration of static code analysis with SonarQube. +* πŸ–₯️ **Phase 3: Version 0.1 – Basic functionality and Docker:** Implementation of the application's basic functionality, release of version 0.1, creation of the required Dockerfile and Docker Compose files, and publication of version 0.1 to Docker Hub. +* πŸ–₯️ **Phase 4: Version 0.2 – Intermediate functionality:** Implementation of the application's intermediate functionality, release of version 0.2, and publication of version 0.2 to Docker Hub. +* πŸ–₯️ **Phase 5: Version 1.0 – Advanced functionality:** Implementation of the application's advanced functionality, release of version 1.0, and publication of version 1.0 to Docker Hub. +* πŸ“ **Phase 6: Thesis report:** Preparation of the project's final report. +* πŸ§‘β€πŸ« **Phase 7: Thesis defense:** Preparation and defense of the project before the evaluation committee. + +The planned start and delivery dates for each phase are shown below: + +| Phase | Start Date | Planned Delivery Date | Actual Delivery Date | +| ----- | :--------: | :-------------------: | :------------------: | +| Phase 1: Definition of features and user interfaces | 30/06/2026 | 15/09/2026 | 13/07/2026 | +| Phase 2: Repository, testing and continuous integration | 16/07/2026 | 15/10/2026 | 18/08/2026 | +| Phase 3: Version 0.1 – Basic functionality and Docker | - | 15/12/2026 | - | +| Phase 4: Version 0.2 – Intermediate functionality | - | 01/03/2027 | - | +| Phase 5: Version 1.0 – Advanced functionality | - | 15/04/2027 | - | +| Phase 6: Thesis report | - | 15/05/2027 | - | +| Phase 7: Thesis defense | - | 15/06/2027 | - | + +## πŸ“Š Gantt chart: + +![Gantt chart](/docs/img/gantt_chart.png) diff --git a/docs/OBJECTIVES.md b/docs/OBJECTIVES.md new file mode 100644 index 0000000..da0c18b --- /dev/null +++ b/docs/OBJECTIVES.md @@ -0,0 +1,44 @@ +# 🎯 Objectives + +This section outlines the functional and technical objectives to be achieved during the development of the PCMod application. + +## Functional Objectives + +The primary functional objectives of PCMod are the implementation of CRUD (Create, Read, Update, Delete) operations for PC components, reviews, and users. The application aims to provide users with an easy and efficient way to browse and filter PC components, as well as complete purchases. + +To meet the authorization requirements based on user roles and resource ownership, it is necessary to implement an user authentication and management system (e.g., access to the administration panel). + +As advanced objectives, the application will integrate services capable of sending emails, generating PDF invoices, and assisting users through an AI-powered chatbot. + +* Enable administrators to perform complete CRUD operations for PC components. +* Provide users with efficient search and filtering capabilities for PC components. +* Implement an user authentication and management system supporting multiple user roles with different privilege levels. +* Enable complete CRUD operations for reviews. +* Enable complete CRUD operations for users. +* Provide a complete purchasing workflow (shopping cart β†’ secure payment using Stripe β†’ email confirmation). +* Send automated email notifications when a new user registers or a purchase is completed. +* Automatically generate and send purchase invoices in PDF format via email. +* Provide administrators with a dashboard containing statistics, a user list, and a purchase history. +* Integrate an AI-powered chatbot to assist users. + +## Technical Objectives + +PCMod follows a client–server architecture, using React and TypeScript for the frontend, Spring Boot and Java for the backend, and MySQL as the relational database management system. The application is deployed over HTTPS on port 443. + +Postman will be used to design, document, and test the REST API endpoints provided by the backend. In addition, SpringDoc and Swagger/OpenAPI will be used to generate and maintain the API documentation. + +To ensure software quality, automated testing will be implemented using tools such as Mockito, Selenium, and JUnit. In addition, static code quality analysis will be performed using SonarQube. + +Finally, the application packaging and publishing process will be carried out using Docker and GitHub Actions workflows. + +* Develop a web application based on a client–server architecture, separating the frontend, backend, and database layers. +* Develop the frontend using React and TypeScript. +* Develop the backend using Spring Boot and Java. +* Manage application data through a MySQL relational database. +* Design, document, and test the available REST API endpoints using Postman, SpringDoc, and Swagger/OpenAPI. +* Integrate external APIs to support secure payment processing and the AI chatbot. +* Use additional technologies for email delivery, chart generation, and PDF generation. +* Ensure software quality through automated testing, GitHub Actions workflows, and static code analysis using SonarQube. +* Containerize the application and publish the Docker image to Docker Hub using GitHub Actions workflows. + +⚠️ **NOTE:** *At this stage, the functional and technical objectives of the application have been defined, and development has begun; however, the implementation is not yet functional.* \ No newline at end of file diff --git a/docs/PROJECT-TRACKING.md b/docs/PROJECT-TRACKING.md new file mode 100644 index 0000000..0bd767a --- /dev/null +++ b/docs/PROJECT-TRACKING.md @@ -0,0 +1,4 @@ +# πŸ“° Project Tracking + +* πŸ“° **Medium blog**: [Medium link](https://medium.com/@jaimeeg5) +* πŸ—ƒοΈ **GitHub Project**: [GitHub Project link](https://github.com/orgs/codeurjc-students/projects/43/views/2) \ No newline at end of file diff --git a/docs/img/gantt_chart.png b/docs/img/gantt_chart.png index ab5eeb8..81733a9 100644 Binary files a/docs/img/gantt_chart.png and b/docs/img/gantt_chart.png differ diff --git a/docs/img/kanban_github_projects.png b/docs/img/kanban_github_projects.png new file mode 100644 index 0000000..d9b90a0 Binary files /dev/null and b/docs/img/kanban_github_projects.png differ diff --git a/docs/img/sonar_results.png b/docs/img/sonar_results.png new file mode 100644 index 0000000..e3f76d8 Binary files /dev/null and b/docs/img/sonar_results.png differ diff --git a/docs/img/testing/backend_tests_coverage.png b/docs/img/testing/backend_tests_coverage.png new file mode 100644 index 0000000..5f24771 Binary files /dev/null and b/docs/img/testing/backend_tests_coverage.png differ diff --git a/docs/img/testing/backend_tests_execution.png b/docs/img/testing/backend_tests_execution.png new file mode 100644 index 0000000..0791e20 Binary files /dev/null and b/docs/img/testing/backend_tests_execution.png differ diff --git a/docs/img/testing/frontend_system_tests_execution.png b/docs/img/testing/frontend_system_tests_execution.png new file mode 100644 index 0000000..844f97d Binary files /dev/null and b/docs/img/testing/frontend_system_tests_execution.png differ diff --git a/docs/img/testing/frontend_tests_execution_and_coverage.png b/docs/img/testing/frontend_tests_execution_and_coverage.png new file mode 100644 index 0000000..0bbb369 Binary files /dev/null and b/docs/img/testing/frontend_tests_execution_and_coverage.png differ diff --git a/frontend/package.json b/frontend/package.json index 4d096c4..bfc1ab5 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -8,6 +8,8 @@ "start": "react-router-serve ./build/server/index.js", "typecheck": "react-router typegen && tsc", "test": "vitest", + "test:unit": "vitest run tests/unit", + "test:integration": "vitest run tests/integration", "test:unit-coverage": "vitest run tests/unit --coverage", "test:coverage": "vitest run tests/ --coverage" },