US-022 — Distribución automática de instructivos

Detalle de la historia¶

Historia¶

Como cliente de FleteChat que acaba de aprobar formalmente una cotización, quiero que los tres instructivos (proveedor, operador logístico, equipo FleteChat) se generen y se distribuyan automáticamente al confirmar la aprobación, para que la operación arranque sin demoras por acciones manuales y sin que yo tenga que reenviar nada a nadie.

Persona de usuario¶

Aplica a todo cliente verificado cuya aprobación formal acaba de registrarse (Paso 3; ver historia de aprobación por WhatsApp). También es punto de observabilidad del equipo operativo de FleteChat, que monitorea el éxito o los fallos de distribución desde el backoffice.

Contexto de negocio¶

Sin distribución automática, la aprobación formal dejaría el embarque "colgado": PDFs generados en el sistema pero sin llegar a sus destinatarios. El operador de FleteChat tendría que revisar manualmente, copiar correos, adjuntar PDFs y enviarlos, aumentando el tiempo entre aprobación y ejecución y abriendo la puerta a errores.

La distribución automática resuelve eso con un solo trigger (el click de aprobación formal): el sistema orquesta la generación y el envío de los tres PDFs a sus destinatarios por los canales acordados por cada historia (correo al proveedor y al operador logístico; almacenamiento interno del PDF del equipo FleteChat). Cualquier fallo parcial queda aislado: un canal que falla no bloquea a los otros, y los reintentos permiten recuperar fallos transitorios.

Criterios de aceptación¶

Trigger y orquestación¶

1. El click de aprobación formal del embarque (Paso 3; ver historia de aprobación por WhatsApp) dispara un único trigger que orquesta: (a) la generación del PDF del proveedor, (b) la generación del PDF del operador logístico, (c) la generación del PDF interno para el equipo FleteChat, y (d) los envíos por los canales definidos en cada historia correspondiente.
2. El trigger es idempotente: si por cualquier razón se re-dispara con el mismo embarque ya procesado, el sistema no duplica envíos ni regenera PDFs sin motivo; el operador ve en el audit log que la re-ejecución se detectó y se descartó.

Aislamiento entre canales¶

1. Un fallo en un canal no bloquea a los otros. Si, por ejemplo, el correo al proveedor falla, el correo al operador logístico y la puesta del PDF interno siguen su curso; el fallo del canal del proveedor queda registrado para reintento.
2. Cada envío registra su resultado (éxito, fallo transitorio, fallo permanente) en el audit log del embarque con destinatario, canal, timestamp y, cuando aplica, causa del fallo.

Reintentos¶

1. Ante fallos transitorios (proveedor de correo momentáneamente caído, timeout puntual), FleteChat aplica reintentos automáticos con política definida en PR-101.
2. Si todos los reintentos fallan en un canal crítico (correo al proveedor o al operador logístico), el embarque pasa a un estado observable distribución incompleta que aparece en el backoffice del operador de FleteChat, con el detalle del canal fallido y la acción sugerida.
3. La distribución incompleta no revierte la aprobación formal: el embarque existe, el número ENNN se emitió, el cliente fue notificado. La operación queda pendiente de completar la distribución con intervención del operador (reenvío manual, corrección de email, etc.).

Visibilidad por embarque¶

1. El backoffice muestra, por cada embarque, el estado de distribución con desglose por destinatario (proveedor, operador logístico, equipo interno) y canal (correo, WhatsApp cuando aplica), con los timestamps y resultados.
2. El operador puede reenviar manualmente cualquier PDF a su destinatario desde la ficha del embarque (cada historia define el alcance del reenvío; ver historias correspondientes).

Cliente como destinatario adicional¶

1. La distribución incluye al cliente final como destinatario adicional del instructivo al proveedor (US-019 AC 7), por correo a su email verificado. El cliente no recibe el instructivo del operador logístico (ver US-020 AC 12) ni el instructivo interno (US-021 PR-099).

Aliados del operador logístico¶

1. Cuando el operador logístico tiene aliados configurados (uno en origen y/o uno en destino, PR-236), la distribución envía el instructivo del operador también al aliado correspondiente al tramo del embarque. Los aliados son invisibles al cliente final (PR-235): no se notifica al cliente su existencia, no aparecen en el portal ni en el chat.

Versionado de instructivos emitidos ante cambios¶

1. Cuando un dato del embarque cambia después de la emisión y afecta a un instructivo ya distribuido, FleteChat regenera el instructivo afectado con versión incrementada (v1, v2, v3, …) y lo reenvía automáticamente a sus destinatarios. El correo del reenvío incluye un diff legible que resume qué cambió respecto de la versión anterior (campos modificados, valores antes/después).
2. El historial del embarque conserva todas las versiones del instructivo emitidas, con fecha, motivo del cambio (campo origen del cambio) y destinatarios alcanzados por cada versión. Una versión anterior nunca se borra: queda marcada como reemplazada.

Reasignación del operador logístico¶

1. Cuando se reasigna el operador logístico de un embarque (ver US-020 AC 10), la distribución dispara tres acciones automáticas: (a) correo de desasignación al operador anterior (sin el PDF nuevo) y a sus aliados si los tenía; (b) emisión del instructivo actualizado al operador nuevo y a sus aliados; (c) evento en audit log con los dos operadores y la lista de destinatarios alcanzados. El cliente no recibe notificación de la reasignación (responsabilidad operativa interna).

Alertas por falta de avance de distribución¶

1. Si la distribución no se completa (estado distinto de éxito en uno o más canales críticos) tras un umbral configurable de horas hábiles (default sugerido 24 horas hábiles), FleteChat envía recordatorio al cliente por WhatsApp indicando que la operación aún no arrancó por completo y ofreciendo handoff con el operador FleteChat para acelerar.
2. Si la distribución sigue sin completarse al doble del umbral (default 48 horas hábiles), FleteChat envía alerta al operador FleteChat asignado al embarque para intervención directa. Los umbrales son parámetros configurables.

Edge cases¶

• Todos los canales fallan al mismo tiempo (caída simultánea del proveedor de correo durante una ventana puntual). Los reintentos reprograman; el estado global del embarque aparece como distribución incompleta y se alerta al operador. El cliente ya recibió su confirmación por WhatsApp en el Paso 3; la operación material arranca cuando la distribución se completa.
• La generación de un PDF falla por un error transitorio del servicio de render. FleteChat aplica reintentos de generación; si persiste, el embarque pasa a distribución incompleta con el detalle del PDF fallido. Los PDFs que sí se generaron siguen sus envíos.
• El FleteChat reconfiguró el operador logístico entre la aprobación y la distribución. El trigger usa la asignación vigente al momento de la aprobación, no la posterior. Si la reconfiguración ocurre antes de que la distribución corra, se aplica la nueva asignación; si ocurre después, requiere regeneración formal (ver historia del PDF al operador logístico).
• Un canal reporta éxito pero el destinatario nunca recibió (falso positivo del proveedor de correo). La visibilidad del estado no puede detectar este caso; el flujo de respaldo son las historias de reenvío manual desde backoffice.

Tamaño, prioridad y tipo¶

• Tamaño: M
• Prioridad: P0 — sin distribución automática, el tiempo entre aprobación y ejecución se degrada y la operación depende de acciones manuales.
• 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-100 — Trigger único e idempotente. El click de aprobación formal es el único disparador de la generación y distribución. El trigger es idempotente: re-ejecuciones sobre el mismo embarque no duplican envíos.
• PR-101 — Política de reintentos por canal. Cada canal aplica reintentos automáticos ante fallo transitorio con política definida por FleteChat (parámetros sugeridos por defecto: hasta 3 reintentos con backoff exponencial de 1, 5 y 30 minutos). Parámetros son configurables.
• PR-102 — Aislamiento entre canales. Un fallo en un canal no bloquea a los otros. Cada envío se trata como una unidad independiente; el éxito global es el AND de los canales críticos (proveedor y operador logístico) más el PDF interno almacenado.
• PR-103 — Estado observable de distribución. Cada embarque tiene un estado de distribución visible en el backoffice del operador, con desglose por destinatario y canal. Un estado distribución incompleta no revierte la aprobación formal.
• PR-104 — Reenvío manual por operador. El operador de FleteChat puede reenviar manualmente cualquier PDF a su destinatario desde la ficha del embarque, con la acción registrada en el audit log.
• PR-235 — Aliado del operador: destinatario operativo invisible al cliente final. Definida en US-012. En la distribución, los aliados reciben el instructivo del operador como destinatarios adicionales sin que el cliente final sea informado de su existencia.
• PR-236 — Un aliado por origen y un aliado por destino por operador. Definida en US-012. Aplica a la distribución: cada embarque alcanza, como máximo, dos aliados (uno por tramo).

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-100 a PR-104 y PR-235 a PR-236 (referenciadas) confirmadas por el cliente
• ⬜ Reglas de negocio aplicables aprobadas
• ⬜ Requerimientos funcionales aplicables aprobados
• ⬜ Historia aprobada formalmente por el cliente