workspace-v1/projects/erp-construccion/docs/02-definicion-modulos/MAI-007-rrhh-asistencias/_MAP.md

_MAP: MAI-006 - RRHH, Asistencias y Nómina

Épica: MAI-006 Nombre: RRHH, Asistencias y Nómina Fase: 1 - Alcance Inicial Presupuesto: $25,000 MXN Story Points: 50 SP Estado: 🚧 Planificado Sprint: Sprint 9-10 (Semanas 13.5-16) Prioridad: P0 - Crítico Última actualización: 2025-11-17

---

📋 Propósito

Implementar sistema completo de gestión de recursos humanos para obra con:

• Catálogo de empleados, cuadrillas y oficios
• Asistencia biométrica desde app móvil ⭐
• Costeo de mano de obra por obra/partida
• Integración con IMSS e INFONAVIT ⭐
• Exportación de archivos SUA para nómina

Justificación: RRHH es crítico para costeo de mano de obra y cumplimiento legal (IMSS/INFONAVIT) desde el inicio de cualquier obra.

Reutilización GAMILIT: 30% (concepto de tracking de usuarios, adaptado)

---

📁 Contenido

Requerimientos Funcionales (5)

ID	Archivo	Título	Estado
RF-HR-001	RF-HR-001-empleados-cuadrillas.md	Gestión de Empleados y Cuadrillas	🚧 Planificado
RF-HR-002	RF-HR-002-asistencia-biometrica.md	Sistema de Asistencia con Biométrico	🚧 Planificado
RF-HR-003	RF-HR-003-costeo-mano-obra.md	Costeo de Mano de Obra	🚧 Planificado
RF-HR-004	RF-HR-004-integracion-imss.md	Integración con IMSS	🚧 Planificado
RF-HR-005	RF-HR-005-integracion-infonavit.md	Integración con INFONAVIT	🚧 Planificado

Especificaciones Técnicas (5)

ID	Archivo	Título	RF	Estado
ET-HR-001	ET-HR-001-empleados-cuadrillas.md	Implementación de Empleados y Cuadrillas	RF-HR-001	🚧 Planificado
ET-HR-002	ET-HR-002-asistencia-biometrica.md	Implementación de Asistencia Biométrica	RF-HR-002	🚧 Planificado
ET-HR-003	ET-HR-003-costeo-mano-obra.md	Implementación de Costeo de Mano de Obra	RF-HR-003	🚧 Planificado
ET-HR-004	ET-HR-004-integracion-imss.md	Integración con API IMSS	RF-HR-004	🚧 Planificado
ET-HR-005	ET-HR-005-integracion-infonavit.md	Integración con API INFONAVIT	RF-HR-005	🚧 Planificado

Historias de Usuario (6)

ID	Archivo	Título	SP	Estado
US-HR-001	US-HR-001-catalogo-empleados.md	Catálogo de Empleados y Cuadrillas	8	🚧 Planificado
US-HR-002	US-HR-002-asistencia-biometrica-app.md	Asistencia con Biométrico desde App	15	🚧 Planificado
US-HR-003	US-HR-003-costeo-mano-obra.md	Costeo de Mano de Obra por Obra	10	🚧 Planificado
US-HR-004	US-HR-004-integracion-nomina.md	Integración con Nómina Externa	8	🚧 Planificado
US-HR-005	US-HR-005-exportacion-imss-infonavit.md	Exportación IMSS/INFONAVIT	12	🚧 Planificado
US-HR-006	US-HR-006-reportes-asistencia.md	Reportes de Asistencia	5	🚧 Planificado

Total Story Points: 50 SP (12 SP más que GAMILIT por integraciones externas)

Implementación

📊 Inventarios de trazabilidad:

• TRACEABILITY.yml - Matriz completa de trazabilidad
• DATABASE.yml - Objetos de base de datos
• BACKEND.yml - Módulos backend e integraciones
• MOBILE.yml - Especificaciones de app móvil ⭐
• INTEGRATIONS.yml - Integraciones IMSS/INFONAVIT ⭐

