# WORKFLOW DE DESARROLLO ROI THEME **ESTE ARCHIVO ES OBLIGATORIO LEER ANTES DE CUALQUIER DESARROLLO** --- ## REGLA DE ORO ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ │ │ SI NO EXISTE spec.md APROBADO → NO SE TOCA CÓDIGO │ │ │ │ NUNCA desarrollar directamente. SIEMPRE seguir el flujo de fases. │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## RUTAS DEL PROYECTO | Carpeta | Contenido | Ruta | |---------|-----------|------| | **Specs Base** | Arquitectura, estándares, nomenclatura | `_openspec/specs/` | | **Specs de Cambios** | Especificaciones por funcionalidad | `_openspec/changes/` | | **Schemas JSON** | Definición de componentes | `Schemas/` | | **Renderers** | Componentes frontend | `Public/[Componente]/` | | **FormBuilders** | Componentes admin | `Admin/[Componente]/` | | **Código Compartido** | Servicios, contratos, entidades | `Shared/` | --- ## CHECKLIST OBLIGATORIO (antes de cualquier desarrollo) ``` [ ] 1. Leer este archivo (WORKFLOW-ROI-THEME.md) [ ] 2. Leer _openspec/specs/arquitectura-limpia.md [ ] 3. Leer _openspec/specs/estandares-codigo.md [ ] 4. Leer _openspec/specs/nomenclatura.md [ ] 5. Identificar qué se va a desarrollar (componente, servicio, fix) [ ] 6. Determinar el flujo apropiado: - Componente UI → Flujo de 5 Fases - Servicio/Feature → Flujo de 3 Fases - Bug fix simple → Flujo directo con spec mínima ``` --- ## FLUJO DE 5 FASES (COMPONENTES UI) > **Usar para:** Nuevos componentes visuales (Renderers + FormBuilders) ``` ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 1: SCHEMA JSON ║ ║ "Definir la estructura de datos" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Entrada: Template HTML de referencia (_planificacion/roi-theme-template/) ║ ║ Salida: Schemas/[nombre-en-kebab-case].json ║ ║ ║ ║ Contenido obligatorio: ║ ║ • component_name: kebab-case (ej: "featured-image") ║ ║ • version: "1.0.0" ║ ║ • description: Qué hace el componente ║ ║ • groups.visibility con 3 campos: ║ ║ - is_enabled (boolean, required) ║ ║ - show_on_desktop (boolean) ║ ║ - show_on_mobile (boolean) ║ ║ • Grupos adicionales con priority 10-90 ║ ║ ║ ║ Agente: roi-schema-architect ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 2: SINCRONIZACIÓN BD ║ ║ "Registrar configuración en base de datos" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Entrada: Schema JSON creado en Fase 1 ║ ║ Salida: Registros en wp_roi_theme_component_settings ║ ║ ║ ║ Comando: ║ ║ powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' \ ║ ║ roi-theme sync-component [nombre-en-kebab-case]" ║ ║ ║ ║ Verificar: ║ ║ • Todos los campos del JSON existen en BD ║ ║ • Valores default aplicados correctamente ║ ║ • No hay campos huérfanos ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 3: RENDERER (Frontend) ║ ║ "Generar HTML y CSS desde BD" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Entrada: Schema + Datos en BD ║ ║ Salida: Public/[PascalCase]/Infrastructure/Ui/[PascalCase]Renderer.php ║ ║ ║ ║ Requisitos obligatorios: ║ ║ • declare(strict_types=1) ║ ║ • Namespace: ROITheme\Public\[Component]\Infrastructure\Ui ║ ║ • final class [Component]Renderer implements RendererInterface ║ ║ • DI via constructor: CSSGeneratorInterface ║ ║ • COMPONENT_NAME constante en kebab-case ║ ║ • supports() retorna kebab-case ║ ║ • Validar: isEnabled(), getVisibilityClass() ║ ║ • CERO CSS hardcodeado (usar $this->cssGenerator) ║ ║ ║ ║ Agente: roi-renderer-builder ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 4: FORMBUILDER (Admin) ║ ║ "Panel de configuración en admin" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Entrada: Schema + Renderer funcionando ║ ║ Salida: Admin/[PascalCase]/Infrastructure/Ui/[PascalCase]FormBuilder.php ║ ║ ║ ║ Requisitos obligatorios: ║ ║ • declare(strict_types=1) ║ ║ • Namespace: ROITheme\Admin\[Component]\Infrastructure\Ui ║ ║ • final class [Component]FormBuilder ║ ║ • DI via constructor: AdminDashboardRenderer ║ ║ • Design System: gradiente #0E2337 → #1e3a5f, borde #FF8600 ║ ║ • Bootstrap 5 form controls ║ ║ • data-component en kebab-case ║ ║ • Registrar en getComponents() con ID kebab-case ║ ║ ║ ║ Agente: roi-form-builder ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 5: VALIDACIÓN ║ ║ "Verificar que todo cumple las specs" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Entrada: Componente completo (Schema + BD + Renderer + FormBuilder) ║ ║ Salida: Reporte de validación ║ ║ ║ ║ Comando: ║ ║ php Shared/Infrastructure/Scripts/validate-architecture.php [nombre] ║ ║ ║ ║ Verifica: ║ ║ • Estructura de carpetas correcta ║ ║ • JSON válido con campos obligatorios ║ ║ • Datos en BD sincronizados ║ ║ • Renderer implementa RendererInterface ║ ║ • FormBuilder registrado en getComponents() ║ ║ • Nomenclatura correcta (PascalCase/kebab-case) ║ ║ • Clean Architecture respetada (DI, capas) ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ``` --- ## FLUJO DE 3 FASES (SERVICIOS/FEATURES) > **Usar para:** Nuevos servicios, features no visuales, mejoras de infraestructura ``` ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 1: ESPECIFICACIÓN ║ ║ "Definir qué se va a construir" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Crear carpeta: _openspec/changes/[nombre-feature]/ ║ ║ ║ ║ Archivos a crear: ║ ║ • proposal.md - Por qué y qué se va a cambiar ║ ║ • tasks.md - Checklist de implementación ║ ║ • spec.md - Especificación detallada (formato Gherkin) ║ ║ ║ ║ >>> REQUIERE APROBACIÓN DEL USUARIO PARA CONTINUAR <<< ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 2: IMPLEMENTACIÓN ║ ║ "Construir siguiendo la spec" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ Ubicación según tipo: ║ ║ • Servicios compartidos → Shared/Infrastructure/Services/ ║ ║ • Contratos → Shared/Domain/Contracts/ ║ ║ • UseCases → [Context]/Application/UseCases/ ║ ║ • Repositorios → [Context]/Infrastructure/Persistence/WordPress/ ║ ║ ║ ║ Requisitos: ║ ║ • declare(strict_types=1) ║ ║ • Namespace correcto según ubicación ║ ║ • DI via constructor (interfaces, no clases concretas) ║ ║ • Métodos pequeños (<30 líneas) ║ ║ • Clases pequeñas (<300 líneas) ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ FASE 3: INTEGRACIÓN Y PRUEBA ║ ║ "Conectar y verificar" ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ • Integrar servicio donde se necesite ║ ║ • Probar funcionalidad en navegador ║ ║ • Verificar que no hay errores PHP ║ ║ • Actualizar tasks.md con estado COMPLETADO ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ``` --- ## CÓMO CREAR NUEVA FEATURE ### Paso 1: Crear estructura de carpetas ``` _openspec/changes/[nombre-feature]/ ├── proposal.md ← Por qué y qué se va a cambiar ├── tasks.md ← Checklist → evoluciona a tracking └── spec.md ← Especificación detallada ``` ### Paso 2: Crear proposal.md ```markdown # Proposal: [Nombre Feature] ## Why [1-2 oraciones sobre el problema a resolver] ## What Changes - [Lista de cambios propuestos] ## Impact - Archivos nuevos: [lista] - Archivos modificados: [lista] - Specs relacionadas: [lista] ``` ### Paso 3: Crear tasks.md ```markdown # Tracking: [nombre-feature] **Estado actual:** EN PROGRESO **Próximo paso:** [describir] --- ## Checklist ### Fase 1: Especificación - [ ] Crear proposal.md - [ ] Crear spec.md con Requirements y Scenarios - [ ] Aprobar spec.md ### Fase 2: Implementación - [ ] Crear interface (si aplica) - [ ] Crear implementación - [ ] Registrar en DI container (si aplica) ### Fase 3: Integración - [ ] Integrar donde se necesite - [ ] Probar funcionalidad - [ ] Verificar sin errores --- ## Historial | Fecha | Avance | |-------|--------| | YYYY-MM-DD | [descripción] | ``` --- ## NOMENCLATURA RÁPIDA | Contexto | Formato | Ejemplo | |----------|---------|---------| | component_name (JSON/BD) | kebab-case | `"featured-image"` | | Archivo schema | kebab-case | `featured-image.json` | | Carpeta módulo | PascalCase | `FeaturedImage/` | | Namespace PHP | PascalCase | `ROITheme\Public\FeaturedImage\...` | | Clase Renderer | PascalCase | `FeaturedImageRenderer` | | Clase FormBuilder | PascalCase | `FeaturedImageFormBuilder` | | Constante | UPPER_SNAKE | `COMPONENT_NAME` | | Método | camelCase | `getVisibilityClass()` | | Variable | $camelCase | `$showDesktop` | **Conversión kebab ↔ Pascal:** `featured-image` ↔ `FeaturedImage` --- ## CLEAN ARCHITECTURE RESUMIDA ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ DOMAIN │ │ (Centro, sin deps) │ │ │ │ • Entities (Component, etc.) │ │ • Contracts/Interfaces │ │ • Value Objects │ │ │ │ PROHIBIDO: WordPress, echo, print, HTML │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ APPLICATION │ │ (Usa Domain) │ │ │ │ • UseCases │ │ • Application Services │ │ │ │ PROHIBIDO: WordPress, acceso BD directo │ │ │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ INFRASTRUCTURE │ │ (Usa Domain y Application) │ │ │ │ • Ui/ (Renderers, FormBuilders) │ │ • Api/ (AJAX handlers, REST) │ │ • Persistence/ (Repositories WordPress) │ │ • Services/ (Implementaciones) │ │ │ │ PERMITIDO: WordPress, HTML, BD, APIs externas │ │ │ └─────────────────────────────────────────────────────────────────┘ Dirección de dependencias: Infrastructure → Application → Domain (afuera depende de adentro, NUNCA al revés) ``` --- ## COMANDOS WP-CLI ```powershell # Ubicación WP-CLI C:\xampp\php_8.0.30_backup\wp-cli.phar # Sincronizar un componente powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-component [nombre]" # Sincronizar todos los componentes powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-all-components" # Ejemplo powershell -Command "php 'C:\xampp\php_8.0.30_backup\wp-cli.phar' roi-theme sync-component featured-image" ``` --- ## AGENTES DISPONIBLES | Agente | Propósito | Cuándo usar | |--------|-----------|-------------| | roi-schema-architect | Genera JSON schemas desde HTML | Fase 1 de componentes | | roi-renderer-builder | Genera Renderers PHP | Fase 3 de componentes | | roi-form-builder | Genera FormBuilders PHP | Fase 4 de componentes | --- ## ESPECIFICACIONES BASE (LECTURA OBLIGATORIA) | Spec | Ruta | Contenido | |------|------|-----------| | Arquitectura | `_openspec/specs/arquitectura-limpia.md` | Capas, dependencias, estructura | | Estándares | `_openspec/specs/estandares-codigo.md` | SOLID, límites, WordPress | | Nomenclatura | `_openspec/specs/nomenclatura.md` | Nombres, formatos, convenciones | --- ## ROLES ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ │ │ CLAUDE CODE (Yo) USUARIO (Tú) │ │ ───────────────── ──────────── │ │ │ │ • Ejecuto los agentes • Defines qué componente crear │ │ • Genero schemas JSON • Apruebas especificaciones │ │ • Genero Renderers • Apruebas diseño │ │ • Genero FormBuilders • Pruebas en navegador │ │ • Ejecuto validaciones • Verificas funcionamiento │ │ • Documento en specs • Decides prioridades │ │ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## GARANTÍAS DEL PROCESO 1. **NUNCA** se escribe código sin spec aprobada 2. **SIEMPRE** se sigue el flujo de fases 3. **CADA** componente tiene las 5 partes (Schema, BD, Renderer, FormBuilder, Validación) 4. **TODO** el CSS se genera vía CSSGenerator (cero hardcodeado) 5. **SIEMPRE** DI via constructor (interfaces, no clases concretas) 6. **NUNCA** WordPress en Domain ni Application --- ## LECCIONES APRENDIDAS > Esta sección documenta ajustes al workflow basados en implementaciones completadas. ### Validación código vs specs (2026-01-08) **Contexto:** Antes de mejorar specs, se validó que el código actual cumple con las especificaciones propuestas. **Hallazgos:** - 17 Renderers siguen el patrón correctamente - 17 FormBuilders siguen el patrón correctamente - 17 Schemas en kebab-case - 43 archivos con strict_types=1 - 39 clases final - 23 interfaces en Domain/Contracts **Conclusión:** El código YA implementa Clean Architecture. Las mejoras a specs son documentación de patrones existentes, no nuevas invenciones. --- **Última actualización:** 2026-01-08