Saltar a contenido

RF05 Unificación de código de decodificación con retrocompatibilidad para Smartv2

Entendimiento

Integrar los procesos de decodificación de datos de venta en un único código con retrocompatibilidad que permita alimentar Smart v2 para todos los casos que pasen por la plataforma Yoda.

De acuerdo con la descripción anterior, este requisito se limita a la extracción de la lógica de transformación, adelgazamiento del programa Dataflow e integración de la nueva librería. Se realizarán los ajustes necesarios para sustituir su lógica objeto relacional (basada en objetos TableRow) al mapeo JSON relacional.

Situación Actual

La lógica de negocio fundamental — el algoritmo que interpreta, limpia y transforma los mensajes crudos (raw) del PoS y eCommerce — está hardcoded y fuertemente acoplada dentro del pipeline de Dataflow en Google Cloud.

Esta configuración monolítica presenta dos riesgos severos:

Violación de la Independencia Operativa (SOI → SOR)

Aunque la arquitectura de referencia prohíbe que el Sistema Operacional (Smart v2) dependa de la nube analítica, existe una dispensa técnica temporal hasta junio de 2026. Las tiendas operan consumiendo datos mediante Reverse ETL desde la capa Bronze de BigQuery. La lógica encerrada en Dataflow no solo alimenta informes, sino que sustenta la operativa diaria de las tiendas.

Imposibilidad de Reutilización Segura

Al ser Dataflow una "caja negra", otros procesos críticos — como la recuperación de backups (RF01) o la futura ingesta local en tiendas — no pueden replicar exactamente la misma interpretación del dato. Si se desarrollaran lógicas paralelas, se introducirían discrepancias matemáticas (redondeos, cálculo de impuestos, IDs) entre el dato recuperado y el original, corrompiendo la información en Smart v2.

Solución Técnica

Extraemos y encapsulamos el 100% de la lógica de transformación en una librería Java independiente e interoperable (Artifact/JAR), eliminando cualquier dependencia de la infraestructura de ejecución.

El nuevo flujo funciona bajo el principio de "Lógica Única, Múltiples Destinos":

  • El Artefacto ("The JAR"): Motor de transformación puro. Recibe el JSON crudo (PoS/eCom) y devuelve un JSON Enriquecido Común ("Meta-JSON"), estructurado jerárquicamente por tablas y columnas de destino, listo para persistir sin procesamiento adicional.
  • Redefinición del Dataflow (Cloud): El pipeline de Google Cloud se vacía de reglas de negocio. Su única responsabilidad: importar el JAR, ejecutar la transformación y persistir el Meta-JSON resultante en BigQuery.
  • Habilitación del Operacional (On-Premise): Smart v2 integra esta misma librería en su entorno local. Al procesar los mensajes de Pub/Sub con el mismo binario que la nube, eliminamos la dependencia del Reverse ETL y garantizamos una consistencia matemática absoluta entre el dato analítico (Google Cloud) y el operacional (Oracle Tienda). La tienda opera autónomamente incluso si la nube no está disponible.

Fuera de Alcance

Exclusiones explícitas

Gasolineras, devoluciones y Suscripciones eCom — Aunque su integración es similar a las datafeeds (devoluciones y suscripciones eCom), la recuperación y gestión de resiliencia para las transacciones de gasolineras está marcada como fuera de alcance y no formará parte del flujo de live streaming basado en Dataflow. Se gestionará de forma independiente vía ELT con Fivetran + dbt retail.

El sistema operacional no tendrá visibilidad de estas transacciones y habrá de integrarlas de forma independiente por otra vía (con o sin live streaming).

Nueva Lógica de Deduplicación (PoS) — No desarrollamos ningún algoritmo nuevo para gestionar duplicados en la ingesta. Usamos el procedimiento almacenado existente en BigQuery. Decisión técnica: N/A (No Aplica).

Eliminación del Reverse ETL (Bronze → Smart v2) — Aunque arquitectónicamente incorrecto, eliminar la dependencia del sistema operacional respecto a BigQuery queda fuera de alcance inmediato. Se gestiona como parte de otro proyecto.

Corrección de Errores en Dataflow — El servicio de recuperación (RF01) mitiga los fallos (reprocesando tickets corruptos), pero no incluye corregir el código Java del Dataflow actual que origina esos fallos (como cabeceras sin líneas).

Arquitectura

graph TB
    subgraph "ANTES (Monolito)"
        DF_OLD["Dataflow<br/>(Lógica + Infra)"] --> BQ_OLD["BigQuery"]
        BQ_OLD -->|"Reverse ETL"| SMART_OLD["Smart v2"]
    end

    subgraph "DESPUÉS (JAR Independiente)"
        RAW["JSON Crudo<br/>(PoS / eCom)"] --> JAR["Librería Java (JAR)<br/>Motor de Transformación"]
        JAR --> META["Meta-JSON"]
        META --> DF_NEW["Dataflow (Cloud)<br/>Solo persistencia"]
        META --> SMART_NEW["Smart v2 (On-Premise)<br/>Autonomía local"]
        DF_NEW --> BQ_NEW["BigQuery"]
    end