RF-007 — Notificaciones transaccionales por correo

Estado	En desarrollo (rama hquintero)
Tipo	Notification provider propio + suscriptores de eventos
Ubicación	src/modules/email-notification/ · identificador email-notification · src/subscribers/
Depende de	Módulos Notification y Event Bus — RF-000

Requisito

Notificar por correo electrónico los hitos del ciclo de vida del cliente y del pedido, con plantillas propias en castellano y con la identidad visual de la tienda; y avisar al equipo comercial de los eventos que requieren su intervención. Desacoplar el envío de la operación que lo origina, de modo que una falla de correo no interrumpa la venta.

Solución adoptada

Implementar un notification provider sobre SMTP y disparar los envíos desde suscriptores del event bus. El contenido y los estilos se mantienen separados de la lógica de envío, de modo que la edición de un texto no requiere tocar código de servicio.

flowchart LR
    E[Evento de dominio] --> S[Suscriptor]
    S --> Q[Resolver datos del pedido o del cliente]
    Q --> N[Módulo Notification]
    N --> P[Provider email-notification]
    P --> T[Plantilla HTML + variables]
    T --> SMTP[(SMTP)]
    SMTP --> C([Cliente])
    SMTP --> V([Equipo comercial])

Matriz de eventos y destinatarios

Evento	Plantilla al cliente	Plantilla interna
customer.created	welcome	—
auth.password_reset	password-reset	—
order.placed	order-confirmation	sales-new-order
order.fulfillment_created	order-shipped	sales-order-shipped
order.completed	order-delivered	—
order.canceled	order-cancelled	—
order.return_requested	return-requested	—
order.return_received	return-received	—

Existen además plantillas registradas sin suscriptor que las dispare: email-verification, order-processing, order-refunded, sales-order-cancelled y sales-return-requested, más contenido redactado para reposición de stock, últimas unidades y carrito abandonado. Quedan disponibles para invocación directa desde el módulo de notificaciones.

Reglas de negocio

• Redactar todo el contenido en castellano, con asunto por plantilla y sustitución de variables —número de pedido, nombre del cliente, importes— en el momento del envío.
• Dirigir los avisos internos a la casilla del área comercial, y omitirlos si no está configurada.
• Enlazar el correo del cliente al storefront y el aviso interno al dashboard, resolviendo el dominio desde la configuración de CORS.
• Tratar el envío como accesorio del evento: los errores se registran sin propagarse a la operación que originó el evento.
• Mantener el contenido y los estilos en módulos separados del servicio de envío.

Configuración

Variable	Uso
SMTP_HOST · SMTP_PORT · SMTP_USER · SMTP_PASS	Credenciales del servidor de correo saliente
SMTP_FROM	Remitente de todos los envíos
SALES_DEPARTMENT_EMAIL	Destinatario de los avisos internos
STORE_CORS · ADMIN_CORS	Origen de los enlaces incluidos en el cuerpo del correo

Criterios de aceptación

#	Criterio
1	Enviar el correo de bienvenida al registrarse un cliente nuevo
2	Enviar confirmación al cliente y aviso al área comercial al confirmarse un pedido
3	Enviar el aviso de envío con los datos del pedido al generarse el fulfillment
4	Completar la compra sin error cuando el servidor SMTP no responde
5	Modificar el texto de una plantilla sin alterar la lógica de envío

Limitaciones conocidas

• Seleccionar la plantilla por sentencia switch sobre una cadena: una plantilla mal nombrada falla en ejecución, no en compilación.
• Disponer de plantillas sin suscriptor asociado, que no llegan a enviarse por sí solas.
• Carecer de reintento y de bitácora persistente de envíos: la única evidencia es el registro del proceso.