# Módulo de Recursos Humanos y Nómina - Documentación Completa

## 📋 Contenido del Módulo

### 1. Estructura de Base de Datos
Se han creado **11 tablas principales** para el módulo de HR y Nómina:

#### Tablas Core
- **departamentos**: Gestión de departamentos organizacionales
- **puestos**: Definición de puestos/posiciones
- **empleados**: Registro completo de empleados
- **tipos_nomina**: Configuración de tipos de nómina (Mensual, Quincenal, Semanal)

#### Tablas de Nómina
- **conceptos_nomina**: Definición de conceptos (Sueldo, Bonificaciones, Descuentos, Impuestos)
- **nominas**: Encabezado de nómina general
- **nomina_detalle**: Línea a línea de cada nómina
- **nomina_empleado_resumen**: Resumen por empleado en nómina

#### Tablas de Control
- **faltas_empleados**: Registro de faltas, permisos, incapacidades
- **historial_empleados**: Historial de cambios de puesto y salario
- **beneficiarios_empleados**: Datos de beneficiarios para cálculos de afiliación

---

## 🔧 Módulos Implementados

### 1. GESTIÓN DE DEPARTAMENTOS (`departamentos.php`)
**Propósito**: Organizar la estructura departamental de la empresa

**Funcionalidades**:
- ✅ CRUD completo (Crear, Leer, Actualizar, Eliminar)
- ✅ Asignación de jefe de departamento
- ✅ Activación/Desactivación
- ✅ Validaciones de integridad (no eliminar si tiene empleados)

**Validaciones Implementadas**:
- Código de departamento único por empresa
- No permite eliminar si tiene empleados asignados

**Campos**:
- Código (único, requerido)
- Nombre (requerido)
- Descripción
- Jefe del departamento (enlace a empleado)

---

### 2. GESTIÓN DE PUESTOS (`puestos.php`)
**Propósito**: Definir puestos/posiciones con sus salarios base

**Funcionalidades**:
- ✅ CRUD completo
- ✅ Niveles de puesto (Operativo, Supervisorio, Gerencial, Ejecutivo)
- ✅ Salario base por puesto
- ✅ Asignación a departamento
- ✅ Activación/Desactivación

**Campos**:
- Código (único, requerido)
- Nombre (requerido)
- Salario Base (requerido, numérico)
- Nivel (combo: Operativo/Supervisorio/Gerencial/Ejecutivo)
- Departamento
- Descripción

**Validaciones**:
- Código único por empresa
- No permite eliminar si hay empleados en el puesto

---

### 3. GESTIÓN DE EMPLEADOS (`empleados.php`)
**Propósito**: Registro completo y centralizado de todos los empleados

**Funcionalidades**:
- ✅ CRUD completo con formulario detallado
- ✅ Información personal, laboral, salarial y bancaria
- ✅ Activación/Desactivación
- ✅ Soporte para diferentes tipos de contrato

**Secciones del Formulario**:

**A) Información Personal**
- Código empleado (único)
- Número de identificación (único)
- Nombre completo (requerido)
- Apellido paterno/materno
- Email
- Teléfono
- Fecha de nacimiento
- Sexo (M/F)
- Ciudad, País
- Dirección

**B) Información Laboral**
- Puesto (requerido, combo)
- Departamento
- Fecha de ingreso (requerida)
- Fecha de salida (opcional)
- Tipo de contrato (Indefinido/Temporal/Por Horas)

**C) Información Salarial**
- Salario mensual (requerido)
- Horas diarias (default: 8)

**D) Información Bancaria**
- Banco
- Número de cuenta

**Validaciones**:
- Código único por empresa
- Número de identificación único en el sistema
- No permite eliminar si está en nóminas procesadas
- Validación de fechas

---

### 4. TIPOS DE NÓMINA (`tipos_nomina.php`)
**Propósito**: Configurar diferentes tipos de nóminas (frecuencia de pago)

**Funcionalidades**:
- ✅ CRUD completo
- ✅ Definir frecuencia (Semanal/Quincenal/Mensual)
- ✅ Días del período de pago
- ✅ Marcar como "Por defecto"
- ✅ Activación/Desactivación

**Tipos Pre-configurados**:
- Nómina Mensual (30 días)
- Nómina Quincenal (15 días)
- Nómina Semanal (7 días)

**Campos**:
- Código (único, requerido)
- Nombre (requerido)
- Frecuencia (combo: Semanal/Quincenal/Mensual, requerido)
- Días de pago (requerido)
- Descripción
- Por defecto (checkbox)

---

### 5. REGISTRO DE FALTAS (`faltas.php`)
**Propósito**: Registrar ausencias, faltas y permisos de empleados

