# HR Efficiency Module

## Descripción

El módulo `hr_efficiency` permite llevar un registro de la eficiencia de los empleados comparando las horas planeadas vs las horas realmente trabajadas. Proporciona análisis mensuales detallados que incluyen:

- **Horas disponibles** (considerando vacaciones y tiempo libre)
- **Horas planeadas** (desde el módulo de planeación)
- **Horas planeadas en proyectos facturables**
- **Horas registradas en proyectos facturables**
- **Horas planeadas en proyectos no facturables**
- **Horas registradas en proyectos no facturables**

## Características

### 🔄 **Cálculo Automático**
- Ejecución semanal automática para los últimos 3 meses y próximos 6 meses
- Cron job configurado para ejecutarse cada semana
- Actualización automática de registros existentes

### 🛠️ **Cálculo Manual**
- Wizard para ejecución manual del cálculo
- Selección de período personalizado
- Filtrado por empleados específicos
- Resultados detallados del proceso

### 📊 **Reportes y Análisis**
- Vista de lista con indicadores visuales de eficiencia
- Reportes pivot y gráficos para análisis
- **Indicadores Configurables**: Sistema flexible de indicadores con fórmulas y ponderaciones
- Filtros por indicadores (Good Planning, Good Time Tracking, High Overall Efficiency)
- Filtros por tipo de proyecto (facturable, no facturable)
- Filtros de meses dinámicos (últimos 2, actual, próximos 2)
- Agrupación por empleado, mes, departamento

### 📈 **Seguimiento Histórico Inteligente**
- Nuevos registros se crean **solo cuando hay cambios** en los datos
- Registros anteriores se archivan automáticamente (campo `active = False`)
- Campo `calculation_date` para rastrear cuándo se realizó cada cálculo
- Permite ver la evolución de la eficiencia a lo largo del tiempo
- Solo los registros más recientes están activos para evitar duplicados

### 🔗 **Integración Completa**
- **Planning**: Extrae horas planeadas de `planning.slot`
- **Timesheets**: Obtiene horas reales de `account.analytic.line`
- **Projects**: Distingue entre proyectos facturables y no facturables
- **Holidays**: Considera vacaciones y tiempo libre en el cálculo de disponibilidad

### ⚙️ **Indicadores Configurables**
- **Indicador 1 - Planeación**: Al menos 90% del tiempo disponible debe estar planeado
- **Indicador 2 - Tiempo Registrado**: Al menos 90% del tiempo planeado debe estar registrado
- **Fórmulas Personalizables**: Cada indicador puede usar fórmulas con variables de eficiencia
- **Ponderaciones**: Cada indicador tiene un peso en el cálculo de eficiencia general
- **Umbrales de Color**: Configuración de colores para diferentes niveles de rendimiento
- **Gestión desde Planning**: Configuración disponible en Planning → Settings → Efficiency Indicators

## Instalación

1. Copiar el módulo a `/extra-addons/custom/hr_efficiency`
2. Actualizar la lista de módulos en Odoo
3. Instalar el módulo "HR Efficiency"

## Uso

### Acceso al Módulo

El módulo se puede acceder desde:
- **Menú HR**: Employees → Efficiency
- **Menú Planning**: Planning → Reporting → Efficiency

### Cálculo Manual

1. Ir a **Employees → Efficiency → Calculate Efficiency**
2. Configurar el período (formato: YYYY-MM)
3. Seleccionar empleados (opcional, por defecto todos)
4. Ejecutar el cálculo
5. Revisar resultados y acceder a los registros

### Configuración de Indicadores

#### Acceso a la Configuración
1. Ir a **Planning → Settings → Efficiency Indicators**
2. Aquí puedes gestionar todos los indicadores de eficiencia

#### Indicadores por Defecto
- **Planning Efficiency**: `(planned_hours / available_hours) * 100`
  - Objetivo: 90%
  - Peso: 50%
  - Mide qué tan bien se planea el tiempo disponible

- **Time Tracking Efficiency**: `((actual_billable_hours + actual_non_billable_hours) / planned_hours) * 100`
  - Objetivo: 90%
  - Peso: 50%
  - Mide qué tan bien se registra el tiempo planeado

#### Variables Disponibles en Fórmulas
- `available_hours`: Horas disponibles
- `planned_hours`: Horas planeadas totales
- `planned_billable_hours`: Horas planeadas en proyectos facturables
- `planned_non_billable_hours`: Horas planeadas en proyectos no facturables
- `actual_billable_hours`: Horas registradas en proyectos facturables
- `actual_non_billable_hours`: Horas registradas en proyectos no facturables

### Visualización de Datos

#### Vista de Lista
- Muestra todos los registros de eficiencia
- Indicadores visuales:
  - 🟢 Verde: Eficiencia ≥ 90%
  - 🟡 Amarillo: Eficiencia 70-89%
  - 🔴 Rojo: Eficiencia < 70%

#### Filtros Disponibles
- **Filtros de Indicadores**:
  - Good Planning (≥ 90%)
  - Good Time Tracking (≥ 90%)
  - High Overall Efficiency (≥ 90%)

- **Filtros de Tipo de Proyecto**:
  - Proyectos Facturables
  - Proyectos No Facturables

- **Filtros de Fecha** (similar a ventas):
  - **Meses**: abril, mayo, junio, julio, agosto (por defecto)
  - **Trimestres**: Trimestre 1, 2, 3, 4
  - **Años**: 2023, 2024, 2025

- **Filtros de Estado**:
  - Archivado
  - No Archivado

