workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-007-seguridad-industrial/implementacion/TRACEABILITY.yml

# TRACEABILITY.yml
# Módulo: MAI-007 - Seguridad Industrial
# Proyecto: Construcción
# Descripción: Trazabilidad de requerimientos funcionales del módulo de Seguridad Industrial

module:
  id: MAI-007
  name: Seguridad Industrial
  description: Gestión integral de seguridad en obras de construcción, incluyendo EPP, inspecciones, incidentes y capacitaciones
  vertical: construccion
  phase: core-business
  priority: high
  status: planned

# Requerimientos Funcionales
functional_requirements:

  # RF-001: Gestión de EPP
  - id: RF-MAI-007-001
    name: Gestión de Equipo de Protección Personal (EPP)
    description: Administración y control de equipos de protección personal asignados a trabajadores
    priority: critical
    status: planned

    user_stories:
      - id: US-MAI-007-001
        title: Registro de EPP
        as_a: Coordinador de Seguridad
        i_want: Registrar y catalogar los diferentes tipos de EPP disponibles
        so_that: Pueda mantener un inventario actualizado de equipos de protección
        acceptance_criteria:
          - Crear catálogo de tipos de EPP (casco, guantes, botas, arnés, etc.)
          - Registrar especificaciones técnicas y normativas de cada EPP
          - Definir vida útil y fecha de caducidad
          - Asignar códigos y ubicación de almacenamiento
          - Registrar proveedor y costo por unidad

      - id: US-MAI-007-002
        title: Asignación de EPP a trabajadores
        as_a: Coordinador de Seguridad
        i_want: Asignar EPP a trabajadores de obra
        so_that: Pueda garantizar que cada trabajador tenga el equipo necesario
        acceptance_criteria:
          - Asignar EPP según puesto y actividades del trabajador
          - Registrar fecha de entrega y firma de recibido
          - Generar acta de entrega de EPP
          - Vincular asignación con expediente del trabajador
          - Notificar próximo vencimiento o renovación

      - id: US-MAI-007-003
        title: Control de EPP en campo
        as_a: Supervisor de Obra
        i_want: Verificar el uso correcto de EPP desde dispositivo móvil
        so_that: Pueda asegurar el cumplimiento de normas de seguridad
        acceptance_criteria:
          - Registrar inspección de uso de EPP vía app móvil
          - Tomar fotografías del equipo en uso
          - Marcar EPP en mal estado o vencido
          - Generar reporte de no conformidades
          - Enviar alertas al coordinador de seguridad

    dependencies:
      modules:
        - MAI-001  # Gestión de Personal
        - MAI-003  # Inventarios y Almacén
        - MGN-005  # Catálogos
      mobile_apps:
        - MOB-003  # App Supervisor
        - MOB-004  # App Capataz

    database_entities:
      - epp_catalog
      - epp_assignments
      - epp_inspections
      - epp_inventory

    api_endpoints:
      - POST /api/v1/safety/epp/catalog
      - GET /api/v1/safety/epp/catalog
      - POST /api/v1/safety/epp/assignments
      - GET /api/v1/safety/epp/assignments/:worker_id
      - PUT /api/v1/safety/epp/assignments/:id
      - POST /api/v1/safety/epp/inspections
      - GET /api/v1/safety/epp/inventory

    ui_components:
      - EPPCatalogManagement
      - EPPAssignmentForm
      - EPPWorkerHistory
      - EPPInventoryDashboard
      - EPPMobileInspection (móvil)

  # RF-002: Inspecciones de Seguridad
  - id: RF-MAI-007-002
    name: Inspecciones de Seguridad
    description: Realización y seguimiento de inspecciones de seguridad en obras
    priority: critical
    status: planned

    user_stories:
      - id: US-MAI-007-004
        title: Creación de checklist de inspección
        as_a: Coordinador de Seguridad
        i_want: Crear listas de verificación personalizadas para inspecciones
        so_that: Pueda estandarizar los criterios de evaluación de seguridad
        acceptance_criteria:
          - Crear plantillas de checklist por tipo de obra
          - Definir criterios de evaluación y puntuación
          - Establecer frecuencia de inspecciones
          - Asignar responsables de inspección
          - Incluir normativas y referencias aplicables

      - id: US-MAI-007-005
        title: Ejecución de inspecciones en campo
        as_a: Supervisor de Obra
        i_want: Realizar inspecciones de seguridad desde dispositivo móvil
        so_that: Pueda documentar hallazgos en tiempo real
        acceptance_criteria:
          - Completar checklist desde app móvil
          - Tomar fotografías de hallazgos
          - Registrar coordenadas GPS del punto inspeccionado
          - Clasificar hallazgos por nivel de riesgo
          - Funcionar en modo offline con sincronización posterior

      - id: US-MAI-007-006
        title: Gestión de hallazgos y acciones correctivas
        as_a: Coordinador de Seguridad
        i_want: Dar seguimiento a hallazgos de inspecciones
        so_that: Pueda asegurar que se implementen acciones correctivas
        acceptance_criteria:
          - Visualizar hallazgos por nivel de riesgo
          - Asignar responsables para acciones correctivas
          - Establecer plazos de solución
          - Registrar evidencia de corrección
          - Generar reportes de cumplimiento

    dependencies:
      modules:
        - MAI-002  # Gestión de Obras
        - MGN-007  # Auditoría
        - MGN-008  # Notificaciones
      mobile_apps:
        - MOB-003  # App Supervisor
        - MOB-004  # App Capataz

    database_entities:
      - safety_inspection_templates
      - safety_inspections
      - inspection_findings
      - corrective_actions

    api_endpoints:
      - POST /api/v1/safety/inspections/templates
      - GET /api/v1/safety/inspections/templates
      - POST /api/v1/safety/inspections
      - GET /api/v1/safety/inspections/:project_id
      - PUT /api/v1/safety/inspections/:id
      - POST /api/v1/safety/inspections/:id/findings
      - POST /api/v1/safety/findings/:id/corrective-actions
      - PUT /api/v1/safety/corrective-actions/:id

    ui_components:
      - InspectionTemplateBuilder
      - InspectionScheduler
      - MobileInspectionForm (móvil)
      - FindingsList
      - CorrectiveActionTracker
      - SafetyComplianceDashboard

  # RF-003: Reportes de Incidentes
  - id: RF-MAI-007-003
    name: Reportes de Incidentes y Accidentes
    description: Registro, investigación y seguimiento de incidentes de seguridad
    priority: critical
    status: planned

    user_stories:
      - id: US-MAI-007-007
        title: Reporte inmediato de incidentes
        as_a: Supervisor de Obra
        i_want: Reportar incidentes o accidentes desde dispositivo móvil
        so_that: Pueda documentar el evento de forma inmediata
        acceptance_criteria:
          - Formulario de reporte rápido en app móvil
          - Clasificar tipo de incidente (leve, grave, fatal)
          - Registrar ubicación con GPS y fotografías
          - Identificar personas involucradas
          - Enviar notificación automática a coordinador

      - id: US-MAI-007-008
        title: Investigación de incidentes
        as_a: Coordinador de Seguridad
        i_want: Documentar la investigación de incidentes
        so_that: Pueda identificar causas raíz y prevenir recurrencias
        acceptance_criteria:
          - Registrar análisis de causas (diagrama de Ishikawa)
          - Documentar testimonios y evidencias
          - Identificar causas raíz y contribuyentes
          - Definir acciones preventivas y correctivas
          - Generar informe de investigación

      - id: US-MAI-007-009
        title: Seguimiento de incidentes
        as_a: Coordinador de Seguridad
        i_want: Dar seguimiento a incidentes hasta su cierre
        so_that: Pueda asegurar la implementación de medidas correctivas
        acceptance_criteria:
          - Visualizar estado de cada incidente
          - Registrar acciones tomadas y responsables
          - Adjuntar documentación médica si aplica
          - Calcular días perdidos y costos asociados
          - Cerrar incidente con verificación de medidas

    dependencies:
      modules:
        - MAI-001  # Gestión de Personal
        - MAI-002  # Gestión de Obras
        - MGN-007  # Auditoría
        - MGN-008  # Notificaciones
      mobile_apps:
        - MOB-003  # App Supervisor
        - MOB-004  # App Capataz

    database_entities:
      - incident_reports
      - incident_investigations
      - incident_witnesses
      - incident_corrective_actions
      - incident_costs

    api_endpoints:
      - POST /api/v1/safety/incidents
      - GET /api/v1/safety/incidents
      - GET /api/v1/safety/incidents/:id
      - PUT /api/v1/safety/incidents/:id
      - POST /api/v1/safety/incidents/:id/investigation
      - POST /api/v1/safety/incidents/:id/witnesses
      - POST /api/v1/safety/incidents/:id/corrective-actions
      - PUT /api/v1/safety/incidents/:id/close

    ui_components:
      - MobileIncidentReport (móvil)
      - IncidentsList
      - IncidentInvestigationForm
      - IncidentCauseAnalysis
      - IncidentFollowUp
      - IncidentStatisticsDashboard

  # RF-004: Capacitaciones de Seguridad
  - id: RF-MAI-007-004
    name: Capacitaciones de Seguridad
    description: Planificación, ejecución y seguimiento de capacitaciones en seguridad
    priority: high
    status: planned

    user_stories:
      - id: US-MAI-007-010
        title: Programación de capacitaciones
        as_a: Coordinador de Seguridad
        i_want: Planificar capacitaciones de seguridad
        so_that: Pueda asegurar que todo el personal esté debidamente capacitado
        acceptance_criteria:
          - Crear catálogo de cursos de seguridad
          - Definir capacitaciones obligatorias por puesto
          - Programar sesiones con fecha, hora y ubicación
          - Asignar instructores internos o externos
          - Calcular capacidad y gestionar inscripciones

      - id: US-MAI-007-011
        title: Registro de asistencia y evaluación
        as_a: Instructor de Seguridad
        i_want: Registrar asistencia y evaluar participantes
        so_that: Pueda documentar el cumplimiento de capacitación
        acceptance_criteria:
          - Registrar asistencia con firma o QR
          - Aplicar evaluación de conocimientos
          - Registrar calificaciones obtenidas
          - Generar constancias de capacitación
          - Tomar fotografías de la sesión

      - id: US-MAI-007-012
        title: Seguimiento de capacitaciones
        as_a: Coordinador de Seguridad
        i_want: Consultar el historial de capacitaciones por trabajador
        so_that: Pueda verificar cumplimiento de requisitos de seguridad
        acceptance_criteria:
          - Visualizar capacitaciones por trabajador
          - Identificar capacitaciones vencidas o pendientes
          - Generar alertas de renovación
          - Exportar matriz de capacitación
          - Generar reportes de cobertura

    dependencies:
      modules:
        - MAI-001  # Gestión de Personal
        - MGN-005  # Catálogos
        - MGN-008  # Notificaciones
      mobile_apps:
        - MOB-003  # App Supervisor (consulta)

    database_entities:
      - training_catalog
      - training_sessions
      - training_attendance
      - training_evaluations
      - training_certificates

    api_endpoints:
      - POST /api/v1/safety/trainings/catalog
      - GET /api/v1/safety/trainings/catalog
      - POST /api/v1/safety/trainings/sessions
      - GET /api/v1/safety/trainings/sessions
      - POST /api/v1/safety/trainings/sessions/:id/attendance
      - POST /api/v1/safety/trainings/sessions/:id/evaluations
      - GET /api/v1/safety/trainings/worker/:worker_id/history
      - GET /api/v1/safety/trainings/compliance-matrix

    ui_components:
      - TrainingCatalogManagement
      - TrainingSessionPlanner
      - AttendanceRegistration
      - TrainingEvaluation
      - WorkerTrainingHistory
      - TrainingComplianceDashboard

