US-045 — Import de precios desde Excel

Detalle de la historia¶

Historia¶

Como gestor de precios de FleteChat con actualizaciones de gran volumen, quiero exportar una plantilla Excel base con todas las combinaciones válidas según la configuración actual, llenarla con precios y luego importarla con preview de cambios antes de aplicar, para actualizar cientos de entradas sin editar una por una, sin inventar combinaciones inválidas y sin arriesgar cambios no intencionales.

Persona de usuario¶

Aplica al rol price_manager y al rol admin. Operator no importa listas.

Contexto de negocio¶

Una renegociación con un proveedor típicamente modifica decenas o cientos de entradas de una lista. Hacerlo entrada por entrada desde la UI (ver historia de actualización manual) es impracticable. El import desde Excel permite al price_manager preparar el archivo offline (con sus herramientas de cálculo), subirlo, revisar un preview de los cambios que provocará y confirmar o cancelar.

Para evitar que el price_manager arme el Excel desde cero (con el riesgo de inventar combinaciones inválidas o perder combinaciones obligatorias), el sistema ofrece un export de plantilla base: descarga un Excel con todas las combinaciones válidas según la configuración actual del sistema (modalidades, Incoterms, tipos de operación, servicios y sus reglas de aplicabilidad; ver US-042 y US-043) con las columnas de precio vacías. El price_manager llena los valores que le corresponden y re-sube el archivo. El ciclo export → llenar → import con preview cierra el flujo de actualización masiva.

El preview es obligatorio (ver PR-178): ningún cambio masivo se aplica sin revisión explícita. Muestra altas, modificaciones (con valor previo y nuevo), eventuales eliminaciones si el archivo las solicita, y filas rechazadas con motivo. El price_manager ve en un vistazo si el archivo tiene sentido antes de tocar la base de datos.

Criterios de aceptación¶

Export de plantilla base¶

1. El backoffice ofrece la acción "Descargar plantilla Excel" dentro de la sección de listas de precios. El price_manager elige la lista destino (existente) y el modo de export: (a) plantilla vacía (columnas de precio sin valores) o (b) plantilla con precios actuales (snapshot de los valores vigentes para edición parcial).
2. La plantilla exportada contiene todas las combinaciones válidas según la configuración actual del sistema: cruza el catálogo de servicios (US-042), modalidades, Incoterms y tipos de operación (US-043) aplicando las reglas de aplicabilidad declaradas (PR-171). Combinaciones no permitidas por la configuración no aparecen en la plantilla.
3. El layout de la plantilla coincide bit a bit con el layout que el import acepta (ver PR-180 y PR-203): una plantilla descargada, llenada y re-subida se parsea sin ajustes.
4. El export deja registro en el audit log con actor, timestamp, lista destino, modo (vacía / con precios) y cantidad de filas generadas.

Carga del archivo¶

1. El backoffice ofrece la acción "Importar lista desde Excel" dentro de la sección de listas de precios. Al elegirla, el price_manager selecciona la lista destino (existente) y sube el archivo.
2. El import acepta un archivo Excel con el layout documentado (ver PR-180): hoja, columnas, tipos y claves documentadas en la plantilla que FleteChat mantiene y exporta (ver AC 3).
3. El sistema parsea el archivo y arma el preview sin tocar la base; si el archivo tiene un layout distinto, el preview no se genera y el sistema devuelve mensaje claro con las diferencias detectadas.

Preview de cambios¶

1. El preview muestra, por cada fila del archivo, la acción propuesta: alta (nueva entrada), modificación (valor anterior vs. nuevo), sin cambios (entrada existente e idéntica), o rechazada (motivo). El preview es navegable con filtros por acción.
2. El preview resalta visualmente cambios con delta porcentual alto (umbral configurable, compartido con US-044) para prevenir errores.
3. Ninguna modificación se aplica sin confirmación explícita del price_manager (ver PR-178). Cancelar el preview descarta el archivo sin dejar rastro en la base.

Aplicación transaccional¶

1. Al confirmar, el sistema aplica los cambios transaccionalmente (ver PR-179): o se aplican todos los cambios confirmados, o ninguno si hay un fallo a mitad del procesamiento. No queda la lista en estado inconsistente.
2. Tras aplicar, el sistema muestra el resumen final con cantidad de altas, modificaciones y filas rechazadas, y deja el audit log con el detalle.

Audit log¶

1. Cada import queda registrado con: actor, timestamp, lista destino, nombre del archivo, resumen (altas, modificaciones, rechazadas), y acceso al preview confirmado para reconstrucción ante necesidad de auditoría. Cada modificación a nivel de entrada también deja entrada en el audit log (compatible con el formato de US-044, AC 10).

