roi-theme/_openspec/project.md

Project Context

Purpose

ROI Theme es un tema WordPress profesional siguiendo Clean Architecture para el sitio analisisdepreciosunitarios.com. Proporciona un sistema de componentes configurables con panel de administración y renderizado frontend dinámico.

Tech Stack

• CMS: WordPress 6.x
• Lenguaje: PHP 8.x (strict types)
• Patrón: Clean Architecture (Domain, Application, Infrastructure)
• Frontend: Bootstrap 5, Bootstrap Icons
• Base de Datos: MySQL (tabla normalizada wp_roi_theme_component_settings)
• CLI: WP-CLI para sincronización de schemas

Project Conventions

Code Style

• declare(strict_types=1) en todos los archivos PHP
• Namespaces: ROITheme\[Context]\[Component]\[Layer]
• Clases finales por defecto
• Propiedades private/protected
• Escaping WordPress: esc_html(), esc_attr(), esc_url(), esc_textarea()

Nomenclatura (NO NEGOCIABLE)

Contexto	Formato	Ejemplo
component_name (JSON/BD)	kebab-case	"featured-image"
Nombre archivo schema	kebab-case	featured-image.json
Carpeta de módulo	PascalCase	FeaturedImage/
Namespace PHP	PascalCase	ROITheme\Public\FeaturedImage...
Clase Renderer/FormBuilder	PascalCase	FeaturedImageRenderer

Architecture Patterns

• Clean Architecture: Domain → Application → Infrastructure
• Domain NO depende de capas superiores
• Domain NO puede tener WordPress, echo/print, HTML
• Application NO puede tener WordPress
• Infrastructure implementa interfaces de Domain
• DI via constructor (interfaces, no clases concretas)

Estructura del Tema

roi-theme/
├── Schemas/                    # JSON schemas (kebab-case)
├── Shared/                     # Código compartido
│   ├── Domain/Contracts/       # Interfaces
│   ├── Application/UseCases/   # Casos de uso
│   └── Infrastructure/         # Implementaciones
├── Public/[PascalCase]/        # Renderers frontend
├── Admin/[PascalCase]/         # FormBuilders admin
└── functions.php               # Bootstrap

Testing Strategy

• Validación de arquitectura: php Shared/Infrastructure/Scripts/validate-architecture.php [nombre]
• Tests unitarios pendientes de implementar

Git Workflow

• Conventional Commits: feat:, fix:, refactor:, docs:
• Branch principal: main
• Tags para releases: v1.0.0, v2.0.0

Domain Context

El sistema maneja componentes UI configurables para un sitio de análisis de precios unitarios (construcción). Cada componente tiene:

• Schema JSON: Define campos configurables
• Renderer: Genera HTML + CSS dinámico desde BD
• FormBuilder: Panel admin para configurar valores

Flujo de 5 Fases para Componentes

Nota: [nombre] = kebab-case (ej: contact-form), [Nombre] = PascalCase (ej: ContactForm)

1. Schema JSON → Schemas/[nombre].json
2. Sincronización → wp roi-theme sync-component [nombre]
3. Renderer → Public/[Nombre]/Infrastructure/Ui/[Nombre]Renderer.php
4. FormBuilder → Admin/[Nombre]/Infrastructure/Ui/[Nombre]FormBuilder.php
5. Validación → validate-architecture.php [nombre]

Important Constraints

• CERO CSS hardcodeado en PHP (usar CSSGeneratorService)
• NO usar global $wpdb en Domain/Application
• NO instanciar servicios directamente (usar DI)
• NO modificar campos en BD manualmente
• Variables CSS del tema: --color-navy-dark, --color-orange-primary

External Dependencies

• WordPress 6.x core
• Bootstrap 5 (CSS/JS)
• Bootstrap Icons
• WP-CLI (C:\xampp\php_8.0.30_backup\wp-cli.phar)

Referencias Documentación

OpenSpec - Especificaciones del Proyecto

Archivo	Descripción	Ubicación
WORKFLOW-ROI-THEME.md	Flujo de trabajo obligatorio, regla de oro	_openspec/WORKFLOW-ROI-THEME.md
AGENTS.md	Agentes disponibles y cuándo usarlos	_openspec/AGENTS.md
arquitectura-limpia	Clean Architecture, capas, estructura	_openspec/specs/arquitectura-limpia.md
estandares-codigo	SOLID, PHP, WordPress, seguridad	_openspec/specs/estandares-codigo.md
nomenclatura	Convenciones de nombres completas	_openspec/specs/nomenclatura.md

Documentación de Planificación

• Template HTML: _planificacion/roi-theme-template/index.html
• Design System: _planificacion/01-design-system/

---

Última actualización: 2026-01-08