US-044 — Actualización manual de precios

Detalle de la historia¶

Historia¶

Como gestor de precios de FleteChat, quiero actualizar manualmente las listas de precios desde el backoffice, con tarifas fijas o variables y costo mínimo donde aplique, para mantener el pricing alineado con los acuerdos comerciales sin depender del equipo técnico.

Persona de usuario¶

Aplica al rol price_manager y al rol admin (admin hereda los permisos de price_manager). El rol operator no edita precios: los consume a través del motor de cotización.

Contexto de negocio¶

Los precios de FleteChat no son uno solo: hay una lista base y varias listas corporativas asociadas a los niveles del Epic 7. Cada lista tiene muchas entradas (combinaciones de modalidad + ruta + servicio), y cada entrada puede ser una tarifa fija (un precio) o una tarifa variable (por unidad de peso, volumen, etc.) con un costo mínimo. El gestor de precios actualiza estos valores cuando cambian los acuerdos con proveedores o cuando se renegocian contratos.

La edición es manual: el price_manager entra al backoffice, encuentra la lista, encuentra la entrada, cambia el valor y guarda. Para volúmenes grandes existe el import desde Excel (ver historia correspondiente). Los precios nuevos aplican a cotizaciones emitidas desde el cambio en adelante; las ya emitidas mantienen su snapshot (ver US-010 y PR-176).

Criterios de aceptación¶

Acceso y estructura¶

1. El backoffice ofrece una sección "Listas de precios" accesible a price_manager y admin. Al rol operator se le deniega el acceso en modo edición con un mensaje claro de permisos insuficientes; el acceso de sólo lectura está deshabilitado por defecto y sólo se habilita si FleteChat lo activa explícitamente para el rol.
2. Cada lista tiene: nombre (único), descripción, estado activo/inactivo, moneda, timestamps, y un conjunto de entradas identificadas por su combinación única (modalidad + ruta + servicio + parámetros aplicables).

Tipos de tarifa¶

1. Cada entrada soporta dos tipos de tarifa: a. Fija: un monto único en la moneda de la lista. b. Variable: un monto por unidad (por ejemplo, USD/kg, USD/m³) más un costo mínimo por debajo del cual se cobra el mínimo (ver PR-177).
2. Las tarifas variables requieren declarar unidad de medida (coherente con el catálogo de unidades cargado en US-041) y el costo mínimo. La UI valida que el monto por unidad y el mínimo sean no negativos.

Ciclo de vida¶

1. El price_manager puede crear, editar y desactivar listas y entradas. No hay borrado físico; desactivar preserva histórico y snapshots de cotizaciones (ver PR-176).
2. Una lista desactivada no se puede asignar a niveles corporativos nuevos (ver US-037). Niveles que ya la usan siguen operando con snapshot en cotizaciones emitidas; en cotizaciones nuevas el admin debe asignar otra lista al nivel.
3. Editar el precio de una entrada activa afecta únicamente a cotizaciones emitidas desde ese momento. Cotizaciones anteriores mantienen el precio del snapshot.

Validaciones¶

1. La UI rechaza valores negativos, tarifas variables sin unidad o sin costo mínimo, y entradas con combinación duplicada dentro de la misma lista.
2. La UI advierte visualmente cuando la edición altera precios con un delta porcentual alto respecto al valor previo (umbral declarado en PR-249, default 30 %, configurable). Cuando el delta supera el umbral, la UI exige segunda confirmación explícita ("Guardar de todos modos") antes de persistir el cambio.

Audit log¶

1. Cada alta, edición y desactivación queda registrada con actor (price_manager o admin), timestamp, valor anterior y valor nuevo. El audit log es la fuente de verdad para reconstruir el historial de precios de una entrada.

Costo máximo opcional¶

1. Cada tarifa variable admite un costo máximo opcional (campo nuevo, además del costo mínimo de PR-177). Cuando está presente, el monto calculado se acota al máximo si el cálculo por unidad lo supera. Cuando el campo está vacío, no hay tope superior. La semántica del rango (mínimo, monto por unidad, máximo) queda definida en PR-248.

Edge cases¶

• Price_manager intenta usar un Incoterm, modalidad o servicio desactivado (ver US-042, US-043). El sistema filtra los desactivados del selector de entrada; entradas históricas que los referencian siguen funcionando.
• Admin desactiva una lista asignada a un nivel corporativo activo. La UI advierte cuántos niveles usan la lista y exige que se asigne una lista alternativa antes de desactivar, o confirma la desactivación sabiendo que las cotizaciones nuevas para esos niveles caerán a lista base.
• Edición accidental con un valor desproporcionado (un cero de más). La alerta de delta alto (AC 9) obliga a confirmar; el audit log registra ambos valores para permitir reversión.
• Entrada nueva para una combinación que aún no tiene servicios configurados (ver US-042). El selector filtra combinaciones inválidas; el price_manager no puede crear entradas huérfanas.
• Cambio de moneda de una lista con entradas existentes. No permitido en v1.0: cambiar la moneda obliga a crear una lista nueva. La UI explica la restricción.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P0 — sin listas de precios operables no hay cotizaciones.
• 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-175 — Gestión por price_manager y admin. Las listas de precios son gestionadas por el rol price_manager (y admin, que hereda). Operator no tiene permisos de escritura sobre listas ni entradas.
• PR-176 — Snapshot de precio en cotización. Cada cotización graba el precio vigente al momento de emisión. Cambios posteriores en la lista no alteran cotizaciones ya emitidas.
• PR-177 — Tarifas variables con costo mínimo. Las tarifas variables declaran un monto por unidad y un costo mínimo obligatorio. Por debajo del mínimo se cobra el mínimo; la unidad de medida debe existir en el catálogo de unidades.
• PR-247 — Warning por delta de tarifa. Toda edición de tarifa cuyo delta supere el umbral declarado en PR-249 dispara un warning visual y exige segunda confirmación antes de guardar. El objetivo es prevenir errores de tipeo. El delta se calcula como abs(nuevo - anterior) / anterior cuando el valor anterior es distinto de cero; cuando el valor anterior es cero, la segunda confirmación se exige siempre.
• PR-248 — Costo máximo opcional para tarifas variables. Las tarifas variables admiten un costo máximo opcional además del costo mínimo de PR-177. Cuando el campo tiene valor, el monto final calculado se acota al máximo si el cálculo por unidad lo supera; cuando el campo está vacío, no hay tope superior. La semántica del rango efectivo es: min(max(mínimo, monto_por_unidad × cantidad), máximo) cuando hay máximo, o max(mínimo, monto_por_unidad × cantidad) cuando no.
• PR-249 — Umbral de delta alto, configurable por FleteChat. El umbral que dispara el warning de PR-247 es parámetro global de FleteChat, con default 30 %. Configurable por operador con rol autorizado desde parámetros globales del sistema.

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-175 a PR-177 y PR-247 a PR-249 confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente