consultoria-as/hotel-hacienda
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: documentación extensiva del proyecto

Browse Source 
- README.md con guía completa de instalación y arquitectura
- docs/BACKEND.md — guía detallada del API
- docs/FRONTEND.md — guía del SPA React
- docs/DATABASE.md — funciones SQL y patrones de datos
- docs/API.md — referencia completa de endpoints REST
- docs/DEPLOYMENT.md — guía de despliegue en producción
- docs/TROUBLESHOOTING.md — solución de problemas comunes
- CHANGELOG.md — historial de cambios
- CONTRIBUTING.md — guía de contribución
This commit is contained in:
Consultoria AS
2026-06-09 16:26:09 -07:00
parent f284a5ca27
commit 411d517ba4
9 changed files with 2728 additions and 295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

529
README.md
View File

@@ -1,362 +1,301 @@
# Hacienda San Angel - Sistema de Gestion Hotelera
# 🏨 Hacienda San Angel — Sistema de Gestión Hotelera
Sistema integral de gestion para el hotel Hacienda San Angel. Incluye modulos de administracion de empleados, nomina, inventario, gastos, ingresos, y reporteria.
> **Versión:** 1.0.0
> **Entorno:** Node.js + PostgreSQL + React 19
> **Repositorio:** `https://git.consultoria-as.com/consultoria-as/hotel-hacienda`
## Documentacion
---
- [Arquitectura y Diagramas de Base de Datos](docs/ARQUITECTURA.md) - Diagramas ERD, arquitectura del sistema y flujo de datos
## 📋 Índice
## Tecnologias
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
- **Node.js** con Express 5
- **PostgreSQL 15** como base de datos
- **Nodemailer** para envio de correos (Brevo/Sendinblue)
- **Stripe** para procesamiento de pagos
- **Axios** para consultas externas (tipo de cambio Banxico)
| 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
- **React 19** con Vite 7
- **React Router DOM 7** para navegacion
- **React Hook Form** + **Yup** para validacion de formularios
- **Bootstrap 5** + **Tailwind CSS** para estilos
- **Axios** para peticiones HTTP
- **XLSX** para exportacion de datos a Excel
### Infraestructura
- **Docker** y **Docker Compose** para contenedorizacion
- **PostgreSQL 15** en contenedor
| 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 |
---
## Estructura del Proyecto
```
Hotel/
├── backend/
│ ├── Dockerfile
│ └── hotel_hacienda/
│ ├── src/
│ │ ├── app.js # Configuracion Express
│ │ ├── server.js # Punto de entrada
│ │ ├── controllers/ # Logica de negocio
│ │ ├── routes/ # Definicion de rutas API
│ │ ├── middlewares/ # Validadores
│ │ ├── db/ # Conexion a PostgreSQL
│ │ └── services/ # Servicios (email)
│ ├── scripts bd/ # Scripts SQL para la BD
│ └── package.json
├── frontend/
│ ├── Dockerfile
│ └── Frontend-Hotel/
│ ├── src/
│ │ ├── App.jsx # Rutas principales
│ │ ├── main.jsx # Punto de entrada
│ │ ├── components/ # Componentes reutilizables
│ │ ├── pages/ # Paginas de la aplicacion
│ │ ├── services/ # Servicios API
│ │ ├── context/ # Context API
│ │ └── styles/ # Estilos globales
│ └── package.json
├── docker-compose.yml
├── .env.example
└── README.md
```
---
## Modulos del Sistema
### 1. Dashboard
- **Income**: Vista general de ingresos
- **Hotel P&L**: Estado de perdidas y ganancias del hotel
- **Restaurant P&L**: Estado de perdidas y ganancias del restaurante
- **Budget**: Presupuesto
- **Cost Per Room**: Costo por habitacion
- **Room Analysis**: Analisis de ocupacion de habitaciones
- **Expenses**: Resumen de gastos
### 2. Nomina y Empleados (Payroll)
- Gestion de empleados (alta, baja, modificacion)
- Contratos laborales
- Control de asistencia
- Uniformes
- Pago diario
### 3. Gastos (Expenses)
- Registro de gastos
- Pagos mensuales recurrentes
- Aprobacion de gastos (flujo de aprobacion)
- Proveedores
- Reportes de gastos
- Entradas de compras
### 4. Inventario (Inventory)
- Catalogo de productos
- Ajustes de inventario
- Salidas de inventario
- Salidas de ama de llaves (Housekeeper)
- Reportes de inventario
- Descarte de productos
### 5. Ingresos (Income)
- Registro de ingresos
- Reportes de ingresos
- Integracion con sistema Horux
### 6. Hotel
- Gestion de propiedades
- Gestion de habitaciones
### 7. Configuracion (Settings)
- Gestion de habitaciones
- Configuracion del sistema
- Gestion de usuarios
---
## API Endpoints
### Autenticacion
- `POST /api/auth/login` - Iniciar sesion
- `POST /api/auth/create` - Crear usuario
- `POST /api/auth/recover` - Recuperar contrasena
### Empleados
- `GET /api/employees` - Listar empleados
- `POST /api/employees/new` - Crear empleado
- `PUT /api/employees/update` - Actualizar empleado
- `GET /api/employees/attendance` - Obtener asistencia
### Contratos
- `GET /api/contracts` - Listar contratos
- `POST /api/contracts` - Crear contrato
- `PUT /api/contracts` - Actualizar contrato
### Productos/Inventario
- `GET /api/products` - Listar productos
- `POST /api/products` - Crear producto
- `PUT /api/products` - Actualizar producto
### Gastos
- `GET /api/expenses` - Listar gastos
- `POST /api/expenses` - Crear gasto
- `PUT /api/expenses` - Actualizar gasto
- `GET /api/expenses/pending` - Gastos pendientes de aprobacion
### Ingresos
- `GET /api/incomes` - Listar ingresos
- `POST /api/incomes` - Registrar ingreso
- `GET /api/incomeshrx` - Ingresos Horux
### Pagos
- `POST /api/payment` - Procesar pago con Stripe
### Tipo de Cambio
- `GET /api/exchange` - Obtener tipo de cambio (Banxico)
### Configuracion
- `GET /api/settings` - Obtener configuracion
- `PUT /api/settings` - Actualizar configuracion
---
## Guia de Instalacion
## Instalación y Configuración
### Requisitos Previos
- Docker y Docker Compose instalados
- Git
- Node.js 18+
- PostgreSQL 13+
- npm o pnpm
### Opcion 1: Instalacion con Docker (Recomendado)
### 1. Clonar el Repositorio
1. **Clonar el repositorio**
```bash
git clone https://git.consultoria-as.com/usuario/Hacienda-San-Angel.git
cd Hacienda-San-Angel
git clone https://git.consultoria-as.com/consultoria-as/hotel-hacienda.git
cd hotel-hacienda
```
2. **Configurar variables de entorno**
### 2. Configurar Base de Datos
Restaurar el backup de PostgreSQL:
```bash
cp .env.example .env
psql -U postgres -c "CREATE DATABASE hotel_hacienda;"
psql -U postgres -d hotel_hacienda -f backupcondatos22122025.sql
```
Editar el archivo `.env` con los valores correspondientes:
```env
POSTGRES_PASSWORD=tu_password_seguro
EMAIL_USER=tu_email@ejemplo.com
EMAIL_PASS=tu_api_key_brevo
BANXICO_TOKEN=tu_token_banxico
```
> **Nota:** El backup contiene las funciones SQL, tablas, catálogos y datos maestros del sistema.
3. **Construir e iniciar los contenedores**
```bash
docker-compose up -d --build
```
### 3. Configurar Backend
4. **Verificar que los servicios esten corriendo**
```bash
docker-compose ps
```
5. **Importar la base de datos**
```bash
# Copiar el archivo SQL al contenedor
docker cp backupcondatos22122025.sql postgres_db:/tmp/
# Ejecutar el script SQL
docker exec -it postgres_db psql -U oposgres -d haciendasanangel -f /tmp/backupcondatos22122025.sql
```
6. **Acceder a la aplicacion**
- Frontend: http://localhost:5172
- Backend API: http://localhost:4000/api
### Opcion 2: Instalacion Manual (Desarrollo)
#### Backend
1. **Navegar al directorio del backend**
```bash
cd backend/hotel_hacienda
```
2. **Instalar dependencias**
```bash
cp .env.example .env # Si no existe, crear manualmente
npm install
```
3. **Configurar variables de entorno**
```bash
cp .env.example .env
# Editar .env con los valores correspondientes
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 el servidor**
### 4. Iniciar Backend
```bash
npm run dev # Desarrollo con nodemon
npm start # Produccion
npm run dev # Desarrollo con nodemon
# o
npm start # Producción
```
#### Frontend
### 5. Configurar Frontend
1. **Navegar al directorio del frontend**
```bash
cd frontend/Frontend-Hotel
```
2. **Instalar dependencias**
```bash
cp .env.example .env
npm install
```
3. **Configurar variables de entorno**
```bash
cp .env.example .env
# Editar .env con la URL del API
Archivo `.env` del frontend:
```env
VITE_API_BASE_URL=http://localhost:3000/api
```
4. **Iniciar la aplicacion**
### 6. Iniciar Frontend
```bash
npm run dev # Desarrollo
npm run build # Construir para produccion
npm run dev # Puerto 5172
```
---
## Base de Datos
## Scripts Disponibles
### Configuracion
- **Motor**: PostgreSQL 15
- **Base de datos**: haciendasanangel
- **Usuario**: oposgres
### Backend (`backend/hotel_hacienda/`)
| Script | Comando | Descripción |
|--------|---------|-------------|
| `start` | `node src/server.js` | Producción |
| `dev` | `nodemon src/server.js` | Desarrollo con hot reload |
### Scripts SQL
Los scripts de la base de datos se encuentran en `backend/hotel_hacienda/scripts bd/funcionesparaproduccion/`. Incluyen:
- Funciones para empleados y contratos
- Funciones para gastos e ingresos
- Funciones para inventario
- Funciones para reporteria
- Funciones de autenticacion
### 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 |
---
## Variables de Entorno
## Documentación Adicional
### Backend (.env)
| Variable | Descripcion |
|----------|-------------|
| PORT | Puerto del servidor (default: 4000) |
| DB_HOST | Host de PostgreSQL |
| DB_PORT | Puerto de PostgreSQL (default: 5432) |
| DB_USER | Usuario de PostgreSQL |
| DB_PASSWORD | Contrasena de PostgreSQL |
| DB_NAME | Nombre de la base de datos |
| EMAIL_HOST | Servidor SMTP |
| EMAIL_PORT | Puerto SMTP |
| EMAIL_USER | Usuario SMTP |
| EMAIL_PASS | Contrasena/API Key SMTP |
| URL_CORS | URL permitida para CORS |
| BANXICO_TOKEN | Token API de Banxico |
| STRIPE_SECRET_KEY | Llave secreta de Stripe |
### Frontend (.env)
| Variable | Descripcion |
|----------|-------------|
| VITE_API_BASE_URL | URL base del API backend |
- [`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.
---
## Despliegue en Produccion
## Integraciones Externas
### Con Docker Compose
1. Asegurarse de tener configurado el archivo `.env` con valores de produccion
2. Modificar `docker-compose.yml` si es necesario:
- Cambiar `URL_CORS` a tu dominio de produccion
- Configurar volumenes persistentes para la base de datos
3. Iniciar los servicios:
```bash
docker-compose up -d
```
### Notas de Seguridad
- Cambiar las contrasenas por defecto
- Usar HTTPS en produccion (configurar con nginx o similar)
- Respaldar la base de datos regularmente
- No exponer el puerto de PostgreSQL al exterior
| 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` |
---
## Mantenimiento
## Seguridad y Autenticación
### Respaldo de Base de Datos
```bash
docker exec postgres_db pg_dump -U oposgres haciendasanangel > backup_$(date +%Y%m%d).sql
```
### Ver logs
```bash
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
```
### Reiniciar servicios
```bash
docker-compose restart
```
> ⚠️ **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
---
## Licencia
## Créditos
Proyecto privado - Hacienda San Angel
Desarrollado para **Consultoría AS** — Hacienda San Angel.
---
## Contacto
Para soporte tecnico, contactar al equipo de desarrollo.
> **Mantenimiento:** Si realizas cambios significativos, actualiza tanto el código como la documentación correspondiente para mantener la integridad del sistema.