rckrdmrd 928eb795e6 [SIMCO-V38] feat: Actualizar a SIMCO v3.8.0 + cambios apps

- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8
- Cambios en backend y frontend

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-10 08:53:05 -06:00

6.5 KiB

Raw Permalink Blame History

type

title

provider

status

integration_type

created_at

updated_at

simco_version

INT-008: OCR de productos

Metadata

Campo	Valor
Codigo	INT-008
Proveedor	Google Cloud Vision
Tipo	Reconocimiento de imágenes
Estado	Pendiente
Multi-tenant	Si
Fecha planeada	2026-Q1
Owner	Backend Team

1. Descripcion

Integración con Google Cloud Vision API para reconocimiento óptico de caracteres (OCR) y análisis de imágenes. Permite a los changarros digitalizar facturas de proveedores, escanear códigos de barras de productos, y extraer información de tickets y documentos mediante fotografías tomadas con el celular.

Casos de uso principales:

Escaneo y extracción de datos de facturas de proveedores
Lectura de códigos de barras y QR de productos
Captura de precios de etiquetas de productos
Digitalización de tickets de compra para gastos
Reconocimiento de texto en notas y pedidos manuscritos

2. Credenciales Requeridas

Variables de Entorno

Variable	Descripcion	Tipo	Obligatorio
GOOGLE_CLOUD_PROJECT_ID	ID del proyecto en GCP	string	SI
GOOGLE_CLOUD_KEYFILE	Ruta al archivo de service account	string	SI
VISION_API_ENDPOINT	Endpoint regional (opcional)	string	NO
VISION_MAX_RESULTS	Máximo de resultados por request	number	NO

Ejemplo de .env

# Google Cloud Vision OCR
GOOGLE_CLOUD_PROJECT_ID=michangarrito-prod
GOOGLE_CLOUD_KEYFILE=/path/to/gcp-service-account.json
VISION_API_ENDPOINT=https://vision.googleapis.com
VISION_MAX_RESULTS=10

Archivo de Service Account

El service account debe tener el rol roles/cloudvision.user:

{
  "type": "service_account",
  "project_id": "michangarrito-prod",
  "private_key_id": "xxx",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "vision-api@michangarrito-prod.iam.gserviceaccount.com",
  "client_id": "123456789",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

3. Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                      MiChangarrito                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   Mobile/    │───▶│  API Server  │───▶│  VisionService   │  │
│  │   Web App    │    │              │    │                  │  │
│  │  (Cámara)    │    │              │    │  - OCR           │  │
│  └──────────────┘    └──────────────┘    │  - Barcode       │  │
│                                          │  - Document      │  │
│                                          └────────┬─────────┘  │
└────────────────────────────────────────────────────┼────────────┘
                                                     │
                                                     ▼
                                          ┌──────────────────┐
                                          │  Google Cloud    │
                                          │  Vision API      │
                                          │                  │
                                          │  - TEXT_DETECTION│
                                          │  - DOCUMENT_TEXT │
                                          │  - PRODUCT_SEARCH│
                                          └──────────────────┘

Flujo de Escaneo de Factura

Usuario toma foto de factura con la app
Imagen se sube a Cloud Storage (temporal)
VisionService envía imagen a Vision API
API retorna texto estructurado detectado
Parser extrae campos: proveedor, productos, montos
Sistema sugiere registro de compra/gasto
Usuario confirma y datos se guardan en BD

4. Endpoints

Endpoints Consumidos (Google Cloud Vision API)

Método	Endpoint	Descripción
POST	`/v1/images:annotate`	Analizar imagen (OCR, labels, etc.)
POST	`/v1/images:asyncBatchAnnotate`	Análisis asíncrono batch
POST	`/v1/files:annotate`	Analizar PDFs
GET	`/v1/operations/{name}`	Estado de operación async

Features Utilizados

Feature	Uso
`TEXT_DETECTION`	OCR básico para texto en imágenes
`DOCUMENT_TEXT_DETECTION`	OCR avanzado para documentos
`PRODUCT_SEARCH`	Búsqueda de productos por imagen
`BARCODE_DETECTION`	Detección de códigos de barras/QR

Endpoints Expuestos (MiChangarrito)

Método	Endpoint	Descripción
POST	`/api/v1/ocr/scan`	Escanear imagen genérica
POST	`/api/v1/ocr/invoice`	Escanear factura
POST	`/api/v1/ocr/barcode`	Leer código de barras
POST	`/api/v1/ocr/receipt`	Escanear ticket de compra
GET	`/api/v1/ocr/jobs/{id}`	Estado de escaneo async

5. Notas de Implementacion

Vision API cobra por imagen procesada (~$1.50 USD por 1000 imágenes)
Implementar caché de resultados para imágenes idénticas
Comprimir imágenes antes de enviar (máx 20MB, recomendado <4MB)
Usar DOCUMENT_TEXT_DETECTION para facturas (mejor precisión)
Implementar parser específico para facturas mexicanas (RFC, CFDI)
Considerar preprocesamiento de imagen (contraste, rotación)
Almacenar imágenes originales para auditoría
Manejar rate limits: 1800 requests/min por proyecto
Implementar retry con exponential backoff
Para alto volumen, considerar batch async
Validar formatos soportados: JPEG, PNG, GIF, BMP, WEBP, PDF
Extraer coordenadas de texto para highlighting en UI

6.5 KiB Raw Permalink Blame History