app-padel/docs/SETUP.md

# 🚀 Guía de Instalación - App Canchas de Pádel

Guía completa para configurar el entorno de desarrollo y producción.

## 📋 Requisitos

### Requisitos del Sistema

| Componente | Versión Mínima | Recomendado |
|------------|----------------|-------------|
| Node.js | 18.x | 20.x LTS |
| npm | 9.x | 10.x |
| PostgreSQL | 14.x | 16.x |
| Git | 2.x | Latest |

### Especificaciones de Hardware

| Entorno | CPU | RAM | Disco |
|---------|-----|-----|-------|
| Desarrollo | 2 cores | 4 GB | 20 GB SSD |
| Producción | 4+ cores | 8+ GB | 50+ GB SSD |

---

## 🛠️ Instalación Paso a Paso

### 1. Clonar el Repositorio

```bash
git clone https://github.com/tu-usuario/app-padel.git
cd app-padel
```

### 2. Instalar Dependencias del Backend

```bash
cd backend
npm install
```

### 3. Configurar Variables de Entorno

Copiar el archivo de ejemplo:

```bash
cp .env.example .env
```

Editar el archivo `.env` con tus valores:

```env
# ============================================
# Configuración de la Base de Datos
# ============================================
DATABASE_URL="postgresql://postgres:tu_password@localhost:5432/app_padel?schema=public"

# ============================================
# Configuración del Servidor
# ============================================
NODE_ENV=development
PORT=3000
API_URL=http://localhost:3000
FRONTEND_URL=http://localhost:5173

# ============================================
# Configuración de JWT
# ============================================
JWT_SECRET=tu_clave_secreta_super_segura_aleatoria_32chars
JWT_EXPIRES_IN=7d
JWT_REFRESH_SECRET=otra_clave_secreta_diferente_32chars
JWT_REFRESH_EXPIRES_IN=30d

# ============================================
# Configuración de Email (SMTP)
# ============================================
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=tu_email@gmail.com
SMTP_PASS=tu_app_password_de_gmail
EMAIL_FROM="Canchas Padel <noreply@tudominio.com>"

# ============================================
# Configuración de Rate Limiting
# ============================================
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# ============================================
# Configuración de MercadoPago (Producción)
# ============================================
MERCADOPAGO_ACCESS_TOKEN=APP_USR-0000000000000000-000000-00000000000000000000000000000000-000000000
MERCADOPAGO_PUBLIC_KEY=APP_USR-00000000-0000-0000-0000-000000000000
```

### 4. Crear Base de Datos

```bash
# Conectar a PostgreSQL
sudo -u postgres psql

# Crear base de datos
CREATE DATABASE app_padel;

# Crear usuario (opcional)
CREATE USER app_padel_user WITH PASSWORD 'tu_password_seguro';
GRANT ALL PRIVILEGES ON DATABASE app_padel TO app_padel_user;

# Salir
\q
```

### 5. Ejecutar Migraciones

```bash
# Generar cliente Prisma
npm run db:generate

# Ejecutar migraciones
npm run db:migrate
```

### 6. Seed de Datos (Opcional)

```bash
# Ejecutar seed para datos de prueba
npm run db:seed
```

Este comando creará:
- Usuario admin por defecto
- Canchas de ejemplo
- Planes de suscripción
- Logros del sistema

### 7. Iniciar Servidor en Desarrollo

```bash
npm run dev
```

El servidor estará disponible en: `http://localhost:3000`

---

## 🔧 Configuración Avanzada

### Variables de Entorno Completas

#### Base de Datos

| Variable | Descripción | Ejemplo |
|----------|-------------|---------|
| `DATABASE_URL` | URL de conexión PostgreSQL | `postgresql://user:pass@host:5432/db` |

#### Servidor

| Variable | Descripción | Default |
|----------|-------------|---------|
| `NODE_ENV` | Entorno (development/production) | `development` |
| `PORT` | Puerto del servidor | `3000` |
| `API_URL` | URL base de la API | `http://localhost:3000` |
| `FRONTEND_URL` | URL del frontend (CORS) | `http://localhost:5173` |

#### Seguridad (JWT)

| Variable | Descripción | Recomendación |
|----------|-------------|---------------|
| `JWT_SECRET` | Secreto para tokens | Mínimo 32 caracteres aleatorios |
| `JWT_EXPIRES_IN` | Duración del access token | `7d` |
| `JWT_REFRESH_SECRET` | Secreto para refresh tokens | Diferente al JWT_SECRET |
| `JWT_REFRESH_EXPIRES_IN` | Duración del refresh token | `30d` |

#### Email (SMTP)