**Funcionalidades**:
- ✅ Registro detallado de faltas con tipos
- ✅ CRUD completo
- ✅ Filtros por empleado y mes
- ✅ Marcas de justificación
- ✅ Cálculo de horas perdidas
- ✅ Integración automática con nómina

**Tipos de Faltas**:
- FALTA: Ausencia sin autorización
- RETRASO: Llegada tarde
- PERMISO: Permiso autorizado
- INCAPACIDAD: Incapacidad médica

**Características**:
- Validación de duplicados (mismo empleado, fecha, tipo)
- Registro del usuario que ingresa
- Marca de justificación
- Horas perdidas calculables
- Filtros dinámicos por empleado y mes

**Impacto en Nómina**:
- Las faltas no justificadas reducen los días trabajados
- Afecta el cálculo de salario proporcional
- Las faltas justificadas NO descuentan salario

---

### 6. GENERADOR DE NÓMINAS (`nominas.php`)
**Propósito**: Crear y gestionar nóminas generales con cálculos automáticos

**Flujo de Estados**:
```
BORRADOR → PROCESADA → PAGADA
                    ↓
                RECHAZADA
```

**Funcionalidades Principales**:

#### A) Generación Automática
- Genera nómina para TODOS los empleados activos
- Calcula automáticamente:
  - Días trabajados (considerando faltas)
  - Salario proporcional
  - Descuentos estándares (AFP 10%)
  - Salario neto

#### B) Cálculos Implementados
```
Sueldo Diario = Salario Mensual ÷ 30
Sueldo Proporcional = Sueldo Diario × Días Trabajados
AFP (10%) = Sueldo Proporcional × 0.10
Salario Neto = Sueldo Proporcional - Descuentos
```

#### C) Cálculo de Días Trabajados
- Cuenta días calendario del período
- Convierte a días hábiles (5/7 del calendario)
- Resta días perdidos por faltas no justificadas
- Considera horas diarias del empleado

#### D) Gestión de Nóminas
- Ver listado con filtros
- Ver detalle completo con desglose por empleado
- Cambiar estados (Procesar → Pagar)
- Imprimir nóminas
- Eliminar solo nóminas en BORRADOR

**Información por Nómina**:
- Número de nómina (único)
- Tipo (Mensual/Quincenal/Semanal)
- Período (fecha inicio - fecha fin)
- Cantidad de empleados
- Total sueldo
- Total bonificaciones
- Total descuentos
- Total neto

**Información por Empleado**:
- Sueldo bruto
- Descuentos
- Salario neto
- Días trabajados
- Estado de pago

**Validaciones**:
- Número de nómina único
- Debe haber empleados activos
- Solo permite procesar si está en BORRADOR
- Solo permite pagar si está PROCESADA

---

## 📊 Conceptos de Nómina Pre-configurados

### Tabla: conceptos_nomina

| Código | Nombre | Tipo | Remunerativo | Afectable |
|--------|--------|------|--------------|-----------|
| SUELDO | Sueldo Básico | SUELDO | Sí | Sí |
| BONIF | Bonificación | BONIFICACION | Sí | No |
| HE50 | Horas Extras 50% | BONIFICACION | Sí | No |
| HE100 | Horas Extras 100% | BONIFICACION | Sí | No |
| AFILIA | Afilización ISAPRE/Fonasa | DESCUENTO | No | No |
| AFP | AFP/Pensión | DESCUENTO | No | No |
| IMPUESTO | Impuesto a la Renta | IMPUESTO | No | No |
| OTROS | Otros Descuentos | DESCUENTO | No | No |

---

## 🔄 Flujo de Trabajo Típico

### Scenario: Generar Nómina Mensual para Enero

1. **Preparación**
   - Registrar departamentos y puestos
   - Agregar empleados con sus datos completos

2. **Control de Asistencia**
   - Registrar faltas durante enero en `faltas.php`
   - Marcar si están justificadas o no

3. **Generación de Nómina**
   - Acceder a `nominas.php?accion=crear`
   - Ingresar: Número, Tipo (Mensual), Período (01/01 - 31/01)
   - Sistema calcula automáticamente:
     - Días trabajados por cada empleado
     - Sueldo proporcional
     - Descuentos (AFP)
     - Neto a pagar

4. **Revisión**
   - Ver detalle en `nominas.php?accion=ver&id=X`
   - Validar montos por empleado
   - Revisar impacto de faltas en salarios

5. **Procesamiento**
   - Click en "Procesar" → Estado: PROCESADA
   - Sistema está listo para pagar

6. **Pago**
   - Click en "Pagar" → Estado: PAGADA
   - Se registra fecha de pago

