roi-theme/_planificacion/validacion-specs-vs-codigo-actual.md

# Validación: Especificaciones vs Código Actual

**Fecha:** 2026-01-08
**Objetivo:** Verificar que las especificaciones reflejan el código existente

---

## Resumen Ejecutivo

**CONCLUSIÓN: El código actual YA cumple con las especificaciones propuestas.**

Las mejoras a las especificaciones son documentación/clarificación de patrones existentes, NO nuevas invenciones.

---

## 1. Arquitectura Clean Architecture

### Verificación de Estructura de Capas

| Capa | Ubicación Esperada | Estado |
|------|-------------------|--------|
| Domain | `*/Domain/` | ✅ Existe |
| Application | `*/Application/` | ✅ Existe |
| Infrastructure | `*/Infrastructure/` | ✅ Existe |

### Evidencia: Estructura de Carpetas

```
Shared/
├── Domain/
│   └── Contracts/           # 23 interfaces
├── Application/
│   └── UseCases/            # Casos de uso
└── Infrastructure/
    └── Services/            # Implementaciones
```

### Evidencia: Contratos en Domain (23 interfaces)

```
Shared/Domain/Contracts/
├── AjaxControllerInterface.php
├── CSSGeneratorInterface.php
├── ComponentRepositoryInterface.php
├── RendererInterface.php
├── SchemaSyncServiceInterface.php
└── ... (18 más)
```

**VEREDICTO:** ✅ Clean Architecture implementada correctamente

---

## 2. Nomenclatura

### Convención: Carpetas en PascalCase

| Módulo | Carpeta Public | Carpeta Admin | Estado |
|--------|---------------|---------------|--------|
| ContactForm | `Public/ContactForm/` | `Admin/ContactForm/` | ✅ |
| FeaturedImage | `Public/FeaturedImage/` | `Admin/FeaturedImage/` | ✅ |
| Footer | `Public/Footer/` | `Admin/Footer/` | ✅ |
| TopNotificationBar | `Public/TopNotificationBar/` | `Admin/TopNotificationBar/` | ✅ |

**Módulos verificados:** 17 en Public/, 17 en Admin/

### Convención: Schemas en kebab-case

| Schema | Nombre Archivo | component_name | Estado |
|--------|---------------|----------------|--------|
| Contact Form | `contact-form.json` | `"contact-form"` | ✅ |
| Featured Image | `featured-image.json` | `"featured-image"` | ✅ |
| Top Notification Bar | `top-notification-bar.json` | `"top-notification-bar"` | ✅ |
| CTA Box Sidebar | `cta-box-sidebar.json` | `"cta-box-sidebar"` | ✅ |

**Schemas verificados:** 17 archivos JSON

### Convención: Clases en PascalCase

| Tipo | Patrón | Ejemplo Real | Estado |
|------|--------|--------------|--------|
| Renderer | `[Component]Renderer` | `ContactFormRenderer` | ✅ |
| FormBuilder | `[Component]FormBuilder` | `ContactFormFormBuilder` | ✅ |
| Handler | `[Component]AjaxHandler` | `NewsletterAjaxHandler` | ✅ |

### Convención: Namespaces

**Patrón:** `ROITheme\[Context]\[Component]\[Layer]`

**Evidencia:**
```php
// ContactFormRenderer.php
namespace ROITheme\Public\ContactForm\Infrastructure\Ui;

// ContactFormFormBuilder.php
namespace ROITheme\Admin\ContactForm\Infrastructure\Ui;

// NewsletterAjaxHandler.php
namespace ROITheme\Public\Footer\Infrastructure\Api\WordPress;
```

**VEREDICTO:** ✅ Nomenclatura consistente en todo el tema

---

## 3. Estándares de Código PHP

### strict_types

**Comando verificación:** `grep "declare(strict_types=1)" Public/ -r`
**Resultado:** 43 archivos con strict_types

| Ubicación | Archivos con strict_types | Total |
|-----------|--------------------------|-------|
| Public/ | 43 | 43 |
| Admin/ (muestra) | ✅ Verificado | - |
| Shared/ (muestra) | ✅ Verificado | - |

### Clases final

**Resultado:** 39 archivos usan `final class`

**Evidencia:**
```php
// ContactFormRenderer.php:24
final class ContactFormRenderer implements RendererInterface

// ContactFormFormBuilder.php:19
final class ContactFormFormBuilder

// NewsletterAjaxHandler.php
final class NewsletterAjaxHandler
```

### Inyección de Dependencias via Constructor

**Patrón esperado:** Interfaces inyectadas, no clases concretas

**Evidencia:**
```php
// ContactFormRenderer.php:28-30
public function __construct(
    private CSSGeneratorInterface $cssGenerator  // ✅ Interface
) {}

// ContactFormFormBuilder.php:21-23
public function __construct(
    private AdminDashboardRenderer $renderer     // ✅ DI via constructor
) {}
```

**VEREDICTO:** ✅ Estándares PHP cumplidos

---

## 4. Patrones de Renderer

### Patrón: supports() retorna kebab-case

**Evidencia ContactFormRenderer.php:71-74:**
```php
private const COMPONENT_NAME = 'contact-form';  // ✅ kebab-case

public function supports(string $componentType): bool
{
    return $componentType === self::COMPONENT_NAME;  // ✅
}
```

### Patrón: Validación de Visibilidad (3 campos)

