VUCEM Scanner

Aplicación web para digitalizar, procesar y estandarizar documentos conforme a los requisitos técnicos de la Ventanilla Única de Comercio Exterior Mexicana (VUCEM).

Permite convertir imágenes y archivos PDF al estándar oficial: formato PDF, tamaño A4, resolución aproximada de 300 DPI, modo de color en escala de grises (8 bits) y tamaño de archivo inferior a 3 MB, incorporando además validación de legibilidad y descarte de hojas en blanco mediante Google Gemini.

---

Características

• Estandarización automática a A4 (300 DPI): Redimensiona y ajusta las páginas a un lienzo de 2480 x 3508 px manteniendo la relación de aspecto y centrando el contenido.
• Conversión a escala de grises: Aplica filtro de desaturación y realce de contraste (1.2x) sobre canvas HTML5 para optimizar nitidez en sellos, firmas y textos.
• Soporte de entrada flexible: Acepta tanto imágenes (JPEG, PNG, WebP) como archivos PDF multipágina (extraídos y rasterizados individualmente en el cliente).
• Control de peso estricto (< 3 MB): Calcula en tiempo real el tamaño estimado del documento final y bloquea la generación si se sobrepasa el límite establecido por VUCEM.
• Auditoría de calidad con IA (Gemini 2.5 Flash): Analiza cada página para alertar si el documento está en blanco (causal inmediata de rechazo en VUCEM), si el texto es legible o si existen sombras/obstrucciones.
• Generación directa en el navegador: Ensambla el PDF final en memoria del cliente usando compresión sin requerir almacenamiento intermedio en servidor.

---

Requisitos Previos

• Node.js: Versión 18.x o superior instalada en el sistema.
• pnpm: Gestor de paquetes oficial recomendado para este proyecto (corepack enable pnpm o npm install -g pnpm).
• Google Gemini API Key: Requerida únicamente para la función de validación de calidad con IA. El procesamiento de imágenes y generación de PDF funciona sin API key.

---

Instalación y Configuración

1. Clonar o descargar el repositorio:

   git clone <URL_DEL_REPOSITORIO>
   cd 10.vucem-scanner

2. Instalar dependencias:

   pnpm install

3. Configurar variables de entorno: Crea o edita el archivo .env.local en la raíz del proyecto y define tu clave de Google Gemini:

   GEMINI_API_KEY=tu_api_key_de_gemini

---

Ejecución

Opción 1: Un solo clic (Recomendado en Windows)

Haz doble clic sobre el archivo iniciar.bat en la carpeta del proyecto.

• Verifica automáticamente Node.js y pnpm.
• Si no existen las dependencias, las instala automáticamente con pnpm install.
• Abre el navegador en http://localhost:3000 e inicia el servidor.

Opción 2: Desde la Terminal

Inicia el servidor local de Vite:

pnpm dev

La aplicación quedará accesible en:

• http://localhost:3000 (o http://<tu-ip-local>:3000)

Compilación para Producción

Genera el paquete optimizado en la carpeta dist/:

pnpm build

Vista Previa de Producción

Para previsualizar la compilación de producción localmente:

pnpm preview

---

Flujo de Trabajo

1. Cargar o capturar páginas:
   • Haz clic en Escanear / Subir PDF para seleccionar imágenes o un PDF completo.
   • Si seleccionas un PDF, cada página se extraerá y procesará de manera independiente.
2. Revisar métricas técnicas:
   • En la tarjeta de cada página se muestran sus dimensiones normalizadas (2480x3508 px), densidad estimada (~300 DPI), modo de color y peso estimado en KB.
3. Verificar calidad con IA (Opcional):
   • Pulsa Verificar Calidad con IA (Gemini) en cualquier página para comprobar si la hoja está en blanco o presenta problemas de legibilidad.
4. Generar y descargar el PDF:
   • Observa la barra inferior con el peso total acumulado. Si el total es menor a 3 MB, el botón Generar PDF VUCEM estará habilitado.
   • Pulsa el botón para compilar y descargar el archivo final con nomenclatura vucem-scan-<timestamp>.pdf.

---

Reglas Técnicas de VUCEM Implementadas

Parámetro	Requisito VUCEM	Implementación en la App
Formato	PDF	Generado vía jsPDF con compresión FAST
Resolución	300 DPI	Canvas estandarizado a 2480 × 3508 px (A4 a 300 DPI)
Color	Escala de grises (8 bits)	Filtro canvas grayscale(100%) contrast(1.2)
Tamaño máximo	Menor a 3 MB (3,145,728 bytes)	Validación acumulada antes de compilar el PDF
Contenido	Sin hojas en blanco, legible	Inspección con Gemini 2.5 Flash y schema JSON forzado

---

Estructura del Proyecto

10.vucem-scanner-pro/
├── components/
│   └── Scanner.tsx           # Componente principal de interfaz y lista de páginas
├── services/
│   ├── geminiService.ts      # Cliente SDK @google/genai y análisis de legibilidad
│   └── pdfService.ts         # Rasterizado, normalización a canvas y generación jsPDF
├── App.tsx                   # Estado global, validación de presupuesto (<3MB) y vistas
├── types.ts                  # Interfaces de datos (ScannedPage, AppStatus)
├── vite.config.ts            # Configuración del servidor Vite y variables de entorno
├── index.html                # Plantilla base con importmap, PDF.js y jsPDF
├── package.json              # Dependencias y scripts del proyecto
├── iniciar.bat               # Lanzador de 1 solo clic para Windows (pnpm)
└── README-TECHNICAL.md       # Documentación de arquitectura y diseño técnico profundo

---

Autor: Brenda
Hecho por: NerdSquad