# RF-MAA017-002: Control de Capacitaciones

**Épica:** MAA-017 - Seguridad HSE
**Versión:** 1.0
**Fecha:** 2025-12-06
**Responsable:** Requirements-Analyst

---

## 1. Descripción General

Sistema integral para la gestión de capacitaciones de seguridad industrial, salud ocupacional y medio ambiente. Permite programar, ejecutar, registrar asistencia y generar constancias oficiales (DC-3, DC-4) conforme a la normativa STPS.

### Objetivos
- Asegurar que el 100% del personal cuente con capacitación requerida
- Cumplir con normativas STPS (NOM-030, NOM-017, NOM-009)
- Generar constancias DC-3 válidas ante autoridades
- Mantener trazabilidad de competencias del personal

---

## 2. Alcance Funcional

### 2.1 Catálogo de Capacitaciones

**Tipos de Capacitación:**
```
├── Inducción General
│   ├── Inducción empresa (obligatoria día 1)
│   ├── Inducción obra específica
│   └── Inducción subcontratistas
├── Seguridad Industrial
│   ├── Trabajos en altura (NOM-009)
│   ├── Espacios confinados (NOM-033)
│   ├── Trabajo en caliente
│   ├── Manejo de materiales peligrosos
│   ├── Bloqueo y etiquetado (LOTO)
│   └── Uso de EPP (NOM-017)
├── Primeros Auxilios
│   ├── RCP básico
│   ├── Primeros auxilios nivel 1
│   └── Brigadas de emergencia
├── Prevención de Riesgos
│   ├── Identificación de peligros (IPER)
│   ├── Análisis de seguridad en el trabajo (AST)
│   └── Reporte de condiciones inseguras
└── Medio Ambiente
    ├── Manejo de residuos
    ├── Ahorro de agua y energía
    └── Respuesta a derrames
```

**Atributos de Capacitación:**
```
- Código único (CAP-{tipo}-{consecutivo})
- Nombre
- Descripción
- Duración (horas)
- Modalidad: presencial, virtual, mixta
- Vigencia (meses)
- Normativa aplicable (NOM referencia)
- Requiere evaluación: sí/no
- Puntaje mínimo aprobatorio: 0-100
- Requiere práctica: sí/no
- Instructor requerido: interno/externo/certificado
- Costo estimado por persona
- Materiales requeridos
```

### 2.2 Programación de Capacitaciones

**Matriz de Capacitación por Puesto:**
```
┌──────────────────────────────────────────────────────────────────┐
│ Puesto              │ Inducción │ Altura │ EPP │ P.Aux │ Freq   │
├─────────────────────┼───────────┼────────┼─────┼───────┼────────┤
│ Residente de obra   │ ●         │ ●      │ ●   │ ●     │ Anual  │
│ Supervisor          │ ●         │ ●      │ ●   │ ●     │ Anual  │
│ Oficial albañil     │ ●         │ ●      │ ●   │ ○     │ Anual  │
│ Oficial electricista│ ●         │ ●      │ ●   │ ○     │ Anual  │
│ Ayudante general    │ ●         │ ○      │ ●   │ ○     │ Anual  │
│ Operador maquinaria │ ●         │ ○      │ ●   │ ●     │ Anual  │
│ Almacenista         │ ●         │ ○      │ ●   │ ○     │ Anual  │
└──────────────────────────────────────────────────────────────────┘
● Obligatoria   ○ Opcional/Recomendada
```

**Programación de Sesiones:**
```
Sesión de Capacitación:
- ID único
- Capacitación (FK)
- Fraccionamiento/Obra
- Fecha y hora inicio
- Fecha y hora fin
- Lugar (aula, obra, virtual)
- Instructor (interno/externo)
- Cupo máximo
- Cupo disponible
- Estado: programada, en_curso, completada, cancelada
- Costo real
- Observaciones
```

### 2.3 Registro de Asistencia

**Proceso de Registro:**
1. Lista de asistencia digital (tablet/móvil)
2. Firma electrónica del participante
3. Foto de evidencia (opcional)
4. Hora de entrada/salida
5. Validación biométrica (opcional)

**Estados de Participante:**
- Inscrito
- Asistió
- No asistió (justificado/injustificado)
- Aprobado
- Reprobado
- Pendiente evaluación

### 2.4 Evaluación de Conocimientos

**Tipos de Evaluación:**
```
├── Examen teórico
│   ├── Opción múltiple (10-20 preguntas)
│   ├── Verdadero/Falso
│   └── Casos prácticos
├── Evaluación práctica
│   ├── Demostración de habilidades
│   ├── Simulacro
│   └── Checklist de competencias
└── Evaluación combinada
    └── Teoría (60%) + Práctica (40%)
```

