US-043 — Catálogos dimensionales

Detalle de la historia¶

Historia¶

Como administrador de FleteChat, quiero gestionar los catálogos de modalidades (aéreo, LCL, FCL-20', FCL-40', etc.), Incoterms (FOB, CIF, DDP, DAP…) y tipos de operación (importación, exportación, tránsito, …), para reflejar los cambios del negocio en el motor sin depender de intervención técnica en cada ajuste.

Persona de usuario¶

Aplica exclusivamente al rol admin. Operator, price_manager y cualquier otro rol sólo consumen los catálogos; no los editan.

Contexto de negocio¶

Estos tres catálogos son dimensiones transversales del negocio logístico. Cada cotización, embarque y servicio se describe en términos de una modalidad, un Incoterm y un tipo de operación. Si el negocio abre un nuevo tipo de modalidad (por ejemplo terrestre regional) o suma un Incoterm menos común, debe poder reflejarse en el sistema sin que el equipo técnico intervenga.

Son catálogos estables: pocos cambios al año. Por eso el alcance es CRUD admin, con soft delete para preservar el histórico de operaciones que hagan referencia a valores ya retirados.

Aplicabilidad por ruta (refinamiento 2026-05-26). El feedback del cliente cambió el modelo: las modalidades, los Incoterms y los tipos de operación no aplican globalmente a todas las rutas. Algunas combinaciones son posibles para ciertas rutas y no para otras (por ejemplo, una modalidad terrestre regional aplica entre ciudades del mismo bloque continental pero no entre continentes; un Incoterm específico tiene sentido para una ruta marítima y no para una aérea). En consecuencia, los tres catálogos siguen siendo globales como diccionarios de valores válidos, pero la aplicabilidad concreta se configura por ruta o familia de rutas (origen → destino). El motor de cotización consulta esta aplicabilidad antes de ofrecer una combinación; las combinaciones no soportadas por la ruta activan handoff conforme a US-033.

Criterios de aceptación¶

Acceso y campos comunes¶

1. El backoffice ofrece tres secciones independientes (Modalidades, Incoterms, Tipos de operación) accesibles exclusivamente al rol admin. Otros roles que intenten acceder en modo edición reciben 403.
2. Cada entrada de cualquiera de los tres catálogos tiene: código corto (único, ej. LCL, FOB, IMP), nombre (texto corto), descripción (texto libre), estado activo/inactivo y timestamps.

Ciclo de vida¶

1. El admin puede crear, editar y desactivar entradas de los tres catálogos. No hay borrado físico (ver PR-173); desactivar conserva el registro y los vínculos históricos.
2. Una entrada desactivada no aparece como opción en nuevas cotizaciones, embarques ni configuraciones de catálogos dependientes (servicios, niveles corporativos). Las operaciones históricas que la referencian siguen intactas.
3. El admin puede reactivar una entrada previamente desactivada; vuelve a estar disponible sin perder su historial.

Unicidad y referencias¶

1. El código corto es único por catálogo; el sistema rechaza crear o renombrar a un código ya usado (activo o desactivado) para preservar trazabilidad.
2. Desactivar una entrada que es referenciada por reglas de aplicabilidad de servicios (ver US-042), por listas de precios (Epic 8), o por asignaciones corporativas no rompe esas referencias históricas; sí impide usarla en nuevas configuraciones. La UI resume el impacto antes de confirmar la desactivación.

Audit log¶

1. Cada alta, edición, desactivación y reactivación queda registrada en el audit log con actor (admin), timestamp y diff.

Aplicabilidad por ruta o familia de rutas¶

1. Además del catálogo global, el admin gestiona una matriz de aplicabilidad que define, para cada ruta o familia de rutas (origen → destino), qué modalidades, qué Incoterms y qué tipos de operación están disponibles para cotizar.
2. El motor de cotización consulta la matriz antes de ofrecer opciones al cliente. Una combinación válida globalmente pero no aplicable a la ruta se trata como "combinación no soportada" y activa handoff con consentimiento explícito (ver US-033 Camino 2).
3. La matriz se carga inicialmente en bootstrap (parte del seed del sistema) y se actualiza desde el backoffice por el admin. El alcance concreto de combinaciones depende de la matriz de servicios/tarifas de Zeverium (en progreso al 2026-05-27 — ver §7.3 del análisis de impacto); el modelo de datos y la UI pueden construirse en paralelo a la entrega de la matriz por Zeverium.

Edge cases¶

• Admin desactiva un Incoterm referenciado por reglas de aplicabilidad activas (ver US-042). La UI muestra cuántas reglas lo usan y advierte que esas reglas dejarán de aceptar nuevas combinaciones con ese Incoterm; el admin confirma o ajusta las reglas antes.
• Admin intenta crear una modalidad con un código ya desactivado. Rechazado por unicidad. El admin puede reactivar la desactivada o elegir otro código.
• Cliente pide cotización con una modalidad recién activada para la que no hay servicios configurados. El motor retorna "combinación no soportada" (ver US-033) y activa handoff con consentimiento. El admin debe completar servicios para esa modalidad.
• Tipo de operación renombrado (por ejemplo, "Importación" → "Importación comercial"). El código corto permanece igual; el nombre visible se actualiza en UI y mensajes nuevos. Operaciones históricas muestran el nuevo nombre porque la referencia es por código.

Tamaño, prioridad y tipo¶

• Tamaño: S
• Prioridad: P1 — sin estos catálogos el motor de cotización no opera; cambios posteriores son poco frecuentes pero deben ser accionables por admin.
• 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-173 — Soft delete de catálogos dimensionales. Las entradas de modalidades, Incoterms y tipos de operación nunca se borran físicamente: se desactivan. Los vínculos históricos con cotizaciones, embarques y configuraciones se preservan.
• PR-174 — Admin único gestor. La gestión de estos tres catálogos es exclusiva del rol admin. Operator y price_manager no tienen permisos de escritura.
• PR-239 — Aplicabilidad por ruta o familia de rutas. Las modalidades, los Incoterms y los tipos de operación se configuran por ruta (o familia de rutas). El catálogo global define los valores válidos; la matriz de aplicabilidad (ruta → combinaciones disponibles) gobierna lo que el motor ofrece al cliente. El alcance real depende de la matriz de servicios/tarifas que está entregando Zeverium (en progreso al 2026-05-27, §7.3 del análisis de impacto).

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