hotel-hacienda/README.md

🏨 Hacienda San Angel — Sistema de Gestión Hotelera

Versión: 1.0.0
Entorno: Node.js + PostgreSQL + React 19
Repositorio: https://git.consultoria-as.com/consultoria-as/hotel-hacienda

---

📋 Índice

1. Descripción del Proyecto
2. Arquitectura General
3. Estructura del Repositorio
4. Tecnologías
5. Instalación y Configuración
6. Scripts Disponibles
7. Documentación Adicional
8. Integraciones Externas
9. Seguridad y Autenticación
10. Créditos

---

Descripción del Proyecto

Sistema administrativo integral para la gestión financiera, operativa y de recursos humanos del hotel Hacienda San Angel. El sistema gestiona:

• Ingresos: Little Hotelier, Stripe, Facturas electrónicas (Horux), análisis P&L
• Gastos: Aprobaciones, pagos, reportes, pagos mensuales recurrentes
• Nómina: Empleados, contratos, asistencia, puestos, áreas
• Inventario: Productos, proveedores, ajustes de stock, consumos, descartes
• Configuraciones: Habitaciones, propiedades, catálogos maestros
• Reportes: Dashboards, análisis de habitaciones, análisis de restaurante

---

Arquitectura General

┌─────────────────────────────────────────────────────────────┐
│                     CLIENTE (Browser)                        │
│              React 19 + Vite + React Router                  │
│                   Puerto: 5172 (dev)                         │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP / JSON
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                    SERVIDOR API (Node.js)                    │
│              Express 5 + CORS + Nodemailer                   │
│                   Puerto: 3000-4000                          │
│                                                              │
│  Endpoints: /api/auth, /api/employees, /api/expenses,       │
│  /api/products, /api/incomes, /api/incomeshrx, etc.         │
└──────────────────────┬──────────────────────────────────────┘
                       │ SQL (funciones PostgreSQL)
                       ▼
┌─────────────────────────────────────────────────────────────┐
│              BASE DE DATOS (PostgreSQL)                      │
│                                                              │
│  Lógica de negocio implementada en funciones SQL:           │
│  newexpensev2(), purchaseentry(), setpaymentstatusv2(),     │
│  getincomehorux(), addstripedatav2(), etc.                  │
└─────────────────────────────────────────────────────────────┘

Patrón arquitectónico: MVC simplificado donde los Controllers solo orquestan llamadas a funciones PostgreSQL. La lógica de negocio reside principalmente en la base de datos.

---

Estructura del Repositorio

hotel-hacienda/
├── backend/
│   └── hotel_hacienda/           # API REST Node.js
│       ├── src/
│       │   ├── server.js         # Entry point
│       │   ├── app.js            # Config Express + rutas
│       │   ├── db/connection.js  # Pool PostgreSQL
│       │   ├── controllers/      # 18 controllers
│       │   ├── routes/           # 16 archivos de rutas
│       │   ├── middlewares/      # Validaciones
│       │   └── services/         # Nodemailer
│       ├── .env                  # Variables de entorno (NO subir)
│       └── package.json
│
├── frontend/
│   └── Frontend-Hotel/           # SPA React
│       ├── src/
│       │   ├── main.jsx          # Entry point React
│       │   ├── App.jsx           # Enrutamiento
│       │   ├── components/       # Layout, Tablas, Modales, etc.
│       │   ├── pages/            # ~50+ páginas por dominio
│       │   ├── context/          # AuthContext, LangContext
│       │   ├── services/         # API clients
│       │   ├── constants/        # Configuración de menú
│       │   └── styles/           # CSS por componente
│       ├── public/               # Assets estáticos
│       ├── .env                  # VITE_API_BASE_URL
│       └── package.json
│
├── backupcondatos22122025.sql    # Backup de base de datos
├── DOCUMENTACION_TECNICA.md      # Documentación técnica completa
├── README.md                     # Este archivo
└── docs/                         # Documentación extendida
    ├── BACKEND.md
    ├── FRONTEND.md
    ├── DATABASE.md
    ├── API.md
    ├── DEPLOYMENT.md
    └── TROUBLESHOOTING.md

---

Tecnologías

Backend

Tecnología	Versión	Propósito
Node.js	—	Runtime
Express	^5.1.0	Framework web
PostgreSQL	—	Base de datos
pg (node-postgres)	^8.16.3	Driver PostgreSQL
Axios	^1.13.2	HTTP client para APIs externas
Nodemailer	^7.0.12	Envío de correos
Stripe	^20.1.0	Integración de pagos
xlsx / csv-parser	^0.18.5 / ^3.2.0	Procesamiento de archivos
express-validator	^7.2.1	Validación de inputs
dotenv	^17.2.2	Variables de entorno