Edge cases¶

• Price_manager intenta generar el Excel desde cero sin usar la plantilla. Es posible si el archivo respeta el layout documentado; el import lo aceptará. Filas con combinaciones no válidas según la configuración actual se marcarán como rechazadas en el preview, alineado con el comportamiento del export (la plantilla no las ofrece, el import las filtra si aparecen).
• Configuración del sistema cambia entre el export de la plantilla y el import (por ejemplo, el admin desactiva un Incoterm o agrega una modalidad). El import valida contra la configuración vigente al momento del import: filas con combinaciones que dejaron de ser válidas se rechazan con motivo "combinación ya no permitida"; combinaciones nuevas que la plantilla descargada antes no incluía pueden agregarse manualmente al archivo y el preview las toma como altas válidas.
• Archivo con layout distinto al esperado (columnas renombradas, hoja faltante). El sistema rechaza el archivo con un mensaje descriptivo; no hay preview ni cambios.
• Archivo con duplicados internos (dos filas con la misma combinación clave). El preview marca las filas duplicadas como rechazadas con motivo "duplicada"; el price_manager corrige el Excel y re-sube.
• Archivo que intenta eliminar entradas (fila marcada como "eliminar"). El preview lo refleja como desactivación (soft delete, alineado con PR-170 análogo para listas); no hay borrado físico.
• Fallo transaccional a mitad de aplicación (timeout de DB, interrupción). La transacción hace rollback; el audit log registra el intento fallido y el price_manager reintenta.
• Preview generado y no confirmado durante largo tiempo (el price_manager abrió el preview y se fue). El preview caduca (ventana configurable) y obliga a re-subir el archivo para garantizar que no se aplican cambios sobre una foto desactualizada de la lista.
• Archivo afecta entradas cuya lista fue modificada manualmente después de generar el preview. Al confirmar, el sistema valida que los valores "anteriores" del preview coincidan con los actuales de la lista; si hay desajuste, aborta con mensaje y pide re-subir.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P1 — indispensable para operar a volúmenes reales de actualización de precios.
• Tipo: feature

Premisas¶

La historia está redactada bajo las siguientes premisas. Si alguna cambia, la historia debe revisarse y ajustarse en consecuencia. Todas deben ser confirmadas por el cliente antes de cerrar la historia.

• PR-178 — Preview obligatorio antes de aplicar. Ningún import aplica cambios sin confirmación explícita del price_manager sobre el preview. Cancelar descarta el archivo sin huella.
• PR-179 — Transaccionalidad del import. La aplicación de los cambios confirmados es atómica: o se aplican todos o ninguno. En caso de fallo parcial, el sistema hace rollback.
• PR-180 — Layout documentado de Excel. El archivo de import respeta un layout documentado (plantilla oficial de FleteChat). Cambios de layout requieren actualizar la plantilla y la lógica de parseo antes de usarse.
• PR-203 — Export de plantilla base con combinaciones válidas. FleteChat ofrece un export de plantilla Excel en dos modos: (a) vacía (sin precios), (b) con precios actuales (snapshot). La plantilla contiene todas las combinaciones válidas según la configuración actual del sistema (aplicabilidad de servicios, modalidades, Incoterms, tipos de operación) y usa el mismo layout que el import acepta (PR-180). Combinaciones no permitidas por la configuración no aparecen en la plantilla.
• PR-227 — Sanitización anti-inyección de celdas. El parser del import sanitiza el contenido de cada celda: celdas cuyo valor (tras recortar espacios) empiece con los caracteres =, +, @, - o \t se consideran potencial fórmula y se tratan como texto neutralizado (prefijando un apóstrofe o descartando la celda según la política configurada). Si el preview detecta celdas sanitizadas en campos que debían ser numéricos o texto plano, las marca como filas con advertencia y el price_manager debe confirmar o rechazar. El mismo tratamiento aplica al export de la plantilla (PR-203) y a cualquier export derivado del preview, de modo que abrir un CSV/Excel resultante no dispare ejecución de fórmulas maliciosas.

Refinamiento y Definition of Ready¶

Notas¶

Checklist¶

• ✅ Historia escrita en formato Como / Quiero / Para
• ✅ Persona de usuario identificada
• ✅ Contexto de negocio documentado
• ✅ Criterios de aceptación observables y pass/fail
• ✅ Edge cases relevantes listados
• ✅ Tamaño y prioridad asignados
• ⬜ Premisas PR-178 a PR-180, PR-203 y PR-227 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente