US-042 — Catálogo de servicios logísticos

Detalle de la historia¶

Historia¶

Como administrador de FleteChat, quiero gestionar el catálogo de servicios logísticos (búsqueda en origen, aduanas, envío, entrega y los que se agreguen) con sus estatus y su aplicabilidad por tipo de operación, modalidad e Incoterm, para adaptar el motor conversacional al portafolio real de FleteChat sin intervención técnica cada vez que se agrega o modifica un servicio.

Persona de usuario¶

Aplica exclusivamente al rol admin. El rol operator no gestiona el catálogo: consume los servicios durante la cotización y embarque. El rol price_manager actualiza los precios de los servicios, pero no los crea ni los desactiva.

Contexto de negocio¶

FleteChat no ofrece un único servicio: combina búsqueda en origen, aduanas, envío y entrega, y cada uno aplica a distintas operaciones. Un envío aéreo con Incoterm FOB tiene servicios distintos a un marítimo FCL con Incoterm DDP. El catálogo declara qué servicios existen y cuándo aplican; el motor de cotización y el ensamblador de embarque consultan el catálogo para armar el alcance de cada operación sin reglas duras en código.

El catálogo vive bajo control del admin porque un cambio en él impacta todo: cotizaciones nuevas, secuencias de estatus (ver US-027), instructivos, reportes. Los cambios se propagan a operaciones nuevas; operaciones ya emitidas mantienen el snapshot del catálogo vigente al momento de la emisión (ver PR-118 de US-027).

Criterios de aceptación¶

Acceso y campos¶

1. El backoffice ofrece una sección "Servicios logísticos" accesible exclusivamente al rol admin; operator y price_manager reciben 403 si intentan acceder en modo edición. El rol price_manager puede consultar el catálogo en modo lectura para gestionar precios.
2. Cada servicio tiene los campos: nombre (único), descripción, aplicabilidad (combinaciones válidas de tipo de operación, modalidad e Incoterm; ver PR-171), estatus asociados con su posición relativa en la secuencia del embarque (ver US-027 para composición dinámica), obligatorio/opcional, estado activo/inactivo y timestamps.

Ciclo de vida¶

1. El admin puede crear, editar y desactivar servicios. No hay borrado físico (ver PR-170); desactivar conserva el registro y la relación con operaciones históricas.
2. Un servicio desactivado no aparece en cotizaciones nuevas, pero sigue presente en las históricas con la etiqueta "desactivado".
3. Editar la aplicabilidad o los estatus de un servicio activo afecta únicamente a operaciones nuevas. Cotizaciones y embarques ya emitidos mantienen el snapshot del servicio al momento de emitirse (ver US-027 para la secuencia de estatus y US-014 para vigencia de cotizaciones).

Validación de la aplicabilidad¶

1. La UI valida que la aplicabilidad no genere ambigüedades no resueltas: si dos servicios aportan el mismo estatus al mismo punto de la secuencia para una combinación dada, el admin debe resolver el orden explícitamente (ver PR-119 de US-027).
2. Un servicio puede declararse obligatorio para una combinación (por ejemplo, aduanas en FOB marítimo) o opcional seleccionable. El motor de cotización exige los obligatorios y expone los opcionales para que el cliente los elija (ver US-009).

Audit log¶

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

Edge cases¶

• Admin desactiva un servicio con embarques activos que lo contienen. Los embarques en curso siguen funcionando (snapshot); el servicio no aparece en nuevas cotizaciones. La UI avisa al admin con el número de embarques activos afectados antes de confirmar.
• Admin agrega un estatus nuevo a un servicio activo. Los embarques en curso mantienen su secuencia congelada (PR-118 de US-027); los nuevos incluyen el estatus.
• Admin intenta renombrar un servicio a un nombre existente. El sistema rechaza por restricción de unicidad.
• Combinación de Incoterm + modalidad + tipo de operación que no tiene servicios obligatorios configurados. El motor de cotización retorna "combinación no soportada" (ver US-033) y activa handoff con consentimiento. El admin debe completar el catálogo para esa combinación.
• Servicio obligatorio cambia a opcional en una edición. Cotizaciones ya emitidas mantienen su snapshot; nuevas cotizaciones permiten al cliente elegir si lo incluye.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P0 — catálogo estructural del motor de cotización y del ensamblador de embarque.
• 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-170 — Soft delete de servicios. Un servicio nunca se borra físicamente: se desactiva. El registro y los vínculos históricos (cotizaciones, embarques, secuencias de estatus) se preservan para auditoría y reportes.
• PR-171 — Aplicabilidad declarativa. La aplicabilidad de un servicio se declara como combinaciones explícitas de tipo de operación, modalidad e Incoterm. El motor no infiere aplicabilidad por criterio implícito.
• PR-172 — Estatus por servicio declara la secuencia. Los estatus que aporta cada servicio y su posición relativa en la secuencia del embarque se declaran en el catálogo del servicio. Ver US-027 para la composición dinámica por embarque.

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