# 🔧 DOCUMENTACIÓN TÉCNICA - BeeLifeMaps

## 📋 ARQUITECTURA DEL SISTEMA

### Estructura General
```
dw_leaflet_app/
├── server/                    # Backend Node.js + Express
│   ├── index.js              # Servidor principal + Google Earth Engine
│   ├── package.json          # Dependencias del backend
│   └── .private-key.json     # Credenciales GCP (NO incluir en repo)
├── web/                      # Frontend completo
│   ├── index.html           # Aplicación SPA completa
│   └── analysis_real.js     # Motor de análisis apícola
└── README.md                # Documentación de usuario
```

### Stack Tecnológico
- **Backend**: Node.js 18+, Express.js, Google Earth Engine API
- **Frontend**: HTML5, CSS3, JavaScript ES6+, Leaflet.js
- **APIs Externas**: SIGPAC WFS/WMS, Dynamic World, OpenStreetMap
- **Datos**: Sentinel-2, SIGPAC oficial, OSM Overpass

## 🔄 FLUJO DE DATOS PRINCIPAL

### 1. Inicialización
```javascript
// server/index.js - Líneas 1-50
app.listen(3000) → Servidor Express activo
ee.initialize() → Autenticación Google Earth Engine
```

### 2. Búsqueda de Localidad
```javascript
// web/index.html - Líneas 200-250
Nominatim API → Coordenadas → Centro del mapa → Círculo de análisis
```

### 3. Análisis Apícola (Dos Modalidades)

#### A) 🐝 Exploración Rápida
```javascript
// web/index.html - Líneas 546-663
findBeeLocationsByGeography() → getAllParcelasInArea() → 
Filtro mejores 6 parcelas → Marcadores con popups detallados
```

#### B) 🔬 Análisis Profundo  
```javascript
// web/analysis_real.js - Líneas 880-928
performDeepAnalysis() → 500 puntos muestreo → 
calcularZonasRecomendadas() → Top 10 zonas → Visualización
```

## 🎯 FUNCIONES CRÍTICAS

### `getAllParcelasInArea()` - Motor Principal
**Ubicación**: `analysis_real.js` líneas 353-500
**Propósito**: Obtiene datos SIGPAC reales para análisis
**Parámetros**: `center` (LatLng), `radiusKm` (número)
**Retorna**: Array de parcelas con datos completos

**Algoritmo**:
1. Genera 500 puntos de muestreo uniformes
2. Para cada punto: consulta GetFeatureInfo SIGPAC
3. Parsea HTML response → extrae cultivo, superficie, sistema
4. Calcula valor apícola basado en cultivo específico
5. Implementa caché para evitar recálculos

### `calculateRealScore()` - Evaluación Apícola
**Ubicación**: `analysis_real.js` líneas 1500-1700
**Propósito**: Calcula idoneidad apícola de cada punto
**Algoritmo**:
```javascript
valorBase = getCultivoValue(cultivo)  // 0.15-0.40 según cultivo
multiplicadorRiego = esRegadio ? 1.2 : 1.0
indiceFloral = getFloralIndex(cultivo, mesActual)  // 0.0-1.0
valorFinal = valorBase * multiplicadorRiego * indiceFloral
```

### `calcularZonasRecomendadas()` - Zonificación
**Ubicación**: `analysis_real.js` líneas 980-1024
**Propósito**: Agrupa parcelas en zonas de alta densidad
**Algoritmo**:
1. Crea grid de celdas 0.001° (~100m)
2. Agrupa parcelas por celda geográfica
3. Calcula score ponderado por zona
4. Ordena y retorna top 10 zonas

## 🔌 INTEGRACIÓN DE APIs

### SIGPAC (Sistema Oficial Español)
```javascript
// URLs base configuradas en analysis_real.js
const SIGPAC_WMS = "https://www.ign.es/wms-inspire/pnoa-ma"
const SIGPAC_WFS = "https://servicios.idee.es/wfs-inspire/ocupacion-suelo"

// Capas disponibles:
- AU.Sigpac:recinto → Recintos con códigos uso
- AU.Sigpac:linea_declaracion → Cultivos específicos declarados
- AU.Sigpac:elemento_paisaje → Elementos naturales categorizados
```

### Google Earth Engine
```javascript
// server/index.js - Configuración
const ee = require('@google/earthengine')
ee.initialize(privateKey) → Autenticación con service account

// Dataset utilizado:
GOOGLE/DYNAMICWORLD/V1 → Clasificación uso suelo global
```

### OpenStreetMap
```javascript
// Overpass API para elementos adicionales
const overpassUrl = "https://overpass-api.de/api/interpreter"
// Consultas: agua, carreteras, infraestructuras
```

## 🎨 SISTEMA DE VISUALIZACIÓN

### Leaflet.js - Configuración Principal
```javascript
// web/index.html - Líneas 180-220
const map = L.map('map').setView([40.4168, -3.7038], 6)
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map)
```

### Capas Dinámicas
- **Dynamic World**: Raster desde Google Earth Engine
- **SIGPAC**: WMS layers con estilos personalizados  
- **Marcadores**: Iconos dinámicos con popups HTML complejos
- **Círculos**: Área de análisis configurable

