# RF-MAA017-008: Indicadores HSE

## Informacion General

| Atributo | Valor |
|----------|-------|
| **Codigo** | RF-MAA017-008 |
| **Nombre** | Indicadores HSE |
| **Modulo** | MAA-017 Seguridad HSE |
| **Prioridad** | P1 - Alta |
| **Complejidad** | Media |

## Descripcion

El sistema debe calcular, visualizar y analizar indicadores clave de desempeno (KPIs) en seguridad, salud ocupacional y medio ambiente. Incluye indicadores reactivos (accidentabilidad) y proactivos (cumplimiento de actividades), dashboards ejecutivos, tendencias historicas y comparativos entre obras.

## Requisitos Funcionales

### RF-MAA017-008.1: Indicadores de Accidentabilidad (Reactivos)

- **LTIR** (Lost Time Incident Rate):
  - Formula: (Accidentes con tiempo perdido x 200,000) / Horas trabajadas
  - Meta tipica: < 1.0
- **TRIR** (Total Recordable Incident Rate):
  - Formula: (Total incidentes registrables x 200,000) / Horas trabajadas
  - Meta tipica: < 3.0
- **Indice de Frecuencia (IF)**:
  - Formula: (Accidentes x 1,000,000) / Horas trabajadas
- **Indice de Gravedad (IG)**:
  - Formula: (Dias perdidos x 1,000,000) / Horas trabajadas
- **Dias sin accidentes**:
  - Contador desde ultimo accidente incapacitante
- **Near Miss Rate**:
  - Formula: (Casi-accidentes x 200,000) / Horas trabajadas
- Calcular por periodo: diario, semanal, mensual, anual
- Calcular por obra, division, empresa

### RF-MAA017-008.2: Indicadores Proactivos

- **Cumplimiento de capacitacion**:
  - Formula: Trabajadores capacitados / Total trabajadores x 100
  - Meta: > 95%
- **Cumplimiento de inspecciones**:
  - Formula: Inspecciones realizadas / Inspecciones programadas x 100
  - Meta: > 90%
- **Cierre de hallazgos**:
  - Formula: Hallazgos cerrados / Total hallazgos x 100
  - Tiempo promedio de cierre
- **Cumplimiento EPP**:
  - Formula: Personal con EPP completo / Total personal x 100
  - Meta: 100%
- **Recorridos de comision**:
  - Formula: Recorridos realizados / Recorridos programados x 100
- **Permisos de trabajo emitidos vs rechazados**
- **Cumplimiento normativo STPS**:
  - Porcentaje de cumplimiento de matriz

### RF-MAA017-008.3: Indicadores Ambientales

- **Residuos peligrosos generados** (toneladas/mes)
- **Tasa de reciclaje**:
  - Formula: Residuos reciclados / Total residuos x 100
- **Manifiestos emitidos en tiempo**
- **Quejas ambientales**:
  - Numero por periodo
  - Tiempo de respuesta promedio
- **Cumplimiento ambiental**:
  - Porcentaje de requisitos SEMARNAT

### RF-MAA017-008.4: Dashboard Ejecutivo

- Vista general de todos los KPIs
- Semaforos de cumplimiento (verde, amarillo, rojo)
- Graficas de tendencia temporal
- Comparativo entre obras
- Comparativo vs meta
- Ranking de obras por desempeno
- Drill-down por indicador
- Filtros por periodo y obra

### RF-MAA017-008.5: Analisis y Tendencias

- Tendencia historica por indicador
- Proyeccion a fin de periodo
- Identificacion de patrones
- Analisis de correlacion:
  - Capacitacion vs accidentes
  - Inspecciones vs hallazgos
  - Cumplimiento vs incidentes
- Alertas de desviacion de meta
- Benchmarking interno

### RF-MAA017-008.6: Reportes Periodicos

- Reporte semanal de seguridad
- Reporte mensual HSE ejecutivo
- Reporte trimestral de indicadores
- Informe anual de desempeno
- Exportar en PDF, Excel, PowerPoint
- Envio automatico programado
- Personalizacion de contenido

## Reglas de Negocio

1. Horas trabajadas se obtienen de sistema de asistencia
2. LTIR y TRIR se calculan con base 200,000 horas (100 trabajadores x 50 semanas x 40 horas)
3. Un accidente incapacitante reinicia contador de dias sin accidentes
4. Metas deben definirse por tipo de obra y tamano
5. Indicadores se recalculan cada 24 horas automaticamente
6. Alertas se envian cuando indicador supera meta en 10%
7. Solo incidentes cerrados se consideran para calculos
8. Historico debe mantenerse minimo 5 anos

