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).

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.

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