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

309
_openspec/changes/adsense-cache-unified-visibility/spec.md Normal file
View File

@@ -0,0 +1,309 @@
# Especificacion: Unificacion de Visibilidad AdSense para Compatibilidad con Cache
## Purpose
Unificar la logica de visibilidad de AdSense para que TODA la evaluacion dependiente de usuario
(hide_for_logged_in) se realice en el cliente via JavaScript-First, eliminando llamadas a
`is_user_logged_in()` durante el render PHP.
**Problema actual:** El `AdsensePlacementRenderer` usa `PageVisibilityHelper::shouldShow()` que
internamente llama `is_user_logged_in()` en PHP. Esto causa que el HTML generado varie segun el
estado de autenticacion, rompiendo la compatibilidad con page cache.
**Solucion:** Cuando `javascript_first_mode` esta activo, el Renderer debe generar SIEMPRE el HTML
de los slots, delegando la decision de `hide_for_logged_in` al endpoint REST y al JavaScript del cliente.
---
## Background
### Arquitectura JavaScript-First existente (spec: adsense-javascript-first)
El sistema JavaScript-First ya implementa:
1. **Endpoint REST** `/wp-json/roi-theme/v1/adsense-placement/visibility`
- Evalua `is_user_logged_in()` en tiempo real (no cacheado)
- Retorna decision `show_ads: true/false` con razones
- Headers anti-cache (no-store, no-cache)
2. **Cliente JavaScript** `adsense-visibility.js`
- Consulta endpoint via AJAX con cookies (credentials: same-origin)
- Cachea decision en localStorage
- Aplica clases CSS para mostrar/ocultar slots
### El gap actual
```
FLUJO ACTUAL (PROBLEMATICO):
Request → PHP Render → PageVisibilityHelper::shouldShow()
↓
is_user_logged_in() ← ROMPE CACHE
↓
HTML con/sin slots (depende de login)
↓
Page Cache ← HTML incorrecto para otros usuarios
```
```
FLUJO DESEADO (CON ESTA SPEC):
Request → PHP Render → [javascript_first_mode=true?]
↓ SI
SIEMPRE genera HTML con slots
↓
Page Cache ← HTML identico para todos
↓
JS consulta endpoint REST
↓
Muestra/oculta segun respuesta
```
---
## Requirements
### Requirement 1: Bypass de hide_for_logged_in en modo JavaScript-First
The AdsensePlacementRenderer MUST skip the `is_user_logged_in()` evaluation during PHP render
when `javascript_first_mode` is enabled.
#### Scenario: JavaScript-First activo, usuario anonimo
- **GIVEN** `javascript_first_mode` esta habilitado en settings
- **AND** `hide_for_logged_in` esta habilitado
- **AND** el visitante NO esta logueado
- **WHEN** se renderiza un slot de AdSense
- **THEN** el HTML del slot DEBE generarse (placeholders visibles)
- **AND** el JavaScript DEBE consultar el endpoint
- **AND** el endpoint retorna `show_ads: true`
- **AND** los anuncios se muestran
#### Scenario: JavaScript-First activo, usuario logueado
- **GIVEN** `javascript_first_mode` esta habilitado
- **AND** `hide_for_logged_in` esta habilitado
- **AND** el visitante ESTA logueado
- **WHEN** se renderiza un slot de AdSense
- **THEN** el HTML del slot DEBE generarse (en cache seria identico a anonimo)
- **AND** el JavaScript DEBE consultar el endpoint
- **AND** el endpoint retorna `show_ads: false` con razon `hide_for_logged_in`
- **AND** los anuncios se OCULTAN via CSS/JS
#### Scenario: JavaScript-First deshabilitado (modo legacy)
- **GIVEN** `javascript_first_mode` esta DESHABILITADO
- **AND** `hide_for_logged_in` esta habilitado
- **AND** el visitante ESTA logueado
- **WHEN** se renderiza un slot de AdSense
- **THEN** el HTML del slot NO se genera (comportamiento legacy)
- **AND** `is_user_logged_in()` SE evalua en PHP
- **BECAUSE** sin JS-First, el modo legacy es la unica opcion
---
### Requirement 2: PageVisibilityHelper debe respetar modo JavaScript-First
The PageVisibilityHelper MUST provide a method that excludes user-dependent checks when
JavaScript-First mode is active for a component.
#### Scenario: Nuevo metodo shouldShowForCache
- **GIVEN** un componente con `javascript_first_mode` habilitado
- **WHEN** se llama `PageVisibilityHelper::shouldShowForCache('adsense-placement')`
- **THEN** DEBE evaluar visibilidad por tipo de pagina (home, posts, pages, etc.)
- **AND** DEBE evaluar exclusiones por categoria, ID, URL pattern
- **AND** NO DEBE evaluar `hide_for_logged_in`
- **BECAUSE** esa evaluacion la hace el cliente
#### Scenario: Componente sin JavaScript-First usa metodo existente
- **GIVEN** un componente sin `javascript_first_mode`
- **WHEN** se llama `PageVisibilityHelper::shouldShow('otro-componente')`
- **THEN** DEBE usar flujo existente incluyendo `hide_for_logged_in`
- **BECAUSE** sin JS-First, PHP es la unica fuente de verdad
---
### Requirement 3: WordPressComponentVisibilityRepository debe soportar modo bypass
The repository MUST support skipping `is_user_logged_in()` check when requested.
#### Scenario: isNotExcluded con bypass de login check
- **GIVEN** se llama `isNotExcluded('adsense-placement', skipLoginCheck: true)`
- **WHEN** el metodo evalua exclusiones
- **THEN** NO DEBE llamar `is_user_logged_in()`
- **AND** DEBE evaluar otras exclusiones normalmente
---
### Requirement 4: El endpoint REST DEBE evaluar hide_for_logged_in
The REST endpoint `/adsense-placement/visibility` MUST evaluate `hide_for_logged_in`
and include it in the decision.
**NOTA:** Esto YA esta implementado en `AdsenseVisibilityController.php`. Solo documentamos
para claridad.
#### Scenario: Endpoint evalua usuario logueado
- **GIVEN** peticion al endpoint con cookies de sesion
- **AND** `hide_for_logged_in` esta habilitado
- **AND** el usuario ESTA logueado
- **WHEN** el endpoint procesa la peticion
- **THEN** retorna `show_ads: false`
- **AND** `reasons` incluye `hide_for_logged_in`
---
### Requirement 5: El CSS de slots ocultos NO debe afectar el layout
When JavaScript hides ad slots, they MUST collapse completely without affecting page layout.
**NOTA:** Esto YA esta implementado con `:has([data-ad-status='unfilled'])`. Documentamos para
verificar que se mantiene.
---
## Implementation
### Archivos a modificar
#### 1. AdsensePlacementRenderer.php
```php
// ANTES (linea 38-43):
public function renderSlot(array $settings, string $location): string
{
// 0. Verificar visibilidad por tipo de pagina y exclusiones
if (!PageVisibilityHelper::shouldShow('adsense-placement')) {
return '';
}
// ...
}
// DESPUES:
public function renderSlot(array $settings, string $location): string
{
// 0. Verificar visibilidad (respetando modo JS-First para cache)
$jsFirstMode = ($settings['behavior']['javascript_first_mode'] ?? false) === true;
if ($jsFirstMode) {
// En modo JS-First, usar evaluacion cache-friendly (sin is_user_logged_in)
if (!PageVisibilityHelper::shouldShowForCache('adsense-placement')) {
return '';
}
} else {
// Modo legacy: usar evaluacion completa
if (!PageVisibilityHelper::shouldShow('adsense-placement')) {
return '';
}
}
// ...
}
```
#### 2. PageVisibilityHelper.php
```php
// AGREGAR nuevo metodo:
/**
* Evalua visibilidad SIN checks dependientes de usuario
*
* Para uso cuando JavaScript manejara los checks de usuario.
* Evalua: tipos de pagina, exclusiones por categoria/ID/URL
* NO evalua: hide_for_logged_in
*
* @param string $componentName
* @return bool
*/
public static function shouldShowForCache(string $componentName): bool
{
$container = DIContainer::getInstance();
$useCase = $container->getEvaluateComponentVisibilityUseCase();
return $useCase->executeForCache($componentName);
}
```
#### 3. EvaluateComponentVisibilityUseCase.php
```php
// AGREGAR nuevo metodo:
/**
* Evalua visibilidad SIN checks dependientes de usuario
*/
public function executeForCache(string $componentName): bool
{
// Paso 1: Verificar visibilidad por tipo de pagina (sin cambios)
$visibleByPageType = $this->pageVisibilityUseCase->execute($componentName);
if (!$visibleByPageType) {
return false;
}
// Paso 2: Verificar exclusiones SIN hide_for_logged_in
$isExcluded = $this->exclusionsUseCase->executeForCache($componentName);
return !$isExcluded;
}
```
#### 4. EvaluateExclusionsUseCase.php
```php
// AGREGAR nuevo metodo:
/**
* Evalua exclusiones SIN hide_for_logged_in
*/
public function executeForCache(string $componentName): bool
{
// Evaluar exclusiones por categoria, ID, URL
// NO evaluar hide_for_logged_in
return $this->repository->isExcludedForCache($componentName);
}
```
#### 5. WordPressComponentVisibilityRepository.php
```php
// MODIFICAR isNotExcluded o agregar nuevo metodo:
/**
* Verifica exclusiones SIN evaluar hide_for_logged_in
*/
public function isNotExcludedForCache(string $componentName): bool
{
// OMITE: shouldHideForLoggedIn()
// MANTIENE: PageVisibilityHelper::shouldShow() para otras exclusiones
return PageVisibilityHelper::shouldShowByPageType($componentName);
}
```
---
## Acceptance Criteria
1. Con `javascript_first_mode=true` y `hide_for_logged_in=true`:
- Usuario anonimo: HTML generado, JS muestra ads
- Usuario logueado: HTML generado, JS oculta ads
- Page cache sirve mismo HTML a ambos
2. Con `javascript_first_mode=false`:
- Comportamiento legacy sin cambios
- `is_user_logged_in()` se evalua en PHP
3. Otras exclusiones (categoria, ID, URL) funcionan igual en ambos modos
4. No hay regresion en visibilidad por tipo de pagina
5. Los slots ocultos por JS colapsan completamente (height: 0)
---
## Migration Notes
- **NO hay breaking changes**: `shouldShow()` mantiene comportamiento actual
- **Nuevo metodo opcional**: `shouldShowForCache()` para modo JS-First
- **Backward compatible**: Si `javascript_first_mode=false`, todo funciona igual
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-12-11 | Initial spec |

