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-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 <token>
|
||||
```
|
||||
|
||||
### 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
|
||||
### 👥 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.
|
||||
|
||||
---
|
||||
Loading…
Reference in New Issue