Actualizado el 18-oct-2026. Primera versión de la arquitectura de esta épica.
Qué responde. Cómo funciona por dentro FT-IA-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-IA-03.json, generada con generar.py; la ficha de la épica es trazabilidad/features/FT-IA-03-enriquecimiento-opcionales-politica-completitud.md.
En 30 segundos
Liverpool quiere productos completos, pero al seller le interesan menos los atributos opcionales y correr la IA sobre millones de SKU cuesta. Esta épica deja que el seller pida a la IA valores para un bloque opcional (sólo con los obligatorios completos) y que Gobierno de Producto marque qué atributos puede llenar la IA, cuáles necesita como contexto y cuáles se persiguen. También fija hasta cuándo se enriquece en automático.
- Módulo dueño: MS-15 IA y enriquecimiento. También participan: MS-01 Catálogo, MS-02 Producto, MS-06 Evaluación.
- Etapa 3 · Captura. Recibe «PE-3 · Plantilla asignada» y entrega a otras épicas.
- APIs: construye 0 y usa 11 que construyen otras épicas.
- Eventos: publica 1 y consume 1.
1. Dónde encaja
Recibe
| De | Qué |
|---|---|
| PE-3 · Plantilla asignada | La propuesta con plantilla asignada y la vista efectiva con el nivel de cada atributo por negocio. |
| FT-PLT-06 · Configuración de atributos por plantilla y por negocio… | Los atributos opcionales y recomendados de cada plantilla, con su marca de enriquecible por IA, de contexto y cómo se persigue. |
| FT-IA-01 · Prellenado con IA y validación obligatoria del usuario | El mecanismo de sugerencia con confirmación del usuario, que se reusa para el bloque opcional. |
Entrega
| A | Qué |
|---|---|
| FT-PRD-07 · Captura guiada por pasos con los mínimos primero | Los valores del bloque opcional confirmados por el seller, para seguir la captura. |
| FT-RAC-02 · Score de calidad del producto | Más recomendados y opcionales llenos, que suben la calificación. |
| FT-IA-05 · Enriquecimiento continuo después de crear el SKU y después… | La política de enriquecimiento: qué atributos se persiguen, cuáles son de contexto y la ventana desde el SKU. |
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 | Seller | Entrada Única · Vendor Center | Pide «correr la IA» en un bloque opcional | — |
| 2 | Entrada Única · Vendor Center | MS-15 IA y enriquecimiento (por el BFF) | Pide valores para los atributos del bloque | API-15-003 |
| 3 | MS-15 IA y enriquecimiento | MS-02 Producto | Revisa que los obligatorios estén completos | API-02-054 |
| 4 | MS-15 IA y enriquecimiento | MS-01 Catálogo | Lee qué puede llenar la IA y qué contexto necesita | API-01-028 |
| 5 | MS-15 IA y enriquecimiento | Modelos de IA | Propone valores con el contexto ya capturado | — |
| 6 | MS-15 IA y enriquecimiento | Base pim | Guarda las sugerencias del bloque | — |
| 7 | Entrada Única · Vendor Center | MS-15 IA y enriquecimiento (por el BFF) | Trae las sugerencias | API-15-008 |
| 8 | Seller | Entrada Única · Vendor Center | Confirma o corrige cada valor | — |
| 9 | Entrada Única · Vendor Center | MS-02 Producto (por el BFF) | Pide el plan con los valores confirmados | API-02-012 |
| 10 | Entrada Única · Vendor Center | MS-02 Producto (por el BFF) | Confirma el plan | API-02-057 |
| 11 | Entrada Única · Vendor Center | MS-06 Evaluación (por el BFF) | Muestra cuánto subió su calificación | API-06-006 |
3.1 Obligatorios incompletos
3.2 Gobierno de Producto marca atributos y fija la política
3.3 La plantilla crece
4. Si algo sale mal
- El seller pide la IA sin completar los obligatorios. MS-15 responde 409 sin llamar al modelo; el seller ve qué obligatorios le faltan. No se gasta IA ni se salta el candado.
- El bloque sólo tiene atributos de contexto o no enriquecibles. No se ofrece «correr la IA» en ese bloque; si se pide igual, MS-15 responde que no hay nada que la IA pueda llenar.
- La IA no encuentra valores. El bloque queda como estaba y el seller ve «no encontramos datos»; no cuenta en contra de su calificación.
- Se cambia la ventana o qué se persigue con productos ya en curso. El plan dice cuántos productos entran o salen de la ventana antes de aplicarlo; lo ya enriquecido no se repite.
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 (11)
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-003 | POST /api/v2/ai/prefill | Pedir sugerencias para un bloque opcional, con el candado de obligatorios | FT-IA-01 · Prellenado con IA y validación obligatoria del usuario |
| API-15-008 | GET /api/v2/ai/jobs/{jobId} | Traer las sugerencias del bloque | FT-IA-04 · Integración de los modelos de IA existentes |
| API-15-011 | POST /api/v2/ai/config/plans | Fijar la ventana de enriquecimiento automático con su impacto | FT-IA-04 · Integración de los modelos de IA existentes |
| API-15-012 | POST /api/v2/ai-plans/{planId}/apply | Confirmar la política de enriquecimiento | FT-IA-04 · Integración de los modelos de IA existentes |
| API-01-025 | POST /api/v2/taxonomies/PRODUCT/nodes/{id}/bindings/plans | Marcar en la plantilla los atributos enriquecibles, de contexto y perseguidos | FT-PLT-06 · Configuración de atributos por plantilla y por negocio… |
| API-01-004 | POST /api/v2/catalog-plans/{planId}/apply | Confirmar el cambio de configuración de la plantilla | FT-PLT-01 · Fundamentos de gobierno de plantillas |
| API-01-028 | GET /api/v2/taxonomies/PRODUCT/nodes/{id}/effective | Leer niveles y marcas de IA de cada atributo | FT-PLT-06 · Configuración de atributos por plantilla y por negocio… |
| API-02-054 | GET /internal/product/products/{id}/publication-snapshot?version= | Revisar los obligatorios antes de correr la IA | FT-CAT-05 · Sitios, enrutamiento y visibilidad por negocio |
| API-02-012 | POST /api/v2/products/{id}/values/plans | Guardar los valores confirmados del bloque | FT-RAC-01 · Motor de validación en línea y candados de datos… |
| API-02-057 | POST /api/v2/product-plans/{planId}/apply | Confirmar los valores | FT-FLU-01 · Motor de estados configurable con dos carreteras y reglas… |
| API-06-006 | POST /api/v2/scores | Ver la calificación subir al llenar opcionales | FT-RAC-02 · Score de calidad del producto |
6. Eventos
Publica
| Evento | Cuándo | Quién lo consume |
|---|---|---|
catalog.governance.changed/TEMPLATE_VIEW_CHANGED | Catálogo agrega atributos a una plantilla o cambia sus marcas de IA | FT-ACT-01, FT-ACT-05, FT-PLT-06, FT-PLT-09, FT-PRD-01, FT-RAC-01, FT-RAC-02 |
Consume
| Evento | Para qué | Quién lo publica |
|---|---|---|
catalog.governance.changed/TEMPLATE_VIEW_CHANGED | MS-15 renueva qué atributos puede enriquecer en cada plantilla | 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 |
|---|---|---|---|
ai_jobs | MS-15 | Cada trabajo de IA con su entrada, su resultado y su confianza. | escribe |
ai_config | MS-15 | Qué modelo atiende cada tarea y con qué umbral. | escribe |
template_views | MS-01 | La vista efectiva ya resuelta por plantilla y negocio: qué atributos pide y cuáles son obligatorios. | lee |
products | MS-02 | La familia del producto con sus variantes, valores, imágenes (URL), clasificaciones, estado, tareas abiertas y rechazos. | lee |
8. Historias que cubre
| Historia | Prioridad | Cómo la cubre |
|---|---|---|
| FT-IA-03·H1 · Pedir a la IA valores | P1 | pasos 1, 2, 3, 4, 5, 7, 8, 9, 10; flujo «Obligatorios incompletos»; API-15-003 |
| FT-IA-03·H2 · Marcar en la plantilla qué atributos puede enriquecer la IA y cuáles necesita… | P1 | flujo «Gobierno de Producto marca atributos y fija la política»; API-01-025, API-01-028 |
| FT-IA-03·H3 · Distinguir los opcionales que perseguimos de los que quedan a interés del… | P2 | flujo «Gobierno de Producto marca atributos y fija la política»; API-15-011, API-15-012 |
| FT-IA-03·H4 · Que los atributos nuevos de una plantilla que crece entren como opcionales que… | P2 | flujo «La plantilla crece» |
9. Decisiones de esta épica
Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.
- D-IA-03-1. Las marcas por atributo viven en la configuración de la plantilla de Catálogo (FT-PLT-06): enriquecible por IA, de contexto (la IA lo necesita y no lo infiere) y cómo se persigue (IA de Liverpool, equipo de Liverpool o a interés del proveedor). MS-15 las lee de la vista efectiva y no guarda copia. Por qué: Un dato, un dueño: qué pide la plantilla y cómo se llena es configuración del catálogo. Se apoya en RF-ENR-10, RF-ENR-11, DEC-09.
- D-IA-03-2. El candado de obligatorios lo revisa MS-15 en el servidor antes de correr un bloque opcional: si faltan, responde 409 y no llama al modelo. Por qué: Ningún obligatorio se salta para usar la IA, y no se paga una corrida que no sirve. Se apoya en RF-ENR-07.
- D-IA-03-3. La ventana del enriquecimiento automático vive en la configuración de MS-15 por negocio: arranca en 90 días desde el SKU y una sola pasada por disparo. Lo marcado «a interés del proveedor» nunca se corre en automático, sólo si el seller lo pide. Por qué: Correr la IA continuamente sobre uno o dos millones de SKU no es viable; acotar por ventana y por lo que se persigue controla el costo. Se apoya en PEN-34, RN-ENR-07.
- D-IA-03-4. Los atributos nuevos de una plantilla que crece entran como opcionales (regla de FT-PLT-06) y quedan disponibles para la IA; no se vuelven obligatorios para el seller. Por qué: No se le pide hoy diez y en tres días quince: lo nuevo lo completa Liverpool o la IA. Se apoya en RN-PLA-11.
- D-IA-03-5. Correr la IA sobre un bloque es una sugerencia con confirmación, igual que el prellenado (FT-IA-01); al confirmar, la calificación sube por los pesos de recomendados y opcionales (FT-RAC-02). Por qué: Una sola regla de validación en el alta y un incentivo visible para completar. Se apoya en RN-ENR-05, RN-CAL-09.
Qué falta decidir
| ID | Qué falta |
|---|---|
| DUD-35 | Capacidades y contrato del modelo de enriquecimiento con el equipo de IA. |
También siguen abiertos: PEN-34, El periodo real de enriquecimiento automático (aquí arranca en 90 días desde el SKU); PEN-45, Qué atributos puede enriquecer la IA y cuáles necesita como contexto; PEN-75, El listado funcional de obligatorios por negocio que se cruza con lo que la IA puede llenar; PEN-76, El listado técnico de mínimos por sistema destino.
Fuentes
- [D]
trazabilidad/features/FT-IA-03-enriquecimiento-opcionales-politica-completitud.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.