# 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