# TRACEABILITY - MAE-011: Nómina
metadata:
  modulo: MAE-011
  nombre: Nómina
  version: 1.0.0
  fecha: 2025-12-06
  reutilizacion_core: 65%
  descripcion: Gestión integral de nómina para personal de obra, incluyendo cálculo de nómina, timbrado CFDI, deducciones y percepciones, finiquitos e integración con checador biométrico
  dependencias:
    - MGN-001 # Usuarios y Autenticación
    - MGN-002 # RBAC
    - MGN-003 # Multi-tenancy
    - MGN-005 # Catálogos
    - MAI-001 # Proyectos de Construcción
  apps_moviles:
    - MOB-001 # Checador Biométrico

requerimientos:
  - id: RF-NOM-001
    titulo: Cálculo de Nómina
    descripcion: Procesamiento automático de nómina semanal, quincenal o mensual con cálculo de percepciones, deducciones e impuestos
    prioridad: alta
    especificaciones:
      - id: ESP-NOM-001-01
        descripcion: Configurar períodos de nómina (semanal, quincenal, mensual)
      - id: ESP-NOM-001-02
        descripcion: Calcular salarios base según contrato y días trabajados
      - id: ESP-NOM-001-03
        descripcion: Calcular tiempo extra (simple y doble) desde checador biométrico
      - id: ESP-NOM-001-04
        descripcion: Calcular prestaciones (prima dominical, vacaciones, aguinaldo)
      - id: ESP-NOM-001-05
        descripcion: Aplicar deducciones automáticas (IMSS, ISR, infonavit, pensiones)
      - id: ESP-NOM-001-06
        descripcion: Calcular cuotas patronales para provisiones
      - id: ESP-NOM-001-07
        descripcion: Generar dispersión bancaria por CLABE
      - id: ESP-NOM-001-08
        descripcion: Validar nómina antes de procesamiento final
    historias_usuario:
      - id: US-NOM-001-01
        titulo: Como jefe de RH necesito procesar la nómina del período
        criterios_aceptacion:
          - Seleccionar período de nómina (semanal/quincenal/mensual)
          - Importar asistencias desde checador biométrico (MOB-001)
          - Revisar y ajustar incidencias (faltas, retardos, permisos)
          - Calcular automáticamente percepciones y deducciones
          - Validar totales antes de autorizar
      - id: US-NOM-001-02
        titulo: Como jefe de RH necesito calcular tiempo extra automáticamente
        criterios_aceptacion:
          - Obtener horas trabajadas desde MOB-001
          - Identificar horas extra simples (después de 8 hrs diarias)
          - Identificar horas extra dobles (después de 9 hrs o en descanso)
          - Aplicar factor de pago según tipo de tiempo extra
          - Generar reporte de tiempo extra por empleado
      - id: US-NOM-001-03
        titulo: Como contador necesito generar dispersión bancaria
        criterios_aceptacion:
          - Generar archivo de dispersión en formato bancario
          - Incluir CLABE, nombre completo y monto neto
          - Validar que suma de dispersión coincida con nómina
          - Exportar en formato del banco (BBVA, Santander, etc)
          - Marcar nómina como dispersada
      - id: US-NOM-001-04
        titulo: Como empleado necesito consultar mi recibo de nómina
        criterios_aceptacion:
          - Ver listado de períodos de nómina
          - Descargar recibo en PDF
          - Ver desglose de percepciones y deducciones
          - Consultar histórico de pagos
    tablas:
      - payroll_management.periodos_nomina
      - payroll_management.nominas
      - payroll_management.nominas_detalle
      - payroll_management.nominas_percepciones
      - payroll_management.nominas_deducciones
      - payroll_management.nominas_provision_patronal
      - payroll_management.dispersiones_bancarias
    endpoints:
      - POST /api/v1/nomina/periodos
      - GET /api/v1/nomina/periodos
      - POST /api/v1/nomina/calcular
      - GET /api/v1/nomina/:periodo_id
      - PUT /api/v1/nomina/:periodo_id
      - POST /api/v1/nomina/:periodo_id/validar
      - POST /api/v1/nomina/:periodo_id/autorizar
      - GET /api/v1/nomina/:periodo_id/dispersion
      - POST /api/v1/nomina/:periodo_id/dispersar
      - GET /api/v1/nomina/empleado/:empleado_id/recibos
      - GET /api/v1/nomina/empleado/:empleado_id/recibo/:periodo_id/pdf
    componentes_ui:
      - NominasListView
      - NominaCalculoWizard
      - NominaDetalleTable
      - NominaValidacionPanel
      - NominaDispersionGenerator
      - ReciboNominaPDFViewer
      - EmpleadoRecibosHistory
      - TiempoExtraCalculator
    integraciones:
      - modulo: MOB-001
        descripcion: Importación de asistencias y horas trabajadas desde checador biométrico
      - modulo: MAI-001
        descripcion: Vinculación de empleados con obras de construcción
      - modulo: MGN-005
        descripcion: Catálogo de empleados, departamentos y puestos
    estado: pendiente

  - id: RF-NOM-002
    titulo: Timbrado CFDI Nómina
    descripcion: Generación y timbrado de comprobantes fiscales digitales (CFDI) de nómina cumpliendo normativa SAT
    prioridad: alta
    especificaciones:
      - id: ESP-NOM-002-01
        descripcion: Generar XML de nómina según estándar SAT vigente
      - id: ESP-NOM-002-02
        descripcion: Integración con PAC (Proveedor Autorizado de Certificación)
      - id: ESP-NOM-002-03
        descripcion: Timbrado automático al autorizar nómina
      - id: ESP-NOM-002-04
        descripcion: Almacenar XML y PDF timbrados
      - id: ESP-NOM-002-05
        descripcion: Envío automático de CFDI por email a empleados
      - id: ESP-NOM-002-06
        descripcion: Consulta de estatus de timbrado en PAC
      - id: ESP-NOM-002-07
        descripcion: Cancelación de CFDI de nómina
      - id: ESP-NOM-002-08
        descripcion: Registro de nóminas extraordinarias (aguinaldo, PTU, bonos)
    historias_usuario:
      - id: US-NOM-002-01
        titulo: Como jefe de RH necesito timbrar recibos de nómina
        criterios_aceptacion:
          - Autorizar nómina calculada
          - Generar XML de cada recibo según estándar SAT
          - Enviar lote a PAC para timbrado
          - Recibir UUID de timbrado
          - Almacenar XML y PDF timbrados
          - Enviar CFDI por email a empleados
      - id: US-NOM-002-02
        titulo: Como contador necesito cancelar CFDIs de nómina
        criterios_aceptacion:
          - Seleccionar CFDI a cancelar
          - Especificar motivo de cancelación
          - Solicitar cancelación al PAC
          - Recibir acuse de cancelación
          - Marcar recibo como cancelado
          - Registrar en bitácora de auditoría
      - id: US-NOM-002-03
        titulo: Como empleado necesito descargar mi CFDI de nómina
        criterios_aceptacion:
          - Ver listado de CFDIs recibidos
          - Descargar XML timbrado
          - Descargar PDF con código QR
          - Verificar autenticidad en portal SAT
      - id: US-NOM-002-04
        titulo: Como jefe de RH necesito procesar nóminas extraordinarias
        criterios_aceptacion:
          - Crear período extraordinario (aguinaldo, PTU, bono)
          - Calcular montos por empleado
          - Generar CFDI con tipo de nómina extraordinaria
          - Timbrar y dispersar
    tablas:
      - payroll_management.cfdi_nomina
      - payroll_management.cfdi_timbrado_log
      - payroll_management.cfdi_cancelaciones
      - payroll_management.nominas_extraordinarias
      - payroll_management.pac_configuration
    endpoints:
      - POST /api/v1/nomina/:periodo_id/timbrar
      - GET /api/v1/nomina/cfdi/:uuid
      - GET /api/v1/nomina/cfdi/:uuid/xml
      - GET /api/v1/nomina/cfdi/:uuid/pdf
      - POST /api/v1/nomina/cfdi/:uuid/cancelar
      - POST /api/v1/nomina/cfdi/:uuid/reenviar-email
      - GET /api/v1/nomina/cfdi/estatus/:uuid
      - POST /api/v1/nomina/extraordinaria
      - GET /api/v1/nomina/pac/saldo-timbres
    componentes_ui:
      - CFDITimbradoPanel
      - CFDIStatusMonitor
      - CFDICancelacionModal
      - CFDIDownloadViewer
      - NominaExtraordinariaForm
      - PACConfigurationPanel
      - TimbradoLogTable
      - CFDIValidationTool
    integraciones:
      - servicio_externo: PAC (Finkok, SW Sapien, etc)
        descripcion: Timbrado y cancelación de CFDIs
      - servicio_externo: SMTP
        descripcion: Envío de CFDIs por email
      - modulo: MGN-007
        descripcion: Auditoría de timbrado y cancelaciones
    estado: pendiente

  - id: RF-NOM-003
    titulo: Deducciones y Percepciones
    descripcion: Gestión completa de conceptos de deducciones y percepciones con cálculos automáticos y manuales
    prioridad: alta
    especificaciones:
      - id: ESP-NOM-003-01
        descripcion: Catálogo de percepciones (salario, tiempo extra, prima dominical, vacaciones, etc)
      - id: ESP-NOM-003-02
        descripcion: Catálogo de deducciones (IMSS, ISR, infonavit, préstamos, pensión alimenticia)
      - id: ESP-NOM-003-03
        descripcion: Configurar fórmulas de cálculo por concepto
      - id: ESP-NOM-003-04
        descripcion: Aplicar deducciones fijas y variables por empleado
      - id: ESP-NOM-003-05
        descripcion: Gestionar préstamos de nómina con amortización automática
      - id: ESP-NOM-003-06
        descripcion: Calcular ISR con tablas y subsidios vigentes
      - id: ESP-NOM-003-07
        descripcion: Calcular IMSS, infonavit y otras cuotas obrero-patronales
      - id: ESP-NOM-003-08
        descripcion: Deducciones judiciales (pensión alimenticia)
    historias_usuario:
      - id: US-NOM-003-01
        titulo: Como jefe de RH necesito gestionar préstamos de empleados
        criterios_aceptacion:
          - Registrar préstamo con monto y plazo
          - Calcular amortización quincenal o mensual
          - Aplicar descuento automático en cada nómina
          - Ver saldo pendiente de cada préstamo
          - Liquidar anticipadamente préstamos
          - Generar reporte de préstamos activos
      - id: US-NOM-003-02
        titulo: Como contador necesito configurar tablas ISR actualizadas
        criterios_aceptacion:
          - Cargar tablas de ISR vigentes por período fiscal
          - Configurar límites inferiores y superiores
          - Definir porcentajes y cuotas fijas
          - Aplicar subsidio al empleo automáticamente
          - Validar cálculo de ISR por empleado
      - id: US-NOM-003-03
        titulo: Como jefe de RH necesito aplicar deducciones especiales
        criterios_aceptacion:
          - Crear deducción manual para un empleado
          - Especificar si es única o recurrente
          - Definir monto fijo o porcentaje
          - Aplicar en período específico
          - Ver histórico de deducciones por empleado
      - id: US-NOM-003-04
        titulo: Como jefe de RH necesito gestionar pensiones alimenticias
        criterios_aceptacion:
          - Registrar orden judicial de pensión
          - Configurar porcentaje o monto fijo a descontar
          - Aplicar automáticamente en cada nómina
          - Generar reporte mensual para autoridad
          - Exportar dispersión a cuenta del acreedor
    tablas:
      - payroll_management.conceptos_percepciones
      - payroll_management.conceptos_deducciones
      - payroll_management.formulas_calculo
      - payroll_management.empleado_percepciones_fijas
      - payroll_management.empleado_deducciones_fijas
      - payroll_management.prestamos_empleados
      - payroll_management.amortizaciones_prestamos
      - payroll_management.tablas_isr
      - payroll_management.pensiones_alimenticias
    endpoints:
      - GET /api/v1/nomina/conceptos/percepciones
      - POST /api/v1/nomina/conceptos/percepciones
      - GET /api/v1/nomina/conceptos/deducciones
      - POST /api/v1/nomina/conceptos/deducciones
      - POST /api/v1/nomina/empleado/:id/prestamo
      - GET /api/v1/nomina/empleado/:id/prestamos
      - PUT /api/v1/nomina/prestamo/:id/liquidar
      - POST /api/v1/nomina/empleado/:id/deduccion-especial
      - GET /api/v1/nomina/empleado/:id/deducciones
      - POST /api/v1/nomina/tablas-isr
      - GET /api/v1/nomina/tablas-isr/vigente
      - POST /api/v1/nomina/empleado/:id/pension-alimenticia
      - GET /api/v1/nomina/pensiones-alimenticias/reporte
    componentes_ui:
      - ConceptosNominaManager
      - FormulaCalculoEditor
      - PrestamosEmpleadoPanel
      - PrestamoFormModal
      - AmortizacionesTable
      - DeduccionEspecialModal
      - TablasISRManager
      - PensionAlimenticiaForm
      - PercepcionesDeduccionesReport
      - CalculadoraISR
    integraciones:
      - modulo: MGN-005
        descripcion: Catálogo de empleados
      - modulo: MAI-001
        descripcion: Vinculación de costos con obras
      - modulo: MGN-010
        descripcion: Provisiones contables de nómina
    estado: pendiente

  - id: RF-NOM-004
    titulo: Finiquitos
    descripcion: Cálculo y generación de finiquitos y liquidaciones por terminación de relación laboral
    prioridad: media
    especificaciones:
      - id: ESP-NOM-004-01
        descripcion: Calcular finiquitos por renuncia voluntaria
      - id: ESP-NOM-004-02
        descripcion: Calcular liquidaciones por despido sin causa
      - id: ESP-NOM-004-03
        descripcion: Calcular indemnizaciones por despido justificado
      - id: ESP-NOM-004-04
        descripcion: Incluir vacaciones no disfrutadas y prima vacacional
      - id: ESP-NOM-004-05
        descripcion: Calcular aguinaldo proporcional
      - id: ESP-NOM-004-06
        descripcion: Aplicar antigüedad para prima de antigüedad
      - id: ESP-NOM-004-07
        descripcion: Generar CFDI de nómina tipo egreso
      - id: ESP-NOM-004-08
        descripcion: Generar documento de finiquito para firma
    historias_usuario:
      - id: US-NOM-004-01
        titulo: Como jefe de RH necesito calcular finiquito por renuncia
        criterios_aceptacion:
          - Seleccionar empleado y fecha de baja
          - Calcular días trabajados del último período
          - Calcular vacaciones pendientes y prima vacacional
          - Calcular aguinaldo proporcional
          - Calcular prima de antigüedad si aplica
          - Ver desglose completo antes de autorizar
      - id: US-NOM-004-02
        titulo: Como jefe de RH necesito procesar liquidación por despido
        criterios_aceptacion:
          - Especificar tipo de terminación (con/sin causa)
          - Calcular indemnización de 3 meses si aplica
          - Calcular 20 días por año de antigüedad
          - Incluir prestaciones proporcionales
          - Generar formato de finiquito
          - Timbrar CFDI de egreso
      - id: US-NOM-004-03
        titulo: Como empleado necesito consultar mi finiquito
        criterios_aceptacion:
          - Ver desglose de conceptos de finiquito
          - Descargar PDF de finiquito
          - Descargar CFDI timbrado
          - Consultar fecha estimada de pago
      - id: US-NOM-004-04
        titulo: Como contador necesito generar reportes de finiquitos
        criterios_aceptacion:
          - Ver finiquitos procesados por período
          - Exportar para póliza contable
          - Generar dispersión de finiquitos
          - Consultar provisiones de finiquitos
    tablas:
      - payroll_management.finiquitos
      - payroll_management.finiquitos_detalle
      - payroll_management.finiquitos_conceptos
      - payroll_management.tipos_terminacion
      - payroll_management.cfdi_finiquitos
    endpoints:
      - POST /api/v1/nomina/finiquito
      - GET /api/v1/nomina/finiquito/:id
      - PUT /api/v1/nomina/finiquito/:id
      - POST /api/v1/nomina/finiquito/:id/calcular
      - POST /api/v1/nomina/finiquito/:id/autorizar
      - POST /api/v1/nomina/finiquito/:id/timbrar
      - GET /api/v1/nomina/finiquito/:id/pdf
      - GET /api/v1/nomina/finiquitos
      - GET /api/v1/nomina/finiquitos/reporte
      - POST /api/v1/nomina/finiquito/:id/dispersar
    componentes_ui:
      - FiniquitoCalculator
      - FiniquitoFormWizard
      - FiniquitoDetailView
      - FiniquitoConceptosTable
      - FiniquitoPDFGenerator
      - FiniquitosListView
      - TipoTerminacionSelector
      - FiniquitoAutorizacionPanel
    integraciones:
      - modulo: RF-NOM-002
        descripcion: Timbrado de CFDI de finiquito
      - modulo: MGN-005
        descripcion: Catálogo de empleados
      - modulo: MGN-010
        descripcion: Registro contable de finiquitos
      - modulo: MGN-007
        descripcion: Auditoría de bajas y finiquitos
    estado: pendiente

  - id: RF-NOM-005
    titulo: Integración Checador Biométrico
    descripcion: Integración con app móvil de checador biométrico para control de asistencias y cálculo de nómina
    prioridad: alta
    especificaciones:
      - id: ESP-NOM-005-01
        descripcion: Importar asistencias desde checador biométrico (MOB-001)
      - id: ESP-NOM-005-02
        descripcion: Procesar entradas y salidas diarias
      - id: ESP-NOM-005-03
        descripcion: Calcular horas trabajadas por día y semana
      - id: ESP-NOM-005-04
        descripcion: Identificar retardos según tolerancia configurada
      - id: ESP-NOM-005-05
        descripcion: Detectar faltas injustificadas
      - id: ESP-NOM-005-06
        descripcion: Calcular tiempo extra automáticamente
      - id: ESP-NOM-005-07
        descripcion: Gestionar incidencias (permisos, vacaciones, incapacidades)
      - id: ESP-NOM-005-08
        descripcion: Sincronización bidireccional con app móvil
      - id: ESP-NOM-005-09
        descripcion: Reportes de asistencia por empleado y obra
    historias_usuario:
      - id: US-NOM-005-01
        titulo: Como jefe de RH necesito importar asistencias del checador
        criterios_aceptacion:
          - Conectar con MOB-001 vía API
          - Importar registros de entrada/salida por período
          - Validar integridad de datos importados
          - Detectar registros duplicados o inconsistentes
          - Ver resumen de asistencias importadas
      - id: US-NOM-005-02
        titulo: Como jefe de RH necesito revisar incidencias detectadas
        criterios_aceptacion:
          - Ver listado de retardos del período
          - Ver listado de faltas injustificadas
          - Ver tiempo extra acumulado por empleado
          - Ajustar o justificar incidencias manualmente
          - Aprobar incidencias para cálculo de nómina
      - id: US-NOM-005-03
        titulo: Como residente de obra necesito gestionar incidencias en checador móvil
        criterios_aceptacion:
          - Registrar permisos desde MOB-001
          - Justificar retardos o faltas
          - Aprobar salidas anticipadas
          - Sincronizar con sistema de nómina
      - id: US-NOM-005-04
        titulo: Como jefe de RH necesito generar reportes de asistencia
        criterios_aceptacion:
          - Reporte de asistencias por empleado
          - Reporte de puntualidad por obra
          - Reporte de tiempo extra por departamento
          - Exportar a Excel para análisis
          - Filtrar por fechas, obra, empleado
      - id: US-NOM-005-05
        titulo: Como empleado necesito consultar mis asistencias desde app móvil
        criterios_aceptacion:
          - Ver mis entradas/salidas del mes (MOB-001)
          - Consultar saldo de vacaciones
          - Ver incidencias reportadas
          - Solicitar corrección de registro erróneo
    tablas:
      - payroll_management.asistencias
      - payroll_management.registros_checador
      - payroll_management.incidencias
      - payroll_management.tipo_incidencia
      - payroll_management.horarios_trabajo
      - payroll_management.tolerancia_retardos
      - payroll_management.horas_extra_calculadas
    endpoints:
      - POST /api/v1/nomina/asistencias/importar
      - GET /api/v1/nomina/asistencias
      - GET /api/v1/nomina/asistencias/empleado/:id
      - GET /api/v1/nomina/asistencias/periodo/:periodo_id
      - POST /api/v1/nomina/incidencias
      - GET /api/v1/nomina/incidencias
      - PUT /api/v1/nomina/incidencias/:id
      - DELETE /api/v1/nomina/incidencias/:id
      - POST /api/v1/nomina/incidencias/:id/aprobar
      - GET /api/v1/nomina/tiempo-extra/calculado
      - GET /api/v1/nomina/reportes/asistencia
      - GET /api/v1/nomina/reportes/puntualidad
      - POST /api/v1/nomina/horarios
      - GET /api/v1/nomina/horarios
    componentes_ui:
      - AsistenciasImportPanel
      - AsistenciasListView
      - IncidenciasManager
      - IncidenciaFormModal
      - TiempoExtraReport
      - AsistenciasPorEmpleadoView
      - PuntualidadChart
      - HorariosTrabajoCRUD
      - ToleranciaConfigPanel
      - RegistrosChecadorTable
    app_movil: MOB-001
    funcionalidades_movil:
      - Registro biométrico de entrada/salida
      - Registro de ubicación GPS
      - Foto de evidencia en check-in
      - Solicitud de permisos e incidencias
      - Consulta de asistencias personales
      - Notificaciones de incidencias
      - Modo offline con sincronización
    integraciones:
      - modulo: MOB-001
        descripcion: Importación de registros de checador biométrico
        tipo: bidireccional
        endpoints:
          - GET /api/v1/checador/registros
          - POST /api/v1/checador/incidencias
          - GET /api/v1/checador/empleado/:id/asistencias
      - modulo: RF-NOM-001
        descripcion: Provisión de horas trabajadas para cálculo de nómina
      - modulo: MAI-001
        descripcion: Vinculación de asistencias con obras de construcción
      - modulo: MGN-008
        descripcion: Notificaciones de incidencias y aprobaciones
    estado: pendiente

