FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas…

En 30 segundos

Es el motor que decide en qué momento de su vida está cada producto y quién tiene que hacer algo. Un solo flujo para Mercaderías, Suburbia y Marketplace: siete estados, catorce tipos de tarea y un estado por canal. Cada negocio cambia las reglas, no el camino, y el SKU se pide con lo mínimo mientras el enriquecimiento avanza aparte. Sólo el motor cambia estados; los demás módulos le informan hechos.

• Módulo dueño: MS-02 Producto. También participan: MS-01 Catálogo, MS-13 Identidad y acceso, MS-06 Evaluación, MS-15 IA y enriquecimiento, MS-12 Estudio fotográfico, MS-07 Ingesta de archivos, MS-14 Avisos y ayuda, MS-05 Auditoría, MS-03 Migración y convivencia.
• Etapa T · Transversal. Recibe «PE-1 · Propuesta en Borrador», «PE-T · Usuario con permisos y bitácora», «PE-C · Catálogo vigente» y entrega «PE-4 · Propuesta enviada».
• APIs: construye 9 y usa 6 que construyen otras épicas.
• Eventos: publica 8 y consume 6.

1. Dónde encaja

Recibe

Entrega

Cambios de estado que hace

Tareas que abre o cierra: Validación automática, Visto bueno de Compras, Calificación de IA, Corrección, SKU en SAP, Gobierno de Datos, Foro: muestra, foto y enriquecimiento, Carga de imagen, Sección con dueño, QA con IA, QA manual, Category, Revisión del cambio, Repoblamiento.

2. Diagrama de contexto

Quién participa y cómo se conecta. Las pantallas llegan por el BFF del portal, que valida el token y compone; cada módulo vuelve a validar el token y decide sus permisos con los roles de MS-13.

🟩 Verde: nuevo, se construye · 🟦 Azul: ya existe y se queda, se reutiliza su código · 🟧 Naranja: temporal o se retira (se apaga en R3) · ⬜ Gris: sistema externo · ★ módulo dueño

3. Diagrama de flujo

El camino principal, paso por paso. Cuando una pantalla llama a un módulo se ven dos flechas: la pantalla al BFF y el BFF al módulo. Los eventos salen del outbox del módulo después de guardar; quien los consume ignora los repetidos.

3.1 Segunda carretera: del SKU a Aprobado con tareas en paralelo

3.2 Entrar y salir del ciclo: primer guardado, alta directa y cancelación

3.3 Configuración versionada y convivencia con P360

4. Si algo sale mal

• Alguien pide una acción que no vale en ese estado, tarea o rol. El plan responde 409 NOT_EDITABLE_IN_STATUS o 403 con el motivo y no cambia nada. Es la misma regla que hoy rechaza una combinación de estatus, acción y rol que no está configurada; ningún proceso puede pedir un SKU desde un estado que no lo permite.
• La Validación automática falla después de enviar. La propuesta regresa a Borrador (T04) con una Corrección de origen «reglas» y el error de cada campo. El proveedor ve «Rechazada» y recibe un aviso; al reenviar, el motor la vuelve a validar.
• El score de Marketplace no alcanza el umbral. La propuesta regresa a Borrador con una Corrección de origen «score». El seller ve «Por completar», no «Rechazada», con lo que baja su calificación; al reenviar se vuelve a calificar.
• SAP rechaza el alta (archivo 141). El producto se queda en Creación de SKU y el motor abre Gobierno de Datos, que relanza, regresa la propuesta a Compras (T07), la rechaza al proveedor con una Corrección o la cancela (T13). El proveedor ve «En revisión» mientras Gobierno de Datos trabaja.
• Un producto queda atorado o con un estado que no corresponde. Gobierno de Producto lo corrige con la corrección administrativa (API-02-021), con motivo obligatorio. Sale STATUS_CORRECTED y la bitácora lo marca como corrección, no como un paso del flujo.

5. APIs

