refactor: reorganizar openspec y planificacion con spec recaptcha
- renombrar openspec/ a _openspec/ (carpeta auxiliar) - mover specs de features a changes/ - crear specs base: arquitectura-limpia, estandares-codigo, nomenclatura - migrar _planificacion/ con design-system y roi-theme-template - agregar especificacion recaptcha anti-spam (proposal, tasks, spec) - corregir rutas y referencias en todas las specs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
FrankZamora
335
_planificacion/validacion-specs-vs-codigo-actual.md
Normal file
335
_planificacion/validacion-specs-vs-codigo-actual.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user