Pruebas

📋 Documentación de testing:

• TEST-PLAN.md - Plan de pruebas
• TEST-CASES.md - Casos de prueba
• INTEGRATION-TESTS.md - Tests de integración IMSS/INFONAVIT ⭐

---

🔗 Referencias

• README: README.md - Descripción detallada de la épica
• Fase 1: ../README.md - Información de la fase completa
• Roadmap: ../ROADMAP-DETALLADO.md - Sprints 9-10

---

📊 Métricas

Métrica	Valor
Presupuesto estimado	$25,000 MXN
Presupuesto target	$25,000 MXN ±5%
Story Points estimados	50 SP
Duración estimada	2.5 semanas (12.5 días)
Reutilización GAMILIT	30%
Integraciones externas	2 (IMSS, INFONAVIT)
RF a implementar	5/5
ET a implementar	5/5
US a completar	6/6

---

🎯 Módulos Afectados

Base de Datos

• Schemas: hr, attendance, payroll
• Tablas: ~15 tablas
  • employees, crews, trades, attendance_records
  • labor_costs, payroll_periods, imss_integration_log, infonavit_integration_log
• Funciones: Cálculo de costeo, validaciones de asistencia
• ENUMs:
  • employee_status (active, suspended, terminated)
  • trade_type (mason, electrician, plumber, carpenter, etc.)
  • attendance_method (biometric, qr, manual, gps)

Backend

• Módulo: hr
• Path: apps/backend/src/modules/hr/
• Services:
  • EmployeeService - CRUD de empleados
  • AttendanceService - Registro y validación de asistencia
  • LaborCostService - Cálculo de costeo
  • IMSSIntegrationService - Integración con IMSS ⭐
  • INFONAVITIntegrationService - Integración con INFONAVIT ⭐
  • BiometricService - Validación de datos biométricos ⭐
• APIs Externas:
  • IMSS SOAP/REST API
  • INFONAVIT REST API

Frontend Web

• Features: hr, attendance, payroll
• Path: apps/frontend/src/features/
• Componentes:
  • Gestión de empleados y cuadrillas
  • Dashboard de asistencias
  • Reportes de costeo
  • Exportación IMSS/INFONAVIT
• Guards: AuthGuard, RoleGuard (solo HR y Finance)

App Móvil (React Native) ⭐

• Features: attendance-capture
• Path: apps/mobile/src/features/attendance/
• Componentes:
  • Login de residente
  • Selector de obra
  • Scanner QR
  • Captura biométrica (huella/facial)
  • Lista de empleados
  • Confirmación de asistencia
  • Historial del día
• Offline: SQLite + sincronización automática
• Biométrico:
  • react-native-biometrics (huella)
  • react-native-camera (facial)
• GPS: @react-native-community/geolocation

---

📱 Funcionalidades de App Móvil

Flujo de Asistencia

flowchart TD
    A[Residente abre app] --> B[Login]
    B --> C[Selecciona obra]
    C --> D{Tipo de registro}
    D -->|Escanear QR| E[Scan QR del empleado]
    D -->|Buscar empleado| F[Lista de empleados]
    D -->|Biométrico| G[Captura huella/facial]
    E --> H[Validar empleado]
    F --> H
    G --> H
    H --> I{Validaciones}
    I -->|GPS| J[Verificar ubicación en obra]
    I -->|Horario| K[Verificar jornada laboral]
    I -->|Estado| L[Verificar empleado activo]
    J --> M{¿Todo OK?}
    K --> M
    L --> M
    M -->|Sí| N[Registrar asistencia]
    M -->|No| O[Mostrar error]
    N --> P{¿Online?}
    P -->|Sí| Q[Enviar a servidor]
    P -->|No| R[Guardar en cola local]
    Q --> S[Confirmación exitosa]
    R --> S
    S --> T[Vibración + sonido]

Pantallas de App

1. Login

   • Email/password
   • Biométrico para login rápido (opcional)

2. Selector de Obra

   • Lista de obras asignadas al residente
   • Filtro por estatus

3. Dashboard de Asistencia

   • Botones: Check-in / Check-out
   • Resumen del día (empleados registrados)
   • Alertas (empleados faltantes, retrasos)

4. Captura de Asistencia

   • Tabs: QR | Lista | Biométrico
   • Foto del empleado
   • Timestamp y GPS
   • Notas opcionales

5. Historial

   • Asistencias del día
   • Filtros por cuadrilla/oficio
   • Estado de sincronización

Validaciones en App

Validación	Descripción	Acción si falla
GPS	Empleado debe estar dentro del radio de la obra (100m)	Advertencia, permitir override manual
Horario	Registro dentro de jornada laboral (6am-8pm típico)	Advertencia, permitir registro
Estado empleado	Empleado debe estar activo y asignado a obra	Bloquear registro
Duplicado	No permitir doble check-in sin check-out	Bloquear registro
Biométrico	Match con template almacenado (>70% confianza)	Fallback a foto

Modo Offline

Capacidades:

• Almacenar hasta 500 registros de asistencia en cola
• Cache de lista de empleados de la obra (actualizado diariamente)
• Cache de templates biométricos (encrypted)
• Indicador visual de registros pendientes de sincronización

Sincronización:

• Automática al detectar conexión
• Manual por botón "Sincronizar ahora"
• Resolución de conflictos (último gana)

---

🔌 Integraciones Externas

1. IMSS (Instituto Mexicano del Seguro Social)

API: SOAP/REST (depende de la región) Autenticación: Certificado digital (.cer + .key)

Funcionalidades:

1. Afiliación de trabajadores

   • Alta de trabajador
   • Baja de trabajador
   • Modificación salarial
   • Reingreso

2. Generación de SUA (Sistema Único de Autodeterminación)

   • Archivo .SUA mensual
   • Cédulas de determinación
   • Cálculo de cuotas obrero-patronales

3. Consultas

   • Vigencia de derechos
   • Semanas cotizadas
   • Salario base de cotización

Endpoints clave:

POST /api/imss/afiliacion/alta
POST /api/imss/afiliacion/baja
POST /api/imss/afiliacion/modificacion
POST /api/imss/sua/generar
GET  /api/imss/vigencia/:nss

Formato de Archivo SUA:

Layout de 80 caracteres por línea
Secciones:
- Encabezado (registro patronal, período)
- Trabajadores (NSS, nombre, salario, días trabajados)
- Totales (suma de cuotas)
- Cierre (checksum)

---

2. INFONAVIT (Instituto del Fondo Nacional de la Vivienda)

API: REST Autenticación: OAuth 2.0 + API Key

Funcionalidades:

1. Registro patronal

   • Alta de patrón
   • Actualización de datos

2. Aportaciones

   • Cálculo de aportaciones (5% del SBC)
   • Generación de archivo de pago
   • Pago referenciado

3. Trabajadores acreditados

   • Consulta de trabajadores con crédito
   • Descuentos de crédito INFONAVIT

Endpoints clave:

POST /api/infonavit/patron/registro
POST /api/infonavit/aportaciones/calcular
POST /api/infonavit/aportaciones/generar-archivo
GET  /api/infonavit/trabajadores/acreditados/:rfc
POST /api/infonavit/descuentos/aplicar

Cálculo de Aportaciones:

// Ejemplo simplificado
const aportacionINFONAVIT = (salarioBaseCotizacion, diasTrabajados) => {
  const aportacionDiaria = salarioBaseCotizacion * 0.05; // 5%
  return aportacionDiaria * diasTrabajados;
};

---

🧪 Testing

Unit Tests (Backend)

describe('AttendanceService', () => {
  it('should register attendance with GPS validation')
  it('should prevent duplicate check-in')
  it('should calculate labor cost per work')
  it('should validate biometric data')
})

describe('IMSSIntegrationService', () => {
  it('should generate valid SUA file')
  it('should calculate IMSS contributions correctly')
  it('should handle API errors gracefully')
})

describe('INFONAVITIntegrationService', () => {
  it('should calculate 5% contributions')
  it('should fetch accredited workers')
  it('should generate payment file')
})

E2E Tests (App Móvil)

describe('Attendance Capture E2E', () => {
  it('should complete full check-in flow with QR')
  it('should complete check-in with biometric')
  it('should handle offline mode correctly')
  it('should sync pending records when online')
  it('should validate GPS within work radius')
})

Integration Tests

describe('IMSS Integration', () => {
  it('should connect to IMSS sandbox API')
  it('should register employee successfully')
  it('should generate valid SUA file')
})

describe('INFONAVIT Integration', () => {
  it('should connect to INFONAVIT sandbox API')
  it('should calculate contributions correctly')
  it('should fetch accredited workers list')
})

---

🚨 Riesgos Específicos

Riesgo	Probabilidad	Impacto	Mitigación
APIs IMSS/INFONAVIT cambian	Media	Alto	Monitoreo de cambios, abstracción de integraciones
Biométrico no funciona en devices antiguos	Media	Medio	Fallback a QR + foto
GPS impreciso en obra	Alta	Bajo	Radio amplio (100m), permitir override
Sincronización offline falla	Media	Alto	Cola persistente, retry automático
Certificados IMSS expiran	Baja	Alto	Alertas automáticas 30 días antes

---

📋 Checklist de Implementación

Backend

• CRUD de empleados, cuadrillas, oficios
• API de registro de asistencia con validaciones
• Servicio de cálculo de costeo de mano de obra
• Integración IMSS (sandbox → producción)
• Integración INFONAVIT (sandbox → producción)
• Generación de archivos SUA
• Exportación de reportes

App Móvil

• Login y autenticación
• Selector de obra
• Scanner QR (react-native-qrcode-scanner)
• Captura biométrica (react-native-biometrics)
• GPS validation (@react-native-community/geolocation)
• Base de datos local (expo-sqlite)
• Cola de sincronización offline
• UI/UX optimizada para campo

Frontend Web

• Gestión de empleados
• Dashboard de asistencias
• Reportes de costeo
• Exportación IMSS/INFONAVIT
• Logs de sincronización

Database

• Schemas y tablas
• Funciones de cálculo
• Triggers de validación
• Índices optimizados

Testing

• Unit tests >80% coverage
• E2E tests de flujo completo
• Integration tests con IMSS/INFONAVIT sandboxes
• Tests de app móvil (offline, GPS, biométrico)

Despliegue

• Variables de entorno (API keys, certificados)
• Secrets management (certificados IMSS)
• Deploy de app a stores (TestFlight, Play Store)
• Configuración de monitoreo
• Documentación de integración

---

💡 Lessons Learned (a documentar post-implementación)

1. Integraciones gubernamentales son complejas: Requieren tiempo para validación y certificación
2. Biométrico debe tener fallback: No todos los dispositivos lo soportan
3. Modo offline es crítico: Obra no siempre tiene buena conexión
4. UX simple es clave: Residentes no son técnicos, UI debe ser intuitiva

---

🎯 Siguiente Paso

Completar documentos RF, ET y US de esta épica, con especial énfasis en:

• RF-HR-002: Especificaciones de biométrico
• ET-HR-004 y ET-HR-005: Detalles técnicos de integraciones
• US-HR-002: Flujos de usuario en app móvil

---

Generado: 2025-11-17 Mantenedores: @tech-lead @backend-team @mobile-team @integrations-team Estado: 🚧 Planificado Prioridad: P0 - Crítico para cumplimiento legal