## Criterios de Aceptacion

- [ ] LTIR y TRIR calculados correctamente segun formula OSHA
- [ ] Dashboard muestra todos los indicadores principales
- [ ] Semaforos cambian segun umbrales configurados
- [ ] Graficas de tendencia muestran 12 meses
- [ ] Comparativo entre obras funcional
- [ ] Drill-down permite ver detalle de cada indicador
- [ ] Reportes exportables en PDF y Excel
- [ ] Alertas automaticas configuradas
- [ ] Datos refrescados cada 24 horas

## Modelo de Datos

### Tabla: hse.indicadores_config
```
- id: UUID PK
- tenant_id: UUID FK
- codigo: VARCHAR(20) UNIQUE
- nombre: VARCHAR(200)
- descripcion: TEXT
- formula: TEXT
- unidad: VARCHAR(50)
- tipo: ENUM(reactivo, proactivo, ambiental)
- meta_global: DECIMAL(10,4)
- umbral_verde: DECIMAL(10,4)
- umbral_amarillo: DECIMAL(10,4)
- umbral_rojo: DECIMAL(10,4)
- frecuencia_calculo: ENUM(diario, semanal, mensual)
- activo: BOOLEAN DEFAULT true
- created_at: TIMESTAMPTZ
```

### Tabla: hse.indicadores_meta_obra
```
- id: UUID PK
- indicador_id: UUID FK
- fraccionamiento_id: UUID FK
- anio: INTEGER
- meta: DECIMAL(10,4)
- created_at: TIMESTAMPTZ
- updated_at: TIMESTAMPTZ
```

### Tabla: hse.indicadores_valores
```
- id: UUID PK
- tenant_id: UUID FK
- indicador_id: UUID FK
- fraccionamiento_id: UUID FK (null para empresa)
- periodo_tipo: ENUM(diario, semanal, mensual, anual)
- periodo_fecha: DATE
- valor: DECIMAL(15,4)
- numerador: DECIMAL(15,4)
- denominador: DECIMAL(15,4)
- estado: ENUM(verde, amarillo, rojo)
- calculado_at: TIMESTAMPTZ
- created_at: TIMESTAMPTZ
```

### Tabla: hse.horas_trabajadas
```
- id: UUID PK
- tenant_id: UUID FK
- fraccionamiento_id: UUID FK
- fecha: DATE
- horas_totales: DECIMAL(12,2)
- trabajadores_promedio: INTEGER
- fuente: ENUM(asistencia, manual)
- created_at: TIMESTAMPTZ
- updated_at: TIMESTAMPTZ
```

### Tabla: hse.dias_sin_accidente
```
- id: UUID PK
- tenant_id: UUID FK
- fraccionamiento_id: UUID FK
- fecha_inicio_conteo: DATE
- dias_acumulados: INTEGER
- record_historico: INTEGER
- ultimo_incidente_id: UUID FK
- updated_at: TIMESTAMPTZ
```

### Tabla: hse.reportes_programados
```
- id: UUID PK
- tenant_id: UUID FK
- nombre: VARCHAR(200)
- tipo_reporte: ENUM(semanal, mensual, trimestral, anual)
- indicadores: UUID[]
- fraccionamientos: UUID[]
- destinatarios: VARCHAR[]
- dia_envio: INTEGER
- hora_envio: TIME
- formato: ENUM(pdf, excel, ambos)
- activo: BOOLEAN DEFAULT true
- ultimo_envio: TIMESTAMPTZ
- created_at: TIMESTAMPTZ
```

### Tabla: hse.alertas_indicadores
```
- id: UUID PK
- tenant_id: UUID FK
- indicador_id: UUID FK
- fraccionamiento_id: UUID FK
- tipo_alerta: ENUM(meta_superada, tendencia_negativa, sin_datos)
- mensaje: TEXT
- valor_actual: DECIMAL(10,4)
- valor_meta: DECIMAL(10,4)
- leida: BOOLEAN DEFAULT false
- fecha_alerta: TIMESTAMPTZ
- created_at: TIMESTAMPTZ
```

## Casos de Uso

### CU-MAA017-008.1: Consultar Dashboard de Indicadores

**Actor**: Gerente de Obra / Director HSE
**Precondicion**: Datos de periodos anteriores disponibles

**Flujo Principal**:
1. Usuario accede a dashboard de indicadores
2. Sistema muestra vista general de KPIs
3. Usuario visualiza semaforos de cumplimiento
4. Usuario puede filtrar por:
   - Periodo (mes, trimestre, ano)
   - Obra/fraccionamiento
   - Tipo de indicador
