ListGift

🎁 ListGist: Servicio Web para Gestión de Listas de Regalos

Índice

Descripción del Proyecto
Funcionalidades Principales
Tecnologías Utilizadas
Comandos por Entorno
Pruebas
Documentación de la API
Contribución
Contacto

✨ Descripción y Arquitectura

El proyecto ListGift es una aplicación web full-stack diseñada para la creación, gestión y compartición de listas de regalos. Combina tecnologías modernas para el frontend y el backend, ofreciendo una experiencia de usuario intuitiva y una base robusta para la manipulación de datos.

El diseño se centra en una arquitectura cliente-servidor, con una clara separación entre la interfaz de usuario y la lógica de negocio, lo que garantiza escalabilidad, fiabilidad y facilidad de mantenimiento.

Frontend (React) Proporciona una interfaz de usuario intuitiva para crear, consultar, actualizar y eliminar listas de regalos y los ítems dentro de ellas.

Backend (PHP) Gestiona la lógica de negocio, la persistencia de datos de las listas e ítems en la base de datos, y el sistema de autenticación.

Base de Datos PostgreSQL/MySQL Almacena todos los datos relacionados con los usuarios, listas, ítems y roles, asegurando una gestión eficiente y segura de la información.

🎯 Funcionalidades Clave

1. Gestión de Recursos (CRUD)

Listas (Lists) e Ítems (Items): Permite la creación, consulta, actualización y eliminación (CRUD) de listas de regalos y de los artículos asociados dentro de cada lista.
Gestión de Usuarios y Perfiles: Manejo de la información de usuario y roles.

2. Seguridad y Acceso (Middlewares)

