roi-theme/openspec/changes/add-advanced-incontent-ads/tasks.md

Tasks: Implementacion de In-Content Ads Avanzados

Diagrama de Dependencias

1.1 ──┬──> 1.3 ──┬──> 2.x FormBuilder ──> 4.x
1.2 ──┘          │
                 └──> 3.x Renderer ──────> 4.x
                                           │
                                           v
                                      5.x Docs

---

1. Schema JSON - Nuevos campos

Prerequisitos: Ninguno

• 1.1 Agregar grupo incontent_advanced con priority 69 al schema JSON
• 1.2 Agregar todos los campos definidos en spec:
  • incontent_mode (select: legacy/conservative/balanced/aggressive/custom)
  • incontent_after_h2_enabled + probability
  • incontent_after_h3_enabled + probability
  • incontent_after_paragraphs_enabled + probability (ubicacion tradicional)
  • incontent_after_images_enabled + probability
  • incontent_after_lists_enabled + probability
  • incontent_after_blockquotes_enabled + probability
  • incontent_after_tables_enabled + probability
  • incontent_max_total_ads (1-15)
  • incontent_min_spacing (2-6)
  • incontent_format
  • incontent_priority_mode (position/priority)
• 1.3 Sincronizar schema con BD via WP-CLI: wp roi-theme sync-component adsense-placement

---

2. FormBuilder Admin - Nueva UI

Prerequisitos: 1.3 completado

• 2.1 Crear metodo buildInContentAdvancedGroup() en AdsensePlacementFormBuilder
• 2.2 Implementar indicador de densidad (HTML + logica de color)
• 2.3 Implementar selector de modo con presets
• 2.4 Crear subseccion colapsable "Ubicaciones por Elemento" usando <details>
  • 2.4.1 Toggle + probabilidad para H2
  • 2.4.2 Toggle + probabilidad para H3
  • 2.4.3 Toggle + probabilidad para parrafos (ubicacion tradicional)
  • 2.4.4 Toggle + probabilidad para imagenes
  • 2.4.5 Toggle + probabilidad para listas
  • 2.4.6 Toggle + probabilidad para blockquotes
  • 2.4.7 Toggle + probabilidad para tablas
• 2.5 Crear subseccion colapsable "Limites y Espaciado"
  • 2.5.1 Select max_total_ads (1-15)
  • 2.5.2 Select min_spacing (2-6)
• 2.6 Agregar warning visual para densidad alta (>10 ads)
• 2.7 Agregar banner de migracion para usuarios con config legacy activa
• 2.8 Mantener seccion legacy existente (modo "legacy" la usa)
• 2.9 Agregar mapeos en AdsensePlacementFieldMapper para todos los campos nuevos:
  • incontent_mode
  • incontent_after_h2_enabled + probability
  • incontent_after_h3_enabled + probability
  • incontent_after_paragraphs_enabled + probability
  • incontent_after_images_enabled + probability
  • incontent_after_lists_enabled + probability
  • incontent_after_blockquotes_enabled + probability
  • incontent_after_tables_enabled + probability
  • incontent_max_total_ads
  • incontent_min_spacing
  • incontent_format
  • incontent_priority_mode
• 2.10 Implementar logica JavaScript:
  • 2.10.1 Auto-switch a "custom" al modificar campos (con toast informativo)
  • 2.10.2 Modal de confirmacion al cambiar de "custom" a preset
  • 2.10.3 Actualizar indicador de densidad en tiempo real

---

3. Renderer - Logica de insercion mejorada

Prerequisitos: 1.3 completado

• 3.1 Crear/modificar ContentAdInjector service con nuevo algoritmo
  • 3.1.1 Implementar PASO 0: Validar min_content_length
  • 3.1.2 Implementar PASO 1: Escaneo con regex multiple

    preg_split('/(<\/(?:p|h[2-3]|figure|ul|ol|table|blockquote)>)/i', ...)
    

  • 3.1.3 Implementar deteccion de <img> standalone (no dentro de figure)
  • 3.1.4 Implementar validacion de listas (usar substr_count, minimo 3 items)
• 3.2 Implementar PASO 2: Filtrado por configuracion (enabled flags)
• 3.3 Implementar PASO 3: Probabilidad deterministica
  • 3.3.1 Calcular seed: crc32(post_id . date('Y-m-d'))
  • 3.3.2 Usar mt_srand(seed) + mt_rand(1, 100)
• 3.4 Implementar PASO 4-5: Filtrado y seleccion (segun incontent_priority_mode)
  • 3.4.1 Definir constantes de prioridad (H2=10, p=8, H3=7, img=6, lists=5, bq=4, table=3)
  • 3.4.2 Implementar modo "position": espaciado primero, luego prioridad
  • 3.4.3 Implementar modo "priority": prioridad primero, luego espaciado
  • 3.4.4 Aplicar limite max_total_ads
  • 3.4.5 Reordenar resultado final por posicion DOM
• 3.5 Implementar PASO 6: Insercion de ads
• 3.6 Implementar logica de precedencia legacy vs nuevo sistema
  • 3.6.1 Si incontent_mode == "legacy", usar campos del grupo behavior
  • 3.6.2 Si incontent_mode != "legacy", usar incontent_advanced

---

4. Validacion y Testing

Prerequisitos: 2.x y 3.x completados

• 4.1 Ejecutar validate-architecture.php adsense-placement
• 4.2 Probar en post con contenido variado (H2, H3, images, lists, tables)
• 4.3 Verificar que seed deterministico funciona (mismas posiciones mismo dia)
• 4.4 Verificar que espaciado minimo se respeta
• 4.5 Verificar que limite max_total_ads se respeta
• 4.6 Verificar que modo legacy sigue funcionando
• 4.7 Verificar que delay de carga sigue funcionando
• 4.8 Probar indicador de densidad en admin
• 4.9 Verificar ambos modos de priority_mode (position vs priority)

---

5. Documentacion

Prerequisitos: 4.x completado

• 5.1 Crear spec.md final en openspec/specs/adsense-placement/
• 5.2 Archivar este change: openspec archive add-advanced-incontent-ads