Saltar al contenido principal

REQ-NOT-01 — Envío por correo de documentos PDF de la mascota

· 4 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación del requerimiento REQ-NOT-01 (Envío por correo de documentos PDF de la mascota), dentro de Notificaciones y con prioridad Media. El módulo de veterinaria ya administraba la clínica; ahora también entrega documentos: genera el PDF de una mascota y lo envía por correo al tutor usando el mismo servicio de Resend que la recuperación de contraseña del login.


📋 Alcance​

Criterio de aceptaciónEntregable
CA1 — PDF de historia clínica, servicios y vacunaciónGenerador veterinaria-documento.pdf.ts (pdfkit) con los tres tipos
CA2 — Adjuntar y enviar con ResendCorreoService.enviarDocumentoAdjunto() con attachments
CA3 — Reutilizar la configuración del loginMismo CorreoService, RESEND_API_KEY, RESEND_FROM_* y CORREO_HABILITADO
CA4 — Destinatario por defecto el dueño y validaciónCorreo del tutor prellenado; validación isEmail y rechazo de saltos de línea
CA5 — Elegir tipo y mascotaPantalla Documentos con buscador de mascotas y tres tarjetas de tipo
CA6 — Informar resultado, motivo y reintentarTarjeta de resultado + POST /documentos/:id/reintentar y botón en el historial
CA7 — Registro consultableTabla veterinaria_envios_documento y listado con filtros
CA8 — Identidad visual y privacidadCabecera del PDF y correo con la marca de la clínica; solo la mascota elegida

🧩 Cómo funciona​

  • PDF en el API, no en el navegador. El servicio consulta MongoDB (consultas, cirugias, historials, vacunaaplicadas, desparasitacionaplicadas), normaliza los datos y compone el PDF con pdfkit. Así el correo y el archivo salen del mismo backend, sin subir binarios desde el frontend.
  • Historia clínica de solo lectura. El almacén no edita el acto clínico: lo lee de la app y lo entrega. Se excluyen registros anulados y se ordenan del más reciente al más antiguo.
  • Mismo correo que el login. Se extendió CorreoService (REQ-COM-02) con un método para adjuntos; no se creó un segundo cliente de Resend ni se duplicaron variables de entorno.
  • Entrega tolerante a fallos. Un rechazo de Resend no rompe la petición: se guarda el envío como fallido con el motivo, se audita y la interfaz ofrece Reintentar (regenera el PDF y actualiza el mismo registro, subiendo intentos).
  • Privacidad. El PDF se arma por mascotaId y solo incluye a esa mascota y a su tutor; el pie recuerda que el documento es confidencial.

🗂️ Pantalla añadida​

MenúRutaQué hace
Documentos/veterinaria-documentosBuscar mascota, elegir tipo, confirmar correo, enviar, ver resultado y consultar el historial con reintento

El ítem 99-documentos se suma a la sección Veterinaria (migración 050) para Administrador, Veterinario y Auxiliar veterinaria.


🔌 Configuración​

No hay variables nuevas; se reutilizan las del correo transaccional:

CORREO_HABILITADO=true
RESEND_API_KEY=re_...
RESEND_FROM_EMAIL=noreply@cdsmaya.com.co # dominio verificado en Resend
RESEND_FROM_NAME=Modulo de Almacen

Pasos de puesta en marcha:

cd ccf-almacen-api
npm run migration:run # 049 (registro de envíos) y 050 (menú Documentos)

Si el correo no está configurado, la pantalla muestra el fallo con ese motivo y el envío queda en el historial para reintentarlo cuando se configure.


🧪 Verificación​

  • tsc --noEmit y eslint sin errores en API y web.
  • Jest API: 6 suites / 57 pruebas, incluidas las del PDF (tres tipos, PDF vacío, fechas y escapado de HTML de la plantilla) y las del servicio (envío, motivo del fallo, correo inválido, reintento y listado).
  • Jest web: 2 suites / 9 pruebas de registro de menú y módulo.
  • PDF renderizado y revisado visualmente (cabecera, ficha, tablas, pie y paginación).
  • Migraciones 049 y 050 aplicadas en ccf_almacen.

📌 Decisiones y límites​

  • El PDF no se almacena en PostgreSQL: se regenera al reintentar. El registro conserva nombre de archivo, tamaño, destinatario y resultado.
  • Logo: el generador admite un Buffer de logo; como configuracioninstitucionals no tiene avatarImagenId cargado, se usa un sello con las iniciales y los colores de marca.
  • Fuera de alcance: firma digital del documento, envíos programados o masivos y edición de la historia clínica desde el almacén.