Skip to content

jdomdev/bizflow-erp-springboot-react-docker

BranchesTags

Repository files navigation

Bizflow ERP

Spring Boot React Java PostgreSQL Docker License

Sistema ERP moderno para gestión de gastos empresariales, empleados y nóminas.

📸 Screenshots

Dashboard Gastos
Dashboard Gastos
Empleados Modo Oscuro
Empleados Modo Oscuro

✨ Características

Seguridad

  • 🔐 Autenticación JWT con refresh tokens y control de acceso basado en roles (ADMIN, MANAGER, USER)
  • 🛡️ Spring Security configurado con protección CSRF y CORS
  • 🔒 Contraseñas encriptadas con BCrypt

Funcionalidades

  • 📊 Dashboard interactivo con estadísticas en tiempo real y gráficos (Chart.js)
  • 💰 Gestión de Gastos con paginación del lado del servidor, filtros y exportación
  • 👥 Gestión de Empleados con vinculación automática a usuarios del sistema
  • 💵 Gestión de Nóminas con cálculos automáticos y historial
  • 🏢 Gestión de Cargos/Posiciones con jerarquía organizacional

Experiencia de Usuario

  • 🌙 Modo Oscuro con persistencia de preferencias en localStorage
  • 🔔 Notificaciones en tiempo real via WebSocket
  • 📱 Diseño 100% responsive para móvil, tablet y escritorio
  • ⚡ Rendimiento optimizado con lazy loading y code splitting

DevOps y Desarrollo

  • 🐳 Docker Compose con perfiles para dev, test y producción
  • 🔄 Hot reload en desarrollo con Vite
  • 🧪 Tests automatizados con JUnit 5 (backend) y Vitest (frontend)
  • 📝 API REST documentada con endpoints versionados (/api/v1)

🚀 Quick Start

Prerrequisitos

Linux / macOS

  • Docker y Docker Compose v2+
  • Git
  • Node.js 18+ (solo para desarrollo local con Vite)
  • Make (generalmente preinstalado)

Windows

⚠️ Importante: Este proyecto usa Makefile y scripts bash. En Windows necesitas WSL2 (Windows Subsystem for Linux).

  1. Instalar WSL2 con Ubuntu
  2. Instalar Docker Desktop con integración WSL2
  3. Ejecutar todos los comandos desde la terminal WSL2
# Desde PowerShell (como administrador)
wsl --install -d Ubuntu

Una vez en WSL2, los comandos son idénticos a Linux.

Paso 1: Clonar el repositorio

git clone https://github.com/jdomdev/bizflow-erp-springboot-react-docker.git
cd bizflow-erp-springboot-react-docker

Paso 2: Configurar credenciales

Antes de ejecutar, debes crear los archivos de credenciales (están ignorados en .gitignore por seguridad):

# Crear directorio de secrets
mkdir -p scripts/secrets/users_with_passwords

# Copiar plantillas y editar contraseñas
cp scripts/seeds/data/dev/users.json.example scripts/secrets/users_with_passwords/dev_users.json
cp scripts/seeds/data/test/users.json.example scripts/secrets/users_with_passwords/test_users.json

# Editar y reemplazar <SEED_PASSWORD_PLACEHOLDER> con contraseñas reales
# nano scripts/secrets/users_with_passwords/dev_users.json

📖 Ver Guía completa de configuración de credenciales

Paso 3: Ejecutar

# Construir imágenes base e iniciar entorno desarrollo
make up-dev

# O con docker compose directamente
docker compose --profile dev up -d --build

🌍 Entornos

Modo Híbrido: Vite Local + Docker (Recomendado para desarrollo)

Este es el modo recomendado para desarrolladores porque ofrece:

  • ⚡ Hot reload instantáneo en el frontend (< 100ms)
  • 🔄 HMR (Hot Module Replacement) para CSS y JS
  • 🐳 Backend y BD aislados en contenedores
# Terminal 1: Levantar backend y base de datos en Docker
make up-dev

# Terminal 2: Iniciar servidor Vite para el frontend
cd frontend
npm install      # Solo la primera vez
npm run dev
Servicio URL Descripción
Frontend (Vite) http://localhost:3000 Servidor de desarrollo con HMR
Backend API http://localhost:8082/api/v1 Spring Boot en Docker
Base de datos localhost:5433 PostgreSQL en Docker

💡 Nota: Vite tiene configurado un proxy para /api que redirige automáticamente al backend en el puerto 8082. Ver vite.config.js.

⚠️ Importante: Aunque existe un contenedor frontend-dev en Docker (puerto 8085), para desarrollo activo se recomienda usar Vite local por la velocidad de recarga.

