@the-bearded-bear/claude-craft 3.0.0

package/Dev/i18n/es/Symfony/templates/clean-architecture-structure.md

@@ -0,0 +1,226 @@
+# Estructura Clean Architecture + DDD - Atoll Tourisme
+
+## Overview
+
+Este documento presenta la estructura **completa** de directorios para una migración hacia Clean Architecture + DDD del proyecto Atoll Tourisme.
+
+> **Referencias:**
+> - `.claude/rules/02-architecture-clean-ddd.md` - Arquitectura global
+> - `.claude/rules/13-ddd-patterns.md` - Patrones DDD detallados
+> - `.claude/examples/aggregate-examples.md` - Ejemplos de Aggregates
+> - `.claude/examples/value-object-examples.md` - Ejemplos de Value Objects
+
+---
+
+## Arquitectura completa
+
+### Estructura src/ completa
+
+```
+src/
+├── Domain/                                    # CAPA DOMINIO (PHP puro, 0 dependencias)
+│   ├── Catalog/                              # BC: Catálogo de estancias
+│   │   ├── Entity/
+│   │   │   └── Sejour.php                    # Aggregate Root
+│   │   ├── ValueObject/
+│   │   │   ├── SejourId.php
+│   │   │   ├── Destination.php
+│   │   │   ├── DateRange.php
+│   │   │   ├── Price.php
+│   │   │   └── Capacity.php
+│   │   ├── Repository/
+│   │   │   ├── SejourRepositoryInterface.php
+│   │   │   └── SejourFinderInterface.php
+│   │   ├── Service/
+│   │   │   ├── SejourAvailabilityService.php
+│   │   │   └── SejourPricingService.php
+│   │   └── Event/
+│   │       ├── SejourPublishedEvent.php
+│   │       └── SejourCapacityChangedEvent.php
+│   │
+│   ├── Reservation/                          # BC: Reservas
+│   │   ├── Entity/
+│   │   │   ├── Reservation.php               # Aggregate Root
+│   │   │   └── Participant.php
+│   │   ├── ValueObject/
+│   │   │   ├── ReservationId.php
+│   │   │   ├── ReservationStatus.php
+│   │   │   ├── Money.php
+│   │   │   └── PersonName.php
+│   │   ├── Repository/
+│   │   │   └── ReservationRepositoryInterface.php
+│   │   ├── Service/
+│   │   │   ├── ReservationPricingService.php
+│   │   │   └── DiscountCalculator.php
+│   │   └── Event/
+│   │       ├── ReservationCreatedEvent.php
+│   │       ├── ReservationConfirmedEvent.php
+│   │       └── ReservationCancelledEvent.php
+│   │
+│   └── Shared/                               # SHARED KERNEL
+│       ├── ValueObject/
+│       │   ├── Email.php
+│       │   ├── PhoneNumber.php
+│       │   └── PostalAddress.php
+│       └── Exception/
+│           ├── DomainException.php
+│           └── ValidationException.php
+│
+├── Application/                              # CAPA APLICACIÓN (Casos de uso)
+│   ├── Reservation/
+│   │   ├── UseCase/
+│   │   │   ├── CreateReservation/
+│   │   │   │   ├── CreateReservationUseCase.php
+│   │   │   │   └── CreateReservationCommand.php
+│   │   │   └── ConfirmReservation/
+│   │   │       ├── ConfirmReservationUseCase.php
+│   │   │       └── ConfirmReservationCommand.php
+│   │   ├── Query/
+│   │   │   └── GetReservationDetails/
+│   │   │       ├── GetReservationDetailsQuery.php
+│   │   │       └── ReservationDetailsDTO.php
+│   │   └── EventHandler/
+│   │       └── SendConfirmationEmailOnReservationCreated.php
+│   │
+│   └── Catalog/
+│       ├── UseCase/
+│       │   └── PublishSejour/
+│       │       ├── PublishSejourUseCase.php
+│       │       └── PublishSejourCommand.php
+│       └── Query/
+│           └── SearchSejours/
+│               ├── SearchSejoursQuery.php
+│               └── SejourSearchResultDTO.php
+│
+├── Infrastructure/                           # CAPA INFRAESTRUCTURA (Técnica)
+│   ├── Persistence/
+│   │   └── Doctrine/
+│   │       ├── Repository/
+│   │       │   ├── DoctrineReservationRepository.php
+│   │       │   └── DoctrineSejourRepository.php
+│   │       ├── Type/
+│   │       │   ├── EmailType.php
+│   │       │   ├── MoneyType.php
+│   │       │   └── ReservationStatusType.php
+│   │       └── Mapping/
+│   │           ├── Reservation.orm.xml
+│   │           └── Sejour.orm.xml
+│   │
+│   ├── Notification/
+│   │   ├── EmailNotificationService.php
+│   │   └── Message/
+│   │       └── SendReservationConfirmationEmail.php
+│   │
+│   └── EventBus/
+│       └── SymfonyEventBusAdapter.php
+│
+└── Presentation/                             # CAPA PRESENTACIÓN (UI)
+    ├── Controller/
+    │   ├── Web/
+    │   │   ├── HomeController.php
+    │   │   └── ReservationController.php
+    │   └── Admin/
+    │       └── ReservationCrudController.php
+    │
+    ├── Form/
+    │   ├── ReservationFormType.php
+    │   └── ParticipantType.php
+    │
+    └── Command/
+        └── ImportSejoursCommand.php
+```
+
+---
+
+## Bounded Contexts detallados
+
+### 1. Catalog (Catálogo de estancias)
+
+**Responsabilidad:** Gestión del catálogo de estancias, destinos, tarifas, disponibilidades.
+
+**Lenguaje ubicuo:**
+- **Estancia (Séjour)** : Viaje organizado con fechas, destino, capacidad
+- **Destino** : Lugar de la estancia (ciudad, país, región)
+- **Capacidad** : Número de plazas disponibles
+- **Tarifa** : Precio por persona según temporada
+
+### 2. Reservation (Reservas)
+
+**Responsabilidad:** Gestión completa de reservas y participantes.
+
+**Lenguaje ubicuo:**
+- **Reserva** : Solicitud de participación en una estancia
+- **Participante** : Persona inscrita (identidad, información médica)
+- **Estado** : EN_ESPERA, CONFIRMADA, CANCELADA, TERMINADA
+- **Monto** : Precio total calculado con descuentos
+
+---
+
+## Principios de organización
+
+### 1. Regla de dependencia
+
+```
+Domain (0 dependencias)
+  ↑
+Application (depende de Domain)
+  ↑
+Infrastructure (depende de Domain + Application)
+  ↑
+Presentation (depende de Application + Infrastructure)
+```
+
+### 2. Convención de nombres
+
+| Tipo | Sufijo | Ejemplo |
+|------|---------|---------|
+| Aggregate Root | Ninguno | `Reservation`, `Sejour` |
+| Value Object | Ninguno | `Money`, `Email` |
+| Repository Interface | `Interface` | `ReservationRepositoryInterface` |
+| Repository Impl | `Repository` | `DoctrineReservationRepository` |
+| Use Case | `UseCase` | `CreateReservationUseCase` |
+| Command | `Command` | `CreateReservationCommand` |
+| Event | `Event` | `ReservationConfirmedEvent` |
+
+---
+
+## Migración progresiva
+
+### Fase 1: Shared Kernel (Semana 1)
+Crear los Value Objects compartidos prioritariamente
+
+### Fase 2: Reservation Bounded Context (Semana 2-3)
+Migrar `Reservation` y `Participant` hacia DDD
+
+### Fase 3: Catalog Bounded Context (Semana 4)
+Migrar `Sejour`
+
+### Fase 4: Application Layer (Semana 5-6)
+Crear los casos de uso
+
+---
+
+## Checklist de migración
+
+### Antes de crear un nuevo archivo
+
+- [ ] **Capa:** Identificar la capa correcta (Domain/Application/Infrastructure/Presentation)
+- [ ] **Bounded Context:** Identificar el BC (Catalog, Reservation, Shared)
+- [ ] **Tipo:** Entity, VO, Service, Repository, UseCase, etc.
+- [ ] **Nombres:** Respetar el sufijo obligatorio
+- [ ] **Dependencias:** Verificar regla de dependencia
+- [ ] **Tests:** Crear test unitario ANTES de la implementación (TDD)
+
+### Después de la creación
+
+- [ ] **PHPStan:** `make phpstan` (nivel máximo)
+- [ ] **CS-Fixer:** `make cs-fix`
+- [ ] **Deptrac:** `make deptrac`
+- [ ] **Tests:** `make test`
+- [ ] **Cobertura:** Verificar cobertura > 80%
+
+---
+
+**Fecha de creación:** 2025-11-26
+**Versión:** 1.0.0
+**Autor:** The Bearded CTO

