diff --git a/memberflow-api/README.md b/memberflow-api/README.md index e768f9b..6bd3ab8 100644 --- a/memberflow-api/README.md +++ b/memberflow-api/README.md @@ -1,60 +1,151 @@ -# MemberFlow-API +# MemberFlow API -## Descripción del Proyecto - -**MemberFlow-API** es el módulo de interfaz de usuario y controladores de la aplicación **MemberFlow**, diseñado para gestionar membresías, usuarios, clases y finanzas en un entorno organizacional. Este proyecto actúa como la capa de presentación y comunicación, exponiendo servicios RESTful que interactúan con el módulo de datos **MemberFlow-Data**. - -El objetivo principal de **MemberFlow-API** es proporcionar una interfaz segura y eficiente para que los clientes (como aplicaciones web o móviles) puedan interactuar con la lógica de negocio y la base de datos subyacente. +MemberFlow es una plataforma integral para la gestión de academias de artes marciales, con funcionalidades que cubren usuarios, clases, asistencias, membresías, pagos y facturación. Este repositorio corresponde al **backend API** desarrollado en **Java + Spring Boot**. --- -## Características Principales +## 🧱 Arquitectura General -- **Controladores REST**: Exposición de endpoints para gestionar usuarios, roles, notificaciones, clases y finanzas. -- **Seguridad**: Implementación de autenticación basada en JWT (JSON Web Tokens). -- **Integración con MemberFlow-Data**: Uso del módulo de datos para acceder a la lógica de negocio y la persistencia. -- **Configuración Centralizada**: Uso de `application.properties` para gestionar parámetros clave como JWT y otros ajustes. -- **Ejecución con Spring Boot**: Aplicación basada en el framework Spring Boot para facilitar el desarrollo y despliegue. -- **Modularidad**: Integración con el módulo **MemberFlow-Data** para mantener una separación clara entre la lógica de negocio y la capa de presentación. +El proyecto sigue una estructura modular con separación clara por dominios: + +- **user_management_controllers**: gestión de usuarios (Admins, Teachers, Students, Roles, Permisos). +- **class_management_controllers**: gestión de clases, grupos, asistencias y membresías. +- **finance_management**: facturación, productos, líneas de factura, pagos, IVA. +- **config**: configuración de seguridad, Swagger y Web CORS. --- -## Estructura del Proyecto +## 🔐 Seguridad y JWT -El proyecto está organizado en los siguientes paquetes y archivos principales: +Se utiliza Spring Security con JWT para autenticar y autorizar usuarios. El token se genera mediante el `AuthController` y se debe incluir en las peticiones siguientes vía header: -### 1. **Configuración** -- **`application.properties`**: Archivo de configuración que incluye parámetros clave como JWT y ajustes de la aplicación. -- **`MemberFlowApplication`**: Clase principal para iniciar la aplicación Spring Boot. +``` +Authorization: Bearer +``` -### 2. **Controladores** -- **`AdminController`**: Gestiona las operaciones relacionadas con los administradores, como la creación y gestión de usuarios administrativos. -- **`AuthController`**: Maneja la autenticación y generación de tokens JWT para garantizar la seguridad de los endpoints. -- **`StudentController`**: Proporciona endpoints para gestionar estudiantes, incluyendo inscripción, actualización de datos y consultas. -- **`TeacherController`**: Gestiona las operaciones relacionadas con los profesores, como la asignación de grupos y la gestión de clases. -- **`UserController`**: Controlador genérico para operaciones relacionadas con usuarios, como la gestión de perfiles y roles. +### Roles soportados: -### 3. **Seguridad** -- **`SecurityConfig`**: Configuración de seguridad para proteger los endpoints mediante autenticación JWT. -- **`JwtAuthFilter`**: Filtro para validar los tokens JWT en cada solicitud, asegurando que solo usuarios autenticados puedan acceder a los recursos protegidos. -- **`JwtUtil`**: Utilidad para generar y validar tokens JWT, incluyendo la configuración de tiempos de expiración y claves secretas. - -### 4. **Recursos** -- **`application.properties`**: Archivo de configuración centralizado para parámetros clave de la aplicación. +- `ADMIN`: acceso completo. +- `TEACHER`: acceso a su información y la de sus estudiantes. +- `STUDENT`: acceso solo a su perfil. --- -## Configuración del Proyecto +## 📂 Endpoints REST por módulo -### Requisitos Previos +### 🔑 Autenticación -1. **Java 17 o superior** -2. **Maven** -3. **Dependencia del módulo MemberFlow-Data** +| Método | URL | Descripción | +|--------|----------------------|------------------------| +| POST | `/auth/login` | Iniciar sesión | +| GET | `/users/me` | Datos del usuario logeado | -### Ejecución del Proyecto +--- -1. Clona el repositorio: - ```bash - git clone https://github.com/tu-usuario/memberflow-api.git - cd memberflow-api \ No newline at end of file +### 👥 Gestión de Usuarios + +- `/api/v1/admins` +- `/api/v1/students` +- `/api/v1/teachers` +- `/api/v1/roles` +- `/api/v1/permissions` +- `/api/v1/notifications` + +Soporta operaciones: `create`, `update`, `getById`, `getAll`, `delete`. + +--- + +### 🏋️‍♂️ Gestión de Clases + +| Entidad | Endpoint Base | +|----------------|-------------------------------| +| TrainingGroup | `/api/v1/training-groups` | +| TrainingSession| `/api/v1/training-sessions` | +| Assistance | `/api/v1/assistances` | +| Membership | `/api/v1/memberships` | + +Las sesiones pueden generarse automáticamente por grupo. Las asistencias se vinculan a estudiantes y sesiones. + +--- + +### 💰 Finanzas + +| Entidad | Endpoint Base | +|-----------------|-----------------------------| +| Invoice | `/api/v1/invoices` | +| InvoiceLine | `/api/v1/invoice-lines` | +| ProductService | `/api/v1/products` | +| Payment | `/api/v1/payments` | +| IVAType | `/api/v1/iva-types` | + +Incluye generación de PDF de facturas vía: + +``` +GET /api/v1/invoices/{id}/pdf +``` + +--- + +## 📄 Swagger UI + +Disponible en: + +``` +http://localhost:8080/swagger-ui/index.html +``` + +Configurado a través de `SwaggerConfig.java`. Expone todos los endpoints REST con documentación interactiva. + +--- + +## ⚙️ Configuración + +Archivo: `application.properties` + +```properties +spring.datasource.url=jdbc:mysql://localhost:3306/mf_db +spring.datasource.username=root +spring.datasource.password=1234 +spring.jpa.hibernate.ddl-auto=validate +spring.profiles.active=dev (opcional para datos de prueba) +``` + +--- + +## 🧪 Datos de prueba + +La clase `TestDataSeeder` inserta automáticamente entidades para facilitar pruebas: usuarios, roles, permisos, clases, facturas, etc. Se activa con el perfil `dev`. + +--- + +## 🧾 Uso y construcción + +### En desarrollo local: + +```bash +mvn clean install +``` + +Luego ejecutar `MemberFlowApplication` desde tu IDE. + +### Docker: + +Integrado en `docker-compose`, se despliega junto a MySQL y frontend automáticamente. + +--- + +## ✅ Pruebas + +```bash +mvn test +``` + +Incluye pruebas unitarias para cada servicio (`UserService`, `InvoiceService`, `MembershipService`, etc.). + +--- + +## 📦 DTOs y Validaciones + +Cada entidad tiene su correspondiente DTO con validaciones `javax.validation`, mapeo bidireccional y lógica encapsulada. Esto asegura una capa REST limpia y desacoplada del modelo de base de datos. + +--- \ No newline at end of file