Frontend

Tecnología	Versión	Propósito
React	^19.1.1	UI Library
React DOM	^19.1.1	Renderizado
React Router DOM	^7.8.2	Enrutamiento SPA
Vite	^7.1.2	Build tool y dev server
Axios	^1.11.0	HTTP client
Tailwind CSS	^4.1.13	Framework CSS (uso parcial)
Bootstrap	^5.3.8	Framework CSS (uso parcial)
react-hook-form	^7.66.1	Manejo de formularios
Yup	^1.7.1	Validación de esquemas
xlsx	^0.18.5	Exportación a Excel
react-icons	^5.5.0	Iconografía

---

Instalación y Configuración

Requisitos Previos

• Node.js 18+
• PostgreSQL 13+
• npm o pnpm

1. Clonar el Repositorio

git clone https://git.consultoria-as.com/consultoria-as/hotel-hacienda.git
cd hotel-hacienda

2. Configurar Base de Datos

Restaurar el backup de PostgreSQL:

psql -U postgres -c "CREATE DATABASE hotel_hacienda;"
psql -U postgres -d hotel_hacienda -f backupcondatos22122025.sql

Nota: El backup contiene las funciones SQL, tablas, catálogos y datos maestros del sistema.

3. Configurar Backend

cd backend/hotel_hacienda
cp .env.example .env   # Si no existe, crear manualmente
npm install

Archivo .env del backend:

PORT=3000
URL_CORS=https://hotel.consultoria-as.com

# PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=TU_PASSWORD
DB_NAME=hotel_hacienda

# Email
EMAIL_HOST=smtp.tudominio.com
EMAIL_PORT=587
EMAIL_USER=soporte@horuxfin.com
EMAIL_PASS=TU_PASSWORD

# Stripe
STRIPE_SECRET_KEY=sk_test_...

# API Facturas (México)
FACTURAS_API_URL=https://api.facturas.com/...
FACTURAS_ISSUER_RFC=RFC_EMISOR
FACTURAS_TYPE=I
FACTURAS_API_TOKEN=token_aqui

# Banxico
BANXICO_TOKEN=token_banxico

4. Iniciar Backend

npm run dev        # Desarrollo con nodemon
# o
npm start          # Producción

5. Configurar Frontend

cd frontend/Frontend-Hotel
cp .env.example .env
npm install

Archivo .env del frontend:

VITE_API_BASE_URL=http://localhost:3000/api

6. Iniciar Frontend

npm run dev        # Puerto 5172

---

Scripts Disponibles

Backend (backend/hotel_hacienda/)

Script	Comando	Descripción
start	node src/server.js	Producción
dev	nodemon src/server.js	Desarrollo con hot reload

Frontend (frontend/Frontend-Hotel/)

Script	Comando	Descripción
dev	vite	Servidor de desarrollo
build	vite build	Build de producción
preview	vite preview	Previsualizar build
lint	eslint .	Linting del código

---

Documentación Adicional

• DOCUMENTACION_TECNICA.md — Análisis técnico completo, endpoints, roles, integraciones y reglas de oro para no romper integridad.
• docs/BACKEND.md — Guía detallada del backend: estructura de carpetas, controllers, servicios y configuración.
• docs/FRONTEND.md — Guía del frontend: componentes, rutas, manejo de estado, permisos y estilos.
• docs/DATABASE.md — Documentación de la base de datos: funciones SQL conocidas, tablas principales y relaciones.
• docs/API.md — Referencia completa de todos los endpoints REST.
• docs/DEPLOYMENT.md — Guía de despliegue en producción.
• docs/TROUBLESHOOTING.md — Problemas comunes y soluciones.

---

Integraciones Externas

Servicio	Uso	Archivo Relacionado
Banxico API	Tipo de cambio USD/MXN	exchange.controller.js
Stripe API	Transfers y balance transactions	incomehrx.controller.js
API Facturas	Descarga de facturas electrónicas (México)	incomehrx.controller.js
Nodemailer/SMTP	Correos transaccionales	mail.controller.js, auth.controller.js

---

Seguridad y Autenticación

⚠️ Advertencia de seguridad: Este sistema utiliza autenticación básica basada en función SQL (validarusuario) sin JWT ni middleware de autorización en los endpoints del backend. El control de acceso se realiza principalmente en el frontend mediante un número de rol guardado en localStorage.

Recomendación: Para producción, considerar implementar:

• JWT o API Keys en el backend
• Middleware de autorización por rol
• HTTPS obligatorio
• Sanitización adicional de inputs

---

Créditos

Desarrollado para Consultoría AS — Hacienda San Angel.

---

Mantenimiento: Si realizas cambios significativos, actualiza tanto el código como la documentación correspondiente para mantener la integridad del sistema.