214
_openspec/changes/adsense-cache-unified-visibility/test-plan.md Normal file
View File

@@ -0,0 +1,214 @@
# Test Plan: Unificacion de Visibilidad AdSense para Cache
## Test Environment
- **DEV URL**: https://dev.analisisdepreciosunitarios.com
- **PROD URL**: https://analisisdepreciosunitarios.com
- **Browsers**: Chrome, Firefox
- **Tools**: DevTools Console, Network tab, Playwright MCP
---
## Pre-requisitos
1. Habilitar `javascript_first_mode` en settings de adsense-placement
2. Habilitar `hide_for_logged_in` en settings de adsense-placement
3. Tener cuenta de usuario para pruebas de login
4. Limpiar cache del sitio antes de cada prueba
---
## Test Cases
### TC01: HTML se genera para usuarios anonimos (JS-First activo)
**Objetivo**: Verificar que los slots de ads se renderizan en HTML para visitantes anonimos
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, `hide_for_logged_in=true`, usuario anonimo |
| Pasos | 1. Limpiar cache del sitio<br>2. Abrir pagina de post en navegacion privada<br>3. Inspeccionar HTML |
| Resultado esperado | Elementos `.roi-adsense-placeholder` presentes en DOM |
| Status | PENDING |
| Notas | |
### TC02: HTML se genera para usuarios logueados (JS-First activo)
**Objetivo**: Verificar que los slots de ads se renderizan en HTML incluso para usuarios logueados
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, `hide_for_logged_in=true`, usuario logueado |
| Pasos | 1. Limpiar cache del sitio<br>2. Login como usuario<br>3. Visitar pagina de post<br>4. Inspeccionar HTML |
| Resultado esperado | Elementos `.roi-adsense-placeholder` presentes en DOM (mismo HTML que TC01) |
| Status | PENDING |
| Notas | Clave: el HTML debe ser IDENTICO al de TC01 |
### TC03: Endpoint retorna show_ads=false para usuarios logueados
**Objetivo**: Verificar que el endpoint REST evalua correctamente hide_for_logged_in
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, `hide_for_logged_in=true`, usuario logueado |
| Pasos | 1. Login como usuario<br>2. En console ejecutar:<br>`fetch('/wp-json/roi-theme/v1/adsense-placement/visibility?post_id=1', {credentials:'same-origin'}).then(r=>r.json()).then(console.log)` |
| Resultado esperado | Respuesta: `{show_ads: false, reasons: ['hide_for_logged_in'], ...}` |
| Status | PENDING |
| Notas | |
### TC04: JavaScript oculta ads para usuarios logueados
**Objetivo**: Verificar que el JavaScript aplica correctamente la decision del endpoint
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, `hide_for_logged_in=true`, usuario logueado |
| Pasos | 1. Login como usuario<br>2. Visitar pagina de post<br>3. Verificar clases CSS de slots<br>4. Verificar evento `roiAdsenseDeactivated` |
| Resultado esperado | Slots tienen clase `roi-adsense-hidden` o altura colapsada |
| Status | PENDING |
| Notas | |
### TC05: JavaScript muestra ads para usuarios anonimos
**Objetivo**: Verificar que el JavaScript muestra correctamente los ads
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, `hide_for_logged_in=true`, usuario anonimo |
| Pasos | 1. Navegacion privada<br>2. Visitar pagina de post<br>3. Verificar clases CSS de slots |
| Resultado esperado | Slots tienen clase `roi-adsense-active` |
| Status | PENDING |
| Notas | |
### TC06: Cache sirve mismo HTML a ambos tipos de usuario
**Objetivo**: Verificar compatibilidad con page cache
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=true`, page cache activo |
| Pasos | 1. Limpiar cache<br>2. Usuario anonimo visita pagina (genera cache)<br>3. Usuario logueado visita misma pagina<br>4. Comparar HTML de `.roi-adsense-placeholder` |
| Resultado esperado | HTML identico, diferencia solo en comportamiento JS |
| Status | PENDING |
| Notas | Este es el test critico de la spec |
### TC07: Modo legacy funciona sin cambios (JS-First deshabilitado)
**Objetivo**: Verificar backward compatibility
| Campo | Valor |
|-------|-------|
| Pre-condicion | `javascript_first_mode=false`, `hide_for_logged_in=true`, usuario logueado |
| Pasos | 1. Deshabilitar JS-First en settings<br>2. Login como usuario<br>3. Visitar pagina de post<br>4. Inspeccionar HTML |
| Resultado esperado | Elementos `.roi-adsense-placeholder` NO presentes (comportamiento legacy) |
| Status | PENDING |
| Notas | Comportamiento identico al actual |
### TC08: Exclusiones por tipo de pagina funcionan en ambos modos
**Objetivo**: Verificar que exclusiones no relacionadas con login siguen funcionando
| Campo | Valor |
|-------|-------|
| Pre-condicion | `show_on_archives=false` configurado |
| Pasos | 1. Visitar pagina de archivo (categoria)<br>2. Verificar que no hay slots de ads |
| Resultado esperado | Sin slots de ads en paginas de archivo |
| Status | PENDING |
| Notas | |
### TC09: Exclusiones por categoria funcionan en ambos modos
**Objetivo**: Verificar que exclusiones por categoria siguen funcionando
| Campo | Valor |
|-------|-------|
| Pre-condicion | Categoria excluida configurada |
| Pasos | 1. Visitar post de categoria excluida<br>2. Verificar que no hay slots de ads |
| Resultado esperado | Sin slots de ads en posts de categoria excluida |
| Status | PENDING |
| Notas | |
---
## Automated Test Scripts
### Script: Verificar HTML identico para cache
```javascript
// Ejecutar en Playwright o consola
// Compara DOM de slots entre usuario anonimo y logueado
async function verifyCacheCompatibility() {
const anonSlots = document.querySelectorAll('.roi-adsense-placeholder').length;
console.log(`Slots encontrados: ${anonSlots}`);
// El HTML debe existir independientemente del estado de login
// La diferencia esta en las clases CSS aplicadas por JS
const activeSlots = document.querySelectorAll('.roi-adsense-active').length;
const hiddenSlots = document.querySelectorAll('.roi-adsense-hidden').length;
console.log(`Activos: ${activeSlots}, Ocultos: ${hiddenSlots}`);
return {
totalSlots: anonSlots,
active: activeSlots,
hidden: hiddenSlots
};
}
verifyCacheCompatibility();
```
### Script: Verificar respuesta del endpoint
```javascript
// Ejecutar en consola con usuario logueado
async function testEndpoint() {
const postId = document.querySelector('article')?.id?.replace('post-', '') || '1';
const url = `/wp-json/roi-theme/v1/adsense-placement/visibility?post_id=${postId}`;
const response = await fetch(url, { credentials: 'same-origin' });
const data = await response.json();
console.log('Respuesta del endpoint:');
console.log('- show_ads:', data.show_ads);
console.log('- reasons:', data.reasons);
console.log('- cache_seconds:', data.cache_seconds);
return data;
}
testEndpoint();
```
---
## Notas de Implementacion
1. **Orden de ejecucion**: Implementar spec primero, luego ejecutar tests
2. **Rollback**: Si falla TC06, revertir cambios (backward compatible)
3. **Monitoreo**: Despues de deploy, verificar metricas de AdSense por 24h
---
## Results Summary
| Test Case | Status | Date | Tester |
|-----------|--------|------|--------|
| TC01 | PENDING | | |
| TC02 | PENDING | | |
| TC03 | PENDING | | |
| TC04 | PENDING | | |
| TC05 | PENDING | | |
| TC06 | PENDING | | |
| TC07 | PENDING | | |
| TC08 | PENDING | | |
| TC09 | PENDING | | |
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2025-12-11 | Initial test plan |