Actualizado el 18-oct-2026. Primera versión de la arquitectura de esta épica.
Qué responde. Cómo funciona por dentro FT-RAC-03: qué piezas participan, en qué orden hablan, qué APIs hay que construir con su request y su response, y qué le entrega a la épica siguiente.
Para quién. Los equipos que van a construir la épica, QA y arquitectura.
Estado. [Propuesta] del TL del Nuevo PIM, 18-oct-2026, construida sobre ADR-12. La spec de cada épica dice el qué; estas páginas, el cómo.
Fuente. docs/arquitectura/por-epica/epicas/FT-RAC-03.json, generada con generar.py; la ficha de la épica es trazabilidad/features/FT-RAC-03-publicacion-por-rangos-de-score.md.
En 30 segundos
En Marketplace no hay comprador que revise cada producto, y mandar todo a una cola de QA manual repetiría el cuello de botella de hoy. Esta épica decide al final del enriquecimiento con el score de calidad: de 95 para arriba se aprueba y se publica; entre 85 y 95 se publica y QA lo revisa después, el más bajo primero; abajo de 85 no sale y el seller ve qué completar. A QA manual sólo llega lo que la IA no aprueba.
- Módulo dueño: MS-02 Producto. También participan: MS-06 Evaluación, MS-15 IA y enriquecimiento, MS-14 Avisos y ayuda.
- Etapa 7 · Calidad y categoría. Recibe «PE-6 · SKU asignado», «PE-7 · Imágenes listas» y entrega «PE-8 · Aprobado».
- APIs: construye 0 y usa 17 que construyen otras épicas.
- Eventos: publica 5 y consume 5.
1. Dónde encaja
Recibe
| De | Qué |
|---|---|
| PE-6 · SKU asignado | La familia en En enriquecimiento, con SKU en cada variante y sus tareas de foto y secciones abiertas. |
| PE-7 · Imágenes listas | Las imágenes listas en MS-11, con URL congelada y ligadas a su variante y posición. |
| FT-RAC-02 · Score de calidad del producto | El score de calidad (obligatorios, completitud y confianza) y su franja de publicación según los rangos de cada negocio en MS-06. |
| FT-IA-05 · Enriquecimiento continuo después de crear el SKU y después… | El resultado de QA con IA (pasa, o lo que no cuadra con su ruta sugerida para QA manual) y los atributos enriquecidos que suben la calificación. |
Entrega
| A | Qué |
|---|---|
| PE-8 · Aprobado | El producto Aprobado, con cada canal del negocio en Pendiente y la petición de publicar; lo que quedó entre 85 y 95, con su revisión posterior abierta. |
| FT-INT-01 · Publicación a e-commerce | La petición de publicar a la tienda lo que alcanzó el umbral, sin pasar por una cola de QA. |
| FT-INT-07 · Repoblamiento masivo de productos hacia la tienda | Lo que QA encuentra mal en algo ya publicado y manda a Repoblamiento. |
| FT-CAT-03 · Categorización de productos | QA aprobado: el momento en que se revisa si la categoría necesita a Category. |
Cambios de estado que hace
| Transición | De → a | Cuándo |
|---|---|---|
| T08 | En enriquecimiento → Aprobado | Calidad aprobada y sin tareas que bloqueen. |
| T09 | Aprobado → En modificación | Alguien cambia un producto aprobado. |
| C01 | Inicio → Pendiente (por canal) | El producto queda Aprobado. |
| C02 | Pendiente → Enviado (por canal) | Cumple el mínimo del canal y el bus confirma que tomó el mensaje. |
Tareas que abre o cierra: QA con IA, QA manual, Corrección.
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.
Los pasos en texto
| Paso | De | A | Qué hace | API o evento |
|---|---|---|---|---|
| 1 | MS-02 Producto | Base pim | Cierra foto y secciones y abre QA con IA | — |
| 2 | MS-02 Producto | Base pim | Revisa la regla fija: obligatorios completos y foto principal | — |
| 3 | MS-02 Producto | MS-15 IA y enriquecimiento | Pide revisar imagen, título y descripción con IA | API-15-005 |
| 4 | MS-15 IA y enriquecimiento | Eventos | Publica el resultado con su confianza | catalog.ai.result/AI_QUALITY_READY |
| 5 | Eventos | MS-02 Producto | Entrega el resultado de la revisión con IA | catalog.ai.result/AI_QUALITY_READY |
| 6 | MS-02 Producto | MS-06 Evaluación | Pide el score y su franja de publicación | API-06-006 |
| 7 | MS-02 Producto | Base pim | Cierra QA con IA y pasa a Aprobado | — |
| 8 | MS-02 Producto | Base pim | Abre la revisión posterior por quedar entre 85 y 95 | — |
| 9 | MS-02 Producto | Base pim | Deja cada canal del negocio en Pendiente | — |
| 10 | MS-02 Producto | Eventos | Avisa que el producto quedó Aprobado | catalog.product.changed/STATUS_CHANGED |
| 11 | MS-02 Producto | Eventos | Pide publicar en cada canal que cumple | catalog.product.publication/PUBLICATION_REQUESTED |
3.1 Revisión posterior de lo publicado entre 85 y 95
3.2 Debajo de 85: el seller completa
3.3 La IA no alcanza el umbral: QA manual
4. Si algo sale mal
- La IA no contesta. El producto no se aprueba sin revisión: se queda con QA con IA abierta y, a los 30 minutos (configurable), MS-02 abre QA manual con «Sin dato de IA». Nunca se toma la falta de respuesta como aprobada.
- MS-06 no devuelve el score. No se decide la franja sin dato: se reintenta y, si sigue sin respuesta, el producto aparece en la bandeja de QA con «Sin score». Nunca se toma como 0 ni como 100.
- QA encuentra un error grave en algo publicado (contenido prohibido o imagen de otro producto). QA lo retira del canal con la baja por canal (FT-CAT-05) y lo regresa al seller; un error menor no despublica: la tienda conserva lo publicado hasta que se aprueba la corrección.
- El seller no completa lo que le falta. El producto ya tiene SKU y no se cancela solo: MS-02 le recuerda cada semana y, a los 60 días, la tarea pasa a la cola de Soporte de Marketplace.
- Gobierno de Producto cambia los rangos. La vista previa de MS-06 dice cuántos productos cambiarían de franja; el cambio vale para las evaluaciones nuevas y no despublica ni republica lo anterior.
5. APIs
Las que construye esta épica (0)
Ninguna: todo lo que usa ya lo construye otra épica.
Las que usa y construye otra épica (17)
Su request y su response están en la página de la épica que la construye.
| API | Método y ruta | Para qué, aquí | La construye |
|---|---|---|---|
| API-15-005 | POST /api/v2/ai/quality-reviews | La revisión de calidad con IA: imagen contra título y título contra descripción, con su confianza | FT-IA-05 · Enriquecimiento continuo después de crear el SKU y después… |
| API-06-006 | POST /api/v2/scores | El score y su franja: PUBLICAR, REVISION_PRIORITARIA o RETENER | FT-RAC-02 · Score de calidad del producto |
| API-06-007 | GET /api/v2/validation-thresholds | Ver los rangos de publicación vigentes por negocio | FT-REF-03 · Servicio de matching |
| API-06-008 | POST /api/v2/validation-thresholds/plans | Cambiar los rangos con vista previa de cuántos productos cambian de franja | FT-REF-03 · Servicio de matching |
| API-06-009 | POST /api/v2/validation-plans/{planId}/apply | Confirmar el cambio de rangos | FT-REF-03 · Servicio de matching |
| API-15-010 | GET /api/v2/ai/config | Ver el umbral de confianza de cada modelo de IA | FT-IA-04 · Integración de los modelos de IA existentes |
| API-15-011 | POST /api/v2/ai/config/plans | Cambiar el umbral de un modelo | FT-IA-04 · Integración de los modelos de IA existentes |
| API-15-012 | POST /api/v2/ai-plans/{planId}/apply | Confirmar el cambio de umbral | FT-IA-04 · Integración de los modelos de IA existentes |
| API-02-036 | GET /api/v2/task-queues/{cola}/pool | La cola de revisión posterior, ordenada del score más bajo al más alto | FT-PRD-06 · Bandeja de pendientes y depuración de borradores… |
| API-02-038 | GET /api/v2/task-queues/{cola}/my | La bandeja de QA manual de quien llama | FT-PRD-06 · Bandeja de pendientes y depuración de borradores… |
| API-02-002 | GET /api/v2/products/{id} | Ver el producto que se revisa | FT-PRD-01 · Modelo canónico de producto |
| API-02-028 | POST /api/v2/workflow/actions/plans | Regresar al seller, o mandar a Compras, a Gobierno de Datos o a Repoblamiento, con el error marcado | FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas… |
| API-02-057 | POST /api/v2/product-plans/{planId}/apply | Confirmar la decisión de QA o los valores del seller | FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas… |
| API-02-012 | POST /api/v2/products/{id}/values/plans | El seller completa valores con la validación en el momento | FT-RAC-01 · Motor de validación en línea y candados de datos… |
| API-02-303 | GET /api/v2/workflow/sku-blockers | El seller ve qué detiene la publicación de su SKU y qué completar | FT-RAC-05 · Estatus del producto y motivos visibles para seller y… |
| API-02-030 | GET /api/v2/workflow/config/{type} | Leer QUALITY_RULES (la regla fija de calidad) y SWITCHES (si la IA ya es segunda regla) | FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas… |
| API-02-031 | POST /api/v2/workflow/config/{type}/plans | Cambiar la regla de calidad o encender la IA como segunda regla | FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas… |
6. Eventos
Publica
| Evento | Cuándo | Quién lo consume |
|---|---|---|
catalog.product.changed/STATUS_CHANGED | El producto pasa a Aprobado | FT-ACT-05, FT-ARQ-02, FT-CAT-05, FT-FLU-01, FT-IA-04, FT-PRD-02, FT-PRD-04, FT-PRD-06, FT-PRD-10, FT-RAC-05, FT-RAC-06 |
catalog.product.changed/TASK_CHANGED | Se cierra QA con IA, o se abre QA manual, la revisión posterior o la Corrección para completar | FT-ACT-05, FT-ACT-06, FT-ARQ-02, FT-CAT-06, FT-FLU-01, FT-IA-06, FT-PRD-02, FT-PRD-05, FT-PRD-06, FT-PRD-07, FT-PRD-08, FT-RAC-02, FT-RAC-04, FT-RAC-05, FT-RAC-06 |
catalog.product.changed/REJECTION_ADDED | QA manda el error al seller o al área que corrige | FT-INT-07, FT-PRD-04, FT-PRD-05, FT-PRD-10, FT-RAC-01, FT-RAC-05, FT-RAC-06 |
catalog.product.publication/PUBLICATION_REQUESTED | Se aprueba con franja PUBLICAR o REVISION_PRIORITARIA, o el seller completa y llega a 85 | FT-CAT-05, FT-CAT-06, FT-INT-01, FT-INT-02, FT-INT-05, FT-INT-07, FT-PLT-08, FT-PRD-05 |
catalog.ai.result/AI_QUALITY_READY | MS-15 termina la revisión de calidad con su confianza | FT-IA-05, FT-RAC-06 |
Consume
| Evento | Para qué | Quién lo publica |
|---|---|---|
catalog.ai.result/AI_QUALITY_READY | MS-02 cierra QA con IA o abre QA manual | esta misma épica |
catalog.product.changed/REJECTION_ADDED | MS-14 avisa a quien tiene que corregir | esta misma épica |
catalog.product.changed/TASK_CHANGED | MS-14 avisa al seller lo que le falta | esta misma épica |
catalog.product.changed/STATUS_CHANGED | MS-14 avisa al seller que su producto quedó aprobado | esta misma épica |
catalog.product.publication/PUBLICATION_REQUESTED | MS-08 publica en cada canal | esta misma épica |
7. Datos
Cada colección tiene un solo dueño, el único que escribe en ella.
| Colección | Dueño | Qué guarda | Esta épica |
|---|---|---|---|
products | MS-02 | La familia del producto con sus variantes, valores, imágenes (URL), clasificaciones, estado, tareas abiertas y rechazos. | escribe |
tasks | MS-02 | Todo el trabajo asignado: visto bueno, corrección, Gobierno de Datos, foto, secciones, QA, revisión del cambio y repoblamiento. | escribe |
product_delivery_status | MS-02 | El estado de publicación por producto y canal: Pendiente, Enviado, Publicado, Error o Retirado. | escribe |
product_receipts | MS-02 | El recibo de cada escritura confirmada en el producto (antes operation_receipts). | escribe |
product_outbox | MS-02 | Los cambios del producto que esperan salir como evento (antes outbox). | escribe |
validation_thresholds | MS-06 | Los umbrales de coincidencia y de calificación por negocio. | lee |
ai_config | MS-15 | Qué modelo atiende cada tarea y con qué umbral. | lee |
template_views | MS-01 | La vista efectiva ya resuelta por plantilla y negocio: qué atributos pide y cuáles son obligatorios. | lee |
product_reference_tables | MS-02 | Configuración del motor de estados y del matching: transiciones, estados externos y pesos. | lee |
8. Historias que cubre
| Historia | Prioridad | Cómo la cubre |
|---|---|---|
| FT-RAC-03·H1 · Pasar directo sin cola de QA | P1 | pasos 6, 7, 11; flujo «Revisión posterior de lo publicado entre 85 y 95» |
| FT-RAC-03·H2 · Publicar por rangos configurables | P1 | pasos 6, 8; API-06-007, API-06-008, API-06-009 |
| FT-RAC-03·H3 · Revisar primero lo publicado entre 85 y 95 | P2 | flujo «Revisión posterior de lo publicado entre 85 y 95»; API-02-036 |
| FT-RAC-03·H4 · Completar para salir | P3 | flujo «Debajo de 85: el seller completa»; API-02-303, API-06-006 |
| FT-RAC-03·H5 · QA manual sólo para lo que la IA no aprueba | P1 | flujo «La IA no alcanza el umbral: QA manual»; API-02-038, API-02-028 |
| FT-RAC-03·H6 · Regla de calidad fija primero | P1 | pasos 2; API-02-030, API-02-031 |
| FT-RAC-03·H7 · Validar cada modelo de IA en su paso | P2 | pasos 3, 4, 5; flujo «La IA no alcanza el umbral: QA manual»; API-15-010, API-15-011, API-15-012 |
9. Decisiones de esta épica
Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.
- D-RAC-03-1. El score decide la publicación, no el SKU. Con franja PUBLICAR (95 o más) el producto pasa a Aprobado y se publica sin revisión; con REVISION_PRIORITARIA (de 85 a menos de 95) se aprueba, se publica y se abre la revisión posterior; con RETENER (menos de 85) no se aprueba y el seller recibe una Corrección de origen «score», que ve como «Por completar» y no cuenta como rechazo (igual que antes del SKU en FT-FLU-01). Los rangos son por negocio y viven en MS-06; arrancan en 85 y 95. Por qué: Lo que cumple pasa directo y lo dudoso se revisa primero sin detener la publicación; es la propuesta vigente para PD-24 y los rangos del taller. Se apoya en PD-24, RN-PUB-06, DEC-45, DEC-46, PEN-36.
- D-RAC-03-2. La revisión posterior es una tarea QA manual que no bloquea, porque el producto ya está Aprobado y publicado; la cola se ordena del score más bajo al más alto. Por qué: Sin una cola que frene, QA deja de ser el cuello de botella; ordenar por score revisa primero lo más dudoso. Se apoya en DEC-47, RN-CAL-07.
- D-RAC-03-3. Un error en algo publicado no despublica: abre una Corrección para el seller sobre el producto aprobado (T09) y la tienda conserva lo publicado hasta que se aprueba el cambio. Sólo un error grave (contenido prohibido, imagen de otro producto o dato legal) se retira del canal con la baja por canal. Por qué: Despublicar por un error menor castiga la venta; la máquina de estados ya separa el cambio en curso de lo publicado. Se apoya en PEN-39, PD-29.
- D-RAC-03-4. Regla fija primero: obligatorios completos y foto principal congelada, en la tabla QUALITY_RULES del motor. La IA se suma como segunda regla con un interruptor de SWITCHES cuando se haya medido su acierto; mientras tanto, lo que no pasa la regla fija abre QA manual. Por qué: No depender de la IA desde el inicio, como pide Gobierno de Producto, y poder encenderla sin cambiar código. Se apoya en S34-RF-07, DUD-35.
- D-RAC-03-5. Cada modelo de IA califica su propio resultado con el umbral de su tarea (configuración de MS-15): lo que queda abajo se reprocesa o se rechaza en ese paso. El validador integral es la revisión de QA con IA (imagen contra título y título contra descripción) y sólo lo que no coincide va a QA manual. Por qué: Cada error se corrige en su paso y nadie revisa a mano lo que la IA ya aprobó. Se apoya en S34-RF-07.
- D-RAC-03-6. Sin dato no hay aprobación: si MS-15 o MS-06 no contestan, el producto no avanza y, vencido el plazo, abre QA manual con el motivo «Sin dato». Por qué: Aprobar por omisión publicaría lo que nadie revisó. Se apoya en DUD-32.
- D-RAC-03-7. QA manual manda cada rechazo a un destino tipificado: el seller o proveedor, Compras, Gobierno de Datos o, si ya está publicado, Repoblamiento, con los rechazos por atributo juntos. Por qué: Es la ruta de hoy de 1022 hacia 1003, 1021, 1028 y 1031, dicha con tareas en lugar de estados. Se apoya en S34-PEN-04, PD-29.
- D-RAC-03-8. QA con IA y QA manual sirven a los tres negocios; los rangos de score, por ahora, sólo a Marketplace. Mercaderías y Suburbia conservan el visto bueno de Compras antes del SKU y su revisión de calidad. Por qué: La épica nace de Marketplace y en Mercaderías no se acordó publicar por score. Se apoya en PD-24, PD-02.
Qué falta decidir
| ID | Qué falta |
|---|---|
| DUD-32 | Pesos y umbrales de Marketplace: se miden en el piloto. |
| PD-24 | Ratificar que el score sólo decide la publicación: Gobierno de Producto con Marketplace, en ADR-09. |
| P-37 | Si Category se conserva como tarea opcional después de QA. |
También siguen abiertos: PEN-36, Los valores de los rangos (85 y 95 de arranque) y si mandan el score combinado o la confianza; PEN-39, Los motivos de rechazo de QA distintos al score.
Fuentes
- [D]
trazabilidad/features/FT-RAC-03-publicacion-por-rangos-de-score.md: la ficha de la épica, con sus historias, reglas y bloqueos. - [D] ADR-12 · Un solo sistema: backend compartido y una sola base (sección 3.4).
- [D]
docs/arquitectura/por-epica/base/: piezas, colecciones, eventos y el hilo de punta a punta. - [D]
docs/arquitectura/omega-a-pim-headless/contratos-api.md: convenciones y endpoints de partida. - [D]
docs/arquitectura/maquina-de-estados-to-be/propuesta-maquina-de-estados.md§7: estados, tareas y canales. - [I] Las decisiones de la sección 9 son del TL sobre esas fuentes.