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>
438 lines
27 KiB
Markdown
438 lines
27 KiB
Markdown
# 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
|