# Aplicación Móvil
app_movil:
  id: MOB-001
  nombre: Checador Biométrico
  descripcion: Aplicación móvil para registro de asistencias con verificación biométrica
  plataformas:
    - Android
    - iOS
  tecnologias:
    - React Native
    - Expo
    - SQLite (offline)
    - Axios (sync)
    - React Native Biometrics
    - React Native Geolocation
  funcionalidades:
    - autenticacion_biometrica: Verificación por huella digital o reconocimiento facial
    - registro_entrada_salida: Check-in/check-out con timestamp
    - captura_ubicacion: GPS y geofencing por obra
    - foto_evidencia: Captura de foto en cada registro
    - consulta_asistencias: Historial personal de asistencias
    - gestion_incidencias: Solicitud de permisos y justificaciones
    - notificaciones_push: Alertas de aprobaciones y rechazos
    - sincronizacion: Sync automática y manual con backend
    - modo_offline: Operación sin conexión con queue de sincronización
  requerimientos_vinculados:
    - RF-NOM-005 # Integración Checador Biométrico
    - RF-NOM-001 # Provisión de datos para cálculo de nómina
  estado: pendiente

# Esquemas de Base de Datos
esquemas:
  - nombre: payroll_management
    descripcion: Esquema para gestión integral de nómina
    tablas:
      # RF-NOM-001: Cálculo de Nómina
      - periodos_nomina
      - nominas
      - nominas_detalle
      - nominas_percepciones
      - nominas_deducciones
      - nominas_provision_patronal
      - dispersiones_bancarias
      # RF-NOM-002: Timbrado CFDI
      - cfdi_nomina
      - cfdi_timbrado_log
      - cfdi_cancelaciones
      - nominas_extraordinarias
      - pac_configuration
      # RF-NOM-003: Deducciones y Percepciones
      - conceptos_percepciones
      - conceptos_deducciones
      - formulas_calculo
      - empleado_percepciones_fijas
      - empleado_deducciones_fijas
      - prestamos_empleados
      - amortizaciones_prestamos
      - tablas_isr
      - pensiones_alimenticias
      # RF-NOM-004: Finiquitos
      - finiquitos
      - finiquitos_detalle
      - finiquitos_conceptos
      - tipos_terminacion
      - cfdi_finiquitos
      # RF-NOM-005: Integración Checador
      - asistencias
      - registros_checador
      - incidencias
      - tipo_incidencia
      - horarios_trabajo
      - tolerancia_retardos
      - horas_extra_calculadas