**Banco de Preguntas:**
```
Pregunta:
- Capacitación (FK)
- Texto de pregunta
- Tipo: multiple, boolean, open
- Opciones (si aplica)
- Respuesta correcta
- Puntos
- Nivel: básico, intermedio, avanzado
- Activa: sí/no
```

### 2.5 Constancias DC-3

**Formato DC-3 (STPS):**
```
┌────────────────────────────────────────────────────────────────┐
│           CONSTANCIA DE COMPETENCIAS O HABILIDADES LABORALES   │
│                          FORMATO DC-3                          │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│ DATOS DEL TRABAJADOR                                          │
│ Nombre: ________________________________________________      │
│ CURP: __________________________________________________      │
│ Puesto: ________________________________________________      │
│ Empresa: _______________________________________________      │
│                                                                │
│ DATOS DE LA CAPACITACIÓN                                      │
│ Nombre del curso: ______________________________________      │
│ Duración: _______ horas                                       │
│ Período: Del __________ al __________                         │
│ Área temática: _________________________________________      │
│                                                                │
│ DATOS DEL INSTRUCTOR                                          │
│ Nombre: ________________________________________________      │
│ Registro STPS: _________________________________________      │
│                                                                │
│ DATOS DEL REPRESENTANTE LEGAL                                 │
│ Nombre: ________________________________________________      │
│ Cargo: _________________________________________________      │
│                                                                │
│ Lugar y fecha: _________________, a __ de _______ de 20__    │
│                                                                │
│                                                                │
│ _____________________          _____________________           │
│ Firma del Instructor           Firma Rep. Legal               │
│                                                                │
│ Folio: DC3-2025-XXXXX                                         │
└────────────────────────────────────────────────────────────────┘
```

**Generación Automática:**
- Al aprobar capacitación
- Datos pre-llenados del sistema
- Folio único secuencial por año
- PDF firmable electrónicamente
- QR de verificación

### 2.6 Vencimientos y Renovaciones

**Alertas Automáticas:**
```
Días antes de vencimiento → Acción
90 días                   → Notificación preventiva
60 días                   → Alerta a supervisor
30 días                   → Alerta a RRHH + empleado
15 días                   → Escalamiento a gerencia
0 días                    → Bloqueo de acceso a obra (configurable)
```

**Dashboard de Vencimientos:**
```
┌────────────────────────────────────────────────────────────────┐
│ PRÓXIMOS VENCIMIENTOS - Diciembre 2025                        │
├────────────────────────────────────────────────────────────────┤
│ 🔴 Vencidos (5)                                               │
│    • Juan Pérez - Trabajo en altura - Venció 01/12/2025       │
│    • María López - EPP - Venció 28/11/2025                    │
│                                                                │
│ 🟡 Próximos 30 días (12)                                      │
│    • Carlos Ruiz - Primeros auxilios - Vence 15/12/2025       │
│    • Ana García - Espacios confinados - Vence 20/12/2025      │
│                                                                │
│ 🟢 Vigentes (145)                                             │
│    • 95% del personal al día                                  │
└────────────────────────────────────────────────────────────────┘
```

---

## 3. Modelo de Datos

