docs: añade documentación completa del proyecto

- README.md: descripción general, stack, instalación rápida - docs/API.md: referencia completa de API REST y WebSocket - docs/ARCHITECTURE.md: arquitectura del sistema con diagramas - docs/INSTALLATION.md: guía detallada de instalación - backend/.env.example: plantilla de configuración Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 23:50:34 +00:00
parent ab201e113a
commit 6248037b47
5 changed files with 1724 additions and 0 deletions
--- a/docs/INSTALLATION.md
+++ b/docs/INSTALLATION.md
@@ -0,0 +1,469 @@
+# Guía de Instalación - Trivy
+
+## Requisitos Previos
+
+### Software Requerido
+
+| Software | Versión Mínima | Notas |
+|----------|----------------|-------|
+| Python | 3.11+ | Con pip |
+| Node.js | 18+ | Con npm |
+| PostgreSQL | 15+ | O Docker |
+| Redis | 7+ | O Docker |
+| Git | 2.0+ | Para clonar |
+
+### API Keys
+
+- **Anthropic Claude API** - Obtener en https://console.anthropic.com
+
+## Opción 1: Instalación con Docker (Recomendado)
+
+### 1. Clonar repositorio
+
+```bash
+git clone https://gitea.local/frank/Trivy.git
+cd Trivy
+```
+
+### 2. Configurar variables de entorno
+
+```bash
+# Backend
+cp backend/.env.example backend/.env
+
+# Editar backend/.env:
+DATABASE_URL=postgresql+asyncpg://trivy:trivy@db:5432/trivy
+REDIS_URL=redis://redis:6379
+ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE
+
+# Frontend
+cp frontend/.env.example frontend/.env
+
+# Editar frontend/.env:
+VITE_API_URL=http://localhost:8000
+VITE_WS_URL=http://localhost:8000
+```
+
+### 3. Iniciar con Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+Esto iniciará:
+- PostgreSQL en puerto 5432
+- Redis en puerto 6379
+- Backend en puerto 8000
+- Frontend en puerto 3000
+
+### 4. Ejecutar migraciones
+
+```bash
+docker-compose exec backend alembic upgrade head
+```
+
+### 5. Crear datos iniciales
+
+```bash
+docker-compose exec backend python scripts/seed_data.py
+```
+
+### 6. Acceder
+
+- Frontend: http://localhost:3000
+- Admin: http://localhost:3000/admin (admin/admin123)
+- API: http://localhost:8000/docs
+
+---
+
+## Opción 2: Instalación Manual
+
+### 1. Clonar repositorio
+
+```bash
+git clone https://gitea.local/frank/Trivy.git
+cd Trivy
+```
+
+### 2. Configurar PostgreSQL
+
+```bash
+# Crear usuario y base de datos
+sudo -u postgres psql
+
+CREATE USER trivy WITH PASSWORD 'trivy';
+CREATE DATABASE trivy OWNER trivy;
+GRANT ALL PRIVILEGES ON DATABASE trivy TO trivy;
+\q
+```
+
+### 3. Configurar Redis
+
+```bash
+# Ubuntu/Debian
+sudo apt install redis-server
+sudo systemctl start redis
+sudo systemctl enable redis
+
+# Verificar
+redis-cli ping
+# Respuesta: PONG
+```
+
+### 4. Configurar Backend
+
+```bash
+cd backend
+
+# Crear entorno virtual
+python3 -m venv venv
+source venv/bin/activate
+
+# Instalar dependencias
+pip install -r requirements.txt
+
+# Configurar variables de entorno
+cp .env.example .env
+```
+
+Editar `backend/.env`:
+
+```env
+# Base de datos
+DATABASE_URL=postgresql+asyncpg://trivy:trivy@localhost:5432/trivy
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Anthropic API
+ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE
+
+# Configuración del juego
+STEAL_PENALTY_MULTIPLIER=0.5
+STEAL_TIME_MULTIPLIER=0.5
+ROOM_TTL_HOURS=3
+
+# CORS (separar con comas)
+CORS_ORIGINS=http://localhost:3000,http://localhost:5173
+```
+
+### 5. Ejecutar migraciones
+
+```bash
+cd backend
+source venv/bin/activate
+alembic upgrade head
+```
+
+### 6. Crear usuario admin
+
+```bash
+python -c "
+import asyncio
+from app.models.base import get_async_session
+from app.models.admin import Admin
+
+async def create_admin():
+    AsyncSession = get_async_session()
+    async with AsyncSession() as db:
+        admin = Admin(username='admin')
+        admin.set_password('admin123')
+        db.add(admin)
+        await db.commit()
+        print('Admin creado: admin/admin123')
+
+asyncio.run(create_admin())
+"
+```
+
+### 7. Crear categorías
+
+```bash
+python -c "
+import asyncio
+from app.models.base import get_async_session
+from app.models.category import Category
+
+categories = [
+    ('Nintendo', '🍄', '#E60012'),
+    ('Xbox', '🎮', '#107C10'),
+    ('PlayStation', '🎯', '#003791'),
+    ('Anime', '⛩️', '#FF6B9D'),
+    ('Música', '🎵', '#1DB954'),
+    ('Películas', '🎬', '#F5C518'),
+    ('Libros', '📚', '#8B4513'),
+    ('Historia', '🏛️', '#6B5B95'),
+]
+
+async def create_categories():
+    AsyncSession = get_async_session()
+    async with AsyncSession() as db:
+        for name, icon, color in categories:
+            cat = Category(name=name, icon=icon, color=color)
+            db.add(cat)
+        await db.commit()
+        print(f'{len(categories)} categorías creadas')
+
+asyncio.run(create_categories())
+"
+```
+
+### 8. Crear preguntas (ejecutar script completo)
+
+```bash
+python scripts/seed_questions.py
+```
+
+### 9. Configurar Frontend
+
+```bash
+cd frontend
+
+# Instalar dependencias
+npm install
+
+# Configurar variables de entorno
+cp .env.example .env
+```
+
+Editar `frontend/.env`:
+
+```env
+VITE_API_URL=http://localhost:8000
+VITE_WS_URL=http://localhost:8000
+```
+
+### 10. Iniciar servicios
+
+**Terminal 1 - Backend:**
+```bash
+cd backend
+source venv/bin/activate
+uvicorn app.main:socket_app --host 0.0.0.0 --port 8000 --reload
+```
+
+**Terminal 2 - Frontend:**
+```bash
+cd frontend
+npm run dev -- --host
+```
+
+### 11. Acceder
+
+- Frontend: http://localhost:3000
+- Admin: http://localhost:3000/admin
+- API Docs: http://localhost:8000/docs
+
+---
+
+## Configuración para Red Local
+
+Para permitir acceso desde otros dispositivos en la red:
+
+### 1. Obtener IP local
+
+```bash
+ip addr show | grep "inet " | grep -v 127.0.0.1
+# Ejemplo: 192.168.1.100
+```
+
+### 2. Actualizar configuración
+
+**backend/.env:**
+```env
+CORS_ORIGINS=http://localhost:3000,http://192.168.1.100:3000
+```
+
+**frontend/.env:**
+```env
+VITE_API_URL=http://192.168.1.100:8000
+VITE_WS_URL=http://192.168.1.100:8000
+```
+
+### 3. Iniciar con host 0.0.0.0
+
+```bash
+# Backend
+uvicorn app.main:socket_app --host 0.0.0.0 --port 8000
+
+# Frontend
+npm run dev -- --host
+```
+
+### 4. Acceder desde otros dispositivos
+
+- http://192.168.1.100:3000
+
+---
+
+## Producción
+
+### Backend con Gunicorn
+
+```bash
+pip install gunicorn
+
+gunicorn app.main:socket_app \
+  -w 4 \
+  -k uvicorn.workers.UvicornWorker \
+  -b 0.0.0.0:8000 \
+  --access-logfile - \
+  --error-logfile -
+```
+
+### Frontend Build
+
+```bash
+cd frontend
+npm run build
+
+# Servir con cualquier servidor estático
+# Ejemplo con serve:
+npm install -g serve
+serve -s dist -l 3000
+```
+
+### Nginx como Reverse Proxy
+
+```nginx
+# /etc/nginx/sites-available/trivy
+server {
+    listen 80;
+    server_name trivy.example.com;
+
+    # Frontend
+    location / {
+        root /var/www/trivy/frontend/dist;
+        try_files $uri $uri/ /index.html;
+    }
+
+    # API
+    location /api {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+
+    # WebSocket
+    location /socket.io {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+    }
+}
+```
+
+### Systemd Service
+
+```ini
+# /etc/systemd/system/trivy-backend.service
+[Unit]
+Description=Trivy Backend
+After=network.target postgresql.service redis.service
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/var/www/trivy/backend
+Environment=PATH=/var/www/trivy/backend/venv/bin
+ExecStart=/var/www/trivy/backend/venv/bin/gunicorn app.main:socket_app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable trivy-backend
+sudo systemctl start trivy-backend
+```
+
+---
+
+## Solución de Problemas
+
+### Error: "Could not connect to Redis"
+
+```bash
+# Verificar Redis
+redis-cli ping
+
+# Si no responde, iniciar Redis
+sudo systemctl start redis
+```
+
+### Error: "Database connection failed"
+
+```bash
+# Verificar PostgreSQL
+sudo systemctl status postgresql
+
+# Verificar credenciales
+psql -U trivy -d trivy -h localhost
+```
+
+### Error: "CORS blocked"
+
+Verificar que la URL del frontend esté en `CORS_ORIGINS` del backend.
+
+### WebSocket no conecta
+
+1. Verificar que `VITE_WS_URL` use `http://` (no `ws://`)
+2. Verificar que el backend use `socket_app` (no `app`)
+3. Verificar firewall/puertos
+
+### Preguntas no cargan
+
+```bash
+# Verificar preguntas en BD
+cd backend
+source venv/bin/activate
+python -c "
+import asyncio
+from sqlalchemy import select
+from app.models.base import get_async_session
+from app.models.question import Question
+from datetime import date
+
+async def check():
+    AsyncSession = get_async_session()
+    async with AsyncSession() as db:
+        result = await db.execute(
+            select(Question).where(Question.date_active == date.today())
+        )
+        qs = result.scalars().all()
+        print(f'Preguntas para hoy: {len(qs)}')
+
+asyncio.run(check())
+"
+```
+
+### Sonidos no funcionan
+
+Los sonidos requieren archivos MP3 en `/public/sounds/{tema}/`. Si no existen, el sistema usa fallbacks generados por Web Audio API (tonos simples).
+
+---
+
+## Actualizaciones
+
+```bash
+cd Trivy
+git pull origin main
+
+# Backend
+cd backend
+source venv/bin/activate
+pip install -r requirements.txt
+alembic upgrade head
+
+# Frontend
+cd frontend
+npm install
+npm run build
+
+# Reiniciar servicios
+sudo systemctl restart trivy-backend
+```