package/Dev/i18n/es/Symfony/templates/domain-event-examples.md

@@ -0,0 +1,375 @@
+# Ejemplos de Domain Events - Atoll Tourisme
+
+## Overview
+
+Este documento presenta **implementaciones completas** de Domain Events y sus Event Handlers para el proyecto Atoll Tourisme.
+
+> **Referencias:**
+> - `.claude/rules/13-ddd-patterns.md` - Patrones DDD
+> - `.claude/rules/02-architecture-clean-ddd.md` - Arquitectura
+> - `.claude/examples/aggregate-examples.md` - Aggregates
+
+---
+
+## Principios de los Domain Events
+
+### Características obligatorias
+
+1. **Inmutabilidad:** clase `readonly`
+2. **Pasado:** Nombrado con verbo en pasado (ReservationCreated, no CreateReservation)
+3. **Timestamp:** Propiedad `occurredOn` (\DateTimeImmutable)
+4. **Datos esenciales:** Solo los datos necesarios
+5. **Sin lógica de negocio:** Solo un DTO
+
+### ¿Cuándo crear un Domain Event?
+
+- ✅ Cambio de estado importante del Aggregate
+- ✅ Evento interesante para otros Bounded Contexts
+- ✅ Disparador de proceso asíncrono (email, notificación)
+- ✅ Auditoría/trazabilidad
+
+---
+
+## Interface DomainEvent
+
+**Ubicación:** `src/Domain/Shared/Interface/DomainEventInterface.php`
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\Shared\Interface;
+
+/**
+ * Interface para todos los Domain Events
+ */
+interface DomainEventInterface
+{
+    /**
+     * Fecha/hora de ocurrencia del evento
+     */
+    public function getOccurredOn(): \DateTimeImmutable;
+}
+```
+
+---
+
+## Events Reservation
+
+### ReservationCreatedEvent
+
+**Ubicación:** `src/Domain/Reservation/Event/ReservationCreatedEvent.php`
+
+**Disparado:** Durante la creación de una nueva reserva
+
+**Handlers:**
+- Enviar email de confirmación al cliente
+- Notificar admin de una nueva reserva
+- Actualizar estadísticas
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\Reservation\Event;
+
+use App\Domain\Reservation\ValueObject\ReservationId;
+use App\Domain\Shared\Interface\DomainEventInterface;
+use App\Domain\Shared\ValueObject\Email;
+
+final readonly class ReservationCreatedEvent implements DomainEventInterface
+{
+    public function __construct(
+        private ReservationId $reservationId,
+        private string $sejourId,
+        private Email $contactEmail,
+        private \DateTimeImmutable $occurredOn,
+    ) {}
+
+    public function getReservationId(): ReservationId
+    {
+        return $this->reservationId;
+    }
+
+    public function getSejourId(): string
+    {
+        return $this->sejourId;
+    }
+
+    public function getContactEmail(): Email
+    {
+        return $this->contactEmail;
+    }
+
+    public function getOccurredOn(): \DateTimeImmutable
+    {
+        return $this->occurredOn;
+    }
+}
+```
+
+---
+
+### ReservationConfirmedEvent
+
+**Ubicación:** `src/Domain/Reservation/Event/ReservationConfirmedEvent.php`
+
+**Disparado:** Durante la confirmación de una reserva por el admin
+
+**Handlers:**
+- Enviar email de confirmación al cliente con detalles
+- Actualizar capacidad de la estancia
+- Crear factura
+- Disparar proceso de pago
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\Reservation\Event;
+
+use App\Domain\Reservation\ValueObject\Money;
+use App\Domain\Reservation\ValueObject\ReservationId;
+use App\Domain\Shared\Interface\DomainEventInterface;
+
+final readonly class ReservationConfirmedEvent implements DomainEventInterface
+{
+    public function __construct(
+        private ReservationId $reservationId,
+        private Money $totalAmount,
+        private int $participantCount,
+        private \DateTimeImmutable $occurredOn,
+    ) {}
+
+    public function getReservationId(): ReservationId
+    {
+        return $this->reservationId;
+    }
+
+    public function getTotalAmount(): Money
+    {
+        return $this->totalAmount;
+    }
+
+    public function getParticipantCount(): int
+    {
+        return $this->participantCount;
+    }
+
+    public function getOccurredOn(): \DateTimeImmutable
+    {
+        return $this->occurredOn;
+    }
+}
+```
+
+---
+
+## Event Handlers
+
+### SendConfirmationEmailOnReservationCreated
+
+**Ubicación:** `src/Application/Reservation/EventHandler/SendConfirmationEmailOnReservationCreated.php`
+
+**Responsabilidad:** Enviar email de confirmación al cliente después de la creación de la reserva
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Reservation\EventHandler;
+
+use App\Domain\Notification\Service\NotificationServiceInterface;
+use App\Domain\Reservation\Event\ReservationCreatedEvent;
+use App\Domain\Reservation\Repository\ReservationRepositoryInterface;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Messenger\Attribute\AsMessageHandler;
+
+/**
+ * Event Handler: Enviar email de confirmación del cliente
+ */
+#[AsMessageHandler]
+final readonly class SendConfirmationEmailOnReservationCreated
+{
+    public function __construct(
+        private ReservationRepositoryInterface $reservationRepository,
+        private NotificationServiceInterface $notificationService,
+        private LoggerInterface $logger,
+    ) {}
+
+    public function __invoke(ReservationCreatedEvent $event): void
+    {
+        $this->logger->info('Manejando ReservationCreatedEvent', [
+            'reservation_id' => (string) $event->getReservationId(),
+            'sejour_id' => $event->getSejourId(),
+        ]);
+
+        try {
+            // Recuperar la reserva completa
+            $reservation = $this->reservationRepository->findById($event->getReservationId());
+
+            // Enviar email de confirmación al cliente
+            $this->notificationService->sendReservationCreatedConfirmation($reservation);
+
+            $this->logger->info('Email de confirmación enviado exitosamente', [
+                'reservation_id' => (string) $event->getReservationId(),
+                'email' => (string) $event->getContactEmail(),
+            ]);
+        } catch (\Exception $e) {
+            $this->logger->error('Error al enviar email de confirmación', [
+                'reservation_id' => (string) $event->getReservationId(),
+                'error' => $e->getMessage(),
+            ]);
+
+            // No re-lanzar: el fallo del envío de email no debe bloquear la reserva
+        }
+    }
+}
+```
+
+---
+
+## Integración Symfony EventDispatcher
+
+### Configuración services.yaml
+
+**Ubicación:** `config/services.yaml`
+
+```yaml
+services:
+    # Auto-configuración de Event Handlers
+    App\Application\:
+        resource: '../src/Application/*/EventHandler/'
+        tags:
+            - { name: messenger.message_handler, bus: event.bus }
+```
+
+### EventBus Adapter
+
+**Ubicación:** `src/Infrastructure/EventBus/SymfonyEventBusAdapter.php`
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Infrastructure\EventBus;
+
+use App\Domain\Shared\Interface\DomainEventInterface;
+use Symfony\Component\Messenger\MessageBusInterface;
+
+/**
+ * Adaptador Symfony Messenger para Domain Events
+ */
+final readonly class SymfonyEventBusAdapter
+{
+    public function __construct(
+        private MessageBusInterface $eventBus,
+    ) {}
+
+    public function dispatch(DomainEventInterface $event): void
+    {
+        $this->eventBus->dispatch($event);
+    }
+
+    /**
+     * @param array<DomainEventInterface> $events
+     */
+    public function dispatchMultiple(array $events): void
+    {
+        foreach ($events as $event) {
+            $this->dispatch($event);
+        }
+    }
+}
+```
+
+---
+
+## Workflow completo
+
+### 1. Creación de una reserva
+
+```php
+// Use Case: CreateReservationUseCase
+
+public function execute(CreateReservationCommand $command): ReservationId
+{
+    // 1. Crear el Aggregate
+    $reservation = Reservation::create(...);
+    // → Registra ReservationCreatedEvent
+
+    // 2. Agregar participantes
+    foreach ($command->participants as $data) {
+        $participant = Participant::create(...);
+        $reservation->addParticipant($participant);
+        // → Registra ParticipantAddedEvent
+    }
+
+    // 3. Calcular precio
+    $totalAmount = $this->pricingService->calculateTotalPrice($reservation);
+    $reservation->setTotalAmount($totalAmount);
+
+    // 4. Guardar
+    $this->reservationRepository->save($reservation);
+
+    // 5. Despachar eventos
+    foreach ($reservation->pullDomainEvents() as $event) {
+        $this->eventBus->dispatch($event);
+        // → ReservationCreatedEvent despachado
+        // → ParticipantAddedEvent x N despachados
+    }
+
+    return $reservation->getId();
+}
+```
+
+### 2. Procesamiento asíncrono (Symfony Messenger)
+
+```
+ReservationCreatedEvent despachado
+    ↓
+Cola Symfony Messenger
+    ↓
+Event Handlers (paralelo):
+    ├─> SendConfirmationEmailOnReservationCreated
+    │   └─> Envía email al cliente
+    │
+    ├─> SendAdminNotificationOnReservationCreated
+    │   └─> Envía email al admin
+    │
+    └─> UpdateStatisticsOnReservationCreated
+        └─> Actualiza contadores
+```
+
+---
+
+## Checklist Domain Events
+
+### Creación de un Event
+
+- [ ] **Inmutable:** Clase `readonly`
+- [ ] **Nombres:** Verbo en pasado (ReservationCreated)
+- [ ] **Interface:** Implementa `DomainEventInterface`
+- [ ] **Timestamp:** Propiedad `occurredOn`
+- [ ] **Datos:** Solo datos esenciales
+- [ ] **Documentación:** PHPDoc con uso y handlers
+
+### Creación de un Event Handler
+
+- [ ] **Responsabilidad única:** Un handler = una tarea
+- [ ] **Atributo:** `#[AsMessageHandler]`
+- [ ] **Readonly:** Clase `readonly`
+- [ ] **Logging:** Registrar éxitos y errores
+- [ ] **Excepciones:** No bloquear si no es crítico
+- [ ] **Tests:** Test unitario con evento mockeado
+
+---
+
+**Fecha de creación:** 2025-11-26
+**Versión:** 1.0.0
+**Autor:** The Bearded CTO

