# Prospector

- Tipo: Modulo interno Vtiger.
- Acceso: `Marketing` -> `Prospector`.
- URL: `admin/index.php?module=Prospector&view=Index`.
- Usuarios: administradores; validado con `admin` id `1`.
- Proposito: buscar prospectos publicos, consolidar fuentes, detectar duplicados con Accounts, importar nuevos y sincronizar datos faltantes en Accounts existentes.

## Estado vigente

Prospector opera como motor multi-fuente:

- Google Maps / Places: fuente primaria para nombre, direccion, telefono, website, coordenadas, rating, place id, categoria y horario.
- Website oficial: enriquecimiento seguro de homepage para title, meta description, OpenGraph, schema/logo, emails, telefonos y links relevantes.
- OpenAI Web Search: complemento para clasificacion, score, descripcion, validacion de giro y fuentes publicas adicionales.

La API Key queda del lado servidor. No se inserta en JavaScript, templates ni respuestas JSON.

## Arquitectura

- `ProspectorGooglePlacesConnector`: consulta Google Places Text Search y Place Details.
- `ProspectorWebsiteConnector`: visita solo website oficial con timeout y limite de bytes; no ejecuta JavaScript remoto.
- `ProspectorOpenAIConnector`: usa OpenAI Responses API con `web_search_preview` para completar informacion faltante.
- `ProspectorResultMerger`: consolida duplicados entre fuentes y prioriza datos por confiabilidad.
- `ProspectorDuplicateDetector`: clasifica cada resultado como `new`, `existing_with_changes` o `existing`.
- `ProspectorImportService`: importa nuevos Accounts y sincroniza solo campos vacios en Accounts existentes.

## Archivos clave

- `admin/config.prospector.php`
- `admin/modules/Prospector/actions/Search.php`
- `admin/modules/Prospector/actions/ImportSelected.php`
- `admin/modules/Prospector/actions/SyncSelected.php`
- `admin/modules/Prospector/services/ProspectorGooglePlacesConnector.php`
- `admin/modules/Prospector/services/ProspectorWebsiteConnector.php`
- `admin/modules/Prospector/services/ProspectorOpenAIConnector.php`
- `admin/modules/Prospector/services/ProspectorResultMerger.php`
- `admin/modules/Prospector/services/ProspectorDuplicateDetector.php`
- `admin/modules/Prospector/services/ProspectorImportService.php`
- `admin/layouts/v7/modules/Prospector/Index.tpl`
- `admin/layouts/v7/modules/Prospector/resources/Prospector.js`

## Persistencia

- `vtiger_prospector_searches`: guarda busquedas, fuentes habilitadas, limites, costo estimado y estado.
- `vtiger_prospector_results`: guarda resultados consolidados, fuentes, place id, website, JSON fusionado, estado de duplicado, estado de sincronizacion, score, coordenadas, rating y horario.

## Flujo

1. Admin abre `Marketing -> Prospector`.
2. Selecciona busqueda, ubicacion, radio, maximo y fuentes.
3. El backend ejecuta conectores server-side.
4. Los resultados se consolidan y se comparan contra Accounts.
5. La UI filtra por Nuevos, Existentes con cambios, Existentes sin cambios o Todos.
6. `Importar seleccionados` crea Accounts solo para nuevos.
7. `Sincronizar informacion` actualiza solo campos vacios de Accounts existentes con informacion nueva.

## Criterios de parada

- Tiempo maximo default: 600 segundos.
- Costo estimado maximo default: 5 USD.
- Google Places max paginas: configurable.
- OpenAI max llamadas: configurable.
- Website timeout y max bytes: configurable.

## Validacion Fase 2

- Busqueda probada: `concreteras` en `Queretaro`, radio `150`, maximo `5`, fuentes Google Places + Website + OpenAI.
- Resultado: Google 5, Website 9 enriquecimientos, OpenAI 5, consolidados 5.
- Clasificacion: 1 nuevo, 4 existentes con informacion nueva, 0 existentes sin cambios.
- Importacion: resultado nuevo importado a Accounts (`account_id=143`).
- Sincronizacion: resultado existente con cambios sincronizado contra Account `3`.
- URL sin sesion: redirige a login; no expone datos ni API Keys.