0f6387ab46
- 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>
27 KiB
27 KiB
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
# 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
# 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
# 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
- NUNCA se escribe código sin spec aprobada
- SIEMPRE se sigue el flujo de fases
- CADA componente tiene las 5 partes (Schema, BD, Renderer, FormBuilder, Validación)
- TODO el CSS se genera vía CSSGenerator (cero hardcodeado)
- SIEMPRE DI via constructor (interfaces, no clases concretas)
- 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