package/Dev/i18n/es/Symfony/templates/domain-event.md

@@ -0,0 +1,95 @@
+# Plantilla: Domain Event (DDD)
+
+> **Patrón DDD** - Evento de negocio que representa un hecho que ha ocurrido
+> Referencia: `.claude/rules/01-architecture-ddd.md`
+
+## ¿Qué es un Domain Event?
+
+Un Domain Event es:
+- ✅ **Inmutable** (clase readonly)
+- ✅ **Nombrado en pasado** (ReservationCreated, no CreateReservation)
+- ✅ **Contiene los datos necesarios** (ID del agregado + contexto)
+- ✅ **Con marca temporal** (occurredOn timestamp)
+- ✅ **Publicado por el aggregate root**
+
+**¿Por qué usar Domain Events?**
+- Desacoplamiento entre agregados
+- Trazabilidad (audit log)
+- Comunicación asíncrona (message bus)
+- Event Sourcing (opcional)
+
+---
+
+## Plantilla PHP 8.2+
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\Event;
+
+use Symfony\Component\Uid\Uuid;
+
+/**
+ * Domain Event: [NombreEvento]
+ *
+ * Disparado cuando: [Condición de disparo]
+ *
+ * Alcance: [Descripción de lo que representa este evento]
+ *
+ * Suscriptores potenciales:
+ * - [Suscriptor 1]: [Acción realizada]
+ * - [Suscriptor 2]: [Acción realizada]
+ */
+final readonly class [NombreEvento]
+{
+    private \DateTimeImmutable $occurredOn;
+
+    public function __construct(
+        private Uuid $aggregateId,
+        // Otros datos del contexto...
+    ) {
+        $this->occurredOn = new \DateTimeImmutable();
+    }
+
+    public function getAggregateId(): Uuid
+    {
+        return $this->aggregateId;
+    }
+
+    public function getOccurredOn(): \DateTimeImmutable
+    {
+        return $this->occurredOn;
+    }
+
+    /**
+     * Devuelve los datos del evento (para serialización)
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'aggregate_id' => $this->aggregateId->toRfc4122(),
+            'occurred_on' => $this->occurredOn->format(\DateTimeInterface::ATOM),
+            // Otros campos...
+        ];
+    }
+}
+```
+
+---
+
+## Checklist Domain Event
+
+- [ ] Clase `final readonly`
+- [ ] Nombrado en pasado (ReservationCreated, no CreateReservation)
+- [ ] Propiedad `occurredOn` (timestamp)
+- [ ] Referencia al ID del agregado (Uuid)
+- [ ] Constructor toma la entidad completa
+- [ ] Método `toArray()` para serialización
+- [ ] Sin lógica de negocio (solo datos)
+- [ ] Documentación del contexto y suscriptores potenciales
+- [ ] Tests unitarios (creación, serialización)
+- [ ] Tests de integración (suscriptores)