# Guía de Instalación y Despliegue - Sistema de Gestión de Facturas 606

## 📋 Tabla de Contenidos

1. [Requisitos del Sistema](#requisitos-del-sistema)
2. [Instalación en Desarrollo](#instalación-en-desarrollo)
3. [Configuración de Base de Datos](#configuración-de-base-de-datos)
4. [Configuración de Variables de Entorno](#configuración-de-variables-de-entorno)
5. [Instalación de Dependencias](#instalación-de-dependencias)
6. [Ejecución en Desarrollo](#ejecución-en-desarrollo)
7. [Despliegue en Producción](#despliegue-en-producción)
8. [Configuración de SSL](#configuración-de-ssl)
9. [Monitoreo y Mantenimiento](#monitoreo-y-mantenimiento)
10. [Solución de Problemas](#solución-de-problemas)

---

## Requisitos del Sistema

### Requisitos Mínimos

| Componente | Desarrollo | Producción |
|------------|------------|------------|
| **CPU** | 2 cores | 4 cores |
| **RAM** | 4 GB | 8 GB |
| **Almacenamiento** | 10 GB | 50 GB SSD |
| **Sistema Operativo** | Windows 10/macOS/Linux | Ubuntu 20.04+ / CentOS 8+ |
| **Python** | 3.11+ | 3.11+ |
| **Node.js** | 18+ | 18+ |
| **Base de Datos** | SQLite | PostgreSQL 15+ |

### Software Requerido

#### Para Desarrollo
- **Python 3.11+** con pip
- **Node.js 18+** con npm/pnpm
- **Git** para control de versiones
- **Editor de código** (VS Code recomendado)

#### Para Producción
- **Docker** y Docker Compose
- **Nginx** como proxy reverso
- **PostgreSQL** como base de datos
- **Redis** para caché y rate limiting
- **Certificados SSL** para HTTPS

---

## Instalación en Desarrollo

### 1. Clonar el Repositorio

```bash
# Clonar el proyecto
git clone https://github.com/tu-organizacion/sistema-facturas-606.git
cd sistema-facturas-606

# Estructura esperada
sistema-facturas-606/
├── invoice-606-backend/     # API Flask
├── invoice-606-web/         # Aplicación web React
├── invoice-606-mobile/      # Aplicación móvil React
├── docs/                    # Documentación
└── docker-compose.yml       # Configuración Docker
```

### 2. Configurar Backend (Flask)

```bash
# Navegar al directorio del backend
cd invoice-606-backend

# Crear entorno virtual
python -m venv venv

# Activar entorno virtual
# En Windows:
venv\Scripts\activate
# En macOS/Linux:
source venv/bin/activate

# Actualizar pip
pip install --upgrade pip

# Instalar dependencias
pip install -r requirements.txt
```

### 3. Configurar Frontend Web

```bash
# Navegar al directorio del frontend web
cd ../invoice-606-web

# Instalar dependencias
npm install
# O usando pnpm (recomendado):
pnpm install
```

### 4. Configurar Frontend Móvil

```bash
# Navegar al directorio del frontend móvil
cd ../invoice-606-mobile

# Instalar dependencias
npm install
# O usando pnpm:
pnpm install
```

---

## Configuración de Base de Datos

### Desarrollo (SQLite)

SQLite se configura automáticamente. La base de datos se crea en:
```
invoice-606-backend/src/database/app.db
```

### Producción (PostgreSQL)

#### Instalación de PostgreSQL

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

**CentOS/RHEL:**
```bash
sudo dnf install postgresql postgresql-server
sudo postgresql-setup --initdb
sudo systemctl start postgresql
sudo systemctl enable postgresql
```

#### Configuración de Base de Datos

```bash
# Conectar como usuario postgres
sudo -u postgres psql

# Crear base de datos y usuario
CREATE DATABASE facturas606_prod;
CREATE USER facturas606_user WITH PASSWORD 'tu_password_seguro';
GRANT ALL PRIVILEGES ON DATABASE facturas606_prod TO facturas606_user;

# Salir de psql
\q
```

#### Configurar Acceso Remoto (si es necesario)

```bash
# Editar postgresql.conf
sudo nano /etc/postgresql/15/main/postgresql.conf

# Cambiar:
listen_addresses = '*'

# Editar pg_hba.conf
sudo nano /etc/postgresql/15/main/pg_hba.conf

# Agregar línea para acceso remoto:
host    facturas606_prod    facturas606_user    0.0.0.0/0    md5

# Reiniciar PostgreSQL
sudo systemctl restart postgresql
```

---

## Configuración de Variables de Entorno

### Backend (.env)

Crear archivo `.env` en `invoice-606-backend/`:

```bash
# Configuración de Flask
FLASK_ENV=development
SECRET_KEY=tu-clave-secreta-muy-segura-aqui
DEBUG=True

# Base de datos
# Para desarrollo (SQLite):
DATABASE_URL=sqlite:///database/app.db
# Para producción (PostgreSQL):
# DATABASE_URL=postgresql://facturas606_user:password@localhost/facturas606_prod

# OpenAI API
OPENAI_API_KEY=tu-clave-openai-aqui
OPENAI_API_BASE=https://api.openai.com/v1

# CORS
CORS_ORIGINS=http://localhost:5173,http://localhost:5174

# Configuración de archivos
MAX_CONTENT_LENGTH=16777216  # 16MB
UPLOAD_FOLDER=uploads

# Redis (para producción)
REDIS_URL=redis://localhost:6379/0

# Email (para notificaciones)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=tu-email@gmail.com
MAIL_PASSWORD=tu-app-password
```

### Frontend Web (.env)

Crear archivo `.env` en `invoice-606-web/`:

```bash
# URL del API
VITE_API_URL=http://localhost:5000

# Configuración de desarrollo
VITE_APP_NAME=Sistema Facturas 606
VITE_APP_VERSION=1.0.0
```

### Frontend Móvil (.env)

Crear archivo `.env` en `invoice-606-mobile/`:

```bash
# URL del API
VITE_API_URL=http://localhost:5000

# Configuración móvil
VITE_APP_NAME=Facturas 606 Móvil
VITE_ENABLE_CAMERA=true
```

---

## Instalación de Dependencias

### Backend (Python)

```bash
cd invoice-606-backend

# Activar entorno virtual
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Instalar dependencias
pip install -r requirements.txt

# Verificar instalación
python -c "import flask, sqlalchemy, openai; print('Dependencias instaladas correctamente')"
```

### Frontend (Node.js)

```bash
# Frontend Web
cd invoice-606-web
pnpm install

# Verificar instalación
pnpm list

# Frontend Móvil
cd ../invoice-606-mobile
pnpm install

# Verificar instalación
pnpm list
```

---

## Ejecución en Desarrollo

### 1. Inicializar Base de Datos

```bash
cd invoice-606-backend
source venv/bin/activate

# Ejecutar script de inicialización
python -c "
from src.main import app, init_database
with app.app_context():
    init_database()
print('Base de datos inicializada')
"
```

### 2. Ejecutar Backend

```bash
# En el directorio invoice-606-backend
cd src
python main.py

# El servidor estará disponible en:
# http://localhost:5000
```

### 3. Ejecutar Frontend Web

```bash
# En una nueva terminal
cd invoice-606-web
pnpm dev

# La aplicación estará disponible en:
# http://localhost:5173
```

### 4. Ejecutar Frontend Móvil

```bash
# En una nueva terminal
cd invoice-606-mobile
pnpm dev --port 5174

# La aplicación estará disponible en:
# http://localhost:5174
```

### 5. Verificar Funcionamiento

Abrir navegador y verificar:

1. **Backend API**: http://localhost:5000/health
2. **Frontend Web**: http://localhost:5173
3. **Frontend Móvil**: http://localhost:5174

**Credenciales de prueba:**
- Super Admin: `admin` / `admin123`
- Contador: `contador1` / `contador123`
- Empleado: `empleado1` / `empleado123`

---

## Despliegue en Producción

### Opción 1: Despliegue con Docker

#### 1. Preparar Archivos de Configuración

**docker-compose.prod.yml:**
```yaml
version: '3.8'

services:
  backend:
    build:
      context: ./invoice-606-backend
      dockerfile: Dockerfile.prod
    environment:
      - FLASK_ENV=production
      - DATABASE_URL=postgresql://facturas606_user:${DB_PASSWORD}@db:5432/facturas606_prod
      - SECRET_KEY=${SECRET_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
    volumes:
      - uploads:/app/uploads
      - logs:/app/logs
    restart: unless-stopped

  frontend-web:
    build:
      context: ./invoice-606-web
      dockerfile: Dockerfile.prod
    environment:
      - VITE_API_URL=https://api.tudominio.com
    restart: unless-stopped

  frontend-mobile:
    build:
      context: ./invoice-606-mobile
      dockerfile: Dockerfile.prod
    environment:
      - VITE_API_URL=https://api.tudominio.com
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=facturas606_prod
      - POSTGRES_USER=facturas606_user
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
      - static_files:/var/www/static
    depends_on:
      - backend
      - frontend-web
      - frontend-mobile
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  uploads:
  logs:
  static_files:
```

#### 2. Crear Archivo de Variables de Entorno

**.env.prod:**
```bash
# Generar clave secreta segura
SECRET_KEY=$(openssl rand -base64 32)

# Configurar contraseña de base de datos
DB_PASSWORD=tu_password_muy_seguro_aqui

# OpenAI API Key
OPENAI_API_KEY=tu_clave_openai_aqui

# Dominio
DOMAIN=tudominio.com
```

#### 3. Ejecutar Despliegue

```bash
# Crear directorio de producción
mkdir facturas606-prod
cd facturas606-prod

# Copiar archivos del proyecto
cp -r /ruta/al/proyecto/* .

# Configurar variables de entorno
cp .env.example .env.prod
nano .env.prod  # Editar con valores reales

# Construir y ejecutar
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

# Verificar estado
docker-compose -f docker-compose.prod.yml ps
```

### Opción 2: Despliegue Manual

#### 1. Preparar Servidor

```bash
# Actualizar sistema
sudo apt update && sudo apt upgrade -y

# Instalar dependencias
sudo apt install -y python3.11 python3.11-venv python3-pip nodejs npm nginx postgresql redis-server

# Instalar pnpm
npm install -g pnpm

# Crear usuario para la aplicación
sudo useradd -m -s /bin/bash facturas606
sudo mkdir -p /opt/facturas606
sudo chown facturas606:facturas606 /opt/facturas606
```

#### 2. Configurar Backend

```bash
# Cambiar a usuario de aplicación
sudo su - facturas606

# Clonar proyecto
cd /opt/facturas606
git clone https://github.com/tu-org/sistema-facturas-606.git .

# Configurar backend
cd invoice-606-backend
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
nano .env  # Editar con valores de producción

# Inicializar base de datos
python -c "
from src.main import app, init_database
with app.app_context():
    init_database()
"
```

#### 3. Configurar Frontend

```bash
# Frontend Web
cd /opt/facturas606/invoice-606-web
pnpm install
pnpm build

# Frontend Móvil
cd /opt/facturas606/invoice-606-mobile
pnpm install
pnpm build
```

#### 4. Configurar Servicios Systemd

**Backend Service (/etc/systemd/system/facturas606-backend.service):**
```ini
[Unit]
Description=Facturas 606 Backend
After=network.target postgresql.service redis.service

[Service]
Type=exec
User=facturas606
Group=facturas606
WorkingDirectory=/opt/facturas606/invoice-606-backend
Environment=PATH=/opt/facturas606/invoice-606-backend/venv/bin
ExecStart=/opt/facturas606/invoice-606-backend/venv/bin/gunicorn --bind 127.0.0.1:5000 --workers 4 src.main:app
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
```

#### 5. Configurar Nginx

**/etc/nginx/sites-available/facturas606:**
```nginx
server {
    listen 80;
    server_name tudominio.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name tudominio.com;

    ssl_certificate /etc/ssl/certs/tudominio.com.crt;
    ssl_certificate_key /etc/ssl/private/tudominio.com.key;

    # Aplicación web principal
    location / {
        root /opt/facturas606/invoice-606-web/dist;
        try_files $uri $uri/ /index.html;
    }

    # API Backend
    location /api/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 16M;
    }

    # Archivos estáticos
    location /static/ {
        root /opt/facturas606;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

server {
    listen 443 ssl http2;
    server_name mobile.tudominio.com;

    ssl_certificate /etc/ssl/certs/tudominio.com.crt;
    ssl_certificate_key /etc/ssl/private/tudominio.com.key;

    # Aplicación móvil
    location / {
        root /opt/facturas606/invoice-606-mobile/dist;
        try_files $uri $uri/ /index.html;
    }
}
```

#### 6. Habilitar y Iniciar Servicios

```bash
# Habilitar servicios
sudo systemctl enable facturas606-backend
sudo systemctl enable nginx
sudo systemctl enable postgresql
sudo systemctl enable redis

# Iniciar servicios
sudo systemctl start facturas606-backend
sudo systemctl start nginx

# Verificar estado
sudo systemctl status facturas606-backend
sudo systemctl status nginx

# Habilitar sitio en Nginx
sudo ln -s /etc/nginx/sites-available/facturas606 /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

---

## Configuración de SSL

### Opción 1: Let's Encrypt (Recomendado)

```bash
# Instalar Certbot
sudo apt install certbot python3-certbot-nginx

# Obtener certificado
sudo certbot --nginx -d tudominio.com -d mobile.tudominio.com

# Verificar renovación automática
sudo certbot renew --dry-run

# Configurar renovación automática
sudo crontab -e
# Agregar línea:
0 12 * * * /usr/bin/certbot renew --quiet
```

### Opción 2: Certificado Personalizado

```bash
# Crear directorio para certificados
sudo mkdir -p /etc/ssl/private
sudo mkdir -p /etc/ssl/certs

# Copiar certificados
sudo cp tudominio.com.crt /etc/ssl/certs/
sudo cp tudominio.com.key /etc/ssl/private/

# Configurar permisos
sudo chmod 644 /etc/ssl/certs/tudominio.com.crt
sudo chmod 600 /etc/ssl/private/tudominio.com.key
```

---

## Monitoreo y Mantenimiento

### 1. Configurar Logs

```bash
# Crear directorio de logs
sudo mkdir -p /var/log/facturas606
sudo chown facturas606:facturas606 /var/log/facturas606

# Configurar logrotate
sudo nano /etc/logrotate.d/facturas606
```

**/etc/logrotate.d/facturas606:**
```
/var/log/facturas606/*.log {
    daily
    missingok
    rotate 52
    compress
    delaycompress
    notifempty
    create 644 facturas606 facturas606
    postrotate
        systemctl reload facturas606-backend
    endscript
}
```

### 2. Configurar Monitoreo

**Script de monitoreo (/opt/facturas606/scripts/health_check.sh):**
```bash
#!/bin/bash

# Verificar servicios
services=("facturas606-backend" "nginx" "postgresql" "redis")

for service in "${services[@]}"; do
    if ! systemctl is-active --quiet $service; then
        echo "$(date): $service is down" >> /var/log/facturas606/health.log
        systemctl restart $service
    fi
done

# Verificar espacio en disco
disk_usage=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $disk_usage -gt 80 ]; then
    echo "$(date): Disk usage is ${disk_usage}%" >> /var/log/facturas606/health.log
fi

# Verificar conectividad de base de datos
if ! sudo -u postgres psql -d facturas606_prod -c "SELECT 1;" > /dev/null 2>&1; then
    echo "$(date): Database connection failed" >> /var/log/facturas606/health.log
fi
```

**Configurar cron para monitoreo:**
```bash
sudo crontab -e
# Agregar línea:
*/5 * * * * /opt/facturas606/scripts/health_check.sh
```

### 3. Backup Automático

**Script de backup (/opt/facturas606/scripts/backup.sh):**
```bash
#!/bin/bash

BACKUP_DIR="/opt/backups/facturas606"
DATE=$(date +%Y%m%d_%H%M%S)

# Crear directorio de backup
mkdir -p $BACKUP_DIR

# Backup de base de datos
sudo -u postgres pg_dump facturas606_prod > $BACKUP_DIR/db_backup_$DATE.sql

# Backup de archivos subidos
tar -czf $BACKUP_DIR/uploads_backup_$DATE.tar.gz /opt/facturas606/uploads/

# Limpiar backups antiguos (mantener 30 días)
find $BACKUP_DIR -name "*.sql" -mtime +30 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +30 -delete

echo "$(date): Backup completed" >> /var/log/facturas606/backup.log
```

**Configurar backup diario:**
```bash
sudo crontab -e
# Agregar línea:
0 2 * * * /opt/facturas606/scripts/backup.sh
```

---

## Solución de Problemas

### Problemas Comunes

#### 1. Error de Conexión a Base de Datos

**Síntomas:**
- Error 500 en la aplicación
- Logs muestran "connection refused"

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

# Verificar configuración de conexión
sudo -u postgres psql -c "\l"

# Verificar variables de entorno
grep DATABASE_URL /opt/facturas606/invoice-606-backend/.env

# Reiniciar servicios
sudo systemctl restart postgresql
sudo systemctl restart facturas606-backend
```

#### 2. Error de CORS

**Síntomas:**
- Frontend no puede conectar al backend
- Errores de CORS en consola del navegador

**Solución:**
```bash
# Verificar configuración CORS en backend
grep CORS_ORIGINS /opt/facturas606/invoice-606-backend/.env

# Verificar URL del API en frontend
grep VITE_API_URL /opt/facturas606/invoice-606-web/.env

# Reiniciar backend
sudo systemctl restart facturas606-backend
```

#### 3. Error de OCR

**Síntomas:**
- Falla al procesar imágenes
- Error de API key de OpenAI

**Solución:**
```bash
# Verificar API key
grep OPENAI_API_KEY /opt/facturas606/invoice-606-backend/.env

# Verificar conectividad
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

# Verificar logs
tail -f /var/log/facturas606/app.log | grep OCR
```

#### 4. Problemas de Rendimiento

**Síntomas:**
- Aplicación lenta
- Timeouts frecuentes

**Diagnóstico:**
```bash
# Verificar uso de recursos
htop
df -h
free -h

# Verificar logs de Nginx
tail -f /var/log/nginx/error.log

# Verificar conexiones de base de datos
sudo -u postgres psql -d facturas606_prod -c "SELECT * FROM pg_stat_activity;"
```

**Optimizaciones:**
```bash
# Aumentar workers de Gunicorn
sudo nano /etc/systemd/system/facturas606-backend.service
# Cambiar --workers 4 por --workers 8

# Configurar caché en Nginx
sudo nano /etc/nginx/sites-available/facturas606
# Agregar configuración de caché

# Reiniciar servicios
sudo systemctl daemon-reload
sudo systemctl restart facturas606-backend
sudo systemctl reload nginx
```

### Comandos Útiles de Diagnóstico

```bash
# Verificar estado de todos los servicios
sudo systemctl status facturas606-backend nginx postgresql redis

# Ver logs en tiempo real
sudo journalctl -u facturas606-backend -f

# Verificar conectividad
curl -I http://localhost:5000/health
curl -I https://tudominio.com

# Verificar certificados SSL
openssl s_client -connect tudominio.com:443 -servername tudominio.com

# Verificar configuración de Nginx
sudo nginx -t

# Verificar espacio en disco
df -h
du -sh /opt/facturas606/*

# Verificar procesos
ps aux | grep -E "(gunicorn|nginx|postgres|redis)"
```

### Contacto de Soporte

Para problemas no resueltos con esta guía:

- **Email**: soporte@facturas606.com
- **Documentación**: https://docs.facturas606.com
- **Issues**: https://github.com/tu-org/sistema-facturas-606/issues

---

**Versión de la Guía**: 1.0  
**Fecha de Actualización**: 27 de Agosto, 2024  
**Sistema**: Gestión de Facturas 606 v1.0