Sistema de Facturación - Proyecto Educativo

🔔 Novedades Recientes

Junio 2025 - v1.3.0 - Autenticación con Redis

✅ Integración con Redis para gestión avanzada de sesiones

✅ Sistema de blacklist para tokens revocados

✅ Mejoras en la seguridad de la autenticación

Junio 2025 - v1.2.0 - Filtrado de Facturas y Mejoras de Servicios

✅ Filtrado de facturas por cliente implementado

✅ Mejoras en los servicios de facturación

Ver CHANGELOG completo para más detalles sobre todas las mejoras.

📚 Descripción

Este es un proyecto educativo de una API REST para gestión de facturación desarrollado con Node.js. El sistema permite la administración de usuarios y facturas, utilizando una arquitectura moderna basada en componentes y siguiendo buenas prácticas de desarrollo.

NOTA IMPORTANTE: Este proyecto ha sido creado con fines exclusivamente educativos como parte de un curso de desarrollo web con Node.js. No está destinado para uso en entornos de producción sin las debidas modificaciones y mejoras de seguridad.

🛠️ Tecnologías Utilizadas

Node.js: Entorno de ejecución para JavaScript del lado del servidor
Express: Framework para crear APIs REST de manera sencilla
MongoDB: Base de datos NoSQL para almacenamiento de documentos
PostgreSQL: Base de datos relacional para datos estructurados
Redis: Almacén de estructura de datos en memoria para gestión de sesiones
Mongoose: ODM para facilitar la interacción con MongoDB
Sequelize: ORM para interactuar con PostgreSQL
Docker: Contenedorización de la aplicación y sus dependencias
Docker Compose: Orquestación de contenedores
JWT (JSON Web Tokens): Autenticación basada en tokens para proteger endpoints
bcrypt: Cifrado de contraseñas para almacenamiento seguro
ioredis: Cliente Redis para Node.js con soporte para Promesas

🏗️ Arquitectura

El proyecto sigue una arquitectura basada en componentes con separación clara de responsabilidades:

src/
├── components/            # Componentes de la aplicación
│   ├── auth/              # Módulo de autenticación
│   │   ├── auth.controller.js  # Controlador de autenticación
│   │   ├── auth.routes.js      # Rutas de autenticación
│   │   └── service.auth.js     # Lógica de negocio de autenticación
│   ├── invoices/          # Módulo de facturas
│   │   ├── controller.invoices.js
│   │   ├── models.invoices.js
│   │   ├── routes.invoices.js
│   │   └── service.invoice.js
│   └── users/             # Módulo de usuarios
│       ├── controller.user.js
│       ├── models.user.js
│       ├── routes.user.js
│       └── service.user.js
├── config/                # Configuración de la aplicación
│   ├── config.js          # Variables de configuración
│   ├── database.js        # Configuración de MongoDB
│   ├── postgress.js       # Configuración de PostgreSQL
│   └── redis.js           # Configuración de Redis para gestión de sesiones
└── middleware/            # Middleware de la aplicación
    ├── logger.js          # Middleware de registro
    ├── middleware.users.js # Middleware de validación de usuarios
    └── middelware.auth.js # Middleware de autenticación y autorización

🚀 Instalación y Configuración

Prerrequisitos

Node.js (v14 o superior)
Docker y Docker Compose
Git

Pasos para la instalación

Clonar el repositorio:

git clone <url-del-repositorio>
cd invoices-app

Configurar variables de entorno:
```
cp .env_example .env
```
Edita el archivo .env con tus propias credenciales y configuraciones.
Instalación con Docker (recomendado):
```
npm run docker
```
Este comando construirá y ejecutará todos los contenedores necesarios.
Instalación local (alternativa):
```
npm install
npm run dev
```
Nota: Para la instalación local, necesitarás tener MongoDB y PostgreSQL instalados y configurados.

🔌 Endpoints API

Autenticación

POST /auth/api/login - Iniciar sesión con email y contraseña
POST /auth/api/register - Registrar un nuevo usuario (redirige al controlador de usuarios)

Usuarios

GET /users/api - Obtener todos los usuarios
POST /users/api - Crear un nuevo usuario
GET /users/api/:id - Obtener un usuario por ID
PUT /users/api/:id - Actualizar un usuario
DELETE /users/api/:id - Eliminar un usuario

Facturas

GET /invoices/api - Obtener todas las facturas
POST /invoices/api - Crear una nueva factura
GET /invoices/api/:id - Obtener una factura por ID
GET /invoices/api/customer/:id - Obtener facturas de un cliente específico
PUT /invoices/api/:id - Actualizar una factura
DELETE /invoices/api/:id - Eliminar una factura

📃 Colección de Postman

El proyecto incluye una colección de Postman lista para ser importada y utilizada para probar todos los endpoints de la API. Esta colección contiene ejemplos preconfigurados para todas las operaciones CRUD tanto para usuarios como para facturas.

Cómo usar la colección de Postman

