================================================================================
GUÍA DE DESARROLLO Y MANTENIMIENTO: PROYECTO OPEN_MAPS (ANTIGRAVITY)
================================================================================

AUTOR: Equipo Antigravity
FECHA: 22/01/2026
VERSIÓN: 1.0

1. INTRODUCCIÓN
--------------------------------------------------------------------------------
Este proyecto es una aplicación de mapa interactivo basada en MapLibre GL JS, 
diseñada para visualizar inmuebles inmobiliarios con capacidades 3D, búsqueda 
avanzada y clustering.

El objetivo fue crear una arquitectura modular, mantenible y sin dependencias 
complejas de compilación (No Webpack/Vite obligatorio), permitiendo funcionar 
directamente en cualquier servidor web estático.

2. ESTRUCTURA DEL PROYECTO
--------------------------------------------------------------------------------
La estructura de carpetas es clean y modular:

/src
  /js
    config.js  -> Constantes globales (IPs, Puertos, Claves).
    main.js    -> Punto de entrada. Inicializa controladores.
    map.js     -> Lógica del Mapa (MapController). Capas, Fuentes, 3D.
    ui.js      -> Lógica de Interfaz (UIController). Búsqueda, Eventos, Popups.
    data.js    -> Carga asíncrona de GeoJSONs.
    icons.js   -> Definiciones SVG de iconos (sin archivos externos).
  /lib
    /maplibre  -> Librería MapLibre GL JS (Local).
    /turf      -> Librería Turf.js (Local).
  /data
    inmuebles.json -> GeoJSON de propiedades regulares.
    destacados.json -> GeoJSON de propiedades destacadas.
index_esp.html -> Documento HTML principal.

3. CONFIGURACIÓN Y DESPLIEGUE (MULTI-PAÍS / MULTI-IDIOMA)
--------------------------------------------------------------------------------
El proyecto ahora soporta múltiples países e idiomas de forma dinámica.
Editar `src/js/config.js` para gestionar la configuración.

- BASE_CONFIG: Configuración común (IP Servidor, Puertos).
- COUNTRY_CONFIG: Configuración específica por país (Centro, Zoom, Estilos, Datos, Código País).
- TRANSLATIONS: Textos de la UI en varios idiomas (ES, EN, EL).

ARCHIVOS DE ENTRADA:
- index_esp.html -> Inicializa España / Español.
- index_cy.html  -> Inicializa Chipre / Inglés.

4. ARQUITECTURA TÉCNICA
--------------------------------------------------------------------------------
El código sigue el patrón Controlador con Inyección de Dependencias:

A. Main Entry (main.js)
   - Exporta `initApp({ country, language, containerId })`.
   - Se llama desde el HTML para arrancar la app con la config deseada.

B. MapController (map.js)
   - Recibe la configuración completa en el constructor.
   - Gestiona lógica del mapa, fuentes y capas según el país activo.
   - `highlightBuildingsUnderPoints()`: Lógica geométrica crítica para 3D.

C. UIController (ui.js)
   - Recibe la configuración y textos traducidos (`this.texts`).
   - Gestiona Búsqueda (Nominatim filtrado por país) y Popups localizados.

5. TRUCOS Y SOLUCIONES IMPLEMENTADAS ("GOTCHAS")
--------------------------------------------------------------------------------

A. ERROR DE ICONOS FALTANTES (styleimagemissing)
   Solución: Interceptamos el evento y generamos un pixel transparente para evitar
   errores 404 en consola si faltan sprites en el servidor.

B. CARGA ASÍNCRONA DE IMÁGENES
   Solución: Uso de `Promise.all` para cargar todos los SVGs antes de añadir capas.

C. FILTRADO NOMINATIM POR PAÍS
   Problema: Búsquedas ambiguas devolvían resultados de otros países.
   Solución: Se inyecta `&countrycodes=es|cy` en la llamada a la API según la config.

6. CÓMO AÑADIR UN NUEVO PAÍS
--------------------------------------------------------------------------------

1. Editar `src/js/config.js`:
   - Añadir entrada en `COUNTRY_CONFIG` (ej: 'fr').
   - Definir `center`, `zoom`, `stylePath` y `countryCode`.
2. Crear archivo de datos:
   - `src/data/inmuebles_fr.json`.
3. Crear HTML de entrada:
   - Copiar `index_esp.html` a `index_fr.html`.
   - Modificar llamada a `initApp({ country: 'fr', ... })`.

7. COOKBOOK / RECETARIO DE EJEMPLOS
--------------------------------------------------------------------------------

A. CÓMO LLAMAR/INSTANCIAR EL MAPA
----------------------------------
Usar la función helper de `main.js`:

   import { initApp } from './src/js/main.js';
   initApp({ country: 'es', language: 'es', containerId: 'map' });

B. CÓMO LLAMAR A NOMINATIM (CON FILTRO DE PAÍS)
-------------------------------------
Ver `src/js/ui.js` -> `setupSearch`.

   import { getNominatimUrl } from './js/config.js';
   // El 3er parámetro es el código de país para filtrar (ej: 'es')
   const url = getNominatimUrl("Madrid", null, 'es'); 

   fetch(url).then(...);

C. CÓMO CREAR UN PUNTO (MARCADOR)
---------------------------------
(Igual que versión anterior, ver map.js)

D. CÓMO ACTUALIZAR TEXTOS / TRADUCCIONES
----------------------------------------
Editar objeto `TRANSLATIONS` en `src/js/config.js`.

8. CHECKLIST DE MANTENIMIENTO
--------------------------------------------------------------------------------
[ ] Verificar conexión a 192.168.23.44 periódicamente.
[ ] Asegurar que los sprites (.json y .png) existen para cada estilo de país.
[ ] Si cambia la IP, actualizar SOLO `BASE_CONFIG` en `config.js`.

FIN DE LA GUÍA
================================================================================