roi-theme/_openspec/changes/recaptcha-anti-spam/tasks.md

Tasks: reCAPTCHA v3 Anti-Spam Protection

Fase 1: Especificación

• Crear proposal.md
• Crear tasks.md
• Crear spec.md con formato Gherkin
• Obtener aprobación del usuario

Fase 2: Implementación

2.1 Capa Domain (Contratos y Entidades)

• Crear Shared/Domain/Contracts/RecaptchaValidatorInterface.php

  interface RecaptchaValidatorInterface {
      public function validate(string $token, string $action): RecaptchaResult;
  }
  

• Crear Shared/Domain/Entities/RecaptchaResult.php

  final class RecaptchaResult {
      public function __construct(
          private bool $success,
          private float $score,
          private string $action,
          private array $errorCodes = []
      ) {}
      public function isValid(float $threshold): bool;
  }
  

2.2 Capa Application (Servicios)

• Crear Shared/Application/Services/RecaptchaValidationService.php
  • Orquestar validación
  • Aplicar threshold configurable
  • Logging de resultados

2.3 Capa Infrastructure (Implementación)

• Crear Shared/Infrastructure/Services/GoogleRecaptchaValidator.php
  • Llamada HTTP a API de Google
  • Manejo de errores y timeout
  • Parseo de respuesta JSON

2.4 Schema y Admin UI

• Crear Schemas/recaptcha-settings.json
  • Campos: is_enabled, site_key, secret_key, score_threshold, actions
• Sincronizar schema con BD: wp roi-theme sync-component recaptcha-settings
• Crear Admin/RecaptchaSettings/Infrastructure/Ui/RecaptchaSettingsFormBuilder.php
• Crear Admin/RecaptchaSettings/Infrastructure/FieldMapping/RecaptchaSettingsFieldMapper.php
• Registrar en getComponents() del AdminDashboardRenderer
• Registrar FieldMapper en FieldMapperRegistry

2.5 Integración Frontend

• Modificar FooterRenderer.php
  • Agregar script de reCAPTCHA con site key
  • Modificar form para incluir token hidden
• Modificar ContactFormRenderer.php
  • Agregar script de reCAPTCHA con site key
  • Modificar form para incluir token hidden
• Crear JS compartido para ejecutar reCAPTCHA y obtener token

2.6 Integración Backend

• Modificar NewsletterAjaxHandler.php
  • Inyectar RecaptchaValidationService
  • Validar token antes de procesar
  • Retornar error si score bajo
• Modificar ContactFormAjaxHandler.php
  • Inyectar RecaptchaValidationService
  • Validar token antes de procesar
  • Retornar error si score bajo

2.7 Registro DI

• Modificar functions.php
  • Registrar RecaptchaValidatorInterface → GoogleRecaptchaValidator
  • Registrar RecaptchaValidationService

Fase 3: Integración y Validación

3.1 Testing Manual

• Probar Newsletter con reCAPTCHA habilitado
• Probar Contact Form con reCAPTCHA habilitado
• Probar con reCAPTCHA deshabilitado (fallback)
• Probar cambio de threshold desde admin
• Verificar logging de intentos

3.2 Validación de Arquitectura

• Ejecutar validate-architecture.php recaptcha-settings
• Verificar cumplimiento Clean Architecture
• Verificar inyección de dependencias correcta

3.3 Documentación

• Actualizar CLAUDE.md si es necesario
• Documentar configuración en admin

Dependencias

Tarea	Depende de
Application Service	Domain Contract
Infrastructure Service	Domain Contract
Admin FormBuilder	Schema JSON sincronizado
Frontend integration	Site Key configurado
Backend integration	Application Service + Infrastructure

Estimación de Archivos

Tipo	Cantidad
Nuevos	7
Modificados	7
Total	14

Archivos Nuevos

1. Shared/Domain/Contracts/RecaptchaValidatorInterface.php
2. Shared/Domain/Entities/RecaptchaResult.php
3. Shared/Application/Services/RecaptchaValidationService.php
4. Shared/Infrastructure/Services/GoogleRecaptchaValidator.php
5. Schemas/recaptcha-settings.json
6. Admin/RecaptchaSettings/Infrastructure/Ui/RecaptchaSettingsFormBuilder.php
7. Admin/RecaptchaSettings/Infrastructure/FieldMapping/RecaptchaSettingsFieldMapper.php

Archivos a Modificar

1. Public/Footer/Infrastructure/Api/WordPress/NewsletterAjaxHandler.php
2. Public/ContactForm/Infrastructure/Api/WordPress/ContactFormAjaxHandler.php
3. Public/Footer/Infrastructure/Ui/FooterRenderer.php
4. Public/ContactForm/Infrastructure/Ui/ContactFormRenderer.php
5. functions.php
6. Admin/Infrastructure/Ui/AdminDashboardRenderer.php
7. Admin/Shared/Infrastructure/FieldMapping/FieldMapperRegistry.php

Última actualización

2025-01-08