Autenticación JWT: Utiliza JSON Web Tokens (JWT), enviados por cookies, para autenticar a los usuarios. Los tokens son validados con la clave secreta JWT_SECRET.
Control de Acceso (RBAC): Implementa middlewares para permisos basados en roles, para asegurar la gestión de recursos limitando el acceso a usuarios ‘Admin’, o al propietario directo del recurso (Control de Propiedad).
Validación: Uso de la librería Respect/Validation (y la clase Validator.php) para asegurar la integridad de los datos de las peticiones.
CORS Configurado: Permite peticiones seguras solo desde el dominio de producción (https://listgift.free.nf) y maneja credenciales (cookies).

3. Utilidades y Almacenamiento

API RESTful: Estructura clara de endpoints usando el router Bramus/Router.
Gestión de Archivos: La lógica de subida (FileUpload.php) está configurada para integrarse con Google Drive, validando archivos con un límite de 5MB.

⚙️ Tecnologías Utilizadas

Frontend

React
- Biblioteca JavaScript principal para construir la interfaz de usuario.
React Router
- Maneja la navegación y el enrutamiento en la aplicación.
Framer Motion
- Proporciona transiciones y animaciones fluidas entre páginas.
Spline
- Integra objetos 3D interactivos y dinámicos para mejorar la visualización de los artículos.
Axios
- Cliente HTTP para la comunicación con la API del backend.
Tailwind CSS
- Framework CSS utility-first para un estilizado rápido y consistente.
Material Tailwind
- Biblioteca de componentes de UI.

Backend

PHP
- Lenguaje de scripting del lado del servidor.
Illuminate/Database
- ORM para operaciones de base de datos.
PHP-JWT
- Implementación de JWT para la autenticación.
Bramus/Router
- Librería de enrutamiento para PHP.
Respect/Validation
- Librería para la validación de datos.
FakerPHP
- Genera datos de prueba para desarrollo.
vlucas/phpdotenv
- Carga variables de entorno desde archivos .env.

Base de Datos

MySQL
- Base de datos relacional para almacenar usuarios, listas, ítems y roles.

Desarrollo y Operaciones - DevOps

Git / GitHub
- Control de versiones y plataforma de colaboración principal.
GitHub Actions
- Motor de Integración/Despliegue Continuo (CI/CD) que automatiza el build y la subida a InfinityFree.
InfinityFree
- Proveedor de alojamiento web gratuito (servidor FTP) para el despliegue.
Postman
- Herramientas para testear, construir y documentar los endpoints de la API de PHP, incluyendo la gestión de tokens JWT y cookies.
Browser DevTools
- Herramientas de Desarrollador del navegador (Consola, Red, Componentes de React) fundamentales para la depuración del frontend..
DBeaver
- Cliente de escritorio para desarrolladores para gestionar y visualizar la base de datos MySQL.
VS Code
- Entorno de desarrollo principal. <!–
Composer
- Administrador de dependencias de PHP utilizado en el backend.
npm
- Administrador de paquetes de Node.js utilizado en el frontend.
Vite
- Herramienta de construcción rápida (Build Tool) para el frontend. –>

🚀 Despliegue y CI/CD Automatizado

El proyecto utiliza un pipeline de Integración Continua / Despliegue Continuo (CI/CD) con GitHub Actions para automatizar la subida a InfinityFree (FTP).

1. Despliegue Condicional

El workflow (main.yml) está configurado con dos jobs separados (frontend_deploy y backend_deploy), que se ejecutan solo si hay cambios en su respectiva carpeta (frontend/ o backend/).

2. Fases del CI/CD

Componente	Comando de Build	Carpeta de Salida	Servidor (FTP Path)
Frontend (Vite)	`cd frontend && npm run build`	`frontend/dist/`	`/htdocs/`
Backend (PHP)	`cd backend && composer install --no-dev`	`backend/`	`/htdocs/backend/`

3. Configuración de Credenciales

Para que GitHub Actions pueda desplegar, debes configurar las siguientes variables como Repository Secrets en GitHub (Configuración > Secrets > Actions):

Secret Name	Valor (Ej. Producción)	Propósito
`FTP_HOST`	`ftpupload.net`	Host del servidor FTP de InfinityFree.
`FTP_USERNAME`	`epiz_12345678`	Usuario FTP.
`FTP_PASSWORD`	`[...contraseña FTP...]`	Contraseña FTP.

📝 Comandos por Entorno

Frontend (Vite + React)

Comando	Descripción
`npm run dev`	Inicia el servidor de desarrollo del frontend.
`npm run build`	Compila el proyecto frontend para producción.
`npm run lint`	Ejecuta el linter (ESLint) en los archivos JS/JSX.
`npm run preview`	Previsualiza la construcción de producción.

Backend (PHP)

Comando	Descripción
`composer start`	Inicia el servidor de desarrollo PHP (en `localhost:8000`).
`composer migrate`	Ejecuta las migraciones de la base de datos (hacia arriba).
`composer migrate:db`	Comando específico para migración de la base de datos (según script).
`composer migrate:down`	Revierte la última migración de la base de datos.
`composer migrate:refresh`	Revierte todas las migraciones y las vuelve a ejecutar.
`composer seed`	Ejecuta los seeders para poblar la base de datos con datos de prueba.
`composer seed:refresh`	Revierte los seeders y los vuelve a ejecutar.
`composer migrate:full`	Ejecuta `migrate:refresh` seguido de `seed`.

🔬 Pruebas

Actualmente, este proyecto no cuenta con una sección de pruebas detallada en la información proporcionada. Si se implementan pruebas (unitarias, de integración, E2E), esta sección se actualizará para incluir instrucciones de ejecución y tipos de pruebas.

🤝 Contribución

Las contribuciones son bienvenidas. Por favor, sigue los siguientes pasos:

Haz un fork del proyecto.
Crea una rama para tu nueva característica (git checkout -b feature/nueva-caracteristica).
Realiza los cambios y haz commit (git commit -m 'Agregada nueva característica').
Envía un pull request.

🧑‍💻 Autor

Ing. Benjamin Tavarez

Si tienes alguna pregunta o comentario sobre este proyecto, no dudes en ponerte en contacto conmigo a través de benjamin.tavarez.98@gmail.com o en LinkedIn.