```typescript
// Tabla: hse.capacitaciones (catálogo)
{
  id: UUID,
  tenant_id: UUID,
  code: VARCHAR(20) UNIQUE,
  name: VARCHAR(200),
  description: TEXT,
  duration_hours: DECIMAL(4,1),
  modality: ENUM('presencial', 'virtual', 'mixta'),
  validity_months: INTEGER,
  norm_reference: VARCHAR(50), // NOM-009-STPS-2011
  requires_evaluation: BOOLEAN,
  min_passing_score: INTEGER, // 0-100
  requires_practice: BOOLEAN,
  instructor_type: ENUM('interno', 'externo', 'certificado'),
  estimated_cost: DECIMAL(10,2),
  materials: TEXT,
  is_mandatory: BOOLEAN,
  applicable_positions: TEXT[], // Array de puestos
  created_at: TIMESTAMP,
  created_by: UUID,
  updated_at: TIMESTAMP,
  is_active: BOOLEAN
}

// Tabla: hse.capacitacion_sesiones
{
  id: UUID,
  tenant_id: UUID,
  capacitacion_id: UUID FK,
  fraccionamiento_id: UUID FK,
  session_date: DATE,
  start_time: TIME,
  end_time: TIME,
  location: VARCHAR(200),
  location_type: ENUM('aula', 'obra', 'virtual'),
  instructor_id: UUID, // Puede ser empleado o externo
  instructor_name: VARCHAR(200),
  instructor_stps_registration: VARCHAR(50),
  max_capacity: INTEGER,
  current_enrollment: INTEGER,
  status: ENUM('programada', 'en_curso', 'completada', 'cancelada'),
  actual_cost: DECIMAL(10,2),
  notes: TEXT,
  created_at: TIMESTAMP,
  created_by: UUID
}

// Tabla: hse.capacitacion_asistentes
{
  id: UUID,
  tenant_id: UUID,
  sesion_id: UUID FK,
  employee_id: UUID FK,
  enrollment_date: TIMESTAMP,
  attendance_status: ENUM('inscrito', 'asistio', 'no_asistio', 'justificado'),
  check_in_time: TIMESTAMP,
  check_out_time: TIMESTAMP,
  signature_url: VARCHAR(500),
  photo_url: VARCHAR(500),
  evaluation_score: INTEGER,
  evaluation_status: ENUM('pendiente', 'aprobado', 'reprobado'),
  certificate_number: VARCHAR(30),
  certificate_date: DATE,
  valid_until: DATE,
  notes: TEXT,
  created_at: TIMESTAMP
}

// Tabla: hse.constancias_dc3
{
  id: UUID,
  tenant_id: UUID,
  asistente_id: UUID FK,
  folio: VARCHAR(20) UNIQUE, // DC3-2025-00001
  employee_name: VARCHAR(200),
  employee_curp: VARCHAR(18),
  employee_position: VARCHAR(100),
  course_name: VARCHAR(200),
  course_duration: DECIMAL(4,1),
  course_start_date: DATE,
  course_end_date: DATE,
  thematic_area: VARCHAR(100),
  instructor_name: VARCHAR(200),
  instructor_stps_reg: VARCHAR(50),
  legal_rep_name: VARCHAR(200),
  legal_rep_position: VARCHAR(100),
  issue_place: VARCHAR(100),
  issue_date: DATE,
  pdf_url: VARCHAR(500),
  qr_verification_code: VARCHAR(50),
  is_valid: BOOLEAN,
  invalidation_reason: TEXT,
  created_at: TIMESTAMP,
  created_by: UUID
}

// Tabla: hse.evaluacion_preguntas
{
  id: UUID,
  tenant_id: UUID,
  capacitacion_id: UUID FK,
  question_text: TEXT,
  question_type: ENUM('multiple', 'boolean', 'open'),
  options: JSONB, // [{text, is_correct}, ...]
  correct_answer: TEXT,
  points: INTEGER,
  difficulty: ENUM('basico', 'intermedio', 'avanzado'),
  is_active: BOOLEAN,
  created_at: TIMESTAMP
}

// Tabla: hse.evaluacion_respuestas
{
  id: UUID,
  tenant_id: UUID,
  asistente_id: UUID FK,
  pregunta_id: UUID FK,
  answer_given: TEXT,
  is_correct: BOOLEAN,
  points_earned: INTEGER,
  answered_at: TIMESTAMP
}
```

---

## 4. Casos de Uso

### CU-001: Programar Sesión de Capacitación
**Actor:** Coordinador HSE
**Flujo:**
1. Accede a "Programar Capacitación"
2. Selecciona capacitación del catálogo
3. Define:
   - Obra/Fraccionamiento
   - Fecha y hora
   - Lugar (aula o virtual)
   - Instructor
   - Cupo máximo
4. Sistema valida disponibilidad de instructor
5. Guarda sesión con estado "Programada"
6. Notifica a supervisores de obra

### CU-002: Registrar Asistencia
**Actor:** Instructor / Supervisor
**Flujo:**
1. Abre sesión en tablet
2. Lista de inscritos aparece
3. Por cada asistente:
   - Marca presente/ausente
   - Captura firma digital
   - Registra hora de entrada
4. Al finalizar:
   - Registra hora de salida de todos
   - Captura foto grupal (evidencia)
5. Cierra registro de asistencia

### CU-003: Aplicar Evaluación
**Actor:** Instructor
**Flujo:**
1. Inicia evaluación de sesión
2. Sistema genera examen:
   - Selecciona preguntas aleatorias del banco
   - 10 preguntas de opción múltiple
3. Participantes responden en tablet/móvil
4. Al terminar:
   - Sistema califica automáticamente
   - Muestra resultados
   - Marca aprobados/reprobados
5. Genera constancias DC-3 para aprobados

### CU-004: Generar Constancia DC-3
**Actor:** Sistema (automático)
**Flujo:**
1. Participante aprueba evaluación
2. Sistema genera:
   - Folio único: DC3-2025-00001
   - PDF con datos completos
   - Código QR de verificación
