Actualizado el 18-oct-2026. Primera versión de la arquitectura de esta épica.
Qué responde. Cómo funciona por dentro FT-MIG-05: 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-MIG-05.json, generada con generar.py; la ficha de la épica es trazabilidad/features/FT-MIG-05-remediacion-productos-faltantes.md.
En 30 segundos
Hay productos que viven en Entrada Única o en Vendor Center y no están en la tienda, y otros que ni siquiera están en P360. Esta épica los encuentra cruzando a nivel variante, con fecha de corte, lo que hay en cada sistema; elige por universo la fuente más completa y los carga con su enriquecimiento y su categoría, sólo con confirmación escrita y sin recapturar.
- Módulo dueño: MS-03 Migración y convivencia. También participan: MS-02 Producto.
- Etapa M · Migración. Recibe de otras épicas y entrega «PE-M · Producto migrado».
- APIs: construye 0 y usa 7 que construyen otras épicas.
- Eventos: publica 0 y consume 0.
1. Dónde encaja
Recibe
| De | Qué |
|---|---|
| FT-MIG-03 · Migración inicial de productos desde P360 | Lo migrado desde P360 con su mapa de identificadores, base del cruce. |
| FT-MIG-01 · Perfilado y limpieza previa | Lo que no pasa, con su regla y su destino, y la política para lo que llega de otra fuente. |
Entrega
| A | Qué |
|---|---|
| PE-M · Producto migrado | Los faltantes cargados desde la fuente elegida, con su enriquecimiento, su categoría y su origen, o en cuarentena si llegan incompletos. |
| FT-CAT-03 · Categorización de productos | Los faltantes que llegaron sin categoría, en la tarea Category, para que el equipo de categorías complete sólo lo pendiente. |
Tareas que abre o cierra: Category.
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 | Entrada Única · Vendor Center | MS-03 Migración y convivencia (por el BFF) | Lanza el cruce por variante con fecha de corte | API-03-001 |
| 2 | MS-03 Migración y convivencia | Tienda en línea | Lee el universo de la tienda por variante | — |
| 3 | Archivos e imágenes (almacén y CDN) | MS-03 Migración y convivencia | Entrega la extracción completa de Entrada Única y Vendor | — |
| 4 | MS-03 Migración y convivencia | Base pim | Cruza por llave y aparta faltantes por universo | — |
| 5 | Entrada Única · Vendor Center | MS-03 Migración y convivencia (por el BFF) | Revisa los faltantes por grupo y fuente posible | API-03-003 |
| 6 | Administración del catálogo | Entrada Única · Vendor Center | Decide por grupo: migrar, cuarentena o excluir | — |
| 7 | Entrada Única · Vendor Center | MS-03 Migración y convivencia (por el BFF) | Lanza la remediación en ensayo | API-03-001 |
| 8 | Gobierno de Datos | Entrada Única · Vendor Center | Confirma por escrito el resultado del ensayo | — |
| 9 | Entrada Única · Vendor Center | MS-03 Migración y convivencia (por el BFF) | Registra la confirmación con su referencia | API-03-011 |
| 10 | MS-03 Migración y convivencia | Tienda en línea | Lee categoría y enriquecimiento de cada faltante | — |
| 11 | MS-03 Migración y convivencia | MS-02 Producto | Carga la familia con su categoría y su origen | API-02-056 |
| 12 | MS-02 Producto | Base pim | Abre Category a lo que llegó sin categoría | — |
3.1 Universos fuera de P360
3.2 Si una remediación sale mal
4. Si algo sale mal
- Producto y SKU no coinciden entre fuentes. El cruce se hace por variante y la regla de qué es producto y qué es SKU queda escrita y confirmada antes de cargar; lo que no cuadra va a cuarentena con su motivo.
- Un faltante llega sin categoría. Entra con la tarea Category abierta y el equipo de categorías sólo completa lo pendiente; no se recaptura nada más.
- No hay confirmación escrita. La remediación se queda en ensayo: sin la firma de Gobierno de Datos la corrida no carga nada.
- Una remediación cargó familias equivocadas. Cada familia lleva el ID de su corrida: se recarga con la marca de cuarentena, sale de la publicación y nada se borra.
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 (7)
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-03-001 | POST /api/v2/migration/runs | Lanzar el cruce y la remediación, primero en ensayo | FT-MIG-01 · Perfilado y limpieza previa |
| API-03-002 | GET /api/v2/migration/runs/{runId} | Ver qué cargó una corrida de remediación | FT-MIG-01 · Perfilado y limpieza previa |
| API-03-003 | GET /api/v2/migration/reconciliation?runId= | Faltantes por universo y diferencias del cruce | FT-MIG-02 · Migración de plantillas, atributos y listas de valores |
| API-03-004 | GET /api/v2/migration/quarantine | Cuarentena de lo que llegó incompleto | FT-MIG-03 · Migración inicial de productos desde P360 |
| API-03-006 | GET /api/v2/migration/id-map?legacyId=&system= | Traducir ID de Entrada Única u Omega a la llave nueva | FT-MIG-03 · Migración inicial de productos desde P360 |
| API-03-011 | POST /api/v2/migration/runs/{runId}/signoffs | Registrar la confirmación escrita y las decisiones por grupo | FT-MIG-01 · Perfilado y limpieza previa |
| API-02-056 | POST /internal/product/bulk-load/products | Cargar la familia faltante con su categoría y su origen | FT-ARQ-01 · Núcleo headless |
6. Eventos
Esta épica no publica ni consume eventos.
7. Datos
Cada colección tiene un solo dueño, el único que escribe en ella.
| Colección | Dueño | Qué guarda | Esta épica |
|---|---|---|---|
mig_runs | MS-03 | Cada corrida de migración con sus conteos. | escribe |
mig_reconciliation | MS-03 | Las diferencias entre P360 y el Nuevo PIM durante la convivencia. | escribe |
mig_issues | MS-03 | Lo que no se pudo migrar y por qué. | escribe |
products | MS-02 | La familia del producto con sus variantes, valores, imágenes (URL), clasificaciones, estado, tareas abiertas y rechazos. | escribe |
8. Historias que cubre
| Historia | Prioridad | Cómo la cubre |
|---|---|---|
| FT-MIG-05·H1 · Identificar faltantes | P1 | pasos 1, 2, 3, 4, 5; API-03-001, API-03-003 |
| FT-MIG-05·H2 · Cargar desde la fuente más completa | P1 | pasos 10, 11, 12; API-02-056 |
| FT-MIG-05·H3 · Respaldo escrito | P1 | pasos 7, 8, 9; API-03-011 |
| FT-MIG-05·H4 · Universos fuera de P360 | P2 | flujo «Universos fuera de P360»; API-03-006 |
9. Decisiones de esta épica
Las tomó el TL como arquitecto; quedan como [Propuesta] hasta que el equipo de la épica las revise.
- D-MIG-05-1. La remediación es una corrida más de MS-03: un cruce (CROSS_CHECK) y una carga (REMEDIATION) con ensayo, conciliación y firma. Nunca un script suelto. Por qué: Así queda idempotente, conciliada y reversible, con la misma traza que la migración principal. Se apoya en RF-MIG-04, DEC-96.
- D-MIG-05-2. La fuente se elige por universo. Lo que vive en P360 sale de P360 (FT-MIG-03) y, si falta en la tienda, se republica después del corte en lugar de cargarse. Lo de Entrada Única sin dueño o con dueño STEP sale de los datos de Entrada Única que se mudan al PIM en R2, completado con la categoría y el enriquecimiento que ya tiene la tienda. Lo que sólo vive en Omega sale de Omega con su marca. ATG no se usa como fuente en el Nuevo PIM. Por qué: La fuente oficial es la base de P360, pero no trae lo que nunca llegó a P360; la tienda tiene la categoría que no se quiere recapturar, y ATG se apaga con su propio decomiso. Se apoya en PEN-68, PD-19, DEC-73, DEC-ARQ-06.
- D-MIG-05-3. Confirmación escrita antes de cargar: la corrida de remediación sólo pasa del ensayo a la carga con la firma de Gobierno de Datos y su referencia (correo, ticket o documento), y TI registra la fecha de remediación en la misma corrida. Por qué: Es la decisión firme del taller y deja la evidencia en el mismo lugar que la carga. Se apoya en DEC-96, PEN-126, PEN-111.
- D-MIG-05-4. El cruce cubre el universo completo por variante, con fecha de corte y sin filtros de fecha; lo de Entrada Única se fecha por la hora de su ObjectId, porque createdAt sólo existe en el 13 %. Por qué: Un filtro de fecha ya dejó casos fuera en una corrección anterior. Se apoya en DEC-93, DUD-26.
- D-MIG-05-5. Lo que llega sin categoría no se recaptura: entra con la tarea Category y el equipo de categorías sólo completa lo pendiente. Por qué: El objetivo de la remediación es no recapturar lo que la tienda ya tenía. Se apoya en RF-MIG-04, DEC-73.
Qué falta decidir
| ID | Qué falta |
|---|---|
| PD-19 | Qué hacer por grupo con lo que no está en P360. |
| DUD-26 | Cruce por llave de los productos de Entrada Única sin dueño y de dueño STEP. |
| DUD-15 | Inventario y fuente de lo que sólo vive en Omega. |
También siguen abiertos: PEN-68, Ratificar la fuente por universo (Entrada Única, tienda u Omega); PEN-150, Si los 200 SKU de stock out de Esfera son migración o producto nuevo; PEN-121, Validar los 20 casos del universo sin migrar.
Fuentes
- [D]
trazabilidad/features/FT-MIG-05-remediacion-productos-faltantes.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.