mve-micro-docs/DOCKER_OCR.md

# 🐳 Guía Rápida: OCR con Docker

## ✅ Lo que YA está incluido en Docker

Cuando usas Docker Compose, **TODO está incluido automáticamente**:
- ✅ Tesseract OCR
- ✅ Idioma español (spa)
- ✅ Poppler (conversión PDF a imagen)
- ✅ Todas las dependencias Python
- ✅ PyMuPDF y pdfplumber

**No necesitas instalar nada en tu máquina local.**

## 🚀 Uso Rápido

### 1. Configurar variables de entorno

Edita tu `.env`:
```env
# OCR ya viene habilitado por defecto
OCR_ENABLED=true
OCR_LANGUAGE=spa
OCR_DPI=300
OCR_TIMEOUT=300
```

### 2. Construir y ejecutar

```bash
# Primera vez o después de cambios en Dockerfile
docker-compose build

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f
```

### 3. Verificar que OCR funciona

```bash
# Verificar Tesseract en el contenedor API
docker exec mve-incrementables-parser tesseract --version

# Verificar idiomas instalados
docker exec mve-incrementables-parser tesseract --list-langs

# Verificar en el worker de Celery
docker exec mve-celery-worker tesseract --version
```

Deberías ver:
```
tesseract 5.x.x
...
spa
eng
osd
```

## 🧪 Probar con un PDF Escaneado

```bash
# 1. Primero obtén un token
curl -X POST http://localhost:9876/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=tu_password"

# 2. Usa el token para subir un PDF
curl -X POST http://localhost:9876/api/v1/incrementables/parse \
  -H "Authorization: Bearer TU_TOKEN_AQUI" \
  -F "file=@/ruta/al/documento.pdf"
```

## 📊 Ver logs del OCR

```bash
# Ver logs del contenedor principal
docker-compose logs -f mve-incrementables-parser

# Ver logs del worker (procesamiento asíncrono)
docker-compose logs -f celery-worker

# Buscar logs específicos de OCR
docker-compose logs | grep -i "ocr"
docker-compose logs | grep -i "tesseract"
```

## 🔧 Configuración Avanzada

### Cambiar idioma del OCR

Edita `.env`:
```env
OCR_LANGUAGE=eng  # Para inglés
# o
OCR_LANGUAGE=spa  # Para español
```

Reinicia los contenedores:
```bash
docker-compose restart
```

### Ajustar rendimiento OCR

Para **mayor velocidad** (menos calidad):
```env
OCR_DPI=200
```

Para **mayor calidad** (más lento):
```env
OCR_DPI=600
```

Reinicia:
```bash
docker-compose restart
```

### Deshabilitar OCR

Si solo quieres procesar PDFs con texto seleccionable:
```env
OCR_ENABLED=false
```

## 🐛 Solución de Problemas

### El servicio no inicia después de agregar OCR

```bash
# Reconstruir la imagen
docker-compose down
docker-compose build --no-cache
docker-compose up -d
```

### Error: "tesseract command not found"

Esto significa que la imagen no se construyó correctamente.

```bash
# Ver si Tesseract está en la imagen
docker exec mve-incrementables-parser which tesseract

# Si no está, reconstruir
docker-compose build --no-cache mve-incrementables-parser
```

### OCR muy lento

El OCR es naturalmente más lento que la extracción de texto normal. Para PDFs escaneados:
- Usa el endpoint **asíncrono** (`/parse-async`)
- El worker de Celery procesará en background
- Reduce `OCR_DPI` si no necesitas máxima calidad

### Ver qué método se usó (texto vs OCR)

El campo `extraction_method` en la respuesta te dice:
- `"pymupdf"` o `"pdfplumber"` → PDF con texto (rápido)
- `"ocr"` → PDF escaneado procesado con Tesseract (lento)

## 📝 Ejemplo de Respuesta

Cuando el sistema usa OCR automáticamente:

```json
{
  "status": "success",
  "message": "Incrementables extraídos exitosamente",
  "data": {
    "incrementables": {
      "fletes": 1591.20,
      "seguros": 0.0,
      "almacenaje": 0.0,
      "regalias": 0.0,
      "currency": "USD",
      "total": 1591.20
    },
    "document_info": {
      "filename": "documento_escaneado.pdf",
      "pages": 5,
      "file_hash": "abc123...",
      "file_size_bytes": 524288
    },
    "extraction_info": {
      "method": "ocr",  // ← Indica que se usó OCR
      "anchors_found": ["AJUSTE DE INCREMENTABLES EN:"],
      "warnings": []
    }
  }
}
```

## 🎯 Resumen

**Con Docker:**
- ✅ Todo incluido automáticamente
- ✅ Sin instalación manual
- ✅ Funciona igual en Windows, Mac, Linux
- ✅ OCR listo para usar desde el primer `docker-compose up`

**Comandos clave:**
```bash
docker-compose build          # Construir imagen
docker-compose up -d          # Iniciar servicios
docker-compose logs -f        # Ver logs
docker-compose restart        # Reiniciar después de cambios en .env
docker-compose down           # Detener todo
```

¡Eso es todo! 🎉