# Políticas RLS
rls_policies:
  archivo: ET-NOM-rls-policies.sql
  descripcion: Políticas de seguridad a nivel de fila para multi-tenancy en nómina
  tablas_protegidas:
    - payroll_management.nominas
    - payroll_management.cfdi_nomina
    - payroll_management.asistencias
    - payroll_management.finiquitos
    - payroll_management.prestamos_empleados
  reglas:
    - Los empleados solo pueden ver sus propios recibos
    - RH puede ver nómina de su constructora/tenant
    - Contador puede acceder a información fiscal
    - Aislamiento total entre diferentes constructoras

# Reportes
reportes:
  - id: REP-NOM-001
    nombre: Recibo de Nómina Individual
    descripcion: Recibo detallado de nómina por empleado
    parametros: [empleado_id, periodo_id]
  - id: REP-NOM-002
    nombre: Resumen de Nómina por Período
    descripcion: Consolidado de nómina con totales por concepto
    parametros: [periodo_id, obra_id]
  - id: REP-NOM-003
    nombre: Dispersión Bancaria
    descripcion: Archivo de dispersión en formato bancario
    parametros: [periodo_id, formato_banco]
  - id: REP-NOM-004
    nombre: Provisión de Cuotas Patronales
    descripcion: Cálculo de IMSS, infonavit, SAR para provisiones
    parametros: [periodo_id]
  - id: REP-NOM-005
    nombre: Reporte de Tiempo Extra
    descripcion: Detalle de horas extra por empleado y obra
    parametros: [fecha_inicio, fecha_fin, obra_id]
  - id: REP-NOM-006
    nombre: Histórico de Préstamos
    descripcion: Préstamos activos y liquidados con saldos
    parametros: [empleado_id, estado]
  - id: REP-NOM-007
    nombre: Reporte de Finiquitos
    descripcion: Finiquitos procesados en período
    parametros: [fecha_inicio, fecha_fin, tipo_terminacion]
  - id: REP-NOM-008
    nombre: Reporte de Asistencias
    descripcion: Asistencias, retardos y faltas por empleado
    parametros: [fecha_inicio, fecha_fin, empleado_id, obra_id]
  - id: REP-NOM-009
    nombre: Análisis de Puntualidad
    descripcion: Indicadores de puntualidad por obra y departamento
    parametros: [fecha_inicio, fecha_fin, obra_id]
  - id: REP-NOM-010
    nombre: Costo de Nómina por Obra
    descripcion: Distribución de costo de nómina por proyecto
    parametros: [periodo_id, obra_id]

# Notificaciones
notificaciones:
  - evento: nomina_calculada
    destinatarios: [jefe_rh, contador]
    canal: [email, app]
  - evento: nomina_autorizada
    destinatarios: [contador, empleados]
    canal: [email, app]
  - evento: cfdi_timbrado
    destinatarios: [empleado]
    canal: [email]
  - evento: dispersion_generada
    destinatarios: [contador, jefe_rh]
    canal: [email]
  - evento: prestamo_otorgado
    destinatarios: [empleado, jefe_rh]
    canal: [email, app]
  - evento: finiquito_calculado
    destinatarios: [empleado, jefe_rh, contador]
    canal: [email]
  - evento: incidencia_pendiente
    destinatarios: [jefe_rh, residente_obra]
    canal: [app, push_movil]
  - evento: retardo_detectado
    destinatarios: [empleado, supervisor]
    canal: [app]
  - evento: falta_registrada
    destinatarios: [empleado, jefe_rh]
    canal: [email, app]
  - evento: tiempo_extra_aprobacion
    destinatarios: [jefe_rh]
    canal: [app]

# Métricas y KPIs
metricas:
  - nombre: tiempo_procesamiento_nomina
    descripcion: Tiempo promedio para calcular y autorizar nómina
    unidad: horas
    objetivo: "< 4 horas"
  - nombre: tasa_timbrado_exitoso
    descripcion: Porcentaje de CFDIs timbrados sin error
    unidad: porcentaje
    objetivo: "> 99%"
  - nombre: morosidad_prestamos
    descripcion: Porcentaje de préstamos con atrasos
    unidad: porcentaje
    objetivo: "< 5%"
  - nombre: tasa_puntualidad
    descripcion: Porcentaje de empleados sin retardos
    unidad: porcentaje
    objetivo: "> 85%"
  - nombre: ausentismo
    descripcion: Porcentaje de faltas injustificadas
    unidad: porcentaje
    objetivo: "< 3%"
  - nombre: tiempo_extra_acumulado
    descripcion: Promedio de horas extra por empleado
    unidad: horas/mes
    objetivo: "< 20 horas"
  - nombre: costo_nomina_vs_presupuesto
    descripcion: Desviación del costo de nómina vs presupuestado
    unidad: porcentaje
    objetivo: "< 5%"

# Validaciones y Reglas de Negocio
reglas_negocio:
  - codigo: RN-NOM-001
    descripcion: No se puede autorizar nómina sin validar totales
  - codigo: RN-NOM-002
    descripcion: Los CFDIs deben timbrarse antes de dispersión bancaria
  - codigo: RN-NOM-003
    descripcion: El ISR se calcula según tablas vigentes del SAT
  - codigo: RN-NOM-004
    descripcion: Los préstamos no pueden exceder 4 meses de salario
  - codigo: RN-NOM-005
    descripcion: La amortización de préstamo no puede exceder 30% del salario neto
  - codigo: RN-NOM-006
    descripcion: Los finiquitos deben incluir vacaciones y aguinaldo proporcional
  - codigo: RN-NOM-007
    descripcion: Las asistencias deben importarse desde MOB-001 para evitar manipulación
  - codigo: RN-NOM-008
    descripcion: El tiempo extra doble aplica después de 9 horas o en día de descanso
  - codigo: RN-NOM-009
    descripcion: Las incidencias deben ser aprobadas por supervisor antes de cálculo
  - codigo: RN-NOM-010
    descripcion: Los registros de checador con ubicación fuera de geofence requieren justificación

# Seguridad
seguridad:
  permisos:
    - nomina.periodos.crear
    - nomina.periodos.leer
    - nomina.nomina.calcular
    - nomina.nomina.validar
    - nomina.nomina.autorizar
    - nomina.nomina.dispersar
    - nomina.cfdi.timbrar
    - nomina.cfdi.cancelar
    - nomina.cfdi.consultar
    - nomina.conceptos.gestionar
    - nomina.prestamos.crear
    - nomina.prestamos.aprobar
    - nomina.prestamos.consultar
    - nomina.finiquitos.calcular
    - nomina.finiquitos.autorizar
    - nomina.asistencias.importar
    - nomina.asistencias.consultar
    - nomina.incidencias.gestionar
    - nomina.incidencias.aprobar
    - nomina.reportes.generar
    - nomina.empleado.ver_propios_recibos
  roles_sugeridos:
    - nombre: jefe_rh
      permisos: [nomina.*, asistencias.*, incidencias.*, prestamos.*, finiquitos.*]
    - nombre: contador
      permisos: [nomina.autorizar, nomina.dispersar, nomina.cfdi.*, nomina.reportes.*]
    - nombre: empleado
      permisos: [nomina.empleado.ver_propios_recibos, asistencias.consultar_propias]
    - nombre: residente_obra
      permisos: [incidencias.gestionar, asistencias.consultar]
    - nombre: auditor
      permisos: [nomina.reportes.generar, cfdi.consultar, finiquitos.consultar]

# Pruebas
pruebas:
  unitarias:
    - calcular_isr_con_tablas_sat
    - calcular_tiempo_extra_simple_doble
    - calcular_aguinaldo_proporcional
    - calcular_prima_antiguedad
    - amortizar_prestamo_empleado
    - validar_existencia_suficiente_para_prestamo
    - aplicar_pension_alimenticia
    - calcular_cuotas_imss_infonavit
  integracion:
    - flujo_completo_calculo_nomina
    - importacion_asistencias_desde_mob001
    - timbrado_cfdi_con_pac
    - generacion_dispersion_bancaria
    - calculo_finiquito_completo
    - sincronizacion_bidireccional_checador
  e2e:
    - proceso_nomina_completo_calculo_a_pago
    - ciclo_vida_prestamo_empleado
    - proceso_finiquito_con_timbrado
    - registro_asistencia_app_a_nomina

# Cronograma Estimado
cronograma:
  - fase: Análisis y Diseño
    duracion: 2 semanas
    entregables: [modelos_datos, diagramas_flujo, especificaciones_api, integracion_pac]
  - fase: Desarrollo Backend - RF-NOM-001 y RF-NOM-003
    duracion: 4 semanas
    entregables: [api_calculo_nomina, api_conceptos, calculos_isr_imss, rls_policies]
  - fase: Desarrollo Backend - RF-NOM-002
    duracion: 2 semanas
    entregables: [integracion_pac, generacion_xml_cfdi, timbrado_automatico]
  - fase: Desarrollo Backend - RF-NOM-004 y RF-NOM-005
    duracion: 3 semanas
    entregables: [api_finiquitos, api_asistencias, integracion_mob001]
  - fase: Desarrollo Frontend
    duracion: 4 semanas
    entregables: [ui_nomina, ui_cfdi, ui_prestamos, ui_finiquitos, ui_asistencias]
  - fase: Desarrollo App Móvil MOB-001
    duracion: 4 semanas
    entregables: [app_checador, biometria, geofencing, sincronizacion]
  - fase: Integración PAC y Pruebas
    duracion: 2 semanas
    entregables: [pruebas_timbrado, pruebas_integracion, validacion_sat]
  - fase: Pruebas de Usuario y Ajustes
    duracion: 2 semanas
    entregables: [pruebas_usuario, ajustes_feedback, optimizaciones]
  - fase: Documentación y Capacitación
    duracion: 1 semana
    entregables: [manual_usuario, manual_tecnico, videos_capacitacion]

# Notas de Implementación
notas:
  - Priorizar RF-NOM-001 (Cálculo) y RF-NOM-005 (Checador) como base del módulo
  - Integración con PAC debe ser configurable para múltiples proveedores
  - Desarrollar MOB-001 (Checador Biométrico) en paralelo con backend de asistencias
  - Implementar caché de tablas ISR para optimizar cálculos
  - Considerar migración de datos históricos de sistema legacy
  - Planificar sincronización offline-online robusta para MOB-001
  - Validar cumplimiento normativo SAT antes de producción
  - Implementar auditoría completa de todas las operaciones de nómina
  - Considerar integración futura con bancos para confirmación de dispersión
  - Evaluar uso de firma electrónica para autorización de nómina
  - El módulo MOB-001 es crítico para la integridad de datos de asistencias
  - Implementar geofencing estricto para evitar registros fraudulentos
  - Considerar funcionalidad de nómina retroactiva para ajustes
