git.admin/roi-theme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: reorganizar openspec y planificacion con spec recaptcha

Browse Source 
- 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
2026-01-08 15:30:45 -06:00
parent 0d6b6db108
commit 0f6387ab46
58 changed files with 15364 additions and 1171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

437
_openspec/WORKFLOW-ROI-THEME.md Normal file
View File

@@ -0,0 +1,437 @@
# 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