roi-theme/admin

Contexto Admin - Administración de Componentes

Propósito

El contexto admin/ contiene todo el código relacionado con la administración de componentes en el panel de WordPress. Cada componente tiene su propia carpeta con su Clean Architecture completa.

Filosofía: Context-First Architecture

En lugar de separar por capas (Domain, Application, Infrastructure), separamos por contextos (admin, public, shared) y cada contexto tiene sus propias capas internas.

Estructura (Fase-00)

En Fase-00 solo creamos la estructura base. Los componentes se crearán en fases posteriores:

admin/
├── README.md (este archivo)
└── .gitkeep (preserva directorio en Git)

Estructura Futura (Post Fase-00)

admin/
├── Navbar/                           # Componente Navbar
│   ├── Domain/
│   │   ├── NavbarComponent.php       # Entidad
│   │   └── NavbarRepositoryInterface.php
│   ├── Application/
│   │   ├── SaveNavbarUseCase.php     # Caso de uso
│   │   └── DTO/
│   │       └── NavbarSettingsDTO.php
│   ├── Infrastructure/
│   │   ├── Persistence/
│   │   │   └── WordPressNavbarRepository.php
│   │   ├── UI/
│   │   │   ├── NavbarAdminPage.php   # Página de admin
│   │   │   ├── NavbarForm.php        # Formulario
│   │   │   └── views/
│   │   │       └── navbar-settings.php
│   │   └── API/
│   │       └── NavbarAjaxHandler.php # AJAX endpoints
│   └── README.md
├── Footer/                           # Otro componente
│   └── (misma estructura)
└── (más componentes...)

Principios del Contexto Admin

1. Aislamiento: Cada componente es independiente
2. Clean Architecture: Cada componente tiene Domain, Application, Infrastructure
3. Sin acoplamiento: Un componente no depende de otro directamente
4. Código compartido: Va en shared/ si es usado por múltiples componentes

Responsabilidades

El contexto admin/ se encarga de:

✅ Formularios de configuración de componentes ✅ Validación de entrada del usuario administrador ✅ Guardado de configuraciones en la base de datos ✅ Páginas de administración en el panel de WordPress ✅ AJAX endpoints para operaciones administrativas ✅ Permisos y capabilities de administrador

❌ NO se encarga de:

• Renderizado frontend de componentes (va en public/)
• Lógica compartida entre contextos (va en shared/)
• Configuraciones globales del tema

Ejemplo de Flujo de Admin

1. Usuario administra el Navbar

Usuario Admin (navegador)
    ↓
NavbarAdminPage.php (muestra formulario)
    ↓
Usuario envía formulario via AJAX
    ↓
NavbarAjaxHandler.php (recibe request)
    ↓
SaveNavbarUseCase.php (orquesta la lógica)
    ↓
WordPressNavbarRepository.php (guarda en DB)
    ↓
Respuesta JSON al navegador

2. Código de ejemplo

// admin/Navbar/Application/SaveNavbarUseCase.php
namespace ROITheme\Admin\Navbar\Application;

use ROITheme\Admin\Navbar\Domain\NavbarRepositoryInterface;
use ROITheme\Shared\Application\Contracts\ValidationServiceInterface;

final class SaveNavbarUseCase
{
    public function __construct(
        private readonly NavbarRepositoryInterface $repository,
        private readonly ValidationServiceInterface $validator
    ) {}

    public function execute(array $data): void
    {
        $validated = $this->validator->validate($data, [
            'logo_url' => 'url',
            'menu_items' => 'array',
            'sticky' => 'bool',
        ]);

        if ($this->validator->fails()) {
            throw new ValidationException($this->validator->errors());
        }

        $this->repository->save($validated);
    }
}

// admin/Navbar/Infrastructure/UI/NavbarAdminPage.php
namespace ROITheme\Admin\Navbar\Infrastructure\UI;

final class NavbarAdminPage
{
    public function register(): void
    {
        add_action('admin_menu', [$this, 'addMenuPage']);
    }

    public function addMenuPage(): void
    {
        add_menu_page(
            'Navbar Settings',
            'Navbar',
            'manage_options',
            'roi-navbar-settings',
            [$this, 'render'],
            'dashicons-menu',
            30
        );
    }

    public function render(): void
    {
        require __DIR__ . '/views/navbar-settings.php';
    }
}

Relación con Otros Contextos

admin/           → Administra configuraciones
    ↓ guarda
Base de Datos    → Almacena settings
    ↓ lee
public/          → Renderiza componentes en frontend

Clave: admin/ y public/ NO se hablan directamente. Se comunican a través de la base de datos.

Reglas de Dependencia

✅ PUEDE depender de:

• shared/Domain/ (Value Objects, Exceptions)
• shared/Application/ (Contracts, Services)
• shared/Infrastructure/ (Implementaciones de servicios)
• WordPress admin functions (add_menu_page, add_settings_section, etc.)

❌ NO PUEDE depender de:

• public/ (contexto independiente)
• Código de frontend (JS/CSS va en Infrastructure/UI/)

Testing

Tests Unitarios

// tests/Unit/Admin/Navbar/Application/SaveNavbarUseCaseTest.php
public function test_saves_valid_navbar_settings()
{
    $repository = $this->createMock(NavbarRepositoryInterface::class);
    $validator = $this->createMock(ValidationServiceInterface::class);

    $useCase = new SaveNavbarUseCase($repository, $validator);
    $useCase->execute(['logo_url' => 'http://example.com/logo.png']);

    // Assertions...
}

Tests de Integración

// tests/Integration/Admin/Navbar/Infrastructure/WordPressNavbarRepositoryTest.php
public function test_saves_and_retrieves_navbar_settings()
{
    $repository = new WordPressNavbarRepository();
    $settings = ['logo_url' => 'http://example.com/logo.png'];

    $repository->save($settings);
    $retrieved = $repository->get();

    $this->assertEquals($settings, $retrieved);
}

Tests E2E (Playwright)

// tests/E2E/Admin/NavbarAdminPageTest.php
public function test_admin_can_save_navbar_settings()
{
    $this->loginAsAdmin();
    $this->visit('/wp-admin/admin.php?page=roi-navbar-settings');
    $this->fillField('logo_url', 'http://example.com/logo.png');
    $this->click('Save Settings');
    $this->see('Settings saved successfully');
}

Cuándo Agregar Código Aquí

Agrega código a admin/ cuando:

• Creas un nuevo componente administrable
• Necesitas una página de configuración en el panel de WordPress
• Manejas formularios de administrador
• Procesas AJAX desde el admin
• Validas o guardas configuraciones

No agregues aquí:

• Renderizado frontend (va en public/)
• Lógica compartida (va en shared/)
• Configuraciones globales del tema

Estado Actual (Fase-00)

En Fase-00, admin/ solo tiene la estructura base. Los componentes se crearán en las siguientes fases:

• Fase-1: Estructura base e infraestructura
• Fase-2: Migración de base de datos
• Fase-3: Implementación de componentes admin
• Fase-4+: Componentes adicionales

Próximos Pasos

1. Crear primer componente en Fase-3 (ej: Navbar)
2. Implementar Domain layer del componente
3. Implementar Application layer (casos de uso)
4. Implementar Infrastructure layer (WordPress integration)
5. Crear tests unitarios e integración
6. Repetir para cada componente