theus-cli 0.2.82 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-quarkus/SKILL.md

@@ -1,729 +0,0 @@
----
-name: patrones-quarkus
-description: Patrones de arquitectura para Quarkus 3.x LTS con Camel para mensajería, diseño de APIs REST, servicios CDI, acceso a datos con Panache y procesamiento asíncrono. Úsala para backends Java con Quarkus y arquitecturas orientadas a eventos.
----
-
-# Patrones de desarrollo con Quarkus
-
-Patrones de arquitectura y APIs para servicios cloud-native y orientados a eventos con Quarkus 3.x y Apache Camel.
-
-## Cuándo usarla
-
-- Al construir APIs REST con JAX-RS o RESTEasy Reactive
-- Al estructurar capas resource → service → repository
-- Al implementar patrones orientados a eventos con Apache Camel y RabbitMQ
-- Al configurar Hibernate Panache, caché o streams reactivos
-- Al añadir validación, mapeo de excepciones o paginación
-- Al configurar perfiles para entornos dev/staging/producción (configuración YAML)
-- Al implementar logging personalizado con LogContext y Logback/encoder de Logstash
-- Al trabajar con CompletableFuture para operaciones asíncronas
-- Al implementar procesamiento con flujos condicionales
-- Al trabajar con compilación nativa GraalVM
-
-## Capa de servicio con múltiples dependencias
-
-```java
-@Slf4j
-@ApplicationScoped
-@RequiredArgsConstructor
-public class OrderProcessingService {
-
-    private final OrderValidator orderValidator;
-    private final EventService eventService;
-    private final OrderRepository orderRepository;
-    private final FulfillmentPublisher fulfillmentPublisher;
-    private final AuditPublisher auditPublisher;
-
-    @Transactional
-    public OrderReceipt process(CreateOrderCommand command) {
-        ValidationResult validation = orderValidator.validate(command);
-        if (!validation.valid()) {
-            eventService.createErrorEvent(command, "ORDER_REJECTED", validation.message());
-            throw new WebApplicationException(validation.message(), Response.Status.BAD_REQUEST);
-        }
-
-        Order order = Order.from(command);
-        orderRepository.persist(order);
-
-        OrderReceipt receipt = OrderReceipt.from(order);
-        fulfillmentPublisher.publishAsync(receipt);
-        auditPublisher.publish("ORDER_ACCEPTED", receipt);
-        eventService.createSuccessEvent(receipt, "ORDER_ACCEPTED");
-
-        log.info("Orden procesada {}", order.id);
-        return receipt;
-    }
-}
-```
-
-**Patrones clave:**
-- `@RequiredArgsConstructor` para inyección por constructor vía Lombok
-- `@Slf4j` para logging con Logback
-- `@Transactional` en métodos de servicio que escriben mediante Panache o repositorios
-- Validar la entrada antes de persistir o publicar mensajes
-- Registro de eventos para escenarios de éxito/error
-- Publicación asíncrona de mensajes con Camel
-
-## Patrón de contexto de logging personalizado (Logback)
-
-```java
-@ApplicationScoped
-public class ProcessingService {
-
-    public void processDocument(Document doc) {
-        LogContext logContext = CustomLog.getCurrentContext();
-        try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
-            // Añade contexto a todas las sentencias de log
-            logContext.put("documentId", doc.getId().toString());
-            logContext.put("documentType", doc.getType());
-            logContext.put("userId", SecurityContext.getUserId());
-
-            log.info("Iniciando procesamiento del documento");
-
-            // Todos los logs dentro de este scope heredan el contexto
-            processInternal(doc);
-
-            log.info("Procesamiento del documento completado");
-        } catch (Exception e) {
-            log.error("Falló el procesamiento del documento", e);
-            throw e;
-        }
-    }
-}
-```
-
-**Configuración de Logback (logback.xml):**
-
-```xml
-<configuration>
-    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
-        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
-            <includeContext>true</includeContext>
-            <includeMdc>true</includeMdc>
-        </encoder>
-    </appender>
-
-    <logger name="com.example" level="INFO"/>
-    <root level="WARN">
-        <appender-ref ref="CONSOLE"/>
-    </root>
-</configuration>
-```
-
-## Patrón de servicio de eventos
-
-```java
-@Slf4j
-@ApplicationScoped
-@RequiredArgsConstructor
-public class EventService {
-    private final EventRepository eventRepository;
-    private final ObjectMapper objectMapper;
-
-    public void createSuccessEvent(Object payload, String eventType) {
-        Objects.requireNonNull(payload, "El payload no puede ser nulo");
-        Event event = new Event();
-        event.setType(eventType);
-        event.setStatus(EventStatus.SUCCESS);
-        event.setPayload(serializePayload(payload));
-        event.setTimestamp(Instant.now());
-
-        eventRepository.persist(event);
-        log.info("Evento de éxito creado: {}", eventType);
-    }
-
-    public void createErrorEvent(Object payload, String eventType, String errorMessage) {
-        Objects.requireNonNull(payload, "El payload no puede ser nulo");
-        if (errorMessage == null || errorMessage.isBlank()) {
-            throw new IllegalArgumentException("El mensaje de error no puede estar en blanco");
-        }
-        Event event = new Event();
-        event.setType(eventType);
-        event.setStatus(EventStatus.ERROR);
-        event.setErrorMessage(errorMessage);
-        event.setPayload(serializePayload(payload));
-        event.setTimestamp(Instant.now());
-
-        eventRepository.persist(event);
-        log.error("Evento de error creado: {} - {}", eventType, errorMessage);
-    }
-
-    private String serializePayload(Object payload) {
-        try {
-            return objectMapper.writeValueAsString(payload);
-        } catch (JsonProcessingException e) {
-            throw new IllegalStateException("No se pudo serializar el payload del evento", e);
-        }
-    }
-}
-```
-
-## Publicación de mensajes con Camel (RabbitMQ)
-
-```java
-@Slf4j
-@ApplicationScoped
-@RequiredArgsConstructor
-public class BusinessRulesPublisher {
-    private final ProducerTemplate producerTemplate;
-
-    public void publishSync(BusinessRulesPayload payload) {
-        producerTemplate.sendBody(
-            "direct:business-rules-publisher",
-            payload
-        );
-    }
-}
-```
-
-**Configuración de la ruta Camel:**
-
-```java
-@ApplicationScoped
-public class BusinessRulesRoute extends RouteBuilder {
-
-    @ConfigProperty(name = "camel.rabbitmq.queue.business-rules")
-    String businessRulesQueue;
-
-    @ConfigProperty(name = "rabbitmq.host")
-    String rabbitHost;
-
-    @ConfigProperty(name = "rabbitmq.port")
-    Integer rabbitPort;
-
-    @Override
-    public void configure() {
-        from("direct:business-rules-publisher")
-            .routeId("business-rules-publisher")
-            .log("Publicando mensaje en RabbitMQ: ${body}")
-            .marshal().json(JsonLibrary.Jackson)
-            .toF("spring-rabbitmq:%s?hostname=%s&portNumber=%d",
-                businessRulesQueue, rabbitHost, rabbitPort);
-    }
-}
-```
-
-## Rutas directas de Camel (en memoria)
-
-```java
-@ApplicationScoped
-public class DocumentProcessingRoute extends RouteBuilder {
-
-    @Override
-    public void configure() {
-        // Manejo de errores
-        onException(ValidationException.class)
-            .handled(true)
-            .to("direct:validation-error-handler")
-            .log("Error de validación: ${exception.message}");
-
-        // Ruta principal de procesamiento
-        from("direct:process-document")
-            .routeId("document-processing")
-            .log("Procesando documento: ${header.documentId}")
-            .bean(DocumentValidator.class, "validate")
-            .bean(DocumentTransformer.class, "transform")
-            .choice()
-                .when(header("documentType").isEqualTo("INVOICE"))
-                    .to("direct:process-invoice")
-                .when(header("documentType").isEqualTo("CREDIT_NOTE"))
-                    .to("direct:process-credit-note")
-                .otherwise()
-                    .to("direct:process-generic")
-            .end();
-
-        from("direct:validation-error-handler")
-            .bean(EventService.class, "createErrorEvent")
-            .log("Error de validación gestionado");
-    }
-}
-```
-
-## Procesamiento de archivos con Camel
-
-```java
-@ApplicationScoped
-public class FileMonitoringRoute extends RouteBuilder {
-
-    @ConfigProperty(name = "file.input.directory")
-    String inputDirectory;
-
-    @ConfigProperty(name = "file.processed.directory")
-    String processedDirectory;
-
-    @ConfigProperty(name = "file.error.directory")
-    String errorDirectory;
-
-    @Override
-    public void configure() {
-        from("file:" + inputDirectory + "?move=" + processedDirectory +
-             "&moveFailed=" + errorDirectory + "&delay=5000")
-            .routeId("file-monitor")
-            .log("Procesando archivo: ${header.CamelFileName}")
-            .to("direct:process-file");
-
-        from("direct:process-file")
-            .bean(OrderProcessingService.class, "processFile")
-            .log("Procesamiento del archivo completado");
-    }
-}
-```
-
-## Invocación de beans desde Camel
-
-```java
-@ApplicationScoped
-public class InvoiceRoute extends RouteBuilder {
-
-    @Override
-    public void configure() {
-        from("direct:invoice-validation")
-            .bean(InvoiceFlowValidator.class, "validateFlowWithConfig")
-            .log("Resultado de validación: ${body}");
-
-        from("direct:persist-and-publish")
-            .bean(DocumentJobService.class, "createDocumentAndJobEntities")
-            .bean(BusinessRulesPublisher.class, "publishAsync")
-            .bean(EventService.class, "createSuccessEvent(${body}, 'PUBLISHED')");
-    }
-}
-```
-
-## Estructura de la API REST
-
-```java
-@Path("/api/documents")
-@Produces(MediaType.APPLICATION_JSON)
-@Consumes(MediaType.APPLICATION_JSON)
-@RequiredArgsConstructor
-public class DocumentResource {
-  private final DocumentService documentService;
-
-  @GET
-  public Response list(
-      @QueryParam("page") @DefaultValue("0") int page,
-      @QueryParam("size") @DefaultValue("20") int size) {
-    List<Document> documents = documentService.list(page, size);
-    return Response.ok(documents).build();
-  }
-
-  @POST
-  public Response create(@Valid CreateDocumentRequest request, @Context UriInfo uriInfo) {
-    Document document = documentService.create(request);
-    URI location = uriInfo.getAbsolutePathBuilder()
-        .path(String.valueOf(document.id))
-        .build();
-    return Response.created(location).entity(DocumentResponse.from(document)).build();
-  }
-
-  @GET
-  @Path("/{id}")
-  public Response getById(@PathParam("id") Long id) {
-    return documentService.findById(id)
-        .map(DocumentResponse::from)
-        .map(Response::ok)
-        .orElse(Response.status(Response.Status.NOT_FOUND))
-        .build();
-  }
-}
-```
-
-## Patrón de repositorio (Panache Repository)
-
-```java
-@ApplicationScoped
-public class DocumentRepository implements PanacheRepository<Document> {
-
-  public List<Document> findByStatus(DocumentStatus status, int page, int size) {
-    return find("status = ?1 order by createdAt desc", status)
-        .page(page, size)
-        .list();
-  }
-
-  public Optional<Document> findByReferenceNumber(String referenceNumber) {
-    return find("referenceNumber", referenceNumber).firstResultOptional();
-  }
-
-  public long countByStatusAndDate(DocumentStatus status, LocalDate date) {
-    return count("status = ?1 and createdAt >= ?2", status, date.atStartOfDay());
-  }
-}
-```
-
-## Capa de servicio con transacciones
-
-```java
-@ApplicationScoped
-@RequiredArgsConstructor
-public class DocumentService {
-  private final DocumentRepository repo;
-  private final EventService eventService;
-
-  @Transactional
-  public Document create(CreateDocumentRequest request) {
-    Document document = new Document();
-    document.setReferenceNumber(request.referenceNumber());
-    document.setDescription(request.description());
-    document.setStatus(DocumentStatus.PENDING);
-    document.setCreatedAt(Instant.now());
-
-    repo.persist(document);
-
-    eventService.createSuccessEvent(document, "DOCUMENT_CREATED");
-
-    return document;
-  }
-
-  public Optional<Document> findById(Long id) {
-    return repo.findByIdOptional(id);
-  }
-
-  public List<Document> list(int page, int size) {
-    return repo.findAll()
-        .page(page, size)
-        .list();
-  }
-}
-```
-
-## DTOs y validación
-
-```java
-public record CreateDocumentRequest(
-    @NotBlank @Size(max = 200) String referenceNumber,
-    @NotBlank @Size(max = 2000) String description,
-    @NotNull @FutureOrPresent Instant validUntil,
-    @NotEmpty List<@NotBlank String> categories) {}
-
-public record DocumentResponse(Long id, String referenceNumber, DocumentStatus status) {
-  public static DocumentResponse from(Document document) {
-    return new DocumentResponse(document.getId(), document.getReferenceNumber(),
-        document.getStatus());
-  }
-}
-```
-
-## Mapeo de excepciones
-
-```java
-@Provider
-public class ValidationExceptionMapper implements ExceptionMapper<ConstraintViolationException> {
-  @Override
-  public Response toResponse(ConstraintViolationException exception) {
-    String message = exception.getConstraintViolations().stream()
-        .map(cv -> cv.getPropertyPath() + ": " + cv.getMessage())
-        .collect(Collectors.joining(", "));
-
-    return Response.status(Response.Status.BAD_REQUEST)
-        .entity(Map.of("error", "validation_error", "message", message))
-        .build();
-  }
-}
-
-@Provider
-@Slf4j
-public class GenericExceptionMapper implements ExceptionMapper<Exception> {
-
-  @Override
-  public Response toResponse(Exception exception) {
-    log.error("Excepción no gestionada", exception);
-    return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
-        .entity(Map.of("error", "internal_error", "message", "Ocurrió un error inesperado"))
-        .build();
-  }
-}
-```
-
-## Operaciones asíncronas con CompletableFuture
-
-```java
-@Slf4j
-@ApplicationScoped
-@RequiredArgsConstructor
-public class FileStorageService {
-    private final S3Client s3Client;
-    private final ExecutorService executorService;
-
-    @ConfigProperty(name = "storage.bucket-name")
-    String bucketName;
-
-    public CompletableFuture<StoredDocumentInfo> uploadOriginalFile(
-            InputStream inputStream,
-            long size,
-            LogContext logContext,
-            InvoiceFormat format) {
-
-        return CompletableFuture.supplyAsync(() -> {
-            try (SafeAutoCloseable ignored = CustomLog.startScope(logContext)) {
-                String path = generateStoragePath(format);
-
-                PutObjectRequest request = PutObjectRequest.builder()
-                    .bucket(bucketName)
-                    .key(path)
-                    .contentLength(size)
-                    .build();
-
-                s3Client.putObject(request, RequestBody.fromInputStream(inputStream, size));
-
-                log.info("Archivo subido a S3: {}", path);
-
-                return new StoredDocumentInfo(path, size, Instant.now());
-            } catch (Exception e) {
-                log.error("No se pudo subir el archivo a S3", e);
-                throw new StorageException("Falló la subida", e);
-            }
-        }, executorService);
-    }
-}
-```
-
-## Caché
-
-```java
-@ApplicationScoped
-@RequiredArgsConstructor
-public class DocumentCacheService {
-  private final DocumentRepository repo;
-
-  @CacheResult(cacheName = "document-cache")
-  public Optional<Document> getById(@CacheKey Long id) {
-    return repo.findByIdOptional(id);
-  }
-
-  @CacheInvalidate(cacheName = "document-cache")
-  public void evict(@CacheKey Long id) {}
-
-  @CacheInvalidateAll(cacheName = "document-cache")
-  public void evictAll() {}
-}
-```
-
-## Configuración en YAML
-
-```yaml
-# application.yml
-"%dev":
-  quarkus:
-    datasource:
-      jdbc:
-        url: jdbc:postgresql://localhost:5432/dev_db
-      username: dev_user
-      password: ${DB_PASSWORD}
-    hibernate-orm:
-      database:
-        generation: drop-and-create
-
-  rabbitmq:
-    host: localhost
-    port: 5672
-    username: ${RABBITMQ_USER}
-    password: ${RABBITMQ_PASSWORD}
-
-"%test":
-  quarkus:
-    datasource:
-      jdbc:
-        url: jdbc:h2:mem:test
-    hibernate-orm:
-      database:
-        generation: drop-and-create
-
-"%prod":
-  quarkus:
-    datasource:
-      jdbc:
-        url: ${DATABASE_URL}
-      username: ${DB_USER}
-      password: ${DB_PASSWORD}
-    hibernate-orm:
-      database:
-        generation: validate
-
-  rabbitmq:
-    host: ${RABBITMQ_HOST}
-    port: ${RABBITMQ_PORT}
-    username: ${RABBITMQ_USER}
-    password: ${RABBITMQ_PASSWORD}
-
-# Configuración de Camel
-camel:
-  rabbitmq:
-    queue:
-      business-rules: business-rules-queue
-      invoice-processing: invoice-processing-queue
-```
-
-## Health checks
-
-```java
-@Readiness
-@ApplicationScoped
-@RequiredArgsConstructor
-public class DatabaseHealthCheck implements HealthCheck {
-  private final AgroalDataSource dataSource;
-
-  @Override
-  public HealthCheckResponse call() {
-    try (Connection conn = dataSource.getConnection()) {
-      boolean valid = conn.isValid(2);
-      return HealthCheckResponse.named("Database connection")
-          .status(valid)
-          .build();
-    } catch (SQLException e) {
-      return HealthCheckResponse.down("Database connection");
-    }
-  }
-}
-
-@Liveness
-@ApplicationScoped
-public class CamelHealthCheck implements HealthCheck {
-  @Inject
-  CamelContext camelContext;
-
-  @Override
-  public HealthCheckResponse call() {
-    boolean isStarted = camelContext.getStatus().isStarted();
-    return HealthCheckResponse.named("Camel Context")
-        .status(isStarted)
-        .build();
-  }
-}
-```
-
-## Dependencias (Maven)
-
-```xml
-<properties>
-    <quarkus.platform.version>3.27.0</quarkus.platform.version>
-    <lombok.version>1.18.42</lombok.version>
-    <assertj-core.version>3.24.2</assertj-core.version>
-    <jacoco-maven-plugin.version>0.8.13</jacoco-maven-plugin.version>
-    <maven.compiler.release>17</maven.compiler.release>
-</properties>
-
-<dependencyManagement>
-    <dependencies>
-        <dependency>
-            <groupId>io.quarkus.platform</groupId>
-            <artifactId>quarkus-bom</artifactId>
-            <version>${quarkus.platform.version}</version>
-            <type>pom</type>
-            <scope>import</scope>
-        </dependency>
-        <dependency>
-            <groupId>io.quarkus.platform</groupId>
-            <artifactId>quarkus-camel-bom</artifactId>
-            <version>${quarkus.platform.version}</version>
-            <type>pom</type>
-            <scope>import</scope>
-        </dependency>
-    </dependencies>
-</dependencyManagement>
-
-<dependencies>
-    <!-- Núcleo de Quarkus -->
-    <dependency>
-        <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-arc</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>io.quarkus</groupId>
-        <artifactId>quarkus-config-yaml</artifactId>
-    </dependency>
-
-    <!-- Extensiones de Camel -->
-    <dependency>
-        <groupId>org.apache.camel.quarkus</groupId>
-        <artifactId>camel-quarkus-spring-rabbitmq</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>org.apache.camel.quarkus</groupId>
-        <artifactId>camel-quarkus-direct</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>org.apache.camel.quarkus</groupId>
-        <artifactId>camel-quarkus-bean</artifactId>
-    </dependency>
-
-    <!-- Lombok -->
-    <dependency>
-        <groupId>org.projectlombok</groupId>
-        <artifactId>lombok</artifactId>
-        <version>${lombok.version}</version>
-        <scope>provided</scope>
-    </dependency>
-
-    <!-- Logging -->
-    <dependency>
-        <groupId>io.quarkiverse.logging.logback</groupId>
-        <artifactId>quarkus-logging-logback</artifactId>
-    </dependency>
-    <dependency>
-        <groupId>net.logstash.logback</groupId>
-        <artifactId>logstash-logback-encoder</artifactId>
-    </dependency>
-</dependencies>
-```
-
-## Buenas prácticas
-
-### Arquitectura
-- Usa `@RequiredArgsConstructor` con Lombok para inyección por constructor
-- Mantén la capa de servicio delgada; delega la lógica compleja a clases especializadas
-- Usa rutas de Camel para enrutamiento de mensajes y patrones de integración
-- Prefiere el patrón Panache Repository para el acceso a datos
-
-### Orientado a eventos
-- Registra siempre las operaciones con EventService (eventos de éxito/error)
-- Usa endpoints `direct:` de Camel para enrutamiento en memoria
-- Usa el componente `spring-rabbitmq` para la integración con RabbitMQ
-- Implementa publicación asíncrona con `ProducerTemplate.asyncSendBody()`
-
-### Logging
-- Usa Logback con el encoder de Logstash para logging estructurado
-- Propaga el LogContext a través de las llamadas de servicio con `SafeAutoCloseable`
-- Añade información contextual al LogContext para el trazado de peticiones
-- Usa `@Slf4j` en lugar de instanciar loggers manualmente
-
-### Operaciones asíncronas
-- Usa CompletableFuture para operaciones de E/S no bloqueantes
-- Llama a `.join()` cuando necesites esperar la finalización
-- Maneja correctamente las excepciones de CompletableFuture
-- Pasa el LogContext a las operaciones asíncronas para el trazado
-
-### Configuración
-- Usa configuración YAML (`quarkus-config-yaml`)
-- Configuración por perfiles para entornos dev/test/prod
-- Externaliza la configuración sensible a variables de entorno
-- Usa `@ConfigProperty` para inyección de configuración con tipos seguros
-
-### Validación
-- Valida en la capa resource con `@Valid`
-- Usa anotaciones de Bean Validation en los DTOs
-- Mapea excepciones a respuestas HTTP adecuadas con `@Provider`
-
-### Transacciones
-- Usa `@Transactional` en métodos de servicio que modifican datos
-- Mantén las transacciones cortas y enfocadas
-- Evita llamar a operaciones asíncronas dentro de transacciones
-
-### Testing
-- Usa `camel-quarkus-junit5` para probar rutas
-- Usa AssertJ para las aserciones
-- Mockea todas las dependencias externas
-- Prueba a fondo la lógica de flujos condicionales
-
-### Específico de Quarkus
-- Mantente en la última versión LTS (3.x)
-- Usa el modo dev de Quarkus para hot reload
-- Añade health checks para preparación de producción
-- Prueba periódicamente la compatibilidad con compilación nativa
-
-## Skills relacionadas
-
-- `seguridad-quarkus`
-- `tdd-quarkus`
-- `verificacion-quarkus`
-- `estandares-java`
-- `patrones-jpa`