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](#descripción-del-proyecto)
2. [Arquitectura General](#arquitectura-general)
3. [Estructura del Repositorio](#estructura-del-repositorio)
4. [Tecnologías](#tecnologías)
5. [Instalación y Configuración](#instalación-y-configuración)
6. [Scripts Disponibles](#scripts-disponibles)
7. [Documentación Adicional](#documentación-adicional)
8. [Integraciones Externas](#integraciones-externas)
9. [Seguridad y Autenticación](#seguridad-y-autenticación)
10. [Créditos](#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

```bash
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:

```bash
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

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

Archivo `.env` del backend:
```env
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

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

### 5. Configurar Frontend

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

Archivo `.env` del frontend:
```env
VITE_API_BASE_URL=http://localhost:3000/api
```

### 6. Iniciar Frontend

```bash
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`](./DOCUMENTACION_TECNICA.md) — Análisis técnico completo, endpoints, roles, integraciones y reglas de oro para no romper integridad.
- [`docs/BACKEND.md`](./docs/BACKEND.md) — Guía detallada del backend: estructura de carpetas, controllers, servicios y configuración.
- [`docs/FRONTEND.md`](./docs/FRONTEND.md) — Guía del frontend: componentes, rutas, manejo de estado, permisos y estilos.
- [`docs/DATABASE.md`](./docs/DATABASE.md) — Documentación de la base de datos: funciones SQL conocidas, tablas principales y relaciones.
- [`docs/API.md`](./docs/API.md) — Referencia completa de todos los endpoints REST.
- [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md) — Guía de despliegue en producción.
- [`docs/TROUBLESHOOTING.md`](./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.