# Integraciones con Apps Móviles
mobile_integrations:

  - app_id: MOB-003
    app_name: App Supervisor
    description: Aplicación móvil para supervisores de obra
    features:
      - Verificación de uso de EPP
      - Inspecciones de seguridad en campo
      - Reporte inmediato de incidentes
      - Consulta de capacitaciones del personal
      - Fotografías y evidencias
      - Funcionalidad offline
    sync_frequency: real-time
    offline_capable: true

  - app_id: MOB-004
    app_name: App Capataz
    description: Aplicación móvil para capataces
    features:
      - Reporte de incidentes
      - Inspecciones básicas de seguridad
      - Verificación de EPP de su cuadrilla
      - Consulta de checklist de seguridad
      - Registro de asistencia a capacitaciones
    sync_frequency: real-time
    offline_capable: true

# Indicadores y Métricas
kpis:
  - name: Tasa de Incidentes
    description: Número de incidentes por cada 100,000 horas trabajadas
    formula: (Número de incidentes / Total horas trabajadas) * 100,000
    target: "< 2.0"

  - name: Cumplimiento de Inspecciones
    description: Porcentaje de inspecciones realizadas vs programadas
    formula: (Inspecciones realizadas / Inspecciones programadas) * 100
    target: ">= 95%"

  - name: Tiempo de Cierre de Hallazgos
    description: Días promedio para cerrar hallazgos de inspecciones
    formula: Promedio de días desde hallazgo hasta cierre
    target: "<= 7 días"

  - name: Cobertura de Capacitación
    description: Porcentaje de trabajadores capacitados
    formula: (Trabajadores capacitados / Total trabajadores) * 100
    target: "100%"

  - name: Cumplimiento de EPP
    description: Porcentaje de trabajadores con EPP vigente
    formula: (Trabajadores con EPP vigente / Total trabajadores) * 100
    target: "100%"