**Evidencia ContactFormRenderer.php:76-99:**
```php
private function isEnabled(array $data): bool
{
    $value = $data['visibility']['is_enabled'] ?? false;  // ✅
    return $value === true || $value === '1' || $value === 1;
}

private function getVisibilityClass(array $data): ?string
{
    $showDesktop = $data['visibility']['show_on_desktop'] ?? true;  // ✅
    $showMobile = $data['visibility']['show_on_mobile'] ?? true;    // ✅
    // ...
}
```

### Patrón: CSS via Generator (no hardcodeado)

**Evidencia ContactFormRenderer.php:49:**
```php
$css = $this->generateCSS($data);  // ✅ Usa CSSGenerator inyectado
```

**VEREDICTO:** ✅ Patrones de Renderer cumplidos

---

## 5. Patrones de FormBuilder

### Patrón: Design System Consistente

**Colores esperados:** `#0E2337`, `#1e3a5f`, `#FF8600`

**Evidencia ContactFormFormBuilder.php:57-58:**
```php
$html .= 'style="background: linear-gradient(135deg, #0E2337 0%, #1e3a5f 100%); border-left: 4px solid #FF8600;">';
```

### Patrón: data-component en kebab-case

**Evidencia ContactFormFormBuilder.php:69:**
```php
$html .= '... data-component="contact-form">';  // ✅ kebab-case
```

### Patrón: Bootstrap 5

**Evidencia ContactFormFormBuilder.php:31:**
```php
$html .= '<div class="row g-3">';  // ✅ Bootstrap 5 grid
```

**VEREDICTO:** ✅ Patrones de FormBuilder cumplidos

---

## 6. Patrones de Schema JSON

### Campos Obligatorios de Visibilidad

**Evidencia contact-form.json:6-31:**
```json
"visibility": {
    "label": "Visibilidad",
    "priority": 10,
    "fields": {
        "is_enabled": { ... },       // ✅ Obligatorio
        "show_on_desktop": { ... },  // ✅ Obligatorio
        "show_on_mobile": { ... }    // ✅ Obligatorio
    }
}
```

### Estructura de Grupos

**Evidencia contact-form.json:**
```json
{
    "component_name": "contact-form",  // ✅ kebab-case
    "version": "1.0.0",                // ✅ Versionado
    "description": "...",               // ✅ Documentado
    "groups": {
        "visibility": { "priority": 10 },
        "content": { "priority": 20 },
        // ...
    }
}
```

**VEREDICTO:** ✅ Patrones de Schema cumplidos

---

## 7. Estructura OpenSpec Actual

### Archivos Existentes

```
openspec/
├── AGENTS.md       ✅ (456 líneas)
├── project.md      ✅ (contiene convenciones)
├── specs/
│   ├── 00arquitectura-limpia/spec.md  ✅ (215 líneas)
│   ├── 00estandares-codigo/spec.md    ✅ (350 líneas)
│   └── ...
└── changes/        ✅ (registro de cambios)
```

### Archivos Faltantes (para mejorar)

| Archivo | Estado | Acción |
|---------|--------|--------|
| WORKFLOW-ROI-THEME.md | ❌ No existe | CREAR |
| nomenclatura/spec.md | ❌ No existe | CREAR |

**NOTA:** Los archivos faltantes son DOCUMENTACIÓN de patrones que YA existen en el código.

---

## 8. Tabla Resumen de Validación

| Especificación | Código Actual | Estado |
|----------------|---------------|--------|
| Clean Architecture (3 capas) | Shared/Domain, /Application, /Infrastructure | ✅ CUMPLE |
| Carpetas PascalCase | ContactForm/, FeaturedImage/, etc. | ✅ CUMPLE |
| Schemas kebab-case | contact-form.json, featured-image.json | ✅ CUMPLE |
| component_name kebab-case | "contact-form", "featured-image" | ✅ CUMPLE |
| strict_types=1 | 43+ archivos verificados | ✅ CUMPLE |
| final class | 39+ clases verificadas | ✅ CUMPLE |
| DI via constructor | CSSGeneratorInterface, etc. | ✅ CUMPLE |
| supports() kebab-case | return 'contact-form' | ✅ CUMPLE |
| 3 campos visibilidad | is_enabled, show_on_desktop, show_on_mobile | ✅ CUMPLE |
| Design System colores | #0E2337, #1e3a5f, #FF8600 | ✅ CUMPLE |
| Namespaces ROITheme\... | ROITheme\Public\ContactForm\... | ✅ CUMPLE |

---

## 9. Conclusión

### El código existente YA implementa:

1. **Clean Architecture** - Capas Domain/Application/Infrastructure
2. **Convenciones de Nomenclatura** - PascalCase, kebab-case según contexto
3. **Estándares PHP** - strict_types, final class, DI
4. **Patrones de Componentes** - Renderer, FormBuilder, Schema
5. **Design System** - Colores consistentes

### Las especificaciones mejoradas serán:

1. **DOCUMENTACIÓN** de patrones existentes (no invenciones)
2. **CLARIFICACIÓN** de reglas implícitas
3. **EJEMPLOS** de código correcto vs incorrecto
4. **WORKFLOW** formalizado (que ya se sigue informalmente)

### Beneficio de las mejoras:

- Mayor claridad para nuevos desarrolladores
- Referencia rápida de patrones
- Validación automatizable
- Onboarding más rápido

---

**Última actualización:** 2026-01-08