| Variable | Descripción | Ejemplo |
|----------|-------------|---------|
| `SMTP_HOST` | Servidor SMTP | `smtp.gmail.com` |
| `SMTP_PORT` | Puerto SMTP | `587` |
| `SMTP_USER` | Usuario SMTP | `tucorreo@gmail.com` |
| `SMTP_PASS` | Contraseña SMTP | `app_password` |
| `EMAIL_FROM` | Remitente por defecto | `Canchas <noreply@tudominio.com>` |

#### Rate Limiting

| Variable | Descripción | Default |
|----------|-------------|---------|
| `RATE_LIMIT_WINDOW_MS` | Ventana en ms | `900000` (15 min) |
| `RATE_LIMIT_MAX_REQUESTS` | Máximo requests | `100` |

#### MercadoPago

| Variable | Descripción | Ejemplo |
|----------|-------------|---------|
| `MERCADOPAGO_ACCESS_TOKEN` | Token de acceso MP | `APP_USR-...` |
| `MERCADOPAGO_PUBLIC_KEY` | Clave pública MP | `APP_USR-...` |
| `MERCADOPAGO_WEBHOOK_SECRET` | Secreto para webhooks | `webhook_secret` |

---

## 🧪 Ejecución en Desarrollo

### Scripts Disponibles

```bash
# Desarrollo con hot reload
npm run dev

# Build para producción
npm run build

# Producción (requiere build previo)
npm start

# Base de datos
npm run db:generate    # Generar cliente Prisma
npm run db:migrate     # Ejecutar migraciones
npm run db:studio      # Abrir Prisma Studio
npm run db:seed        # Ejecutar seed

# Calidad de código
npm run lint           # Ejecutar ESLint
npm test              # Ejecutar tests
```

### Estructura de Archivos en Desarrollo

```
backend/
├── src/
│   ├── config/        # Configuraciones
│   ├── controllers/   # Controladores
│   ├── middleware/    # Middlewares
│   ├── routes/        # Rutas
│   ├── services/      # Lógica de negocio
│   ├── utils/         # Utilidades
│   ├── validators/    # Validaciones Zod
│   └── index.ts       # Entry point
├── prisma/
│   └── schema.prisma  # Esquema de base de datos
├── logs/              # Archivos de log
├── .env               # Variables de entorno
└── package.json
```

---

## 🚀 Ejecución en Producción

### 1. Preparar el Build

```bash
# Instalar dependencias de producción
npm ci --only=production

# Compilar TypeScript
npm run build
```

### 2. Configurar PM2

Crear archivo `ecosystem.config.js`:

```javascript
module.exports = {
  apps: [{
    name: 'app-padel-api',
    script: './dist/index.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    log_file: './logs/combined.log',
    out_file: './logs/out.log',
    error_file: './logs/error.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    merge_logs: true,
    max_memory_restart: '1G',
    restart_delay: 3000,
    max_restarts: 5,
    min_uptime: '10s'
  }]
};
```

### 3. Iniciar con PM2

```bash
# Iniciar aplicación
pm2 start ecosystem.config.js

# Guardar configuración
pm2 save

# Configurar inicio automático
pm2 startup
```

### 4. Verificar Estado

```bash
pm2 status
pm2 logs app-padel-api
```

---

## 🐳 Docker (Alternativa)

### Usar Docker Compose

```bash
# Iniciar todos los servicios
docker-compose up -d

# Ver logs
docker-compose logs -f backend

# Ejecutar migraciones
docker-compose exec backend npx prisma migrate deploy
```

### Dockerfile (Backend)

```dockerfile
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["node", "dist/index.js"]
```

---

## ✅ Verificación de Instalación

### Health Check

```bash
# Verificar API
curl http://localhost:3000/api/v1/health

# Respuesta esperada
{
  "success": true,
  "message": "API funcionando correctamente",
  "timestamp": "2026-01-31T12:00:00.000Z"
}
```

### Lista de Endpoints

```bash
# Ver todas las rutas disponibles
curl http://localhost:3000/api/v1
```

---

## 🔍 Troubleshooting

### Error: "Cannot find module"

```bash
# Reinstalar dependencias
rm -rf node_modules package-lock.json
npm install
```

### Error de conexión a base de datos

```bash
# Verificar PostgreSQL
sudo systemctl status postgresql

# Verificar conexión
psql $DATABASE_URL -c "SELECT 1"
```

### Error: "Prisma schema not found"

```bash
# Regenerar cliente
npx prisma generate
```

### Puerto 3000 en uso

```bash
# Encontrar proceso
lsof -i :3000

# O cambiar el puerto en .env
PORT=3001
```

---

## 📚 Recursos Adicionales

- [Documentación API](./API.md)
- [Guía de Deploy](./DEPLOY.md)
- [Prisma Documentation](https://www.prisma.io/docs)
- [Express.js Guide](https://expressjs.com/en/guide/routing.html)

---

*Última actualización: Enero 2026*