# 🚀 GUÍA DE INSTALACIÓN - BeeLifeMaps

## 📋 REQUISITOS PREVIOS

### Software Necesario
- **Node.js 18 o superior** - [Descargar aquí](https://nodejs.org/)
- **Navegador web moderno** (Chrome, Firefox, Edge)
- **Editor de código** (VS Code recomendado)

### Cuentas y Servicios
- **Google Cloud Platform** - Cuenta activa con facturación habilitada
- **Google Earth Engine** - Registro como desarrollador

## 🔧 CONFIGURACIÓN PASO A PASO

### PASO 1: Configurar Google Cloud Platform

1. **Crear proyecto GCP**:
   - Ir a [Google Cloud Console](https://console.cloud.google.com/)
   - Crear nuevo proyecto o seleccionar existente
   - Anotar el **Project ID**

2. **Habilitar APIs necesarias**:
   ```bash
   # En Cloud Shell o con gcloud CLI
   gcloud services enable earthengine.googleapis.com
   ```

3. **Crear Service Account**:
   - IAM & Admin → Service Accounts → Create Service Account
   - Nombre: `beelifemaps-service`
   - Roles necesarios:
     - `Earth Engine Resource Viewer`
     - `Earth Engine Resource Writer`

4. **Generar clave JSON**:
   - Seleccionar service account creada
   - Keys → Add Key → Create New Key → JSON
   - **Guardar archivo** como `service-account-key.json`

### PASO 2: Registrar en Earth Engine

1. **Solicitar acceso**:
   - Ir a [Google Earth Engine](https://earthengine.google.com/)
   - Sign Up → Register a new project
   - Seleccionar "Unpaid usage" para desarrollo

2. **Autorizar Service Account**:
   - En Earth Engine Code Editor
   - Ir a Assets → Cloud Projects
   - Añadir service account email como viewer/writer

### PASO 3: Configurar el Proyecto

1. **Clonar/Descargar código**:
   ```bash
   # Si tienes el código en repositorio
   git clone [URL_REPOSITORIO]
   cd dw_leaflet_app
   
   # O crear estructura manualmente
   mkdir dw_leaflet_app
   cd dw_leaflet_app
   mkdir server web
   ```

2. **Configurar backend**:
   ```bash
   cd server
   npm init -y
   npm install @google/earthengine express cors
   ```

3. **Configurar credenciales**:
   ```bash
   # Copiar archivo de ejemplo
   cp .private-key.example.json .private-key.json
   
   # Editar con credenciales reales
   nano .private-key.json
   ```

   Contenido de `.private-key.json`:
   ```json
   {
     "type": "service_account",
     "project_id": "TU_PROJECT_ID",
     "private_key_id": "...",
     "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
     "client_email": "beelifemaps-service@tu-project.iam.gserviceaccount.com",
     "client_id": "...",
     "auth_uri": "https://accounts.google.com/o/oauth2/auth",
     "token_uri": "https://oauth2.googleapis.com/token"
   }
   ```

### PASO 4: Ejecutar la Aplicación

1. **Iniciar servidor backend**:
   ```bash
   cd server
   npm start
   ```
   Debería mostrar: `Servidor ejecutándose en http://localhost:3000`

2. **Servir frontend**:
   ```bash
   cd ../web
   
   # Opción 1: Con Live Server (VS Code)
   # Clic derecho en index.html → Open with Live Server
   
   # Opción 2: Con http-server
   npx http-server -p 8080
   
   # Opción 3: Con Python
   python -m http.server 8080
   ```

3. **Abrir en navegador**:
   - Ir a `http://localhost:8080` (o puerto configurado)
   - La aplicación debería cargar correctamente

## ✅ VERIFICACIÓN DE INSTALACIÓN

### Checklist de Funcionamiento

- [ ] **Servidor backend activo** (puerto 3000)
- [ ] **Frontend servido** (puerto 8080 u otro)
- [ ] **Búsqueda funciona** (prueba con "Madrid")
- [ ] **Capas SIGPAC cargan** (botón "Mostrar SIGPAC")
- [ ] **Dynamic World funciona** (cambiar probabilidad)
- [ ] **Análisis rápido ejecuta** (botón "🐝 Exploración Rápida")
- [ ] **Análisis profundo ejecuta** (botón "🔬 Análisis de Zonas")

### Prueba Completa

1. **Buscar localidad**: "Fresnillo de las Dueñas"
2. **Activar SIGPAC**: Verificar parcelas visibles
3. **Exploración rápida**: Debe mostrar 6 marcadores
4. **Análisis profundo**: Debe completar 4 pasos y mostrar 10 zonas

## 🐛 SOLUCIÓN DE PROBLEMAS

### Error: "Earth Engine authentication failed"
```bash
# Verificar credenciales
cat server/.private-key.json | jq .client_email

# Verificar permisos en Earth Engine
# Ir a https://code.earthengine.google.com/
# Assets → Cloud Projects → Verificar service account
```

### Error: "SIGPAC layers not loading"
```javascript
// Verificar en consola del navegador
// Network tab → Buscar errores 404 o CORS
// URLs SIGPAC pueden cambiar anualmente
```

### Error: "CORS blocked"
```javascript
// Verificar configuración CORS en server/index.js
app.use(cors({
  origin: ['http://localhost:8080', 'http://127.0.0.1:5500'],
  credentials: true
}))
```

### Error: "Module not found"
```bash
# Reinstalar dependencias
cd server
rm -rf node_modules package-lock.json
npm install
```

## 🔒 CONFIGURACIÓN DE SEGURIDAD

### Archivo .gitignore
```gitignore
# Credenciales (NUNCA commitear)
server/.private-key.json
server/service-account-key.json

# Dependencias
node_modules/
package-lock.json

# Logs
*.log
.DS_Store
```

### Variables de Entorno (Producción)
```bash
# Crear archivo .env en server/
GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
GCP_PROJECT_ID=tu-project-id
PORT=3000
NODE_ENV=production
```

## 🌐 DESPLIEGUE EN PRODUCCIÓN

### Backend (Heroku, Railway, etc.)
```bash
# Configurar variables de entorno
heroku config:set GOOGLE_APPLICATION_CREDENTIALS="$(cat service-account.json)"
heroku config:set GCP_PROJECT_ID=tu-project-id

# Deploy
git push heroku main
```

### Frontend (Netlify, Vercel, etc.)
```bash
# Actualizar URLs en código
const API_BASE_URL = 'https://tu-backend.herokuapp.com'

# Deploy estático
npm run build  # Si usas bundler
# O subir directamente archivos web/
```

## 📞 SOPORTE Y MANTENIMIENTO

### Logs y Debugging
```bash
# Ver logs del servidor
tail -f server/logs/app.log

# Debug en navegador
# F12 → Console → Network → Buscar errores
```

### Actualizaciones Regulares
- **Credenciales GCP**: Renovar cada 90 días
- **Dependencias npm**: `npm audit fix` mensual
- **URLs SIGPAC**: Verificar anualmente
- **Códigos cultivos**: Actualizar según campañas PAC

### Contacto Técnico
- **Logs de error**: Exportar desde aplicación
- **Información del sistema**: Navegador, OS, Node.js version
- **Pasos para reproducir**: Descripción detallada

---

**🎯 RESULTADO ESPERADO**: Aplicación completamente funcional con análisis apícola en tiempo real usando datos oficiales SIGPAC y Google Earth Engine.