Las que construye esta épica (9)

null

{
  "success": true,
  "data": {
    "items": [
      {
        "productId": "PRD-0004812",
        "status": "APROBADO",
        "openTasks": [],
        "version": 12,
        "actions": [
          "INACTIVATE",
          "REQUEST_REPOPULATION"
        ],
        "fieldGroups": [
          {
            "group": "DATOS_BASE",
            "access": "READ_ONLY"
          },
          {
            "group": "ENVASE",
            "access": "EDIT_DIRECT",
            "owner": "COMPRAS"
          },
          {
            "group": "LOGISTICA",
            "access": "EDIT_WITH_REVIEW",
            "owner": "LOGISTICA"
          },
          {
            "group": "EAN",
            "access": "READ_ONLY",
            "note": "El EAN sólo cambia por la liberación de EAN o por Gobierno de Datos"
          }
        ],
        "isContentOwner": false
      }
    ]
  }
}

{
  "action": "REJECT",
  "items": [
    {
      "productId": "PRD-0004812",
      "version": 6
    }
  ],
  "reason": {
    "code": "DATOS_INCOMPLETOS",
    "comment": "Faltan medidas del empaque",
    "target": "PROVEEDOR",
    "fields": [
      {
        "attribute": "ALTO_EMPAQUE",
        "code": "REQUIRED",
        "comment": "Captura el alto en centímetros"
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "planId": "pln-7f3a91",
    "expiresAt": "2026-10-18T15:14:05Z",
    "summary": {
      "ok": 1,
      "blocked": 0
    },
    "items": [
      {
        "productId": "PRD-0004812",
        "from": "EN_REVISION",
        "to": "BORRADOR",
        "closesTasks": [
          "VISTO_BUENO_COMPRAS"
        ],
        "opensTasks": [
          "CORRECCION"
        ],
        "correctionDueAt": "2026-12-17T15:04:05Z",
        "visibleToSupplier": "Rechazada"
      }
    ],
    "applyUrl": "/api/v2/product-plans/pln-7f3a91/apply"
  }
}

{}

{
  "success": true,
  "data": {
    "requestId": "req-55e0c2",
    "status": "ACCEPTED",
    "receiptUrl": "/api/v2/product-receipts/req-55e0c2"
  }
}

null

{
  "success": true,
  "data": {
    "requestId": "req-55e0c2",
    "status": "DONE",
    "finishedAt": "2026-10-18T15:04:07Z",
    "items": [
      {
        "productId": "PRD-0004812",
        "result": "APPLIED",
        "version": 7,
        "status": "BORRADOR",
        "openTasks": [
          "CORRECCION"
        ],
        "visibleToSupplier": "Rechazada"
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "version": 4,
    "statuses": [
      {
        "code": "BORRADOR",
        "label": "Borrador"
      },
      {
        "code": "EN_REVISION",
        "label": "En revisión"
      },
      {
        "code": "CREACION_SKU",
        "label": "Creación de SKU"
      },
      {
        "code": "EN_ENRIQUECIMIENTO",
        "label": "En enriquecimiento"
      },
      {
        "code": "APROBADO",
        "label": "Aprobado"
      },
      {
        "code": "EN_MODIFICACION",
        "label": "En modificación"
      },
      {
        "code": "CANCELADO",
        "label": "Cancelado"
      }
    ],
    "tasks": [
      {
        "code": "VALIDACION_AUTOMATICA",
        "attendedBy": "SISTEMA"
      },
      {
        "code": "VISTO_BUENO_COMPRAS",
        "attendedBy": "COMPRAS"
      },
      {
        "code": "CALIFICACION_IA",
        "attendedBy": "SISTEMA"
      },
      {
        "code": "CORRECCION",
        "attendedBy": "PROVEEDOR"
      },
      {
        "code": "SKU_EN_SAP",
        "attendedBy": "SISTEMA"
      },
      {
        "code": "GOBIERNO_DE_DATOS",
        "attendedBy": "GOBIERNO_DE_DATOS"
      },
      {
        "code": "FORO",
        "attendedBy": "ESTUDIO"
      },
      {
        "code": "CARGA_DE_IMAGEN",
        "attendedBy": "PROVEEDOR"
      },
      {
        "code": "SECCION_CON_DUENO",
        "attendedBy": "AREA_DUENA"
      },
      {
        "code": "QA_CON_IA",
        "attendedBy": "SISTEMA"
      },
      {
        "code": "QA_MANUAL",
        "attendedBy": "QA"
      },
      {
        "code": "CATEGORY",
        "attendedBy": "CATEGORY"
      },
      {
        "code": "REVISION_DEL_CAMBIO",
        "attendedBy": "DUENO_DEL_DATO"
      },
      {
        "code": "REPOBLAMIENTO",
        "attendedBy": "REPOBLAMIENTO"
      }
    ],
    "channelStatuses": [
      "PENDIENTE",
      "ENVIADO",
      "PUBLICADO",
      "ERROR",
      "RETIRADO"
    ],
    "supplierLabels": [
      {
        "label": "Borrador",
        "p360Code": "10031"
      },
      {
        "label": "Rechazada",
        "p360Code": "1027"
      },
      {
        "label": "Revisión de compras",
        "p360Code": "1003"
      },
      {
        "label": "En revisión",
        "p360Code": "1001"
      },
      {
        "label": "En proceso Liverpool",
        "p360Code": "1026"
      },
      {
        "label": "Carga de imagen",
        "p360Code": "1004"
      },
      {
        "label": "Aprobada",
        "p360Code": "1007"
      },
      {
        "label": "Modificación",
        "p360Code": "1008"
      },
      {
        "label": "Por actualizar",
        "p360Code": "1006"
      },
      {
        "label": "Cancelada",
        "p360Code": "1009"
      },
      {
        "label": "Por completar",
        "p360Code": null
      }
    ]
  }
}

null

{
  "success": true,
  "data": {
    "type": "DEADLINES",
    "version": 3,
    "rows": [
      {
        "business": "MER",
        "task": "CORRECCION",
        "days": 60,
        "remindEveryDays": 7,
        "onExpire": "CANCEL"
      },
      {
        "business": "MER",
        "task": "VISTO_BUENO_COMPRAS",
        "days": 30,
        "remindEveryDays": 15,
        "onExpire": "ESCALATE"
      },
      {
        "business": "MER",
        "task": "DRAFT",
        "days": 90,
        "remindBeforeDays": 7,
        "onExpire": "PURGE"
      },
      {
        "business": "MER",
        "task": "ENRICHMENT",
        "anchor": "RECEPTION",
        "offsetDays": -4,
        "fallbackDays": 30,
        "remindBeforeDays": [
          15,
          3
        ],
        "onExpire": "RESCUE_TO_FORO"
      }
    ]
  }
}

{
  "version": 3,
  "changes": [
    {
      "business": "MER",
      "task": "CORRECCION",
      "days": 45
    }
  ]
}

{
  "success": true,
  "data": {
    "planId": "pln-c2d410",
    "expiresAt": "2026-10-18T15:14:05Z",
    "impact": {
      "openTasks": 214,
      "dueAtMovedEarlier": 214
    },
    "applyUrl": "/api/v2/product-plans/pln-c2d410/apply"
  }
}

{
  "command": "APPROVE",
  "items": [
    {
      "taskId": "tsk-52108",
      "version": 3
    }
  ],
  "comment": "Peso confirmado con la ficha técnica"
}

{
  "success": true,
  "data": {
    "planId": "pln-91be20",
    "expiresAt": "2026-10-18T15:14:05Z",
    "items": [
      {
        "taskId": "tsk-52108",
        "productId": "PRD-0004812",
        "closes": "REVISION_DEL_CAMBIO",
        "from": "EN_MODIFICACION",
        "to": "APROBADO",
        "appliesFields": [
          "PESO_EMPAQUE"
        ],
        "republishChannels": [
          "TIENDA",
          "OMS"
        ],
        "visibleToSupplier": "Aprobada"
      }
    ],
    "applyUrl": "/api/v2/product-plans/pln-91be20/apply"
  }
}

{
  "version": 9,
  "status": "EN_ENRIQUECIMIENTO",
  "closeTasks": [
    "tsk-40211"
  ],
  "openTasks": [
    {
      "type": "QA_CON_IA"
    }
  ],
  "reason": {
    "code": "ESTADO_INCONSISTENTE",
    "comment": "Quedó con Gobierno de Datos abierta después de que SAP sí creó el artículo"
  }
}

{
  "success": true,
  "data": {
    "planId": "pln-0a91c3",
    "expiresAt": "2026-10-18T15:14:05Z",
    "item": {
      "productId": "PRD-0004812",
      "from": {
        "status": "EN_ENRIQUECIMIENTO",
        "openTasks": [
          "GOBIERNO_DE_DATOS"
        ],
        "visibleToSupplier": "En proceso Liverpool"
      },
      "to": {
        "status": "EN_ENRIQUECIMIENTO",
        "openTasks": [
          "QA_CON_IA"
        ],
        "visibleToSupplier": "En revisión"
      },
      "warnings": [
        "La tarea tsk-40211 sale de la bandeja de Gobierno de Datos"
      ]
    },
    "applyUrl": "/api/v2/product-plans/pln-0a91c3/apply"
  }
}

Las que usa y construye otra épica (6)

Su request y su response están en la página de la épica que la construye.

6. Eventos

Publica

Consume

7. Datos

Cada colección tiene un solo dueño, el único que escribe en ella.

8. Historias que cubre

9. Decisiones de esta épica

Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.

• D-FLU-01-1. El motor es el modelo B guardado como datos: 7 estados, 14 tareas y 5 estados por canal. Sólo tiene las 14 transiciones del ciclo de vida (T01 a T14) y reglas por negocio que deciden qué tareas abre cada una. La llave de NextStatus ya no decide nada: queda como tabla de equivalencias con P360 (P360_CODES). Por qué: Cumple lo que piden los talleres con 7 estados en lugar de 28 y cada combinación conserva su código de P360. Las 239 llaves con estado previo sobran porque el origen de cada rechazo viaja en la tarea. Se apoya en PD-29, DMS-69, ADR-12.
• D-FLU-01-2. Los permisos de dominio viven en el motor de MS-02 como configuración versionada: ROLE_MATRIX (rol × acción × tarea × negocio) y FIELD_OWNERS (dueño de cada grupo de campos). MS-13 sólo dice qué roles, áreas y negocios tiene cada usuario y el BFF sólo decide los permisos de pantalla. La matriz falla cerrada: lo que no está, no se permite. Por qué: Quién puede hacer qué en el flujo es una regla del flujo. Repartirla entre directorio, BFF y motor repetiría el desorden de roles de P360 y dejaría dos lugares que se contradicen. Se apoya en DMS-71, DUD-22, ADR-12.
• D-FLU-01-3. Sólo MS-02 cambia el estado y las tareas, siempre por plan y confirmación (API-02-028, API-02-035 y API-02-057) o por su reloj de plazos. Los demás módulos informan hechos con sus eventos (el estudio terminó, la imagen se validó) o responden cuando el motor los llama (score, revisión con IA); nunca escriben el estado. Por qué: Una sola máquina de estados en lugar de las dos de hoy (P360 y Entrada Única) evita los SKU que cambian de estado sin registro y las propuestas en aprobación que piden SKU. Se apoya en ADR-12, PD-29, RF-ALT-11.
• D-FLU-01-4. Las reglas por negocio son guardas de la misma transición. Al enviar, Mercaderías y Suburbia abren Visto bueno de Compras y Marketplace abre Calificación de IA. Los obligatorios salen de la vista efectiva de MS-01 por negocio (unos 5 en Marketplace frente a 30 o 40 en Liverpool), sin copias en MS-02. Marketplace suma controles (lista negra, coincidencias, coherencia), no más atributos. Por qué: Un solo flujo con candados por negocio: «no son dos plataformas». Se apoya en RN-GEN-02, RN-GEN-05, RF-GEN-02.
• D-FLU-01-5. Dos carreteras: el SKU se pide con los datos maestros mínimos y, al llegar el 122, foto, secciones con dueño y Gobierno de Datos se abren en paralelo. Aprobado sólo espera a las tareas que bloquean: foto, secciones obligatorias, QA y Category si su negocio la tiene encendida (SWITCHES). El enriquecimiento opcional nunca frena el SKU ni la publicación. Por qué: Volumetría, logística comercial y precios no deben detener el SKU. Category se apaga por negocio, sin tocar el motor, cuando se mida el acierto de la IA. Se apoya en RN-GEN-03, RF-GEN-03, DEC-01, P-37.
• D-FLU-01-6. Si el score de Marketplace no alcanza el umbral, la propuesta regresa a Borrador con una Corrección de origen «score», que el seller ve como «Por completar», con lo que baja su calificación. No cuenta como rechazo; es la misma etiqueta que lleva la franja RETENER de FT-RAC-03 después del SKU. Antes del SKU el score sólo mira lo que el SKU necesita; la calidad del contenido frena después la publicación de cada canal. Por qué: En el taller se acordó que no avanzar no es un rechazo. Separar las dos compuertas cumple a la vez «dos carreteras» y el score antes del SKU que dibujan los diagramas. Se apoya en RN-CAL-06, DEC-46, PD-24.
• D-FLU-01-7. Un producto Aprobado o En modificación no se cancela: se retira de cada canal. Cancelar sólo vale de Borrador a En enriquecimiento (T11 a T14), cierra todas sus tareas y libera los EAN en la misma transacción. Si llega un 122 de un producto ya cancelado, no se reabre: queda una tarea de Gobierno de Datos, sin cambiar el estado, para dar de baja el artículo en SAP. Por qué: Hoy se puede cancelar desde cualquier estado y se pierde qué estaba publicado. La baja por canal deja ver qué se retiró y dónde. Se apoya en PD-29, ADR-12.
• D-FLU-01-8. Toda tabla del motor es versionada: el cambio se revisa con vista previa (API-02-031), se confirma con plan y sale como evento para la bitácora. El código de P360 se calcula sólo con P360_CODES, que leen MS-03 mientras P360 sea la fuente y los reportes que todavía lo usen. Ninguna pantalla lee códigos y no hay rutas /public/rt. Por qué: Sin capa de compatibilidad para los fronts (decisión 20 que adopta ADR-12) y con una sola tabla, nadie recalcula estados por su cuenta. Se apoya en DUD-36, ADR-06, ADR-12.

Qué falta decidir

También siguen abiertos: PEN-55, Cómo se identifica el negocio de un proveedor híbrido al dar de alta: el motor necesita un solo negocio por producto.

Fuentes

1. [D] trazabilidad/features/FT-FLU-01-motor-de-estados-configurable.md: la ficha de la épica, con sus historias, reglas y bloqueos.
2. [D] ADR-12 · Un solo sistema: backend compartido y una sola base (sección 3.4).
3. [D] docs/arquitectura/por-epica/base/: piezas, colecciones, eventos y el hilo de punta a punta.
4. [D] docs/arquitectura/omega-a-pim-headless/contratos-api.md: convenciones y endpoints de partida.
5. [D] docs/arquitectura/maquina-de-estados-to-be/propuesta-maquina-de-estados.md §7: estados, tareas y canales.
6. [I] Las decisiones de la sección 9 son del TL sobre esas fuentes.