📣 Alpura Back Java Library — Notificaciones v1.3

Esta librería facilita la construcción y el envío uniforme de notificaciones desde tu aplicación Java 21 + Spring Boot 3.4.4 a un microservicio de notificaciones HTTP utilizando Spring RestClient.

---

🛠️ Requisitos

• Java: 21 (Temurin recomendado)
• Spring Boot: 3.4.4 o superior
• Alpura BOM: 1.0.4

---

📥 Instalación

Opción A: Heredando versión desde Alpura BOM 1.0.4 (RECOMENDADO)

En el pom.xml de tu proyecto:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.alpura</groupId>
            <artifactId>bom</artifactId>
            <version>1.0.4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>com.alpura.notification</groupId>
        <artifactId>alpura-back-java-lib-notification</artifactId>
    </dependency>
</dependencies>

Opción B: Uso directo (Standalone)

<dependency>
    <groupId>com.alpura.notification</groupId>
    <artifactId>alpura-back-java-lib-notification</artifactId>
    <version>1.3</version>
</dependency>

Gradle: implementation("com.alpura.notification:alpura-back-java-lib-notification:1.3")

---

🔍 Escanear paquete

Incluye el paquete en tu @ComponentScan para registrar automáticamente los beans internos:

@SpringBootApplication
@ComponentScan({
        "com.alpura.notification", // 🧠 Obligatorio
        // otros paquetes…
})
public class ExApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExApplication.class, args);
    }
}

---

🚀 ¿Qué hace esta librería?

1. Modela la notificación completa en un solo objeto (NotificationVO).
2. Valida campos obligatorios con Bean Validation.
3. Separa la construcción del payload del envío HTTP.
4. Realiza peticiones HTTP modernas y eficientes a través de Spring RestClient con timeout configurado (10s conexión, 60s lectura).
5. Propaga automáticamente el token Bearer desde UserLoggedInfoVO.token en los encabezados HTTP.

---

📦 Estructura de datos

NotificationVO

public class NotificationVO {
  @NotEmpty List<ChannelEnum> channel;        // ✅ Obligatorio (EMAIL, WHATSAPP, etc.)
  @NotEmpty Map<String,String> data;          // ✅ Obligatorio (≥1 par clave-valor)
  @NotEmpty List<RecipientVO> recipient;      // ✅ Obligatorio (≥1 destinatario)
           List<FileBase64VO> files;         // ❌ Opcional (archivos adjuntos en base64)
  @NotNull  Integer templateId;              // ✅ Obligatorio
  @NotNull  UserLoggedInfoVO userLoggedInfo; // ✅ Obligatorio
}

Campos clave

• data: mapa de pares clave–valor que la plantilla sustituye. Ej.: username, orderId.
• templateId: identificador numérico de la plantilla registrada en el microservicio de notificaciones.
• userLoggedInfo: contexto del usuario autenticado (userId, email, roles, token) usado para auditoría y propagación del header Authorization.

RecipientVO

public class RecipientVO {
  String userEmail;  // Correo válido
  String userPhone;  // Teléfono internacional '+XXXXXXXXXXX'
}

FileBase64VO (Adjuntos Base64)

public class FileBase64VO {
  @NotBlank(message = "File name must be provided")
  String fileName;    // Nombre del archivo (ej. "reporte.pdf")
  @NotBlank(message = "Content type must be provided")
  String contentType; // Tipo MIME (ej. "application/pdf")
  @NotBlank(message = "Base64 content must be provided")
  @Pattern(regexp = "^[A-Za-z0-9+/=\\r\\n,:;._\\-]+$")
  String base64;      // Contenido codificado en Base64
}

ChannelEnum

public enum ChannelEnum { EMAIL, WHATSAPP, TELEGRAM, TEAMS, PUSH }

---

🧩 Uso paso a paso

1. Configura la URL base del servicio

En application.yml de tu microservicio:

alpura:
  notification:
    base-url: http://nc-notification.svc.internal.arquitectura.com/nc-notification

La librería concatena automáticamente la ruta relativa api/v1/notification/message a la base-url.

2. Inyecta el servicio en tu componente Java

@Autowired
private INotificationServiceLib notificationService;

3. Crea y envía una notificación

@PostMapping("/send")
public ResponseEntity<Void> sendNotification(
  @Validated(BaseNoBlankGroup.class) @RequestBody NotificationVO notification) {
  // Es importante mandar el UserLoggedInfo para propagar las cabeceras con autorización
  notification.setUserLoggedInfo(getUserInfoFromContext());
  notificationService.sendNotification(notification);
  return ResponseEntity.ok().build();
}

---

✅ Validaciones automáticas

• channel, recipient, data no deben estar vacíos.
• templateId y userLoggedInfo no deben ser nulos.
• El adjunto FileBase64VO valida formato de contenido Base64 con expresión regular.
• Si falla alguna validación se lanza ConstraintViolationException con detalle.

---

📋 Ejemplo de payload JSON

{
  "channel": ["EMAIL"],
  "templateId": 42,
  "data": {
    "username": "María",
    "orderId": "12345"
  },
  "files": [
    {
      "fileName": "factura.pdf",
      "contentType": "application/pdf",
      "base64": "JVBERi0xLjRN..."
    }
  ],
  "recipient": [
    {
      "userEmail": "maria.gomez@example.com",
      "userPhone": "+525599988877"
    }
  ],
  "userLoggedInfo": {
    "userId": "abc123",
    "email": "admin@example.com",
    "roles": ["ADMIN"],
    "token": "eyJhbGciOi..."
  }
}

---

🔧 Arquitectura interna

Componentes clave

Clase	Paquete	Rol
INotificationServiceLib	com.alpura.notification.service	Contrato para enviar notificaciones.
NotificationServiceImpl	com.alpura.notification.service.impl	Implementación que ejecuta la petición HTTP usando RestClient.
NotificationClientConfig	com.alpura.notification.config	Configura el bean RestClient con baseUrl y timeouts (10s connect, 60s read).

Flujo de ejecución

---