# Reportes
reports:
  - id: REP-MAI-007-001
    name: Dashboard de Seguridad
    description: Panel general de indicadores de seguridad
    frequency: diario
    sections:
      - Indicadores de incidentes
      - Estado de inspecciones
      - Hallazgos pendientes
      - Cumplimiento de EPP
      - Capacitaciones próximas

  - id: REP-MAI-007-002
    name: Reporte de Incidentes
    description: Informe detallado de incidentes del período
    frequency: mensual
    sections:
      - Resumen de incidentes por tipo
      - Análisis de causas
      - Acciones correctivas implementadas
      - Costos asociados
      - Tendencias y recomendaciones

  - id: REP-MAI-007-003
    name: Matriz de Capacitación
    description: Estado de capacitaciones por trabajador
    frequency: mensual
    sections:
      - Capacitaciones vigentes
      - Capacitaciones próximas a vencer
      - Capacitaciones pendientes
      - Estadísticas de evaluación

  - id: REP-MAI-007-004
    name: Reporte de Inspecciones
    description: Resultados de inspecciones de seguridad
    frequency: semanal
    sections:
      - Inspecciones realizadas
      - Hallazgos por nivel de riesgo
      - Acciones correctivas pendientes
      - Tendencias de cumplimiento

# Normativas y Regulaciones
compliance:
  standards:
    - name: NOM-031-STPS-2011
      description: Construcción - Condiciones de seguridad y salud en el trabajo
      scope: General

    - name: NOM-017-STPS-2008
      description: Equipo de protección personal
      scope: Gestión de EPP

    - name: NOM-019-STPS-2011
      description: Comisiones de seguridad e higiene
      scope: Inspecciones

    - name: OSHA 1926
      description: Safety and Health Regulations for Construction
      scope: General (referencia internacional)

