# Tasks: reCAPTCHA v3 Anti-Spam Protection

## Fase 1: Especificación
- [x] Crear proposal.md
- [x] Crear tasks.md
- [x] 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`
  ```php
  interface RecaptchaValidatorInterface {
      public function validate(string $token, string $action): RecaptchaResult;
  }
  ```
- [ ] Crear `Shared/Domain/Entities/RecaptchaResult.php`
  ```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