# Capa de Aplicación - Shared (Casos de Uso Compartidos)

## Propósito

La capa de Aplicación de `shared/` contiene **casos de uso y servicios compartidos** que orquestan la lógica
de dominio. Esta capa coordina el flujo de datos entre el dominio y la infraestructura.

## Principios

1. **Orquestación**: Coordina objetos de dominio para realizar casos de uso
2. **Sin lógica de negocio**: Delega la lógica al dominio
3. **Independiente de frameworks**: No depende de WordPress directamente
4. **Contratos claros**: Define interfaces para servicios

## Estructura

```
shared/Application/
├── Contracts/           # Interfaces de servicios (CacheServiceInterface, etc.)
└── Services/            # Implementaciones de servicios compartidos
```

## Ejemplos de Uso

### Contracts (Interfaces de Servicios)

```php
namespace ROITheme\Shared\Application\Contracts;

interface CacheServiceInterface
{
    public function get(string $key): mixed;
    public function set(string $key, mixed $value, int $ttl = 3600): bool;
    public function delete(string $key): bool;
    public function flush(): bool;
}
```

```php
namespace ROITheme\Shared\Application\Contracts;

interface ValidationServiceInterface
{
    public function validate(array $data, array $rules): array;
    public function fails(): bool;
    public function errors(): array;
}
```

### Services (Implementaciones Abstractas)

Servicios que pueden tener múltiples implementaciones:

```php
namespace ROITheme\Shared\Application\Services;

use ROITheme\Shared\Application\Contracts\ValidationServiceInterface;

abstract class BaseValidationService implements ValidationServiceInterface
{
    protected array $errors = [];

    public function fails(): bool
    {
        return !empty($this->errors);
    }

    public function errors(): array
    {
        return $this->errors;
    }

    abstract public function validate(array $data, array $rules): array;
}
```

## Relación con Infrastructure

La capa de Application **define contratos** (interfaces), pero **no implementa** la lógica específica
de frameworks. Las implementaciones concretas van en `shared/Infrastructure/`:

```
shared/Application/Contracts/CacheServiceInterface.php (interface)
                    ↓
shared/Infrastructure/Services/WordPressCacheService.php (implementación)
```

## Reglas de Dependencia

✅ **PUEDE** depender de:
- `shared/Domain/` (Value Objects, Entities, Exceptions)
- Interfaces dentro de `shared/Application/Contracts/`

❌ **NO PUEDE** depender de:
- `shared/Infrastructure/` (implementaciones concretas)
- `admin/` o `public/`
- WordPress functions directamente
- Detalles de implementación

## Testing

Los servicios de esta capa se testean con **tests unitarios usando mocks**:

```php
// tests/Unit/Shared/Application/Services/SomeServiceTest.php
public function test_validates_data_correctly()
{
    $validator = $this->createMock(ValidationServiceInterface::class);
    $validator->method('validate')->willReturn(['name' => 'Test']);

    $service = new SomeService($validator);
    $result = $service->process(['name' => 'Test']);

    $this->assertTrue($result);
}
```

## Cuándo Agregar Código Aquí

Agrega código a `shared/Application/` cuando:
- Defines un contrato para un servicio compartido
- Necesitas orquestar múltiples objetos de dominio
- El servicio será usado por admin/ y public/
- Necesitas abstraer implementaciones de infraestructura

No agregues aquí:
- Lógica de negocio (va en Domain/)
- Implementaciones concretas de WordPress (van en Infrastructure/)
- Lógica específica de un solo contexto
- Código acoplado a frameworks

## Ejemplos de Servicios Comunes

- `ValidationServiceInterface`: Validación de datos
- `CacheServiceInterface`: Manejo de caché
- `SerializerServiceInterface`: Serialización de datos
- `LoggerServiceInterface`: Logging
- `EventDispatcherInterface`: Eventos del sistema