# Tecnologías y Stack
technical_stack:
  backend:
    - Node.js / Express
    - PostgreSQL
    - Redis (caché)
  frontend:
    - React / Next.js
    - Material-UI
  mobile:
    - React Native
    - Offline storage: SQLite
  cloud:
    - AWS S3 (almacenamiento de fotos)
    - AWS SNS (notificaciones push)
  integrations:
    - API Gateway
    - WebSockets (sincronización real-time)

# Seguridad y Permisos
security:
  roles:
    - role: Coordinador de Seguridad
      permissions:
        - Gestión completa del módulo
        - Crear y modificar EPP, inspecciones, incidentes
        - Aprobar acciones correctivas
        - Generar todos los reportes

    - role: Supervisor de Obra
      permissions:
        - Realizar inspecciones
        - Reportar incidentes
        - Verificar EPP
        - Consultar reportes de su obra

    - role: Capataz
      permissions:
        - Reportar incidentes
        - Realizar inspecciones básicas
        - Verificar EPP de su cuadrilla

    - role: Trabajador
      permissions:
        - Consultar su historial de EPP
        - Consultar sus capacitaciones
        - Reportar sugerencias de seguridad

# Roadmap de Implementación
implementation_phases:

  - phase: 1
    name: Gestión de EPP
    duration: 4 semanas
    deliverables:
      - Catálogo de EPP
      - Asignación a trabajadores
      - Control de inventario
      - Integración con app móvil para verificación

  - phase: 2
    name: Inspecciones de Seguridad
    duration: 5 semanas
    deliverables:
      - Plantillas de inspección
      - App móvil para inspecciones
      - Gestión de hallazgos
      - Sistema de acciones correctivas

  - phase: 3
    name: Reportes de Incidentes
    duration: 4 semanas
    deliverables:
      - Reporte de incidentes
      - Investigación de causas
      - Seguimiento y cierre
      - Estadísticas y KPIs

  - phase: 4
    name: Capacitaciones
    duration: 3 semanas
    deliverables:
      - Catálogo de capacitaciones
      - Programación de sesiones
      - Registro de asistencia y evaluaciones
      - Matriz de cumplimiento

# Testing
testing_strategy:
  unit_tests:
    - Lógica de negocio de EPP
    - Cálculo de KPIs
    - Validaciones de formularios

  integration_tests:
    - APIs de seguridad
    - Sincronización móvil-backend
    - Integración con módulos dependientes

  e2e_tests:
    - Flujo completo de inspección
    - Flujo de reporte de incidente
    - Asignación de EPP

  mobile_tests:
    - Funcionalidad offline
    - Sincronización de datos
    - Captura de fotos y GPS

# Documentación
documentation:
  technical:
    - API Documentation (Swagger/OpenAPI)
    - Database Schema
    - Mobile App Architecture

  user:
    - Manual de Usuario - Coordinador de Seguridad
    - Guía Rápida - Supervisor (App Móvil)
    - Guía Rápida - Capataz (App Móvil)
    - Videos tutoriales

# Changelog
changelog:
  - version: 1.0.0
    date: 2025-12-06
    changes:
      - Creación inicial del documento de trazabilidad
      - Definición de 4 requerimientos funcionales principales
      - Integración con apps móviles MOB-003 y MOB-004
      - Definición de KPIs y reportes