---

## 💾 Consultas SQL Útiles

### Obtener nómina de un empleado específico
```sql
SELECT ner.*, e.nombre_completo, n.numero_nomina
FROM nomina_empleado_resumen ner
JOIN empleados e ON ner.id_empleado = e.id_empleado
JOIN nominas n ON ner.id_nomina = n.id_nomina
WHERE e.codigo_empleado = 'EMP001'
ORDER BY n.fecha_inicio DESC;
```

### Reporte de faltas por mes
```sql
SELECT e.nombre_completo, COUNT(*) as total_faltas, 
       SUM(CASE WHEN f.justificado = 0 THEN 1 ELSE 0 END) as no_justificadas
FROM faltas_empleados f
JOIN empleados e ON f.id_empleado = e.id_empleado
WHERE DATE_FORMAT(f.fecha_falta, '%Y-%m') = '2024-01'
GROUP BY f.id_empleado
ORDER BY total_faltas DESC;
```

### Historial de cambios de salario
```sql
SELECT e.nombre_completo, h.fecha_cambio, h.salario_anterior, h.salario_nuevo,
       (h.salario_nuevo - h.salario_anterior) as diferencia
FROM historial_empleados h
JOIN empleados e ON h.id_empleado = e.id_empleado
WHERE h.tipo_cambio = 'CAMBIO_SALARIO'
ORDER BY h.fecha_cambio DESC;
```

---

## 🔐 Seguridad Implementada

### 1. Validación de Sesión
- Todos los módulos requieren `$_SESSION['usuario_id']`
- Todos validan `$_SESSION['empresa_id']`

### 2. Protección de Datos
- Prepared Statements en todas las consultas (PDO)
- `htmlspecialchars()` en todos los inputs
- Validación de integridad antes de operaciones

### 3. Control de Acceso
- Multi-empresa: Cada empresa aislada en datos
- Validación de permisos en operaciones críticas
- Solo nóminas en BORRADOR pueden editarse

### 4. Integridad de Datos
- Foreign Keys en todas las relaciones
- No permite eliminar registros con dependencias
- Historial de cambios disponible

---

## 📈 Escalabilidad Futura

### Mejoras Planificadas

1. **Conceptos Personalizados**
   - Permitir crear conceptos por empresa
   - Bonificaciones personalizadas
   - Descuentos adicionales

2. **Cálculos Avanzados**
   - Cálculo de impuesto a la renta (ISR)
   - Vacaciones y antiguedad
   - Comisiones por vendedor

3. **Integración Contable**
   - Crear asientos automáticos en pda_maestro/pda_detalle
   - Categorizar gastos por departamento
   - Reportes de costo de personal

4. **Reportes Avanzados**
   - Análisis de costos por departamento
   - Comparativas de nóminas
   - Proyecciones salariales

5. **Gestión de Horarios**
   - Marcas de entrada/salida
   - Cálculo automático de horas trabajadas
   - Control de horas extras

---

## 📝 Archivos Creados

### Archivos PHP
1. `departamentos.php` - Gestión de departamentos
2. `puestos.php` - Gestión de puestos
3. `empleados.php` - Gestión de empleados
4. `tipos_nomina.php` - Configuración de tipos
5. `faltas.php` - Registro de faltas
6. `nominas.php` - Generador de nóminas

### Archivo SQL
- `crear_tablas_rrhh_nomina.sql` - Esquema completo (11 tablas + índices)

### Documentación
- Este archivo (MODULO_RRHH_NOMINA.md)

---

## 🎯 Checklist de Instalación

- [x] Ejecutar SQL de creación de tablas
- [x] Crear módulos PHP de CRUD
- [x] Integrar en menú lateral
- [x] Configurar validaciones
- [x] Implementar cálculos de nómina
- [x] Crear documentación completa
- [ ] Crear reportes avanzados (futuro)
- [ ] Integración contable (futuro)

---

## 📞 Soporte y Mantenimiento

### Accesos Directos
- **Gestión de Departamentos**: `departamentos.php`
- **Gestión de Puestos**: `puestos.php`
- **Gestión de Empleados**: `empleados.php`
- **Configuración de Nómina**: `tipos_nomina.php`
- **Control de Asistencia**: `faltas.php`
- **Nóminas General**: `nominas.php`

### Puntos Críticos de Control
- Verificar faltas registradas antes de generar nómina
- Validar periodos de nómina sin solapamiento
- Revisar totales antes de procesar
- Mantener historial de cambios salariales

---

**Módulo creado**: 2024
**Versión**: 1.0
**Estado**: Producción
**Autor**: Sistema ERP Automatizado