3. Almacena en repositorio
4. Envía por email al participante
5. Notifica a RRHH

### CU-005: Consultar Vencimientos
**Actor:** Gerente RRHH
**Flujo:**
1. Accede a "Dashboard de Capacitación"
2. Visualiza:
   - Capacitaciones vencidas (rojo)
   - Por vencer 30 días (amarillo)
   - Vigentes (verde)
3. Filtra por:
   - Obra
   - Tipo de capacitación
   - Supervisor
4. Exporta reporte Excel
5. Programa sesiones de renovación

---

## 5. Interfaces de Usuario

### Vista: Catálogo de Capacitaciones
```
┌──────────────────────────────────────────────────────────────────┐
│ Catálogo de Capacitaciones                    [+ Nueva] [⚙]     │
├──────────────────────────────────────────────────────────────────┤
│ 🔍 Buscar: [________________________] [🔎]                      │
│ Tipo: [Todos ▼]  Modalidad: [Todos ▼]  Estado: [Activas ▼]     │
├──────────────────────────────────────────────────────────────────┤
│ Código     │ Nombre                    │ Horas │ Vigencia │ ⋮  │
├────────────┼───────────────────────────┼───────┼──────────┼────┤
│ CAP-IND-01 │ Inducción General         │ 4h    │ 12 meses │ ⋮  │
│ CAP-ALT-01 │ Trabajo en Altura NOM-009 │ 8h    │ 12 meses │ ⋮  │
│ CAP-EPP-01 │ Uso de EPP NOM-017        │ 2h    │ 12 meses │ ⋮  │
│ CAP-PAU-01 │ Primeros Auxilios Básico  │ 8h    │ 24 meses │ ⋮  │
│ CAP-ESP-01 │ Espacios Confinados       │ 8h    │ 12 meses │ ⋮  │
└──────────────────────────────────────────────────────────────────┘
```

### Vista: Registro de Asistencia (Tablet)
```
┌──────────────────────────────────────────────────────────────────┐
│ Trabajo en Altura NOM-009           Fecha: 06/12/2025  14:00    │
│ Instructor: Ing. Roberto Sánchez    Obra: Fracc. Los Pinos     │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│ ┌────┬─────────────────────────┬──────────┬─────────┬────────┐ │
│ │ #  │ Nombre                  │ Puesto   │ Entrada │ Firma  │ │
│ ├────┼─────────────────────────┼──────────┼─────────┼────────┤ │
│ │ 1  │ Juan Pérez García       │ Oficial  │ 14:02   │ ✓      │ │
│ │ 2  │ María López Ruiz        │ Ayudante │ 14:05   │ ✓      │ │
│ │ 3  │ Carlos Hernández        │ Oficial  │ --:--   │ -      │ │
│ │ 4  │ Ana Martínez            │ Superv.  │ 14:01   │ ✓      │ │
│ └────┴─────────────────────────┴──────────┴─────────┴────────┘ │
│                                                                  │
│ Asistencia: 3/4 (75%)                                           │
│                                                                  │
│ [Agregar Participante]         [Cerrar Asistencia]              │
└──────────────────────────────────────────────────────────────────┘
```

---

## 6. Reglas de Negocio

1. **Inducción obligatoria**: Todo trabajador nuevo debe completar inducción antes de ingresar a obra
2. **Vigencia estricta**: Personal con capacitación vencida no puede realizar trabajos de alto riesgo
3. **Instructor certificado**: Capacitaciones de NOM requieren instructor con registro STPS
4. **Evaluación requerida**: Capacitaciones de seguridad requieren evaluación con mínimo 80%
5. **DC-3 único**: Un trabajador solo puede tener una DC-3 vigente por capacitación
6. **Asistencia mínima**: Se requiere 90% de asistencia para aprobar

---

## 7. Criterios de Aceptación

- [ ] Catálogo de capacitaciones con todos los atributos
- [ ] Programación de sesiones con validación de disponibilidad
- [ ] Registro de asistencia digital con firma
- [ ] Evaluación automática de conocimientos
- [ ] Generación de constancias DC-3 en PDF
- [ ] Dashboard de vencimientos con alertas
- [ ] Matriz de capacitación por puesto
- [ ] Reportes de cumplimiento por obra
- [ ] Integración con módulo RRHH (empleados)
- [ ] Notificaciones automáticas de vencimiento

---

## 8. Métricas de Éxito

- **Cobertura**: 100% del personal con inducción completada
- **Cumplimiento**: >95% de capacitaciones al día
- **Eficiencia**: Generación de DC-3 en <5 minutos
- **Trazabilidad**: 100% de capacitaciones con evidencia

---

**Estado:** ✅ Ready for Development
