Guía de Operación: Lista de Conceptos v2 (Global Payroll)
  • Identificarse

    • Guía de Operación: Lista de Conceptos v2 (Global Payroll)

    • modulo: Nómina (Global Payroll)
    • version_producto: v2.0.0
    • audiencia: Administrador de Nómina, Gestor de Nómina, Especialista de TI/Soporte
    • ultima_actualizacion: 2026-05-28
    • palabras_clave: concepts_list2, Administración de Conceptos, Subscription Sources, Flipper, SWAT, Rankmi

    2. PROPÓSITO

    Este feature unifica y moderniza la pestaña "Lista" en la administración de conceptos de nómina, reemplazando las antiguas tablas individuales por país con un componente único y optimizado. Resuelve la falta de herramientas de búsqueda avanzada y la desconexión operativa en la suscripción de catálogos maestros para clientes multi-país. Debe usarse para realizar búsquedas avanzadas (por fórmulas, segmentos o procesos), gestionar suscripciones de conceptos a nivel tenant y agilizar la navegación diaria; NO debe usarse para configurar las fórmulas propiamente tales ni para realizar el mapeo legal físico (LRE/DJ), tareas que ocurren dentro de la ficha de edición y en la pestaña complementaria de "Clasificación" respectivamente.

    3. CONCEPTOS CLAVE

    Feature Flag concepts_list2: Interruptor de software gestionado vía Flipper que determina, a nivel de Tenant, si se renderiza la nueva interfaz unificada (v2) o el listado heredado por país (v1).

    Subscription Sources: Arquitectura del sistema que permite a ciertos tenants actuar como suscriptores de un catálogo maestro de conceptos, habilitando funciones de sincronización y logs de errores específicos en el listado.

    Vista Dual (Tarjetas/Lista): Modalidad de visualización que permite alternar entre un diseño resumido de tarjetas (para escaneo visual rápido de fórmulas y etiquetas) y una tabla tradicional con columnas ordenables.

    Persistencia de Filtros (URL Sync): Sincronización automática de los parámetros de búsqueda, paginación, ordenamiento y modo de vista directamente con la query string de la URL (?tab=list&name=...), posibilitando compartir enlaces directos con el mismo contexto exacto.

    Pestaña Clasificación: Sección independiente de la lista de conceptos (que no depende del flag concepts_list2) diseñada para asociar conceptos de nómina a códigos de servicios externos mediante interacciones de arrastrar y soltar (drag & drop).

    4. PRERREQUISITOS

    1. El Tenant debe tener activo el feature flag concepts_list2 habilitado en consola SWAT (u otra vía autorizada de base de datos/API).
    2. El usuario debe contar con permisos mínimos de lectura (para visualización y búsqueda) o escritura (para creación, edición y suscripción de conceptos) dentro del módulo de administración de nómina (hasReadOnlyPermissions o hasWritePermissions).
    3. Para visualizar las opciones asociadas a suscripciones (columnas, filtros y sync logs), el Tenant debe tener configurada una suscripción activa bajo el modelo de Subscription Sources.
    4. Para interactuar con los conmutadores de suscripción individual y la acción de "Suscribir todos", el usuario debe poseer el rol de administrador del sistema (role.name === 'admin').

    5. PASOS DE USO

    Paso 1 — Activación Técnica del Feature (SWAT)

    • Acción: Habilitar el feature flag para el tenant específico.
    • Ubicación en el sistema: Consola de Administración SWAT > Feature Flags (/rankmi_swat/feature_flags).
    • Campos requeridos:
      • Flag: concepts_list2 (Texto, clave única)
      • Acción: "Enable" (Botón de activación)
    • Campos opcionales: Ninguno.
    • Resultado esperado: El feature flag queda activado para el tenant activo en la sesión SWAT actual. La base de datos registra la habilitación y la API pública responde de forma afirmativa al consultar el estado de la clave.

    Paso 2 — Navegación y Filtrado Avanzado

    • Acción: Filtrar y buscar conceptos de nómina mediante la barra de filtros avanzada lateral.
    • Ubicación en el sistema: Nómina > Administración > Conceptos (pestaña "Lista"). Ruta de URL: /payroll-app/countries/{legislation}/administration-concepts?tab=list.
    • Campos requeridos: Ninguno (la visualización por defecto carga la totalidad de los conceptos activos).
    • Campos opcionales:
      • Nombre/Código: Cadena de texto para buscar coincidencias.
      • Fórmula: Fragmento de código o texto a buscar dentro de la lógica del concepto (formula_cont).
      • Tipo de valor: Selección múltiple de tipo de dato (Manual, Fórmula, Fijo, Aprobable).
      • Proceso de nómina: Selección de procesos vinculados.
      • Categoría: Casillas de verificación correspondientes a la clasificación del concepto (las etiquetas varían según la legislación, ej: Haberes/Descuentos en CL, o Percepciones/Deducciones en MX).
      • Segmentos: Casillas de selección múltiple (incluyendo la opción "Sin segmento").
      • Estado: Selector excluyente (Activo, Inactivo, Todos).
    • Resultado esperado: La lista o cuadrícula de tarjetas se actualiza en tiempo real de acuerdo a los criterios aplicados. La barra de direcciones URL se actualiza automáticamente conteniendo los parámetros utilizados para facilitar la posterior compartición del enlace.

    Paso 3 — Gestión de Suscripción de Conceptos (Solo Tenants con Subscription Sources)

    • Acción: Suscribir conceptos específicos del catálogo maestro de manera individual o masiva y auditar la sincronización.
    • Ubicación en el sistema: Nómina > Administración > Conceptos (pestaña "Lista", columna o controles de suscripción).
    • Campos requeridos: Ninguno.
    • Campos opcionales:
      • Switch de suscripción: Botón tipo toggle ubicado en cada fila/tarjeta de concepto.
      • Suscribir todos: Botón de acción masiva en la parte superior derecha de la interfaz de la lista.
    • Resultado esperado: Al activar la suscripción de un concepto de forma individual o masiva, se realiza la llamada correspondiente a la API (PATCH /concepts/:id/subscription o POST /concepts/subscribe_all). Se sincronizan los metadatos del concepto maestro y, en caso de fallo, los detalles quedan registrados y visibles en el panel lateral de "Últimas sincronizaciones" con su respectivo código y descripción de error.

    Paso 4 — Asociación de Conceptos a Servicios Externos (Pestaña Clasificación)

    • Acción: Mapear conceptos de nómina a clasificaciones de entidades u órganos regulatorios externos (ej: LRE, DJ, clasificaciones fiscales).
    • Ubicación en el sistema: Nómina > Administración > Conceptos > Pestaña "Clasificación" (independiente del flag de la v2).
    • Campos requeridos:
      • Concepto de origen: Tarjeta de concepto disponible en la columna izquierda.
      • Servicio externo: Destino o contenedor clasificado en la sección derecha del panel (external_service_values).
    • Campos opcionales: Ninguno.
    • Resultado esperado: El usuario arrastra el concepto y lo suelta en el casillero correspondiente del servicio externo. La API procesa la asociación (POST /createAssociation), actualizando de inmediato la UI. Es posible deshacer la asociación eliminando la tarjeta mapeada (DELETE /deleteAssociation).