# Corrección legal del módulo de competencia — cómo aplicarla Esta carpeta contiene los archivos corregidos de tu repo Laravel. Reemplazan el scraping ilegal por fuentes legales, sin romper el resto del sistema. ## Qué cambió y por qué Tu repo tenía un módulo de competencia que hacía **scraping** de redes y guardaba **nombre, usuario y afinidad política** de cada ciudadano que comentaba en las cuentas de los rivales. Eso es tratamiento de dato sensible sin autorización, prohibido por la Ley 1581 de 2012. El detalle completo está en `AUDITORIA-COMPETENCIA.md`. ## Cómo aplicar 1. **Respalda tu repo** antes de tocar nada (o trabaja en una rama nueva). 2. **Copia los archivos** de esta carpeta sobre tu repo, respetando las rutas. Todos van en las mismas ubicaciones que ya tenías, más dos nuevos: - `app/Services/Competitor/CompetitorIntelligenceService.php` (reemplazo legal) - `app/Console/Commands/SyncCompetitorIntelligenceCommand.php` (reemplaza social:scrape) - la migración de purga en `database/migrations/` 3. **Purga los datos ya recolectados** (si el sistema corrió antes): ```bash php artisan migrate ``` La migración `purge_third_party_social_comments` elimina los comentarios de terceros que hubiera en la base. 4. **Verifica que compila:** ```bash php artisan config:clear composer dump-autoload php artisan route:list | grep -i social # las rutas siguen respondiendo ``` 5. **Configura el token de Ad Library** por tenant (no en `.env` compartido). El servicio lo lee de `config('services.meta.ad_library_token')`, que a su vez debe venir de `tenant_integrations` descifrado. 6. **Programa la sincronización legal** en `app/Console/Kernel.php`: ```php $schedule->command('sync:competitor-intelligence')->everySixHours(); ``` ## Qué sigue funcionando igual - El controlador `SocialScraperController` responde en las mismas rutas: internamente delega en el servicio legal, así que el frontend no nota el cambio. - El modelo `PoliticalCompetitor` no se tocó: ya guardaba solo datos públicos. - La demo con datos de ejemplo sigue intacta. ## Qué revisar antes de producción - **`app/Models/SocialComment.php`**: hoy sirve tanto para comentarios propios (legal) como para los de terceros (ilegal). Restríngelo a canales propios, o añade una columna `is_own_channel` y filtra por ella en todas las consultas. - **`app/Services/QrData/QrDataScrapingService.php`**: no scrapea de verdad (genera datos con `rand()`), pero el nombre confunde y arma perfiles demográficos por ubicación. Renómbralo y revisa que los datos reales que lo reemplacen sean agregados anónimos, no perfiles individuales. --- # Segunda entrega — Inteligencia legal + landing ## Ad Library y métricas públicas (backend completo) Archivos nuevos: - `app/Services/Competitor/CompetitorIntelligenceService.php` — ahora guarda en BD - `app/Jobs/SyncCompetitorIntelligenceJob.php` — sincroniza en background con reintentos - `app/Console/Commands/SyncCompetitorIntelligenceCommand.php` — despacha los jobs - `app/Http/Controllers/Api/CompetitorIntelligenceController.php` — expone al panel - `app/Models/CompetitorAdSnapshot.php` + `CompetitorMetricSnapshot.php` - `database/migrations/2026_07_24_130000_create_competitor_intelligence_tables.php` ### Cómo activarlo 1. Migrar las tablas nuevas: ```bash php artisan migrate ``` 2. Configurar el token de la Ad Library en `config/services.php`: ```php 'meta' => [ 'ad_library_token' => env('META_AD_LIBRARY_TOKEN'), ], ``` En producción, ese token debe venir descifrado de `tenant_integrations`, no de `.env` compartido. 3. Programar la sincronización en `app/Console/Kernel.php`: ```php $schedule->command('sync:competitor-intelligence')->everySixHours(); ``` 4. Probar manualmente: ```bash php artisan sync:competitor-intelligence --campaign=1 ``` ### Cómo lo consume el panel - `GET /api/campaigns/{campaign}/competitors/intelligence` — resumen de todos los rivales - `POST /api/competitors/{competitor}/sync` — fuerza una actualización El panel lee de los snapshots guardados, no llama a Meta en cada carga. Así una lentitud de la API externa nunca afecta la experiencia del usuario. ## Landing pública - **Suelta:** `goberdata-landing.html` en la raíz de outputs — HTML autocontenido, ábrela en cualquier navegador o súbela a un hosting estático. - **En Laravel:** `resources/views/landing.blade.php`, servida en `/landing` y `/planes`. ### Planes Tres planes pensados para el calendario electoral: Mensual, Semestral (destacado como "más elegido") y Campaña completa. Los precios están como `$—` a propósito: pon la cifra cuando la definas, o deja el "solicita cotización" que ya trae. La recomendación es no fijar precios públicos, porque varían por tamaño de ciudad. Para poner precios, busca en la landing los bloques `plan-price` y reemplaza el `$—`. --- # Tercera entrega — Registro de demo con enlace mágico Sistema completo de captación de leads con acceso automático, sin contraseñas. ## Cómo funciona 1. El prospecto llena el formulario en la landing (nombre, correo, departamento, ciudad, teléfono). 2. Se crea un lead con un token único que vence en 7 días. 3. Se le envía por correo un enlace mágico. Un clic y entra — sin usuario ni contraseña. 4. El acceso caduca solo. No quedan usuarios basura. ## Por qué así y no con usuario/contraseña - **Seguro:** no viaja ninguna contraseña por correo (mala práctica común). - **Sin fricción:** un clic desde el correo. Más prospectos completan la demo. - **Automático:** registro, envío y caducidad ocurren solos. - **Deja el lead:** cada solicitud queda guardada para seguimiento comercial. ## Archivos nuevos - `database/migrations/2026_07_24_140000_create_demo_requests_table.php` - `app/Models/DemoRequest.php` - `app/Mail/DemoAccessMail.php` + `resources/views/emails/demo-access.blade.php` - `app/Http/Controllers/DemoRequestController.php` - `app/Http/Controllers/Admin/DemoLeadsController.php` - Vistas: `demo-enviada`, `demo-acceso-invalido`, `admin/demo-leads` ## Cómo activarlo 1. Migrar: ```bash php artisan migrate ``` 2. Configurar el correo en `.env` (hoy está en modo `log`, que escribe el correo en `storage/logs` en vez de enviarlo — útil para probar): ``` MAIL_MAILER=smtp MAIL_HOST=smtp.tuservidor.com MAIL_PORT=587 MAIL_USERNAME=... MAIL_PASSWORD=... MAIL_FROM_ADDRESS=hola@goberdata.co MAIL_FROM_NAME="GoberData" ``` Para producción se recomienda un servicio como Mailgun, Postmark o Amazon SES. 3. (Opcional) Encolar el envío para que el formulario responda al instante: el Mailable ya usa `Queueable`; solo configura un `QUEUE_CONNECTION=redis` y corre `php artisan queue:work`. ## Rutas | Ruta | Qué hace | |---|---| | `POST /demo/solicitar` | Recibe el formulario | | `GET /demo/enviada` | Confirmación "revisa tu correo" | | `GET /demo/acceso/{token}` | Valida el enlace y entra a la demo | | `GET /admin/demo-leads` | Panel de leads para ventas (protegido con `auth`) | ## El panel de leads En `/admin/demo-leads` tu equipo comercial ve: quién pidió la demo, si entró y cuántas veces, cuándo vence su acceso y en qué estado está (nuevo, contactado, cliente…). Puede reenviar el enlace con un clic, y si venció se renueva solo. ## Nota sobre la demo aislada El controlador guarda en sesión `demo_visitor => true` y redirige a la ruta `demo`. Ese acceso debe apuntar a una **campaña demo con datos de ejemplo**, nunca a un tenant real de un cliente. Usa los seeders (`CompleteDataSeeder`) para poblarla. --- # Cuarta entrega — Desplegables dependientes (departamento → ciudad) El formulario de demo ahora usa dos desplegables encadenados: eliges departamento y las ciudades se cargan solas. Evita errores de escritura y te da datos limpios. ## De dónde salen los datos De las tablas `states` y `cities` que ya pobla `ColombiaCompleteSeeder` (33 departamentos, 101 ciudades principales). No hay listas quemadas en el código. ## Archivos nuevos - `app/Http/Controllers/GeoController.php` — dos endpoints: - `GET /geo/departamentos` — lista de departamentos - `GET /geo/departamentos/{state}/ciudades` — ciudades de ese departamento - El JavaScript va dentro de `landing.blade.php`. ## Cómo activarlo Solo necesitas los datos en BD: ```bash php artisan db:seed --class=ColombiaCompleteSeeder ``` Si quieres los 1.103 municipios completos (no solo los principales), amplía ese seeder con la lista de la Registraduría o el DANE. La estructura ya lo soporta. ## Detalle robusto Si la API de geografía falla por lo que sea, el formulario **cae a campos de texto libre** automáticamente, así que nunca queda un formulario inutilizable. La ciudad arranca deshabilitada hasta que eliges departamento, y la capital aparece primero en la lista. --- # Quinta entrega — Encuestas de calle (constructor dinámico) Sistema para que cada tenant arme formularios de entrevista en la calle, con preguntas dinámicas que alimentan el mapa y el análisis de IA. ## Lo que ya existía en tu repo Buena noticia: gran parte ya estaba. `StreetSurvey`, `SurveyResponse` (con campo `answers` en JSON dinámico), `StreetSurveyController` con dashboard, exportación, submit de respuestas y stats por encuestador. Los datos del entrevistado ya eran anónimos (rango de edad, género, estrato — sin nombre). ## Lo que añadí Faltaba el **constructor de preguntas**. Nuevo: - `database/migrations/2026_07_24_150000_create_survey_templates_tables.php` - `app/Models/SurveyTemplate.php` — con banco de preguntas listo (`bancoPreguntas()`) - `app/Http/Controllers/SurveyTemplateController.php` — CRUD del constructor - `app/Services/Survey/SurveyAnalysisService.php` — convierte respuestas en: - intención de voto por comuna (alimenta el mapa) - preocupaciones agregadas por zona - resumen con IA de "qué cambiaría tu voto" - indicadores de reconocimiento e intensidad ## Cómo activarlo ```bash php artisan migrate ``` Para crear la plantilla estándar de una campaña: ```php SurveyTemplate::crearEstandar($campaignId); ``` ## Diseño de privacidad (importante) - Las respuestas se guardan **anónimas**: rango de edad, género, estrato, zona — nunca nombre ni cédula obligatorios. - El contacto (nombre, teléfono) es **opcional** y solo con `consent_given` y `allow_contact` marcados por el entrevistado. - La afinidad política se guarda separada de cualquier dato de contacto. Esto mantiene el sistema dentro de la Ley 1581: mides el ambiente sin perfilar votantes identificables. ## Las 6 preguntas del banco estándar 1. ¿Por quién piensa votar? (intención → mapa) 2. ¿Qué tema le preocupa más? (prioridades → IA) 3. ¿Qué cambiaría su voto hacia nuestro candidato? (motivadores → IA, la más valiosa) 4. ¿Conoce a nuestro candidato? (reconocimiento) 5. ¿Qué tan probable es que vote por él? escala 1-5 (intensidad) 6. ¿Cómo evalúa la alcaldía actual? (ambiente) --- # Sexta entrega — Pasarela de pagos Bold (donaciones) Integración completa con Bold (bold.co) para recibir donaciones de campaña, con control de tope legal y trazabilidad para el CNE. ## ⚠️ Importante antes de activar Cobrar donaciones políticas tiene requisitos legales fuertes en Colombia: - Cada aporte debe reportarse al CNE (cuentas claras). - Hay topes por persona y por campaña (Ley 1475). - Fuentes prohibidas: contratistas del Estado, empresas extranjeras, etc. - Bold puede exigir documentación adicional para donaciones políticas. La integración técnica está lista; el cumplimiento legal es responsabilidad de la campaña. Consulta con un abogado electoral antes de recibir dinero real. ## Archivos nuevos - `app/Services/Payments/BoldPaymentService.php` — genera el hash de integridad (SHA-256, server-side), consulta transacciones, registra resultados. - `app/Http/Controllers/BoldDonationController.php` — valida el tope legal ANTES del pago, maneja el resultado y el webhook. - Vistas: `donaciones/formulario`, `donaciones/pagar`, `donaciones/resultado`. - `config/services.php` — bloque `bold`. - `.env.example` — variables BOLD_*. ## Cómo funciona el flujo 1. El aportante entra a `/campaigns/{id}/donar`, elige monto y llena sus datos. 2. Se valida el tope legal (10% del tope de campaña por persona). 3. Se crea la donación en estado `pendiente` con el consentimiento registrado. 4. Se muestra el botón oficial de Bold, firmado desde el servidor. 5. El aportante paga. Bold redirige a `/donaciones/resultado`. 6. El webhook (`/webhooks/bold`) confirma el pago de forma definitiva y genera el número de recibo para el CNE. ## Seguridad (verificada) - La llave secreta NUNCA llega al frontend. - El hash de integridad se genera en el servidor (si no, un atacante podría alterar el monto). - El webhook es la fuente de verdad, no el redirect. ## Cómo activarlo 1. Crear cuenta en bold.co y obtener las llaves (API key y llave secreta). 2. Ponerlas en `.env`: ``` BOLD_API_KEY=... BOLD_SECRET_KEY=... BOLD_WEBHOOK_SECRET=... ``` 3. Registrar el webhook en el panel de Bold apuntando a `https://tudominio.com/webhooks/bold`. 4. Migrar si hace falta y probar con el ambiente de pruebas de Bold antes de pasar a producción. ## Pendiente para producción - Validar la firma del webhook de Bold (hoy se registra; falta verificar la firma con BOLD_WEBHOOK_SECRET según su documentación). - Calcular el tope real de la campaña según el censo electoral (hoy usa un valor de ejemplo en `config/campaign.tope_1475`). - Probar en el ambiente sandbox de Bold con tarjetas de prueba. --- # Séptima entrega — Resumen ejecutivo IA + GOTV + WhatsApp Tres módulos de alto valor, en la demo y en el Laravel. ## 1. Resumen ejecutivo diario con IA (NUEVO) Lo primero que ve el candidato al abrir: un panorama del día en 30 segundos. - `app/Services/AI/ExecutiveBriefService.php` — reúne señales de todos los módulos (escaneos, encuestas, competencia, agenda), calcula indicadores vs ayer, genera alertas y 3 acciones prioritarias. La IA redacta la narrativa; si no hay IA disponible, usa una plantilla. - `app/Http/Controllers/ExecutiveBriefController.php` — `GET /campaigns/{id}/brief` - Cacheado 30 min para no recalcular en cada carga. ## 2. GOTV — Día de elección (YA EXISTÍA en tu repo) `GotvController` ya estaba completo: panel del día, brigadas, marcar voto, reportar y listar incidentes. Los modelos `GotvBrigade`, `GotvIncident`, `GotvActivity`, `ConfirmedVoter`, `PollingStation` ya existían. En la demo añadí la interfaz: panel con participación por puesto, brigadas de movilización e incidentes con severidad. ## 3. WhatsApp (YA EXISTÍA en tu repo) `WhatsAppController` ya estaba: campañas, plantillas, auto-respuestas. Modelos `WhatsAppCampaign`, `WhatsAppTemplate`, `WhatsAppAutoReply` presentes. En la demo añadí la interfaz: métricas de envío, campañas, plantillas con variables, y respuestas automáticas. ## Nota sobre lo que ya existía Buena parte del backend de GOTV y WhatsApp ya estaba construido en tu repo, solo sin interfaz visible. Lo aproveché en vez de duplicarlo. Lo genuinamente nuevo es el resumen ejecutivo con IA, que integra todos los módulos. ## Ideas para seguir (documentadas, no implementadas) De la revisión completa del sistema, otros módulos con potencial que ya tienen modelos pero poca interfaz: Email marketing (`EmailCampaign`), PQRS (`Pqrs`), Propuestas (`Proposal`), Call center (`CallCenterScript`), Puestos de votación con participación en vivo (`PollingStationTurnout`), Resultados preliminares (`PreliminaryResult`). --- # Octava entrega — Email, PQRS, Propuestas y Jornada electoral Cuatro módulos más, en la demo y en el Laravel. Como antes, la mayoría del backend ya existía; añadí lo que faltaba y toda la interfaz en la demo. ## Ya existían en tu repo (con controlador API) - **Email marketing** — `Api/EmailMarketingController` (10 métodos), modelos `EmailCampaign`, `EmailClick`, `EmailTemplate`. - **PQRS** — `Api/PqrsController` (6 métodos), modelos `Pqrs`, `PqrsCategory`. - **Propuestas** — `Api/ProposalController` (9 métodos), modelos `Proposal`, `ProposalComment`, `ProposalAmendment`. Solo les faltaba interfaz visible, que añadí en la demo. ## Nuevo — Jornada electoral `app/Http/Controllers/ElectionDayController.php`. Los modelos ya existían (`PreliminaryResult`, `PollingStationTurnout`), faltaba el controlador: - `GET /campaigns/{id}/jornada/participacion` — participación en vivo por puesto - `GET /campaigns/{id}/jornada/resultados` — resultados preliminares consolidados - `POST /puestos/{station}/participacion` — registrar medición de participación - `POST /puestos/{station}/resultado` — capturar acta de una mesa (con foto) Privacidad: todo agregado por puesto/mesa. Nunca por quién votó cada persona. El resultado oficial siempre es el de la Registraduría; esto es referencia interna para reaccionar rápido el día D. ## En la demo Cuatro vistas nuevas: - **Correo**: métricas de apertura/clic y lista de campañas. - **PQRS**: bandeja de tickets ciudadanos + desglose por categoría. - **Propuestas**: plan de gobierno con apoyos y comentarios ciudadanos. - **Resultados en vivo**: conteo preliminar, % escrutado, posición y resultados por puesto; pestaña de participación comparando tu base vs el promedio. ## Pulido de esta ronda - Corregido un bug en los indicadores del resumen ejecutivo (mostraban "NaN%" cuando el delta venía como texto en vez de número). --- # Novena entrega — Registro legal de rivales + cifrado de credenciales ## La diferencia: conectar vs consultar - **Tus cuentas** (Facebook, Instagram, X del candidato) se CONECTAN con login real, porque son tuyas. Van en `TenantIntegration`. - **Las cuentas del rival** NO se conectan. Solo se registra su usuario público (@handle) en `PoliticalCompetitor.social_handles`. Con ese dato, la plataforma CONSULTA lo público: Ad Library de Meta + métricas vía API oficial. Nunca se pide ni usa la contraseña del rival. Eso sería ilegal. ## Mejora de seguridad aplicada `TenantIntegration.credentials` guardaba las llaves de las cuentas propias como `array` (texto plano en la BD). Se cambió a `encrypted:array`: ahora las credenciales se cifran en la base de datos. Si alguien accede a la BD, no puede leer las llaves de ningún candidato. **Ojo al migrar:** si ya tenías credenciales guardadas en texto plano, hay que re-guardarlas para que se cifren (Laravel no cifra retroactivamente lo que ya estaba). En un sistema nuevo no hay problema. ## En la demo En Competencia se añadió un panel "¿Cómo agrego a un rival?" que explica los 3 pasos (anotar su usuario público → la plataforma consulta lo público → nunca conectas su cuenta) y un formulario que solo pide el @handle, sin contraseña. --- # Décima entrega — Roles alineados demo ↔ Laravel ## Los 8 roles ahora coinciden `database/seeders/RolesAndPermissionsSeeder.php` reescrito con los 8 roles de la demo, cada uno con permisos por módulo: | Rol | Ve competencia | Resumen | |---|---|---| | super_admin | sí | dueño de plataforma, todo | | candidate | **sí** | candidato, acceso amplio | | campaign_manager | **sí** | gerente, administra operación | | treasurer | no | finanzas y donaciones | | territorial_coordinator | no | calle, mapa, GOTV | | digital_coordinator | **no** | redes, IA, contenido | | volunteer | no | captura en calle | | auditor | no | solo lectura, control | Se conservan roles legacy (admin, campaign_admin, coordinator) para no romper datos existentes. ## Competencia: solo candidato y gerente El permiso `view_competitor_intelligence` se aplicó como middleware en las rutas que CONFIGURAN rivales (`POST/PUT/DELETE /competitors`) y en la de inteligencia (Ad Library). Así no basta con ocultar el menú: el backend rechaza a quien no tenga el permiso. Esto responde a la decisión de que agregar/quitar rivales sea estratégico (candidato/gerente), no operativo. El coordinador digital ve datos de redes pero no configura la consulta de rivales. ## Cómo aplicarlo ```bash php artisan db:seed --class=RolesAndPermissionsSeeder php artisan permission:cache-reset ``` Los usuarios se asignan a un rol con spatie: `$user->assignRole('campaign_manager')`. --- # Undécima entrega — Modelos de IA dependientes del proveedor ## El problema En el modal de "Proveedor de IA", al elegir un proveedor (ej: OpenAI) el select de modelo seguía mostrando modelos de otro proveedor (ej: claude-sonnet). Se podía guardar una combinación inválida. ## Arreglo **Demo:** el select de modelo ahora se actualiza al cambiar el proveedor (función `actualizarModelos`). Cada proveedor muestra solo sus modelos: - Anthropic → claude-opus-4-5, claude-sonnet-4-6, claude-haiku-4-5 - OpenAI → gpt-4o, gpt-4o-mini, gpt-4-turbo, o1 - Google → gemini-2.0-flash, gemini-1.5-pro, gemini-1.5-flash - On-premise → llama-3.1-70b, mixtral-8x7b, personalizado **Laravel:** `AIProviderController`: - `modelosPorProveedor()` — catálogo de modelos actualizado por proveedor - `GET /ai-providers/modelos` — endpoint para que el frontend pueble el select - Validación en `store`: rechaza (422) si el modelo no corresponde al proveedor - `getDefaultModel()` actualizado a modelos actuales El frontend real debe consumir `GET /ai-providers/modelos` y, al cambiar el `