#### Reportes
- **Efficiency Analysis**: Reportes pivot y gráficos
- Agrupación por mes, empleado, departamento
- Métricas de eficiencia y utilización

## Estructura del Módulo

```
hr_efficiency/
├── __init__.py
├── __manifest__.py
├── models/
│   ├── __init__.py
│   └── hr_efficiency.py
├── wizard/
│   ├── __init__.py
│   ├── hr_efficiency_calculation_wizard.py
│   └── hr_efficiency_calculation_wizard_views.xml
├── views/
│   ├── hr_efficiency_views.xml
│   └── planning_views.xml
├── report/
│   ├── __init__.py
│   ├── hr_efficiency_report.py
│   └── hr_efficiency_report_views.xml
├── security/
│   └── ir.model.access.csv
├── data/
│   └── hr_efficiency_cron.xml
└── README.md
```

## Modelos

### hr.efficiency
Modelo principal que almacena los registros de eficiencia mensual por empleado.

**Campos principales:**
- `month_year`: Mes y año (formato: YYYY-MM)
- `employee_id`: Empleado
- `calculation_date`: Fecha y hora cuando se realizó el cálculo (para seguimiento histórico)
- `available_hours`: Horas disponibles
- `planned_hours`: Horas planeadas totales
- `planned_billable_hours`: Horas planeadas en proyectos facturables
- `planned_non_billable_hours`: Horas planeadas en proyectos no facturables
- `actual_billable_hours`: Horas reales en proyectos facturables
- `actual_non_billable_hours`: Horas reales en proyectos no facturables
- `efficiency_rate`: Porcentaje de eficiencia general
- `billable_efficiency_rate`: Porcentaje de eficiencia en proyectos facturables

### hr.efficiency.calculation.wizard
Wizard para ejecutar cálculos manuales de eficiencia.

**Comportamiento de Registros:**
- **Creación inteligente**: Nuevos registros se crean solo cuando hay cambios en los datos
- **Archivo automático**: Registros anteriores se archivan (campo `active = False`) antes de crear nuevos
- **Seguimiento histórico**: Permite ver cómo evolucionan los datos de eficiencia a lo largo del tiempo
- **Sin duplicados activos**: Solo el registro más reciente está activo para cada empleado y mes
- **Timestamp de cálculo**: Cada registro incluye la fecha y hora exacta cuando se realizó el cálculo
Wizard para cálculo manual de eficiencia.

### hr.efficiency.report
Modelo de reporte para análisis y visualización de datos.

## Cálculos

### Horas Disponibles
```python
# Horas totales del calendario del empleado
total_work_hours = employee._list_work_time_per_day(start_date, end_date)

# Restar horas de vacaciones aprobadas
time_off_hours = get_approved_leaves_hours(employee, start_date, end_date)

available_hours = total_work_hours - time_off_hours
```

### Horas Planeadas
```python
# Obtener slots de planning del empleado
planning_slots = env['planning.slot'].search([
    ('employee_id', '=', employee.id),
    ('start_datetime', '>=', start_datetime),
    ('end_datetime', '<=', end_datetime),
    ('state', 'in', ['draft', 'published'])
])

# Separar por tipo de proyecto
for slot in planning_slots:
    if slot.project_id.allow_billable:
        planned_billable += slot.allocated_hours
    else:
        planned_non_billable += slot.allocated_hours
```

### Horas Reales
```python
# Obtener timesheets del empleado (excluyendo vacaciones)
timesheets = env['account.analytic.line'].search([
    ('employee_id', '=', employee.id),
    ('date', '>=', start_date),
    ('date', '<=', end_date),
    ('project_id', '!=', False),
    ('holiday_id', '=', False)  # Excluir timesheets de vacaciones
])

# Separar por tipo de proyecto
for timesheet in timesheets:
    if timesheet.project_id.allow_billable:
        actual_billable += timesheet.unit_amount
    else:
        actual_non_billable += timesheet.unit_amount
```

## Configuración

### Cron Job
El módulo incluye un cron job configurado para ejecutarse semanalmente:
- **Nombre**: HR Efficiency: Calculate Efficiency (Weekly)
- **Frecuencia**: Semanal
- **Prioridad**: 10
- **Método**: `_cron_calculate_efficiency()`

### Permisos
- **Usuarios HR**: Lectura, escritura y creación de registros
- **Managers HR**: Acceso completo incluyendo eliminación
- **Reportes**: Solo lectura para análisis

## Dependencias

- `hr`: Gestión de empleados
- `hr_timesheet`: Timesheets
- `hr_holidays`: Gestión de vacaciones
- `project`: Gestión de proyectos
- `planning`: Planeación de recursos
- `project_timesheet_holidays`: Integración de vacaciones con timesheets

## Notas Técnicas

### Consideraciones de Rendimiento
- El cálculo se ejecuta por empleado y mes para optimizar el rendimiento
- Los registros existentes se actualizan en lugar de crear duplicados
- El cron job está configurado para ejecutarse en horarios de baja actividad

### Integración con Vacaciones
- El módulo considera automáticamente las vacaciones aprobadas
- Excluye timesheets generados automáticamente por vacaciones
- Calcula la disponibilidad real considerando el calendario del empleado

### Proyectos Facturables
- Utiliza el campo `allow_billable` de `project.project`
- Distingue entre proyectos facturables y no facturables
- Permite análisis separado de eficiencia por tipo de proyecto

## Soporte

Para reportar problemas o solicitar mejoras, contactar al equipo de desarrollo.

## Licencia

LGPL-3