El enfoque, de punta a punta —
para definiciones finales

Dos agencias escriben sobre la misma tienda Shopify sin coordinación: los cambios de una pisan los de la otra y no hay registro de quién cambió qué. El Mantenedor convierte ese caos en un sistema gobernado: una sola fuente de verdad del contenido, con carriles por agencia, versionado total y evidencia de cada intercambio.

Regla de oro (contrato v1.1): los sistemas, los bots y la IA proponen; las personas revisan, aprueban, publican y exportan. Nada escribe en Shopify sin decisión humana.

01Capas y cómo interactúan

Arquitectura del Mantenedor — El Mantenedor al centro: todo lo que entra o sale queda registrado en logs de sincronización.

Shopify — el canal de venta

Salida: Admin GraphQL API (productSet, upsert completo) vía outbox transaccional con reintentos y respeto del rate limit.
Entrada: webhooks products/* con firma HMAC verificada + reconciliación programada cada 6 h (los webhooks no son garantizados).
Seguridad: dedup por entrega, tienda validada, eliminaciones verificadas contra la API antes de registrarse.

Multivende — la operación de Quintec

Quintec no cambia su herramienta: sigue operando en Multivende.
Hoy (F0–F2): Multivende publica directo a Shopify como siempre; el Mantenedor solo observa y registra pisadas sobre campos gobernados.
Desde F3: sus webhooks de precio/estado entran además como borradores del carril Quintec (capacidad ya construida y testeada).
El stock va SIEMPRE directo Multivende → Shopify: nunca pasa por el Mantenedor, en ninguna fase.

Agentes IA — vía MCP v1.1

Doble gate: ability del token + rol por agencia; idempotencia obligatoria.
Pueden: leer catálogo, proponer borradores (incluye SEO/metafields), comentar, consultar estado de sync y pisadas.
No pueden: aprobar, publicar, exportar, tocar otra agencia.

Panel — donde deciden las personas

Filament con identidad belkin.cl; selector de agencia (Belkin / OQO / Quintec).
Por producto: variantes, versiones con diff, medios, comentarios, Sincronización (evidencia) y actividad.
Botón “Publicar en Shopify”: humano-only, permiso shopify.export.

02Alcance: qué gobierna y qué no

Campo	Dueño	Cómo entra	Flujo
Nombre, descripción, handle (URL), SEO, metafields, tags, medios, estructura de variantes	OQO	Panel / agentes IA (propuesta)	Editorial completo con revisión
Precio, moneda, estado de venta	Quintec	Hoy: directo a Shopify (observado) · Desde F3: webhooks de Multivende	Carril rápido (auto-propuesta, aprobación humana)
Stock / inventario	Quintec	Multivende → Shopify directo, en todas las fases	Fuera del Mantenedor (por diseño)
Conflictos, pisadas y arbitraje	Belink	Panel + informe de pisadas	Decisión: sobrescribir o absorber

Dentro del alcance

Versionado total con historial restaurable (rollback).
Gobernanza por campo con 3 modos: off / warn / enforce.
Detección de pisadas con evidencia y snapshot inmutable.
Merge de 3 vías por campo cuando dos carriles divergen.
Trazabilidad completa: quién, qué campo, cuándo, por qué vía.

Fuera del alcance (hoy)

Stock/inventario: sigue fluyendo Multivende → Shopify directo (dato operacional de alta frecuencia, no editorial).
Export de imágenes: detrás de flag (exige URLs públicas), apagado por defecto.
Pedidos, clientes, promociones: no son catálogo; no se tocan.

03Los cuatro flujos

¿Por dónde pasa cada cosa? — hoy vs. estado final

Hoy (F0–F2): nadie cambia su flujo; el Mantenedor observa y OQO ya publica por él

flowchart LR
    MV["Multivende
(Quintec)"] -- "precio + stock
(directo, como siempre)" --> SH["Shopify
belkin.cl"]
    OQO["OQO
(SEO y contenido)"] -- "flujo editorial
con aprobación" --> M["Mantenedor"]
    M -- "export gobernado (F2)" --> SH
    SH -. "webhooks + reconcile
espejo de cambios externos" .-> M
    M -. "pisada detectada
evidencia + snapshot" .-> B(["Belkin decide"])

Estado final (F3–F4): precio entra por el carril Quintec; el stock sigue directo

flowchart LR
    MV["Multivende
(Quintec)"] -- "stock (siempre directo)" --> SH["Shopify
belkin.cl"]
    MV -- "webhook precio/estado" --> CQ["Carril Quintec
borrador + aprobación"]
    OQO["OQO"] -- "carril editorial" --> CE["Carril OQO
borrador + revisión"]
    IA["Agentes IA
(MCP)"] -- "solo proponen" --> CE
    CQ --> M["Mantenedor
fuente de verdad"]
    CE --> M
    M -- "única vía de escritura (F4)" --> SH
    SH -. espejo .-> M

Importante para la mesa: el Mantenedor nunca frena la operación de Quintec. Hoy no le cambia nada; en F3 sus precios ganan trazabilidad y aprobación en lote; el stock jamás pasa por acá. El corte del acceso directo (F4) es una decisión contractual de Belkin, no un hecho técnico consumado.

A. Flujo editorial (OQO)

Secuencia: de la edición al catálogo publicado

sequenceDiagram
    autonumber
    actor E as Editor OQO
    participant M as Mantenedor
    actor R as Revisor (≠ autor)
    participant S as Shopify
    E->>M: Abrir borrador (carril OQO)
    E->>M: Editar SEO / contenido (diff visible)
    E->>M: Enviar a revisión (borrador se congela)
    R->>M: Aprobar / pedir cambios / rechazar
    R->>M: Publicar (proyección atómica + versión N)
    M->>S: Export productSet (outbox, idempotente)
    S-->>M: IDs remotos + confirmación
    M->>M: Log de sincronización (evidencia)

B. Espejo y pisadas (drift)

Ciclo de una pisada — Cada cambio externo se compara contra lo gobernado; si difiere, queda evidencia y decide un humano.

Secuencia: pisada detectada y resuelta

sequenceDiagram
    autonumber
    participant X as Alguien (fuera del Mantenedor)
    participant S as Shopify
    participant M as Mantenedor
    actor H as Humano (Belkin/OQO)
    X->>S: Cambia SEO/título directo en Shopify
    S->>M: Webhook firmado (o reconcile cada 6 h)
    M->>M: Compara contra lo gobernado
    alt Coincide (eco de nuestro export)
        M->>M: Silencio. Si había pisada, se marca resuelta
    else Difiere (pisada real)
        M->>M: Evidencia: campos exactos + snapshot restaurable + alerta ⚠
        H->>M: Decide: sobrescribir (re-export) o absorber (rollback)
    end

C. Operación Quintec vía Multivende

Quintec cambia un precio en Multivende como siempre.

El webhook llega al Mantenedor; se valida el token y se filtra al dominio operacional (SEO/contenido del webhook se descarta; SKUs desconocidos se ignoran).

El cambio abre/actualiza el borrador del carril Quintec con autoría del bot (trazable) y se auto-envía a revisión.

Un humano aprueba y publica — en lote si quiere. Si el carril está en revisión, el cambio se difiere con evidencia LANE_BUSY.

Secuencia (F3): precio de Multivende por el carril Quintec — el stock ni entra

sequenceDiagram
    autonumber
    actor Q as Quintec
    participant MV as Multivende
    participant M as Mantenedor
    actor H as Humano
    participant S as Shopify
    Q->>MV: Cambia precio (su herramienta de siempre)
    MV->>S: Stock: directo, sin pasar por el Mantenedor
    MV->>M: Webhook precio (token) → borrador carril Quintec
    M->>M: Filtra: solo dominio operacional, solo SKUs existentes
    M->>M: Auto-envía a revisión (autoría del bot, trazable)
    H->>M: Aprueba y publica (en lote si quiere)
    M->>S: Export gobernado con evidencia

D. Conflicto entre carriles (merge de 3 vías)

OQO edita SEO mientras Quintec publica un precio: la base del borrador de OQO queda atrás → el sistema lo detecta y bloquea el pisoteo.

Acción Rebase: lo que no chocó se fusiona solo; en un choque real del mismo campo gana el dueño del dominio.

Si el campo no tiene dueño definido, el humano elige lado campo por campo en el panel.

04Procesos operativos

Automáticos

Reconciliación Shopify cada 6 h (red de seguridad de webhooks; detecta también eliminaciones).
Reaper del outbox cada 15 min: re-encola exports varados (worker caído, reintentos agotados).
Locks de edición: liberación de bloqueos vencidos cada 5 min.

Garantías técnicas

Export idempotente por hash: repetir nunca duplica.
No-op si nada cambió (salvo pisada pendiente: ahí siempre re-envía para poder sobrescribir).
Anti-eco: nuestros propios exports no generan falsas pisadas.
Publicar nunca depende de que Shopify esté disponible (outbox).

Evidencia

Pestaña Sincronización por producto: export / import / drift con request, respuesta y actor.
Timeline de actividad: humanos, bots e IA distinguibles.
Snapshot restaurable de cada estado pisado.

05Adopción por fases — sin fricción

Fases de adopción — Cada fase entrega valor sin exigir la siguiente. Se activan con configuración, sin re-deploy.

Fase	Qué pasa	Qué requiere
F0 Espejo	Solo observar: catálogo importado, pisadas registradas. Cero fricción para las agencias.	Secreto de webhooks + import inicial
F1 Alertas	Informe de pisadas para Belink con evidencia fechada.	Nada adicional
F2 Escritura OQO	OQO publica sus campos vía Mantenedor.	Credenciales de Custom App Shopify
F3 Ingesta Quintec	Multivende entra al carril Quintec; gobernanza dura (enforce).	App OAuth2 Multivende + acuerdo de campos
F4 Cierre	Belink revoca la escritura directa en Shopify: el Mantenedor es la única vía.	Decisión contractual de Belink

06Definiciones a cerrar en esta reunión

Mandato de Belink: el Mantenedor es la vía oficial del catálogo (sponsor y dueño formal del sistema).
RACI de campos firmado: confirmar la matriz OQO = contenido/SEO, Quintec = precio/operación — y qué pasa con los casos grises (títulos con precio, tags promocionales).
Cuentas staff separadas por agencia en Shopify: atribución exacta de cada cambio externo.
Modo de gobernanza: partir en warn (se aplica y se registra) y fecha para pasar a enforce (se rechaza).
SLA de revisión: tiempo máximo para aprobar el carril contrario (propuesta: 4 h hábiles) y el modo emergencia auditado.
Fecha de F0: activar el espejo esta semana; primer informe de pisadas en 15 días.
Credenciales: quién crea la Custom App de Shopify (scopes write_products) y la app OAuth2 de Multivende.
Stock: ratificar que queda fuera del Mantenedor (Multivende → Shopify directo) en esta etapa.

El enfoque, de punta a punta —para definiciones finales