Abre Postman
Haz clic en "Import"
Selecciona el archivo invoices-app.postman_collection.json incluido en la raíz del proyecto
Una vez importada, configura las variables de entorno necesarias:
- url_base: URL base para los endpoints de facturas (ej. http://localhost:X000/invoices/api)

Flujo de trabajo recomendado

Crear un usuario con el endpoint POST /auth/api/register
Iniciar sesión con el endpoint POST /auth/api/login para obtener las cookies HTTP-Only con los tokens
Las cookies se envían automáticamente en cada solicitud, no es necesario configurar headers manualmente
El refresh token se renueva automáticamente cuando el access token expira usando el endpoint POST /auth/api/refresh
Para cerrar sesión, usa el endpoint POST /auth/api/logout
¡Ahora puedes realizar operaciones en facturas y usuarios!
Para filtrar facturas por cliente, utiliza el endpoint GET /invoices/api/customer/:id

📊 Bases de Datos

Este proyecto utiliza múltiples sistemas de almacenamiento para diferentes propósitos:

MongoDB: Almacena documentos como facturas
PostgreSQL: Almacena datos estructurados de usuarios
Redis: Gestiona sesiones activas y blacklist de tokens

🔒 Seguridad y Autenticación

El sistema implementa un esquema de seguridad avanzado con JWT y Redis:

Autenticación por Tokens:
- Access Token (15 min de duración)
- Refresh Token (7 días, almacenado en Redis)
- Cookies HTTP-Only seguras
Protecciones de Seguridad:
- Blacklist de tokens revocados
- Protección contra CSRF
- Headers de seguridad HTTP
verifyRole: Middleware que verifica si el usuario tiene el rol adecuado para acceder a ciertos recursos
bcrypt: Utilizado para el hash seguro de contraseñas antes de almacenarlas en la base de datos

Roles de Usuario

El sistema soporta dos tipos de roles:

user: Rol estándar con acceso limitado (valor por defecto)
- Puede crear, leer, actualizar y eliminar SOLO SUS PROPIAS facturas
- No tiene acceso a información de otros usuarios
- Al listar facturas, solo ve las asociadas a su ID de usuario
admin: Rol con privilegios elevados para operaciones administrativas
- Acceso completo a todos los recursos del sistema
- Puede gestionar todos los usuarios (crear, leer, actualizar, eliminar)
- Puede gestionar todas las facturas independientemente del cliente
- No tiene restricciones en listados o búsquedas

Implementación de Permisos

El control de acceso se implementa en dos niveles:

Middleware de Autenticación:
- Valida que el token JWT sea válido en cada solicitud a endpoints protegidos
- Extrae la información del usuario (ID y rol) y la adjunta al objeto de solicitud
Middleware de Autorización:
- verifyRole: Valida que el usuario tenga el rol "admin" para acceder a rutas restringidas
- Controles de acceso basados en la propiedad de los recursos (un usuario regular solo puede acceder a sus propios recursos)

Flujo de Autenticación y Autorización

Inicio de Sesión:
- El usuario envía credenciales válidas
- El servidor genera dos tokens:
  - Access Token (corto, 15 minutos)
  - Refresh Token (largo, 7 días) almacenado en Redis
- Ambos tokens se envían como cookies HTTP-Only
Acceso a Rutas Protegidas:
- El cliente envía automáticamente las cookies con cada solicitud
- El middleware verifyToken:
  - Verifica el token de acceso
Refresco de Tokens:
- Cuando el access token expira, el cliente usa el refresh token
- Consulta la blacklist en Redis
- Si el token es válido, permite el acceso
- El middleware verifyRefreshToken:
  - Verifica el refresh token contra Redis
  - Si es válido, genera nuevos tokens
  - Invalida el refresh token anterior
Cierre de Sesión:
- El servidor invalida ambos tokens
- Los tokens se agregan a la blacklist en Redis
- Se eliminan las cookies del cliente
Control de Acceso:
- Para rutas de administrador, se usa verifyRole
- Los controladores verifican la propiedad de los recursos
- Todas las operaciones se registran para auditoría

Validaciones de Datos

El sistema incluye validaciones robustas mediante Sequelize:

Validación de Usuarios

Email:
- Debe tener formato válido de correo electrónico
- No puede estar vacío ni ser nulo
- Debe ser único en la base de datos
Contraseña:
- Longitud entre 6 y 12 caracteres
- No puede estar vacía ni ser nula
- Se almacena cifrada mediante bcrypt
Nombre de usuario:
- Requerido (no puede estar vacío)
- Debe ser único en la base de datos

🧪 Objetivos Educativos

Este proyecto está diseñado para enseñar:

Desarrollo de APIs REST con Express
Integración con múltiples bases de datos (SQL, NoSQL y Redis)
Gestión de sesiones con Redis
Implementación de blacklist para tokens JWT
Arquitectura de aplicaciones basada en componentes
Uso de Docker para desarrollo y despliegue
Estructura de carpetas en Node.js
Gestión de configuración y variables de entorno
Autenticación de usuarios con JWT y bcrypt
Seguridad avanzada en APIs mediante tokens
Validaciones de datos con Sequelize
Manejo de roles y permisos
Implementación de tokens de refresco seguros
Gestión de la expiración de sesiones

📝 Licencia

Este proyecto está bajo la licencia MIT, lo que permite su uso con fines educativos.

👩‍💻 Autor

Desarrollado por Lizeth Castillo - @liztechcode como parte del curso de desarrollo web con Node.js.

Nota: Este README es parte del material educativo y puede ser modificado según las necesidades del curso.

Home