5. Sistema actualiza graficas segun filtros
6. Usuario selecciona indicador para drill-down
7. Sistema muestra detalle y tendencia
8. Usuario puede exportar vista actual

### CU-MAA017-008.2: Analizar Tendencia de Accidentabilidad

**Actor**: Director HSE / Gerente General
**Precondicion**: Historico de al menos 6 meses

**Flujo Principal**:
1. Usuario accede a seccion de analisis
2. Usuario selecciona indicador (ej: LTIR)
3. Sistema muestra grafica de tendencia 12 meses
4. Usuario puede comparar:
   - Vs periodo anterior
   - Vs meta
   - Entre obras
5. Sistema identifica patron (mejora/empeora)
6. Sistema muestra correlaciones relevantes
7. Usuario genera informe de analisis
8. Sistema exporta con comentarios

### CU-MAA017-008.3: Configurar Reporte Automatico

**Actor**: Coordinador HSE
**Precondicion**: Indicadores configurados

**Flujo Principal**:
1. Coordinador accede a configuracion de reportes
2. Selecciona tipo de reporte (semanal/mensual)
3. Selecciona indicadores a incluir
4. Selecciona obras a reportar
5. Ingresa destinatarios (emails)
6. Define dia y hora de envio
7. Sistema programa envio automatico
8. Sistema envia reporte en fecha/hora

### CU-MAA017-008.4: Actualizar Horas Trabajadas

**Actor**: Sistema / Administrador
**Precondicion**: Sistema de asistencia integrado

**Flujo Principal**:
1. Sistema ejecuta tarea programada diaria
2. Sistema consulta horas de asistencia por obra
3. Sistema calcula total de horas del dia
4. Sistema actualiza tabla de horas trabajadas
5. Sistema recalcula indicadores afectados
6. Sistema evalua cumplimiento de metas
7. Si hay desviacion, sistema genera alerta
8. Sistema notifica a responsables

## Mockups

### Pantalla: Dashboard Principal HSE
```
+------------------------------------------------------------------+
| DASHBOARD HSE                          Periodo: [Dic 2025 v]     |
| Obra: [Todas v]                                                   |
+------------------------------------------------------------------+
| INDICADORES REACTIVOS                                             |
+------------------------------------------------------------------+
|  +----------+   +----------+   +----------+   +----------+       |
|  |   0.45   |   |   1.85   |   |   156    |   |   23     |      |
|  |   LTIR   |   |   TRIR   |   |   Dias   |   | Near Miss|      |
|  | Meta:<1.0|   | Meta:<3.0|   |Sin Accid |   |          |      |
|  |  [VERDE] |   | [VERDE]  |   |  [META]  |   |          |      |
|  +----------+   +----------+   +----------+   +----------+       |
+------------------------------------------------------------------+
| TENDENCIA LTIR (12 meses)                                        |
|  1.5 |                                                           |
|  1.0 |----*----*----*----*----*----*----*----*----*---- Meta    |
|  0.5 |         *    *    *    *    *    *    *    *    |        |
|  0.0 +---+----+----+----+----+----+----+----+----+----+---      |
|      Ene Feb  Mar  Abr  May  Jun  Jul  Ago  Sep  Oct  Nov  Dic  |
+------------------------------------------------------------------+
| INDICADORES PROACTIVOS                                           |
+------------------------------------------------------------------+
|  Capacitacion:  ██████████████████░░  92%  [AMARILLO]           |
|  Inspecciones:  █████████████████████  98%  [VERDE]             |
|  Hallazgos:     ████████████████░░░░  78%  [ROJO]               |
|  EPP Completo:  █████████████████████ 100%  [VERDE]             |
+------------------------------------------------------------------+
| COMPARATIVO POR OBRA                                             |
+------------------------------------------------------------------+
| Obra                | LTIR  | TRIR  | Capacit | Inspec          |
+------------------------------------------------------------------+
| Residencial Norte   | 0.32  | 1.45  |   95%   |  100%           |
| Torres del Valle    | 0.58  | 2.10  |   88%   |   92%           |
| Industrial Poniente | 0.45  | 1.90  |   91%   |   98%           |
+------------------------------------------------------------------+
| [Exportar PDF]  [Exportar Excel]  [Enviar por Email]            |
+------------------------------------------------------------------+
```

