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>
2026-01-08 15:30:45 -06:00
parent 0d6b6db108
commit 0f6387ab46
58 changed files with 15364 additions and 1171 deletions
--- a/_planificacion/plan-mejora-especificaciones-openspec.md
+++ b/_planificacion/plan-mejora-especificaciones-openspec.md
@@ -0,0 +1,366 @@
+# Plan de Mejora de Especificaciones OpenSpec - ROI Theme
+
+**Fecha:** 2026-01-08
+**Referencia:** Modelo de especificaciones de Aditec (`D:\_Desarrollo\100Aditec\_openspec`)
+
+---
+
+## INSTRUCCIONES DE RECUPERACIÓN (LEER PRIMERO)
+
+> **Si la conversación se compactó, se fue el internet o se apagó la computadora:**
+
+1. **Estado actual:** Ver sección "ESTADO ACTUAL" abajo
+2. **Buscar primer `[ ]`:** Ir a la tarea sin marcar
+3. **Continuar desde ahí:** No repetir tareas marcadas `[x]`
+4. **Marcar `[x]` al completar:** Guardar después de cada cambio
+
+### ESTADO ACTUAL
+
+| Campo | Valor |
+|-------|-------|
+| **Última actualización** | 2026-01-08 |
+| **Última tarea completada** | FASE 3 - Referencias y verificación COMPLETADO |
+| **Próxima tarea** | CASO PILOTO P.1 - Crear spec para AntiSpamValidator |
+| **Progreso total** | 66/75 tareas |
+
+### Archivos de contexto a leer si es necesario:
+- `_planificacion/analisis-spam-formularios.md` - Análisis de spam
+- `_planificacion/validacion-specs-vs-codigo-actual.md` - Validación código vs specs
+- `_openspec/specs/` - Specs base del proyecto (3 archivos)
+- `_openspec/changes/` - Specs de features específicos
+- `D:\_Desarrollo\100Aditec\_openspec\` - Referencia de Aditec
+
+---
+
+## CHECKLIST MAESTRO DE PROGRESO
+
+### Estado General
+- [x] Análisis de especificaciones Aditec completado
+- [x] Comparación ROI Theme vs Aditec completado
+- [x] Validación código actual vs especificaciones propuestas
+- [x] **FASE 1: Crear archivos faltantes** (COMPLETADO)
+- [x] **FASE 2: Expandir archivos existentes** (COMPLETADO)
+- [x] **FASE 3: Actualizar referencias** (COMPLETADO)
+- [ ] **CASO PILOTO: Implementar anti-spam con nuevo sistema**
+
+---
+
+## FASE 1: CREAR ARCHIVOS FALTANTES
+
+### 1.1 WORKFLOW-ROI-THEME.md (~300 líneas)
+**Ubicación:** `_openspec/WORKFLOW-ROI-THEME.md`
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+#### Secciones a crear:
+- [x] **1.1.1** Encabezado y metadata (version, fecha)
+- [x] **1.1.2** Regla de Oro del proyecto
+  - [x] "SI NO EXISTE spec.md → NO SE TOCA CÓDIGO"
+  - [x] Explicación de por qué esta regla
+- [x] **1.1.3** Flujo de 3 fases obligatorio
+  - [x] Fase 1: Proponer (qué archivos se crean)
+  - [x] Fase 2: Especificar (qué archivos se crean)
+  - [x] Fase 3: Implementar (qué archivos se crean)
+- [x] **1.1.4** Flujo de 5 fases para componentes ROI Theme
+  - [x] Fase 1: Schema JSON (ubicación, formato, campos obligatorios)
+  - [x] Fase 2: Sincronización BD (comando WP-CLI)
+  - [x] Fase 3: Renderer (ubicación, patrones, DI)
+  - [x] Fase 4: FormBuilder (ubicación, patrones, Design System)
+  - [x] Fase 5: Validación (script, qué valida)
+- [x] **1.1.5** Agentes disponibles y cuándo usarlos
+  - [x] roi-schema-architect
+  - [x] roi-renderer-builder
+  - [x] roi-form-builder
+- [x] **1.1.6** Comandos WP-CLI disponibles
+  - [x] sync-component
+  - [x] sync-all-components
+  - [x] Ejemplos de uso
+- [x] **1.1.7** Reglas de Clean Architecture resumidas
+  - [x] Qué puede y no puede hacer Domain
+  - [x] Qué puede y no puede hacer Application
+  - [x] Qué puede y no puede hacer Infrastructure
+- [x] **1.1.8** Sección de Lecciones Aprendidas
+  - [x] Errores comunes y cómo evitarlos
+  - [x] Patrones que funcionan
+
+---
+
+### 1.2 nomenclatura.md (~600 líneas)
+**Ubicación:** `_openspec/specs/nomenclatura.md`
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+#### Pre-requisitos:
+- [x] **1.2.0** Archivo plano en `_openspec/specs/` (sin carpeta anidada)
+
+#### Secciones a crear:
+- [x] **1.2.1** Encabezado y Feature principal
+- [x] **1.2.2** Tabla resumen de TODAS las nomenclaturas (vista rápida)
+- [x] **1.2.3** Nomenclatura de Carpetas
+  - [x] Carpetas principales (Admin/, Public/, Shared/)
+  - [x] Carpetas de módulo (PascalCase)
+  - [x] Carpetas auxiliares (_planificacion, _arquitectura)
+  - [x] Carpetas de capas (Domain/, Application/, Infrastructure/)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.4** Nomenclatura de Archivos PHP
+  - [x] Archivos de clase (PascalCase.php)
+  - [x] Archivos de interface (PascalCaseInterface.php)
+  - [x] Archivos de trait (PascalCaseTrait.php)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.5** Nomenclatura de Archivos JSON (Schemas)
+  - [x] Nombres en kebab-case
+  - [x] Extensión .json
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.6** Nomenclatura de Namespaces
+  - [x] Patrón: ROITheme\[Context]\[Component]\[Layer]
+  - [x] Context: Admin, Public, Shared
+  - [x] Layer: Domain, Application, Infrastructure
+  - [x] Subcapas: Ui, Api, Persistence, Services
+  - [x] Ejemplos completos
+- [x] **1.2.7** Nomenclatura de Clases
+  - [x] Clases regulares (PascalCase)
+  - [x] Renderers ([Component]Renderer)
+  - [x] FormBuilders ([Component]FormBuilder)
+  - [x] UseCases ([Action][Entity]UseCase)
+  - [x] Services ([Entity]Service)
+  - [x] Repositories ([Entity]Repository)
+  - [x] Handlers ([Action]Handler)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.8** Nomenclatura de Interfaces
+  - [x] Sufijo Interface o Contract
+  - [x] Ubicación en Domain/Contracts/
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.9** Nomenclatura de Métodos
+  - [x] Métodos públicos (camelCase)
+  - [x] Métodos privados (camelCase)
+  - [x] Métodos booleanos (is*, has*, can*, should*)
+  - [x] Getters/Setters (get*, set*)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.10** Nomenclatura de Propiedades
+  - [x] Propiedades (camelCase)
+  - [x] Propiedades booleanas (is*, has*)
+  - [x] Visibilidad (private por defecto)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.11** Nomenclatura de Variables
+  - [x] Variables locales ($camelCase)
+  - [x] Parámetros ($camelCase)
+  - [x] Variables de iteración ($item, $key, $i)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.12** Nomenclatura de Constantes
+  - [x] Constantes de clase (UPPER_SNAKE_CASE)
+  - [x] Constantes globales (ROI_THEME_*)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.13** Nomenclatura de component_name
+  - [x] Formato kebab-case en JSON
+  - [x] Formato kebab-case en BD
+  - [x] Conversión kebab-case ↔ PascalCase
+  - [x] Ejemplos de conversión
+- [x] **1.2.14** Nomenclatura de Hooks WordPress
+  - [x] Actions (roi_theme_*)
+  - [x] Filters (roi_theme_filter_*)
+  - [x] Ejemplos correctos e incorrectos
+- [x] **1.2.15** Validación Pre-commit
+  - [x] Checklist de nomenclatura
+  - [x] Errores comunes a evitar
+
+---
+
+## FASE 2: EXPANDIR ARCHIVOS EXISTENTES
+
+### 2.1 arquitectura-limpia.md (+485 líneas)
+**Ubicación:** `_openspec/specs/arquitectura-limpia.md`
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+#### Secciones a agregar:
+- [x] **2.1.1** Diagrama ASCII de las 3 capas
+  - [x] Domain (centro, sin dependencias)
+  - [x] Application (usa Domain)
+  - [x] Infrastructure (usa Application y Domain)
+  - [x] Flechas de dependencia
+- [x] **2.1.2** Estructura completa de carpetas del tema
+  - [x] Árbol completo roi-theme/
+  - [x] Explicación de cada carpeta
+  - [x] Cuándo crear nuevas carpetas
+- [x] **2.1.3** Reglas de anidamiento
+  - [x] Profundidad máxima: 4 niveles
+  - [x] Regla de 3 archivos para subcarpetas
+  - [x] Ejemplos de estructuras válidas e inválidas
+- [x] **2.1.4** Diferencia entre niveles de Shared
+  - [x] Shared/ (raíz) - código global
+  - [x] Admin/Shared/ - compartido solo en Admin
+  - [x] Public/Shared/ - compartido solo en Public
+  - [x] Cuándo usar cada uno
+- [x] **2.1.5** Ejemplos de código PHP por capa
+  - [x] Domain: Entidad correcta vs incorrecta
+  - [x] Domain: Interface correcta vs incorrecta
+  - [x] Application: UseCase correcto vs incorrecto
+  - [x] Infrastructure: Repository correcto vs incorrecto
+  - [x] Infrastructure: Renderer correcto vs incorrecto
+- [x] **2.1.6** Patrones de herencia
+  - [x] Herencia para Renderers (si aplica)
+  - [x] Herencia para FormBuilders (si aplica)
+  - [x] Composición vs Herencia
+  - [x] Profundidad máxima de herencia
+- [x] **2.1.7** Mapeo de terminología
+  - [x] Tabla: Clean Architecture estándar → ROI Theme
+  - [x] Entity → Component/Entity
+  - [x] UseCase → UseCase
+  - [x] Gateway → Repository
+  - [x] Presenter → Renderer
+- [x] **2.1.8** Validación de arquitectura
+  - [x] Script validate-architecture.php
+  - [x] Qué valida
+  - [x] Cómo ejecutarlo
+  - [x] Cómo interpretar errores
+
+---
+
+### 2.2 estandares-codigo.md (+877 líneas)
+**Ubicación:** `_openspec/specs/estandares-codigo.md`
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+#### Secciones a agregar:
+- [x] **2.2.1** Ejemplos de código PHP para SOLID
+  - [x] SRP: Ejemplo correcto vs incorrecto
+  - [x] OCP: Ejemplo correcto vs incorrecto
+  - [x] LSP: Ejemplo correcto vs incorrecto
+  - [x] ISP: Ejemplo correcto vs incorrecto
+  - [x] DIP: Ejemplo correcto vs incorrecto
+- [x] **2.2.2** Manejo de errores WordPress
+  - [x] Cuándo usar wp_die()
+  - [x] Cuándo usar WP_Error
+  - [x] Cuándo usar excepciones
+  - [x] Ejemplos de cada caso
+- [x] **2.2.3** Sanitización y validación
+  - [x] sanitize_text_field()
+  - [x] sanitize_email()
+  - [x] absint()
+  - [x] wp_kses()
+  - [x] Tabla de funciones por tipo de dato
+- [x] **2.2.4** Escaping para output
+  - [x] esc_html()
+  - [x] esc_attr()
+  - [x] esc_url()
+  - [x] esc_textarea()
+  - [x] wp_kses_post()
+  - [x] Tabla de funciones por contexto
+- [x] **2.2.5** Hooks WordPress
+  - [x] add_action() - cuándo y cómo
+  - [x] add_filter() - cuándo y cómo
+  - [x] Prioridades
+  - [x] Número de argumentos
+  - [x] Ejemplos correctos
+- [x] **2.2.6** Recursos y cleanup
+  - [x] Transients (set, get, delete)
+  - [x] Object cache
+  - [x] Cuándo limpiar recursos
+  - [x] Ejemplos
+- [x] **2.2.7** Checklist pre-commit detallado
+  - [x] Verificaciones de sintaxis
+  - [x] Verificaciones de estilo
+  - [x] Verificaciones de seguridad
+  - [x] Verificaciones de arquitectura
+  - [x] Verificaciones de nomenclatura
+
+---
+
+## FASE 3: ACTUALIZAR REFERENCIAS
+
+### 3.1 Actualizar project.md
+**Ubicación:** `_openspec/project.md`
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+- [x] **3.1.1** Agregar referencia a WORKFLOW-ROI-THEME.md
+- [x] **3.1.2** Agregar referencia a nomenclatura/spec.md
+- [x] **3.1.3** Actualizar índice de specs
+- [x] **3.1.4** Verificar que links funcionan
+
+### 3.2 Cross-references entre specs
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+- [x] **3.2.1** arquitectura-limpia → nomenclatura (referencias a nombres)
+- [x] **3.2.2** estandares-codigo → arquitectura-limpia (referencias a capas)
+- [x] **3.2.3** nomenclatura → estandares-codigo (referencias a convenciones)
+- [x] **3.2.4** WORKFLOW → todas las specs (referencias a cada fase)
+
+### 3.3 Verificación final
+**Estado:** [x] NO INICIADO | [x] EN PROGRESO | [x] COMPLETADO
+
+- [x] **3.3.1** Consistencia de ejemplos entre archivos
+- [x] **3.3.2** Todos los links funcionan
+- [x] **3.3.3** No hay contradicciones entre specs
+- [x] **3.3.4** Todos los archivos tienen fecha de actualización
+
+---
+
+## CASO PILOTO: ANTI-SPAM
+
+### Implementación usando nuevo sistema de specs
+**Estado:** [ ] NO INICIADO | [ ] EN PROGRESO | [ ] COMPLETADO
+
+- [ ] **P.1** Crear spec para AntiSpamValidator siguiendo WORKFLOW
+- [ ] **P.2** Validar que spec cumple nomenclatura
+- [ ] **P.3** Validar que spec cumple arquitectura-limpia
+- [ ] **P.4** Validar que spec cumple estandares-codigo
+- [ ] **P.5** Implementar AntiSpamValidator
+- [ ] **P.6** Aplicar a Newsletter Footer
+- [ ] **P.7** Aplicar a Contact Form
+- [ ] **P.8** Probar que spam es rechazado
+- [ ] **P.9** Documentar lecciones aprendidas en WORKFLOW
+
+---
+
+## RESUMEN DE ARCHIVOS A CREAR/MODIFICAR
+
+| # | Archivo | Acción | Líneas | Estado |
+|---|---------|--------|--------|--------|
+| 1 | `_openspec/WORKFLOW-ROI-THEME.md` | CREAR | ~438 | [x] COMPLETADO |
+| 2 | `_openspec/specs/nomenclatura.md` | CREAR | ~687 | [x] COMPLETADO |
+| 3 | `_openspec/specs/arquitectura-limpia.md` | EXPANDIR | ~770 | [x] COMPLETADO |
+| 4 | `_openspec/specs/estandares-codigo.md` | EXPANDIR | ~1228 | [x] COMPLETADO |
+| 5 | `_openspec/project.md` | ACTUALIZAR | ~107 | [x] COMPLETADO |
+
+### Estructura Final
+```
+_openspec/
+├── AGENTS.md
+├── WORKFLOW-ROI-THEME.md
+├── project.md
+├── specs/                    # Solo specs BASE
+│   ├── arquitectura-limpia.md
+│   ├── estandares-codigo.md
+│   └── nomenclatura.md
+└── changes/                  # Features/cambios específicos
+    ├── add-advanced-incontent-ads/
+    ├── adsense-auto-ads-toggle/
+    ├── adsense-cache-unified-visibility/
+    ├── adsense-javascript-first/
+    ├── cache-first-architecture/
+    ├── flujo-componentes/
+    ├── patrones-wordpress/
+    ├── post-grid-shortcode/
+    ├── refactor-adsense-lazy-loading/
+    └── templates-unificados/
+```
+
+---
+
+## MÉTRICAS DE PROGRESO
+
+### Contadores actuales:
+- **Tareas FASE 1:** 32/32 completadas
+- **Tareas FASE 2:** 23/23 completadas
+- **Tareas FASE 3:** 11/11 completadas
+- **Tareas PILOTO:** 0/9 completadas
+- **TOTAL:** 66/75 tareas completadas
+
+### Al completar:
+| Métrica | Antes | Después |
+|---------|-------|---------|
+| Total líneas specs | ~1021 | ~2200 |
+| Archivos fundamentales | 3/5 | 5/5 |
+| Diagramas ASCII | 0 | 3+ |
+| Ejemplos código | ~5 | ~30 |
+| Checklists | 1 parcial | 3 completos |
+
+---
+
+**Fin del documento**