# Implementación de Cálculos Forestales - Sistema de Inventario Forestal Guatemala

## Resumen

Se ha implementado completamente el sistema de cálculos forestales automáticos según los requisitos 9.1-9.5 del proyecto. El sistema incluye:

- ✅ Clase ForestCalculations con fórmulas de Área Basal y Volumen
- ✅ Endpoints para cálculos automáticos por rodal
- ✅ Cálculo de promedios (DAP, altura) y conteo de árboles
- ✅ Funcionalidad de exportación a CSV con formato INAB
- ✅ ReportController para generar reportes estructurados

## Archivos Implementados

### 1. `api/utils/ForestCalculations.php`
Clase principal con todas las fórmulas forestales:

**Métodos principales:**
- `calcularAreaBasal($registros, $areaRodal)` - Calcula área basal en m²/ha
- `calcularVolumen($registros, $areaRodal)` - Calcula volumen en m³/ha
- `contarArboles($registros)` - Cuenta total de árboles
- `calcularDAPPromedio($registros)` - Calcula DAP promedio en cm
- `calcularAlturaPromedio($registros)` - Calcula altura promedio en m
- `calcularMetricasCompletas($registros, $areaRodal)` - Todas las métricas
- `generarDatosCSV($registros, $rodalInfo, $proyectoInfo)` - Datos para CSV

### 2. `api/controllers/ReportController.php`
Controlador para manejar endpoints de reportes:

**Métodos principales:**
- `getCalculationsByRodal($rodalId)` - GET /rodales/{id}/calculations
- `exportRodalToCSV($rodalId)` - GET /rodales/{id}/export-csv
- `getProjectSummary($projectId)` - GET /projects/{id}/summary
- `refreshCalculations($rodalId)` - POST /calculations/refresh/{rodalId}

### 3. `api/routes/reports.php`
Rutas para los endpoints de reportes con autenticación y autorización.

### 4. Actualizaciones en modelos existentes
- `FieldData.php` - Agregado método `getByRodalId()`
- `Rodal.php` - Agregados métodos `getById()` y `getByProjectId()`
- `Project.php` - Agregado método `getById()`

## Fórmulas Forestales Implementadas

### 1. Área Basal (m²/ha)
```php
foreach ($registros as $registro) {
    $radio = $registro['dap_cm'] / 2 / 100; // convertir a metros
    $areaBasalArbol = pi() * pow($radio, 2);
    $sumaAreaBasal += $areaBasalArbol;
}
return round($sumaAreaBasal / $areaRodal, 2);
```

### 2. Volumen (m³/ha)
```php
foreach ($registros as $registro) {
    $areaBasalArbol = pi() * pow(($registro['dap_cm'] / 2 / 100), 2);
    $volumenArbol = $areaBasalArbol * $registro['altura_m'] * 0.7; // Factor de forma
    $volumenTotal += $volumenArbol;
}
return round($volumenTotal / $areaRodal, 2);
```

### 3. Promedios
- **DAP Promedio**: Suma de todos los DAP / número de árboles
- **Altura Promedio**: Suma de todas las alturas / número de árboles

## Endpoints de API Implementados

### 1. GET /api/rodales/{id}/calculations
Obtiene cálculos automáticos para un rodal específico.

**Respuesta:**
```json
{
  "rodal_id": 1,
  "nombre_rodal": "Rodal Norte",
  "area_ha": 2.5,
  "fecha_calculo": "2024-01-15 10:30:00",
  "metricas": {
    "conteo_arboles": 125,
    "dap_promedio": 28.5,
    "altura_promedio": 16.2,
    "area_basal": 15.8,
    "volumen": 180.5,
    "area_rodal": 2.5
  },
  "total_registros": 125
}
```

### 2. GET /api/rodales/{id}/export-csv
Exporta datos del rodal a formato CSV compatible con INAB.

**Características:**
- Headers HTTP para descarga de archivo
- Formato UTF-8 con BOM
- Estructura similar a cuadros resumen de INAB
- Incluye información del proyecto, rodal y métricas

### 3. GET /api/projects/{id}/summary
Obtiene resumen completo del proyecto con todos sus rodales.

**Respuesta:**
```json
{
  "proyecto": { /* datos del proyecto */ },
  "fecha_reporte": "2024-01-15 10:30:00",
  "totales_proyecto": {
    "total_arboles": 450,
    "area_total": 8.5,
    "area_basal_total": 134.2,
    "volumen_total": 1532.8,
    "area_basal_promedio": 15.8,
    "volumen_promedio": 180.3
  },
  "rodales": [ /* array de rodales con métricas */ ],
  "total_rodales": 4
}
```

### 4. POST /api/calculations/refresh/{rodalId}
Actualiza cálculos después de sincronización de nuevos datos.

## Formato CSV Generado

El CSV incluye las siguientes secciones:

1. **Encabezado**: Información del sistema e INAB
2. **Información del Proyecto**: Datos básicos del proyecto
3. **Información del Rodal**: Nombre y área
4. **Resumen de Métricas**: Todas las métricas calculadas
5. **Detalle de Registros**: Datos individuales de cada árbol

## Seguridad y Permisos

- Todos los endpoints requieren autenticación JWT
- Solo usuarios con rol "Administrador" o "Regente" pueden acceder
- Validación de existencia de rodales y proyectos
- Manejo de errores con códigos HTTP apropiados

## Pruebas

### Archivos de Prueba Creados:
1. `test_forest_calculations.php` - Prueba las fórmulas de cálculo
2. `test_reports_api.php` - Prueba los endpoints de API

### Para ejecutar las pruebas:
```bash
# Probar cálculos forestales
php test_forest_calculations.php

# Probar API de reportes (requiere servidor configurado)
php test_reports_api.php
```

## Cumplimiento de Requisitos

### ✅ Requisito 9.1: Cálculos automáticos
- Conteo de árboles, DAP promedio, Altura promedio implementados
- Cálculos se actualizan automáticamente al visualizar datos

### ✅ Requisito 9.2: Métricas forestales
- Área Basal (m²/ha) y Volumen (m³/ha) implementados
- Fórmulas basadas en estándares forestales

### ✅ Requisito 9.3: Exportación CSV
- Archivo CSV con datos estructurados
- Formato compatible con INAB

### ✅ Requisito 9.4: Formato INAB
- CSV similar a cuadros resumen de plan de manejo
- Incluye toda la información requerida

### ✅ Requisito 9.5: Actualización automática
- Cálculos se actualizan al sincronizar nuevos datos
- Endpoint específico para refrescar cálculos

## Integración con el Sistema

Los cálculos forestales están completamente integrados con:

- **Sistema de autenticación**: Requiere login y permisos
- **Base de datos MySQL**: Lee datos de `datos_campo`, `rodales`, `proyectos`
- **API REST**: Endpoints RESTful estándar
- **Sincronización**: Se actualiza automáticamente con nuevos datos

## Próximos Pasos

El sistema de cálculos forestales está completo y listo para:

1. **Integración frontend**: Los endpoints están listos para ser consumidos
2. **Pruebas en producción**: Con datos reales de inventarios
3. **Optimizaciones**: Si se requiere mejor rendimiento con grandes volúmenes

## Notas Técnicas

- **Factor de forma**: Se usa 0.7 como factor estándar para cálculo de volumen
- **Precisión**: Todos los cálculos se redondean a 2 decimales
- **Validación**: Se valida existencia de rodales y proyectos antes de calcular
- **Rendimiento**: Los cálculos se realizan en tiempo real, optimizar si es necesario

La implementación cumple completamente con los requisitos del sistema y está lista para uso en producción.