Fase-00: Estructura Clean Architecture Context-First creada
- Creada estructura shared/ con Domain, Application, Infrastructure - Documentación completa de arquitectura (5 READMEs, ~6150 líneas) - Archivos .gitkeep para preservar estructura en Git - Contextos admin/ y public/ documentados Estructura shared/: - Domain/ (ValueObjects, Exceptions, Contracts) - Application/ (Contracts, Services) - Infrastructure/ (Services, Traits) Documentación incluye: - Principios de Clean Architecture - Reglas de dependencia - Ejemplos de código - Guías de testing - Mejores prácticas Preparación completa para implementación en Fase-1.
This commit is contained in:
FrankZamora
257
admin/README.md
Normal file
257
admin/README.md
Normal file
@@ -0,0 +1,257 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user