### Sistema de Popups
```javascript
// Popups responsivos con CSS Grid
const popupContent = `
<div style="width: 60vw; max-width: none; min-width: 400px;">
  <h4>Información detallada</h4>
  <div style="display: grid; grid-template-columns: 1fr 1fr;">
    // Contenido estructurado
  </div>
</div>`
```

## 🔄 SISTEMA DE CACHÉ

### Caché de Parcelas SIGPAC
```javascript
// analysis_real.js - Líneas 354-361
const analysisCache = new Map()
const cacheKey = `${lat}_${lng}_${radius}`
if (analysisCache.has(cacheKey)) return cached_data
```

### Caché de Exploración Rápida
```javascript
// web/index.html - Líneas 551-572
let exploracionRapidaCache = {
  center: null,
  radius: null, 
  parcelas: [],
  markers: []
}
```

## 🐛 DEBUGGING Y LOGGING

### Sistema de Logs
```javascript
// analysis_real.js - Líneas 1-50
let analysisLog = []
function logAnalysis(message, data) {
  analysisLog.push({timestamp, message, data})
  console.log(message, data)
}
```

### Exportación de Logs
```javascript
function exportAnalysisLog() {
  // Genera archivo .log descargable con análisis completo
  const blob = new Blob([logContent], {type: 'text/plain'})
  // Descarga automática con timestamp
}
```

## ⚙️ CONFIGURACIÓN Y DESPLIEGUE

### Variables de Entorno Requeridas
```bash
# Google Cloud Platform
GOOGLE_APPLICATION_CREDENTIALS=path/to/service-account.json
GCP_PROJECT_ID=your-project-id

# Earth Engine
EE_PRIVATE_KEY=service-account-private-key
EE_CLIENT_EMAIL=service-account@project.iam.gserviceaccount.com
```

### Instalación Paso a Paso
```bash
# 1. Clonar repositorio
git clone [repo-url]
cd dw_leaflet_app

# 2. Configurar backend
cd server
npm install
cp .private-key.example.json .private-key.json
# Editar .private-key.json con credenciales reales

# 3. Ejecutar servidor
npm start  # Puerto 3000

# 4. Servir frontend
cd ../web
# Usar cualquier servidor HTTP (Live Server, http-server, etc.)
```

### Dependencias Críticas
```json
// server/package.json
{
  "@google/earthengine": "^0.1.374",
  "express": "^4.18.2", 
  "cors": "^2.8.5"
}
```

## 🔒 SEGURIDAD Y MEJORES PRÁCTICAS

### Credenciales
- ❌ NUNCA commitear `.private-key.json`
- ✅ Usar `.gitignore` para archivos sensibles
- ✅ Rotar service accounts periódicamente

### CORS y APIs
```javascript
// server/index.js - Configuración CORS
app.use(cors({
  origin: ['http://localhost:3000', 'http://127.0.0.1:5500'],
  credentials: true
}))
```

### Rate Limiting
- SIGPAC: Máximo 10 req/segundo
- Earth Engine: Límites por proyecto GCP
- Implementar delays entre consultas masivas

## 🚀 OPTIMIZACIONES DE RENDIMIENTO

### Caché Inteligente
- Parcelas SIGPAC: Cache por ubicación+radio
- Marcadores: Reutilización de objetos Leaflet
- Consultas: Batch processing cuando es posible

### Consultas Optimizadas
```javascript
// Bbox independiente del zoom para consistencia
const bbox = [sw.x, sw.y, ne.x, ne.y].join(',')
const url = `${SIGPAC_WMS}?SERVICE=WMS&REQUEST=GetFeatureInfo&BBOX=${bbox}`
```

### Gestión de Memoria
```javascript
// Limpiar marcadores previos
beeMarkers.forEach(marker => map.removeLayer(marker))
beeMarkers.length = 0
```

## 📊 MÉTRICAS Y MONITOREO

### Logs de Análisis
- Tiempo de respuesta por consulta SIGPAC
- Número de parcelas válidas encontradas  
- Tasa de éxito real vs. mostrada
- Errores de conectividad por API

### Indicadores de Calidad
```javascript
// Métricas calculadas automáticamente
const parcelasValidas = parcelas.filter(p => p.valorApicola > 0).length
const tasaExito = (parcelasValidas / totalParcelas * 100).toFixed(1)
```

## 🔧 MANTENIMIENTO Y ACTUALIZACIONES

### Actualizaciones Regulares Requeridas
1. **Credenciales GCP**: Renovar cada 90 días
2. **URLs SIGPAC**: Verificar endpoints anuales
3. **Códigos cultivo**: Actualizar según campañas PAC
4. **Índices florales**: Ajustar por cambio climático

### Monitoreo de APIs Externas
- SIGPAC: Disponibilidad 99.5%
- Earth Engine: Cuotas y límites
- Nominatim: Rate limiting 1 req/segundo

---

**⚠️ IMPORTANTE**: Esta documentación debe actualizarse con cada cambio significativo en el código. Mantener sincronizada con la implementación real.
