Skip to content

README.md

Latest commit

 

History

History
325 lines (243 loc) · 7.55 KB

README.md

File metadata and controls

325 lines (243 loc) · 7.55 KB

Enterprise Management API

API REST de nivel producción construida con Java 17, Spring Boot 3.2 y arquitectura hexagonal para la gestión empresarial, productos, clientes y órdenes.

Arquitectura

Este proyecto implementa Arquitectura Hexagonal (Ports & Adapters) con separación clara de responsabilidades:

src/main/java/com/litethinking/enterprise/
├── domain/              # Lógica de negocio pura (sin dependencias externas)
│   ├── model/          # Entidades de dominio y Value Objects
│   ├── port/           # Interfaces (puertos de entrada y salida)
│   └── exception/      # Excepciones de dominio
├── application/         # Casos de uso y orquestación
│   ├── usecase/        # Servicios de aplicación
│   ├── dto/            # Data Transfer Objects
│   └── mapper/         # Mappers (MapStruct)
├── infrastructure/      # Implementaciones técnicas
│   ├── persistence/    # JPA entities y repositorios
│   ├── security/       # JWT, BCrypt, configuración de seguridad
│   ├── integration/    # reCAPTCHA, AWS SES, PDF
│   └── config/         # Configuraciones de Spring
└── interfaces/          # Adaptadores de entrada
    ├── rest/           # Controllers REST
    └── exception/      # Exception handlers globales

Tecnologías

  • Java 17
  • Spring Boot 3.2.1
  • PostgreSQL (base de datos principal)
  • Spring Security + JWT (autenticación stateless)
  • BCrypt (hashing de contraseñas, cost 12)
  • MapStruct (mapeo de objetos)
  • Hibernate/JPA (ORM)
  • Swagger/OpenAPI (documentación)
  • Google reCAPTCHA v3 (protección de login)
  • AWS SES (envío de correos)
  • iText7 (generación de PDF)
  • JUnit 5 + Mockito (testing)

Requisitos Previos

  • JDK 17 o superior
  • Maven 3.8+
  • PostgreSQL 14+
  • Cuenta de Google Cloud (reCAPTCHA)
  • Cuenta de AWS (SES para correos)

Configuración de Base de Datos

Ejecutar el script SQL proporcionado para crear el esquema completo:

-- Ver archivo: database/schema.sql

El modelo incluye:

  • Seguridad: roles, usuarios
  • Catálogos: monedas, categorias
  • Negocio: empresas, productos, producto_precios, producto_categoria
  • Transaccional: clientes, estados_orden, ordenes, orden_detalles
  • Monitoreo: excepciones_sistema

Variables de Entorno

Crear archivo .env o configurar en el sistema:

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=enterprise_db
DB_USER=postgres
DB_PASSWORD=your_password

# Security
JWT_SECRET=your-256-bit-secret-key-minimum-32-characters-long
RECAPTCHA_SECRET=your-recaptcha-secret-key

# AWS
AWS_REGION=us-east-1
AWS_ACCESS_KEY=your-access-key
AWS_SECRET_KEY=your-secret-key
AWS_SES_FROM=noreply@yourdomain.com
AWS_SES_ENABLED=true

# Server
SERVER_PORT=8080

Ejecución Local

# Compilar
mvn clean install

# Ejecutar
mvn spring-boot:run

# O directamente
java -jar target/enterprise-api-1.0.0.jar

La aplicación estará disponible en: http://localhost:8080

Documentación API

Swagger UI: http://localhost:8080/swagger-ui.html

OpenAPI JSON: http://localhost:8080/api-docs

Nota: Swagger requiere autenticación JWT. Primero hacer login y copiar el token en "Authorize".

Endpoints Principales

Autenticación

POST /api/v1/auth/login
POST /api/v1/auth/register

Empresas (requiere ADMIN)

POST   /api/v1/empresas
GET    /api/v1/empresas
GET    /api/v1/empresas/{nit}
PUT    /api/v1/empresas/{nit}
DELETE /api/v1/empresas/{nit}

Productos (requiere ADMIN)

POST   /api/v1/productos
GET    /api/v1/productos
GET    /api/v1/productos/{codigo}
PUT    /api/v1/productos/{codigo}
DELETE /api/v1/productos/{codigo}

Órdenes (requiere ADMIN)

