Updated API README
This commit is contained in:
Dennis Eckerskorn
parent
843b5a8561
commit
d256eb7cfb
|
|
@ -1,60 +1,151 @@
|
||||||
# MemberFlow-API
|
# MemberFlow API
|
||||||
|
|
||||||
## Descripción del Proyecto
|
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**.
|
||||||
|
|
||||||
**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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Características Principales
|
## 🧱 Arquitectura General
|
||||||
|
|
||||||
- **Controladores REST**: Exposición de endpoints para gestionar usuarios, roles, notificaciones, clases y finanzas.
|
El proyecto sigue una estructura modular con separación clara por dominios:
|
||||||
- **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.
|
- **user_management_controllers**: gestión de usuarios (Admins, Teachers, Students, Roles, Permisos).
|
||||||
- **Configuración Centralizada**: Uso de `application.properties` para gestionar parámetros clave como JWT y otros ajustes.
|
- **class_management_controllers**: gestión de clases, grupos, asistencias y membresías.
|
||||||
- **Ejecución con Spring Boot**: Aplicación basada en el framework Spring Boot para facilitar el desarrollo y despliegue.
|
- **finance_management**: facturación, productos, líneas de factura, pagos, IVA.
|
||||||
- **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.
|
- **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.
|
Authorization: Bearer <token>
|
||||||
- **`MemberFlowApplication`**: Clase principal para iniciar la aplicación Spring Boot.
|
```
|
||||||
|
|
||||||
### 2. **Controladores**
|
### Roles soportados:
|
||||||
- **`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.
|
|
||||||
|
|
||||||
### 3. **Seguridad**
|
- `ADMIN`: acceso completo.
|
||||||
- **`SecurityConfig`**: Configuración de seguridad para proteger los endpoints mediante autenticación JWT.
|
- `TEACHER`: acceso a su información y la de sus estudiantes.
|
||||||
- **`JwtAuthFilter`**: Filtro para validar los tokens JWT en cada solicitud, asegurando que solo usuarios autenticados puedan acceder a los recursos protegidos.
|
- `STUDENT`: acceso solo a su perfil.
|
||||||
- **`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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Configuración del Proyecto
|
## 📂 Endpoints REST por módulo
|
||||||
|
|
||||||
### Requisitos Previos
|
### 🔑 Autenticación
|
||||||
|
|
||||||
1. **Java 17 o superior**
|
| Método | URL | Descripción |
|
||||||
2. **Maven**
|
|--------|----------------------|------------------------|
|
||||||
3. **Dependencia del módulo MemberFlow-Data**
|
| POST | `/auth/login` | Iniciar sesión |
|
||||||
|
| GET | `/users/me` | Datos del usuario logeado |
|
||||||
|
|
||||||
### Ejecución del Proyecto
|
---
|
||||||
|
|
||||||
|
### 👥 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:
|
||||||
|
|
||||||
1. Clona el repositorio:
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/tu-usuario/memberflow-api.git
|
mvn clean install
|
||||||
cd memberflow-api
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
---
|
||||||
Loading…
Reference in New Issue