Entornos Docker (Todo containerizado)

Para testing, CI/CD o cuando no necesitas hot reload:

Entorno Frontend Backend API Base de datos Comando
Dev http://localhost:8085 http://localhost:8082/api/v1 localhost:5433 make up-dev
Test http://localhost:8086 http://localhost:8083/api/v1 localhost:5434 make up-test
Prod http://localhost:8080 http://localhost:8181/api/v1 localhost:5442 make up-prod

Credenciales de acceso

Los archivos de credenciales deben crearse manualmente (están en .gitignore):

Entorno Usuario admin Archivo de contraseñas
Dev ada.lovelace@bizflowerp.com scripts/secrets/users_with_passwords/dev_users.json
Test ada.lovelace@bizflowerp.com scripts/secrets/users_with_passwords/test_users.json
Prod ada.lovelace@bizflowerp.com scripts/secrets/users_with_passwords/prod_users.json

📖 Primer uso: Sigue la Guía de configuración de credenciales para crear estos archivos.

⚠️ Seguridad: Las contraseñas de producción DEBEN ser diferentes a las de desarrollo.

pgAdmin (Solo Dev)

  • Disponible solo cuando se levanta el perfil debug de Docker Compose
  • Para usarlo: docker compose --profile debug up -d
  • URL: http://localhost:5050
  • Credenciales: Ver variables en .env

📖 Documentación

🌐 Documentación Online (Recomendada)

Documentación en Netlify

➡️ https://bizflowerp.netlify.app

La documentación online incluye:

  • 🏗️ Arquitectura del sistema - Diagramas y explicaciones detalladas
  • 🐳 Guías de Docker - Comandos, perfiles y troubleshooting
  • 🔗 API Reference - Todos los endpoints documentados
  • 🧪 Guías de testing - Estrategias y configuración
  • 🚀 Guías de despliegue - Configuración de producción
Home Arquitectura
Docs Home Arquitectura
Guía Docker API Reference
Docker Guide API Reference

📂 Documentación Local

También disponible en la carpeta /docs:

🛠️ Stack Tecnológico

Backend Frontend Infraestructura
Java 17 (OpenJDK) React 18 Docker Compose
Spring Boot 3.3.4 Vite 5 PostgreSQL 16
Spring Security + JWT Tailwind CSS Nginx
JPA/Hibernate Zustand pgAdmin
Maven Vitest

🎯 Guía para Nuevos Desarrolladores

Si eres nuevo en el proyecto, sigue este orden de lectura:

1️⃣ Configuración inicial

  1. Este README - Visión general y quick start
  2. Configuración de credenciales - OBLIGATORIO antes de ejecutar

2️⃣ Entender la arquitectura

  1. Arquitectura del sistema 🌐 - Estructura general
  2. Guía de desarrollo - Convenciones y flujos

3️⃣ Sistema de datos

  1. Sistema de Seeds - Cómo se cargan datos iniciales
  2. Inicialización de BD - Secuencia de arranque

4️⃣ Docker y comandos

  1. Comandos Makefile - Todos los comandos disponibles
  2. Guía de entornos - Cambiar entre dev/test/prod

📁 Estructura del Proyecto

├── backend/          # Spring Boot API
├── frontend/         # React + Vite
├── docker/           # Dockerfiles base
├── scripts/          # Scripts de utilidad
├── sql/              # Migraciones y seeds
├── docs/             # Documentación
└── docker-compose.yml

🔧 Comandos Útiles

# Entornos
make up-dev           # Iniciar entorno desarrollo
make up-prod          # Iniciar entorno producción
make up-test          # Iniciar entorno testing
make down-dev         # Detener entorno desarrollo
make down-prod        # Detener entorno producción
make down-test        # Detener entorno testing

# Base de datos
make backup-dev       # Crear backup de BD (desarrollo)
make backup-prod      # Crear backup de BD (producción)
make backup-test      # Crear backup de BD (testing)
make backup-all       # Crear backup de todas las bases de datos

# Ayuda
make help             # Ver todos los comandos disponibles

🤝 Contribuir

  1. Fork del repositorio
  2. Crear rama feature (git checkout -b feat/nueva-funcionalidad)
  3. Commit cambios (git commit -m 'feat: añadir nueva funcionalidad')
  4. Push a la rama (git push origin feat/nueva-funcionalidad)
  5. Abrir Pull Request

📄 Licencia

Este proyecto está bajo la Licencia GNU General Public License v3.0 - ver LICENSE.txt para más detalles.

Desarrollado con ☕ y 💻

About

Spring Boot application about a company employee expense note.

Resources

Readme

License

View license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages