rckrdmrd a9703b2727 Initial commit - erp-construccion

2026-01-04 06:12:06 -06:00

16 KiB

Raw Blame History

_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

Login
- Email/password
- Biométrico para login rápido (opcional)
Selector de Obra
- Lista de obras asignadas al residente
- Filtro por estatus
Dashboard de Asistencia
- Botones: Check-in / Check-out
- Resumen del día (empleados registrados)
- Alertas (empleados faltantes, retrasos)
Captura de Asistencia
- Tabs: QR | Lista | Biométrico
- Foto del empleado
- Timestamp y GPS
- Notas opcionales
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

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

Funcionalidades:

Afiliación de trabajadores
- Alta de trabajador
- Baja de trabajador
- Modificación salarial
- Reingreso
Generación de SUA (Sistema Único de Autodeterminación)
- Archivo .SUA mensual
- Cédulas de determinación
- Cálculo de cuotas obrero-patronales
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:

Registro patronal
- Alta de patrón
- Actualización de datos
Aportaciones
- Cálculo de aportaciones (5% del SBC)
- Generación de archivo de pago
- Pago referenciado
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)

Integraciones gubernamentales son complejas: Requieren tiempo para validación y certificación
Biométrico debe tener fallback: No todos los dispositivos lo soportan
Modo offline es crítico: Obra no siempre tiene buena conexión
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

16 KiB Raw Blame History

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

📋 Propósito

📁 Contenido

Requerimientos Funcionales (5)

Especificaciones Técnicas (5)

Historias de Usuario (6)

Implementación

Pruebas

🔗 Referencias

📊 Métricas

🎯 Módulos Afectados

Base de Datos

Backend

Frontend Web

App Móvil (React Native) ⭐

📱 Funcionalidades de App Móvil

Flujo de Asistencia

Pantallas de App

Validaciones en App

Modo Offline

🔌 Integraciones Externas

1. IMSS (Instituto Mexicano del Seguro Social)

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

🧪 Testing

Unit Tests (Backend)

E2E Tests (App Móvil)

Integration Tests

🚨 Riesgos Específicos

📋 Checklist de Implementación

Backend

App Móvil

Frontend Web

Database

Testing

Despliegue

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

🎯 Siguiente Paso

16 KiB

Raw Blame History