### Pantalla: Detalle de Indicador
```
+------------------------------------------------------------------+
| DETALLE: Lost Time Incident Rate (LTIR)                          |
+------------------------------------------------------------------+
| Formula: (Accidentes incapacitantes x 200,000) / Horas trabajadas|
| Meta: < 1.0                                                       |
+------------------------------------------------------------------+
| VALOR ACTUAL: 0.45                                               |
| Estado: [VERDE] Cumple meta                                      |
+------------------------------------------------------------------+
| DATOS DEL CALCULO (Diciembre 2025)                               |
| Accidentes incapacitantes: 2                                     |
| Horas trabajadas: 890,000                                        |
| Calculo: (2 x 200,000) / 890,000 = 0.45                         |
+------------------------------------------------------------------+
| TENDENCIA ANUAL                                                  |
|                                                                  |
|  1.2 |    *                                                     |
|  1.0 |----*----*---------------------------------------- Meta   |
|  0.8 |         *                                                |
|  0.6 |              *    *                                      |
|  0.4 |                        *    *    *    *    *    *        |
|  0.2 |                                                          |
|  0.0 +---+----+----+----+----+----+----+----+----+----+---     |
|      Ene Feb  Mar  Abr  May  Jun  Jul  Ago  Sep  Oct  Nov  Dic |
+------------------------------------------------------------------+
| PROYECCION FIN DE ANO: 0.52 (Cumple meta)                       |
+------------------------------------------------------------------+
| CORRELACIONES DETECTADAS                                         |
| - Aumento de capacitacion = Reduccion 15% en LTIR               |
| - Obras con >95% inspeccion tienen LTIR 30% menor               |
+------------------------------------------------------------------+
| [Volver al Dashboard]  [Exportar Analisis]                      |
+------------------------------------------------------------------+
```

### Pantalla: Configuracion de Reportes
```
+--------------------------------------------------+
| CONFIGURAR REPORTE AUTOMATICO                    |
+--------------------------------------------------+
| Nombre: [Reporte Mensual HSE Ejecutivo____]     |
|                                                  |
| Tipo: ( ) Semanal (x) Mensual ( ) Trimestral    |
|                                                  |
| Dia de envio: [Primer dia habil v]              |
| Hora: [08:00 v]                                 |
+--------------------------------------------------+
| INDICADORES A INCLUIR                            |
| [✓] LTIR                                        |
| [✓] TRIR                                        |
| [✓] Dias sin accidente                          |
| [✓] Cumplimiento capacitacion                   |
| [✓] Cumplimiento inspecciones                   |
| [ ] Cierre de hallazgos                         |
| [✓] Indicadores ambientales                     |
+--------------------------------------------------+
| OBRAS A REPORTAR                                 |
| [✓] Residencial Norte                           |
| [✓] Torres del Valle                            |
| [✓] Industrial Poniente                         |
| [ ] Comercial Centro (En pausa)                 |
+--------------------------------------------------+
| DESTINATARIOS                                    |
| [+ Agregar email]                               |
| - director@empresa.com                          |
| - gerente.hse@empresa.com                       |
| - gerente.ops@empresa.com                       |
+--------------------------------------------------+
| Formato: [✓] PDF  [✓] Excel                     |
+--------------------------------------------------+
| [Cancelar]  [Vista Previa]  [Guardar]           |
+--------------------------------------------------+
```

## Especificaciones Tecnicas Relacionadas

- ET-MAA017-DB-001: Schema HSE Database
- ET-MAA017-BE-012: KPI Calculation Service
- ET-MAA017-BE-013: Report Generation Service
- ET-MAA017-FE-019: HSE Dashboard
- ET-MAA017-FE-020: Indicator Detail View
- ET-MAA017-FE-021: Report Configuration

## User Stories Relacionadas

- US-MAA017-009: Consultar indicadores HSE
- US-MAA017-029: Analizar tendencia de accidentabilidad
- US-MAA017-030: Comparar desempeno entre obras
- US-MAA017-031: Configurar reporte automatico
- US-MAA017-032: Recibir alertas de desviacion

## Integraciones

### Internas
- RF-MAA017-001: Datos de incidentes para calculo
- RF-MAA017-002: Datos de capacitaciones
- RF-MAA017-003: Datos de inspecciones y hallazgos
- RF-MAA017-004: Datos de EPP
- RF-MAA017-006: Datos ambientales
- MAI-007: Horas trabajadas de asistencia

### Externas
- Email: Envio de reportes automaticos
- BI Tools: Exportacion para analisis avanzado (opcional)

---

**Autor**: Requirements-Analyst
**Fecha**: 2025-12-06
**Version**: 1.0.0
