roi-theme/admin/README.md

# 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

```php
// 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);
    }
}
```

```php
// 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
```php
// 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
```php
// 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)
```php
// 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