hotel-hacienda/docs/TROUBLESHOOTING.md

# 🔧 Solución de Problemas Comunes

## Índice
1. [Backend](#backend)
2. [Frontend](#frontend)
3. [Base de Datos](#base-de-datos)
4. [Integraciones Externas](#integraciones-externas)
5. [Producción](#producción)

---

## Backend

### Error: "Conectado a PostgreSQL" no aparece

**Causa:** Variables de entorno de DB incorrectas o PostgreSQL no está corriendo.

**Solución:**
```bash
# Verificar PostgreSQL
sudo systemctl status postgresql

# Verificar variables de entorno
cat backend/hotel_hacienda/.env | grep DB_

# Probar conexión manual
node -e "require('./backend/hotel_hacienda/src/db/connection')"
```

### Error: CORS bloquea peticiones del frontend

**Causa:** `URL_CORS` no coincide con el dominio del frontend.

**Solución:**
```bash
# En backend/.env
URL_CORS=https://hotel.consultoria-as.com
# Sin slash al final
```

### Error: "Cannot find module 'pg'"

**Causa:** Dependencias no instaladas.

**Solución:**
```bash
cd backend/hotel_hacienda
npm install
```

### Emails no se envían

**Causa:** Credenciales SMTP incorrectas o servidor bloqueando.

**Solución:**
1. Verificar variables `EMAIL_HOST`, `EMAIL_PORT`, `EMAIL_USER`, `EMAIL_PASS`
2. Para Gmail, usar "App Password", no la contraseña normal
3. Revisar logs: `pm2 logs hotel-api`

---

## Frontend

### Error: "Failed to fetch" o "Network Error"

**Causa:** `VITE_API_BASE_URL` apunta a localhost en producción.

**Solución:**
```bash
# Verificar .env del frontend
cat frontend/Frontend-Hotel/.env

# Debe ser:
VITE_API_BASE_URL=https://hotel.consultoria-as.com/api
```

### Página en blanco después del build

**Causa:** Rutas de React Router no configuradas en Nginx.

**Solución:** Asegurar que Nginx tenga:
```nginx
location / {
    try_files $uri $uri/ /index.html;
}
```

### Error: `useAuth` is not exported

**Causa:** Bug conocido. `AuthContext.jsx` no exporta `useAuth`.

**Solución temporal:**
```jsx
// En vez de:
import { useAuth } from "../context/AuthContext";

// Usar:
import { AuthContext } from "../context/AuthContext";
const { user, login, logout } = useContext(AuthContext);
```

### Tailwind no aplica estilos

**Causa:** Tailwind v4 usa configuración diferente o `index.css` no tiene las directivas.

**Solución:** Verificar que `src/index.css` contenga:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

---

## Base de Datos

### Error: "function newexpensev2 does not exist"

**Causa:** Backup no restaurado completamente o función no migrada.

**Solución:**
```bash
# Restaurar backup completo
sudo -u postgres psql -d hotel_hacienda -f backupcondatos22122025.sql

# Verificar funciones existentes
sudo -u postgres psql -d hotel_hacienda -c "\df public.*"
```

### Error: "duplicate key value violates unique constraint"

**Causa:** Algunas funciones SQL no son idempotentes y se llaman dos veces.

**Solución:** Revisar la función SQL correspondiente. Agregar `IF EXISTS` o `ON CONFLICT`.

### Stock duplicado en inventario

**Causa:** Dos procesos tocan el mismo stock (ver análisis técnico en `DOCUMENTACION_TECNICA.md`, sección "Problema de duplicación en inventario").

**Solución:** Decidir si el stock se actualiza en `purchaseentry()` o en `setpaymentstatusv2()`, no en ambos.

---

## Integraciones Externas

### Stripe no devuelve datos

**Causa:** `STRIPE_SECRET_KEY` incorrecta o modo live/test mezclado.

**Solución:**
```bash
# Verificar que la key comience con sk_test_ o sk_live_
cat backend/.env | grep STRIPE
```

### API de Facturas devuelve error

**Causa:** Token expirado, RFC incorrecto, o fechas fuera de rango.

**Solución:**
1. Verificar `FACTURAS_API_TOKEN` y `FACTURAS_ISSUER_RFC`
2. Verificar que el rango de fechas no exceda el límite de la API
3. Revisar logs del backend

### Banxico retorna error

**Causa:** Token inválido o serie incorrecta.

**Solución:**
1. Verificar `BANXICO_TOKEN`
2. La serie usada es `SF43718` (Fix de USD/MXN)
3. Verificar que el token no haya expirado

---

## Producción

### PM2 no inicia al reiniciar servidor

**Solución:**
```bash
pm2 startup
pm2 save
```

### Nginx error 502 Bad Gateway

**Causa:** Backend no está corriendo o escucha en puerto diferente.

**Solución:**
```bash
# Verificar proceso
pm2 list

# Verificar puerto
sudo ss -tlnp | grep 3000

# Reiniciar
pm2 restart hotel-api
sudo systemctl restart nginx
```

### Certificado SSL expirado

**Solución:**
```bash
sudo certbot renew --dry-run
sudo certbot renew
sudo systemctl reload nginx
```

---

> Para problemas no listados aquí, revisar los logs detallados:
> - Backend: `pm2 logs hotel-api`
> - Nginx: `sudo tail -f /var/log/nginx/hotel-error.log`
> - PostgreSQL: `sudo tail -f /var/log/postgresql/postgresql-*.log`