roi-theme/shared/Application/README.md

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)

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;
}

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:

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:

// 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