POST   /api/v1/ordenes
GET    /api/v1/ordenes
GET    /api/v1/ordenes/{id}
PUT    /api/v1/ordenes/{id}/estado

Inventario (requiere ADMIN)

GET /api/v1/inventario/pdf?empresaNit={nit}
POST /api/v1/inventario/enviar-pdf

Roles y Permisos

  • ADMIN: Acceso completo a todas las operaciones
  • EXTERNO: Solo lectura de empresas y productos

Seguridad

  • Contraseñas hasheadas con BCrypt (cost 12)
  • Tokens JWT con expiración de 24 horas
  • Login protegido con Google reCAPTCHA v3
  • Validación de roles con @PreAuthorize
  • Headers de seguridad configurados
  • CORS configurado

Manejo de Errores

Respuestas estandarizadas:

{
  "timestamp": "2024-01-15T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Descripción del error",
  "path": "/api/v1/empresas"
}

Códigos HTTP:

  • 200: Éxito
  • 201: Recurso creado
  • 400: Validación fallida
  • 401: No autenticado
  • 403: Sin permisos
  • 404: Recurso no encontrado
  • 409: Conflicto de negocio
  • 422: Entidad no procesable
  • 500: Error interno

Los errores críticos se registran automáticamente en excepciones_sistema.

Testing

# Ejecutar todos los tests
mvn test

# Solo tests unitarios
mvn test -Dtest=*UnitTest

# Solo tests de integración
mvn test -Dtest=*IntegrationTest

# Con cobertura
mvn test jacoco:report

Patrones de Diseño Aplicados

  • Hexagonal Architecture: Separación de capas
  • Repository Pattern: Acceso a datos
  • Factory Pattern: Creación de entidades complejas
  • Strategy Pattern: Validaciones de estados
  • Adapter Pattern: Integraciones externas (reCAPTCHA, AWS)
  • Mapper Pattern: Conversión de objetos (MapStruct)
  • DTO Pattern: Transferencia de datos

Principios SOLID

  • Single Responsibility: Cada clase tiene una única responsabilidad
  • Open/Closed: Extensible sin modificar código existente
  • Liskov Substitution: Interfaces bien definidas
  • Interface Segregation: Interfaces específicas
  • Dependency Inversion: Dependencias hacia abstracciones

Despliegue en AWS

Opción 1: EC2

# Construir JAR
mvn clean package -DskipTests

# Transferir a EC2
scp target/enterprise-api-1.0.0.jar ec2-user@your-ec2-ip:/home/ec2-user/

# Conectar y ejecutar
ssh ec2-user@your-ec2-ip
nohup java -jar enterprise-api-1.0.0.jar &

Opción 2: Elastic Beanstalk

eb init -p corretto-17 enterprise-api
eb create enterprise-api-env
eb deploy

Opción 3: ECS (Docker)

docker build -t enterprise-api .
docker tag enterprise-api:latest your-ecr-repo/enterprise-api:latest
docker push your-ecr-repo/enterprise-api:latest

Estructura de Datos Inicial

Crear roles iniciales

INSERT INTO roles (nombre, descripcion) VALUES
('ADMIN', 'Administrador con acceso completo'),
('EXTERNO', 'Usuario externo con acceso de solo lectura');

Crear usuario administrador

-- Password: Admin123! (hasheado con BCrypt cost 12)
INSERT INTO usuarios (correo, password, rol_id, activo) VALUES
('admin@litethinking.com', '$2a$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5GyYKKMQzzzm6', 1, true);

Crear monedas

INSERT INTO monedas (codigo_iso, nombre, simbolo) VALUES
('COP', 'Peso Colombiano', '$'),
('USD', 'Dólar Estadounidense', '$'),
('EUR', 'Euro', '€');

Crear estados de orden

INSERT INTO estados_orden (nombre) VALUES
('PENDIENTE'),
('PAGADA'),
('ANULADA');

Credenciales de Prueba

Usuario Administrador:

  • Correo: admin@litethinking.com
  • Password: Admin123!

Usuario Externo:

  • Correo: externo@litethinking.com
  • Password: Externo123!

Monitoreo y Logs

Los logs se almacenan en:

  • Consola: Desarrollo
  • Archivo: logs/application.log (rotación diaria)
  • Base de datos: excepciones_sistema (errores críticos)

Licencia

MIT License