pedidosClientes/GUIA_INSTALACION.md

Guía de Instalación y Ejecución - Paso a Paso

Requisitos Previos

1. Python 3.8+ instalado
2. Node.js y npm instalados (para Prisma CLI)
3. PostgreSQL instalado y corriendo
4. OpenAI API Key (para OCR)

Paso 1: Instalar Dependencias Node.js

npm install

Esto instalará Prisma CLI necesario para gestionar la base de datos.

Paso 2: Instalar Dependencias Python

pip install -r requirements_prisma.txt

Paso 3: Configurar Base de Datos PostgreSQL

Opción A: PostgreSQL local

1. Crear base de datos:

CREATE DATABASE pedidos_clientes;

2. O usar el usuario por defecto postgres

Opción B: Docker (Recomendado)

docker-compose up -d db

Esto iniciará PostgreSQL en un contenedor Docker.

Paso 4: Configurar Variables de Entorno

Crear archivo .env en la raíz del proyecto:

# Base de datos
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/pedidos_clientes

# OpenAI API Key
OPENAI_API_KEY=tu-openai-api-key-aqui

# Opcional
DEBUG=True

Importante: Reemplaza postgres:postgres con tu usuario y contraseña de PostgreSQL.

Paso 5: Generar Cliente Prisma

prisma generate

Esto generará el cliente Prisma Python que se usará en la aplicación.

Paso 6: Crear Migraciones de Base de Datos

prisma migrate dev --name init

Esto creará todas las tablas en la base de datos según el schema de Prisma.

Nota: Si ya tienes datos, puedes usar prisma db push en lugar de migrate.

Paso 7: Verificar Base de Datos (Opcional)

prisma studio

Esto abrirá una interfaz web para ver y gestionar la base de datos.

Paso 8: Ejecutar Backend

En una terminal:

python run.py

O con uvicorn directamente:

uvicorn app.main:app --reload

El backend estará disponible en:

• API: http://localhost:8000
• Documentación: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Paso 9: Configurar Frontend

Editar frontend/js/config.js y verificar que la URL de la API sea correcta:

const API_CONFIG = {
    BASE_URL: 'http://localhost:8000/api',
};

Paso 10: Ejecutar Frontend

En otra terminal:

cd frontend
python -m http.server 3000

O con Node.js:

cd frontend
npx http-server -p 3000

El frontend estará disponible en:

• Aplicación: http://localhost:3000

Verificación

1. Abre http://localhost:3000 en tu navegador
2. Deberías ver el Kanban (aunque esté vacío si no hay datos)
3. Abre http://localhost:8000/docs para ver la documentación de la API
4. Prueba hacer una petición GET a http://localhost:8000/api/kanban/

Solución de Problemas

Error: "No module named 'prisma'"

pip install prisma

Error: "DATABASE_URL not found"

Verifica que el archivo .env existe y tiene la variable DATABASE_URL

Error: "Connection refused" (PostgreSQL)

• Verifica que PostgreSQL esté corriendo
• Verifica las credenciales en .env
• Verifica que el puerto 5432 esté disponible

Error: "prisma: command not found"

npm install
# O instalar Prisma globalmente:
npm install -g prisma

Error CORS en el navegador

• Verifica que el backend esté corriendo en el puerto 8000
• Verifica la URL en frontend/js/config.js
• Revisa la consola del navegador para más detalles

Frontend no carga

• Verifica que el servidor HTTP esté corriendo
• Abre la consola del navegador (F12) para ver errores
• Verifica que los archivos estén en frontend/

Comandos Útiles

# Ver logs del backend
python run.py

# Regenerar cliente Prisma (si cambias el schema)
prisma generate

# Crear nueva migración
prisma migrate dev --name nombre_migracion

# Ver estado de migraciones
prisma migrate status

# Abrir Prisma Studio (GUI para BD)
prisma studio

# Verificar sintaxis del schema
prisma validate

Estructura de Carpetas Importante

pedidosClientesAyutec/
├── .env                    # ⚠️ Crear este archivo con tus credenciales
├── app/                    # Backend FastAPI
├── frontend/               # Frontend HTML/JS
├── prisma/
│   └── schema.prisma      # Schema de base de datos
└── requirements_prisma.txt # Dependencias Python

Próximos Pasos

1. Crear datos de prueba:

   • Usa Prisma Studio para crear clientes y proveedores
   • O crea un script de seeding

2. Probar funcionalidades:

   • Subir un albarán desde el frontend
   • Crear un pedido de cliente
   • Ver el Kanban actualizarse

3. Configurar producción:

   • Cambiar CORS a dominios específicos
   • Configurar variables de entorno seguras
   • Usar Gunicorn para el backend
   • Servir frontend con Nginx

¿Necesitas Ayuda?

Si encuentras algún error, verifica:

1. Que todas las dependencias estén instaladas
2. Que PostgreSQL esté corriendo
3. Que el archivo .env esté configurado correctamente
4. Que los puertos 8000 y 3000 estén disponibles