Appearance
Enriquecimiento y Consultas Avanzadas de Miembros
Modulo: Membresias Tipo: Process Estado: Implementado Fecha: 2026-01-27
Descripcion
Problema que resuelve
El modulo de membresias gestiona informacion de miembros que esta distribuida en multiples entidades de negocio: datos basicos del miembro, categoria de membresia, disciplinas asignadas, productos asociados y datos extendidos del grupo familiar. Sin un mecanismo inteligente de consulta, cada vista o proceso que necesita informacion de miembros enfrenta los siguientes problemas:
- Exceso de datos: Las consultas siempre devuelven toda la informacion del miembro, incluso cuando solo se necesitan datos basicos (nombre, identificacion, estado)
- Multiples consultas por miembro: Para mostrar un listado de 50 miembros con sus categorias, disciplinas y productos, el sistema deberia ejecutar cientos de consultas individuales
- Dificultad para filtrar: Los usuarios necesitan localizar miembros por multiples criterios simultaneos (estado, categoria, disciplinas, productos, busqueda de texto) y el sistema no ofrece un mecanismo unificado
- Rendimiento degradado: Sin optimizacion de carga, los listados de miembros se vuelven lentos a medida que crece la base de socios
Solucion implementada
Se implementa un sistema dual de enriquecimiento inteligente y filtrado avanzado que permite:
- Enriquecimiento por alcance (scope): Controlar la profundidad de datos devueltos segun la necesidad del consumidor
- Enriquecimiento selectivo (include): Solicitar solo las relaciones necesarias (categoria, disciplinas, productos) con sus propios sub-alcances
- Carga por lotes (batch): Obtener datos relacionados de multiples miembros en consultas agrupadas en lugar de individuales
- Filtrado avanzado: Combinar multiples criterios de busqueda con paginacion del lado del servidor
Valor de negocio
- Tiempos de respuesta optimizados: Los listados de miembros cargan significativamente mas rapido al solicitar solo los datos necesarios
- Experiencia de usuario mejorada: Los usuarios pueden localizar miembros rapidamente usando multiples filtros combinados
- Escalabilidad: El sistema mantiene buen rendimiento al crecer la base de socios
- Flexibilidad: Cada pantalla o proceso solicita exactamente la informacion que necesita, sin exceso ni carencia de datos
Contexto del sistema
Esta funcionalidad es transversal al modulo de membresias y es utilizada por:
- Listado de miembros: Vista principal con paginacion y filtros
- Gestion de grupos familiares: Busqueda y seleccion de miembros
- Facturacion por lotes: Obtencion de miembros activos con sus productos y categorias
- Integraciones con otros modulos: Ventas, CtaCte y CRM cuando consultan datos de miembros
Proceso de Negocio
Componente 1: Enriquecimiento de Miembro
El enriquecimiento permite obtener datos de un miembro en diferentes niveles de detalle segun el contexto de uso.
Niveles de alcance (scope)
| Alcance | Datos incluidos | Uso tipico |
|---|---|---|
| Minimo | Solo datos basicos del miembro (nombre, identificacion, estado, fecha de alta) | Listados, selectores, busquedas rapidas |
| Maximo | Datos basicos + datos extendidos de membresia (informacion adicional del contribuyente) | Vista de detalle del miembro, edicion |
Datos relacionados incluibles (include)
Ademas del alcance, se puede solicitar la inclusion selectiva de las siguientes entidades relacionadas:
| Relacion | Descripcion | Cuando se necesita |
|---|---|---|
| Categoria | Categoria de membresia asignada al miembro (con su producto base y listas de precio) | Vista de detalle, facturacion, reportes |
| Disciplinas | Disciplinas o actividades en las que participa el miembro (con signo, tipo y valor de ajuste) | Gestion de disciplinas, vista de detalle |
| Productos | Productos asociados al miembro con sus ajustes de precio individuales | Facturacion, vista de detalle, reportes |
Cada relacion incluida puede a su vez tener su propio alcance y sub-relaciones, formando un arbol de inclusion. Por ejemplo, se puede solicitar la categoria con su producto asociado en alcance maximo.
Verificacion de funcionalidad de disciplinas
Antes de enriquecer con disciplinas, el sistema verifica si la empresa tiene habilitada la funcionalidad de disciplinas. Si no esta habilitada, se devuelve una lista vacia de disciplinas sin realizar consultas adicionales. Esta verificacion se realiza una sola vez por solicitud.
Componente 2: Carga por Lotes (Batch Loading)
Para evitar el problema de multiples consultas individuales al cargar listados, el sistema agrupa las consultas de datos relacionados:
Flujo de carga por lotes:
- Se obtiene el listado de miembros segun los filtros aplicados
- Se recolectan todos los identificadores de miembros del listado
- Se ejecuta UNA consulta para obtener todas las relaciones categoria-miembro
- Se ejecuta UNA consulta para obtener todas las relaciones disciplina-miembro
- Se ejecuta UNA consulta para obtener todas las relaciones producto-miembro
- Se recolectan los identificadores unicos de categorias, disciplinas y productos referenciados
- Se ejecuta UNA consulta por cada tipo de entidad para obtener sus datos completos
- Se mapean los resultados a cada miembro del listado
Resultado: En lugar de ejecutar N consultas por cada miembro (donde N es la cantidad de relaciones), se ejecutan un numero fijo de consultas agrupadas independientemente de la cantidad de miembros.
Componente 3: Filtros Avanzados de Miembros
El sistema de filtrado permite combinar multiples criterios para localizar miembros.
Filtros disponibles
| Filtro | Descripcion | Valores posibles |
|---|---|---|
| Estado de membresia | Filtrar por estado actual del miembro | Todos, Activos, Inactivos (dados de baja), No socios |
| Categoria | Filtrar por categoria de membresia asignada | Cualquier categoria configurada |
| Disciplinas | Filtrar por disciplinas en las que participa | Cualquier disciplina configurada |
| Productos | Filtrar por productos asociados | Cualquier producto configurado |
| Busqueda global | Busqueda por texto libre en nombre e identificacion | Texto libre |
| Ordenamiento | Ordenar resultados por cualquier columna | Ascendente o descendente por columna |
Paginacion del lado del servidor
Todos los listados de miembros con filtros utilizan paginacion del lado del servidor:
- El usuario define el tamano de pagina y navega entre paginas
- Solo se consultan los registros de la pagina actual
- El sistema devuelve el total de registros que coinciden con los filtros para mostrar la paginacion completa
- Los filtros se aplican antes de paginar para mostrar totales precisos
Frontend (Perspectiva de Usuario)
Vistas
Listado de miembros con filtros avanzados
- Tabla paginada con los datos de miembros
- Panel de filtros con selectores para estado, categoria, disciplinas y productos
- Campo de busqueda global para buscar por nombre o identificacion
- Controles de ordenamiento por columna
- Indicador de total de resultados y pagina actual
Vista de detalle de miembro
- Muestra toda la informacion del miembro con alcance maximo
- Incluye categoria asignada, disciplinas y productos con sus ajustes
- Datos extendidos de membresia
Interacciones del usuario
- Filtrar por estado: El usuario selecciona un estado (Todos, Activos, Inactivos, No socios) y el listado se actualiza automaticamente
- Filtrar por categoria: El usuario selecciona una categoria del selector y solo se muestran miembros de esa categoria
- Filtrar por disciplinas: El usuario selecciona una o mas disciplinas y se muestran miembros que participan en ellas
- Filtrar por productos: El usuario selecciona uno o mas productos y se muestran miembros que los tienen asignados
- Buscar por texto: El usuario escribe en el campo de busqueda y el sistema filtra por coincidencia en nombre o identificacion
- Ordenar por columna: El usuario hace clic en el encabezado de una columna para ordenar ascendente o descendente
- Navegar entre paginas: El usuario avanza o retrocede en las paginas del listado
- Ver detalle de miembro: El usuario selecciona un miembro y visualiza toda su informacion enriquecida
Estados de UI
- Cargando: Indicador de carga mientras se obtienen los datos filtrados
- Sin resultados: Mensaje informativo cuando los filtros no devuelven resultados
- Error de conexion: Mensaje de error si no se puede obtener la informacion
- Datos cargados: Tabla poblada con los datos del miembro y la paginacion visible
Backend (Perspectiva de Datos de Negocio)
Entidades de negocio involucradas
Miembro
Entidad principal que representa a un socio o contribuyente del sistema de membresias.
| Dato de negocio | Descripcion |
|---|---|
| Datos basicos | Nombre, identificacion, estado, fecha de alta |
| Datos extendidos | Informacion adicional de membresia del contribuyente |
| Estado de membresia | Activo, Inactivo (dado de baja), No socio |
Categoria de Membresia
Clasificacion del miembro segun su tipo de membresia.
| Dato de negocio | Descripcion |
|---|---|
| Nombre | Nombre de la categoria |
| Producto base | Producto asociado a la categoria para facturacion |
Disciplina
Actividad o disciplina deportiva en la que participa el miembro.
| Dato de negocio | Descripcion |
|---|---|
| Nombre | Nombre de la disciplina |
| Signo | Indica si el ajuste es incremento (+) o descuento (-) |
| Tipo de ajuste | Porcentaje (P) o valor fijo (F) |
| Valor | Monto o porcentaje del ajuste |
Producto Asociado
Producto vinculado al miembro con ajustes de precio individuales.
| Dato de negocio | Descripcion |
|---|---|
| Nombre | Nombre del producto |
| Signo | Indica si el ajuste es incremento (+) o descuento (-) |
| Tipo de ajuste | Porcentaje (P) o valor fijo (F) |
| Valor | Monto o porcentaje del ajuste |
| Listas de precio | Precios del producto en cada lista de precios |
Relaciones de negocio
- Un miembro puede tener una categoria de membresia asignada
- Un miembro puede participar en multiples disciplinas
- Un miembro puede tener multiples productos asociados con ajustes individuales
- Una categoria tiene un producto base asociado para facturacion
- Las disciplinas pueden estar habilitadas o deshabilitadas a nivel de empresa
Validaciones de negocio
| Validacion | Descripcion |
|---|---|
| Habilitacion de disciplinas | Solo se consultan disciplinas si la empresa tiene habilitada esta funcionalidad |
| Alcance valido | El alcance solicitado debe ser uno de los valores permitidos (minimo o maximo) |
| Filtro de estado valido | El estado de membresia debe ser uno de los valores permitidos (Todos, Activos, Inactivos, No socios) |
Reglas de Negocio
RN-001: Enriquecimiento segun alcance solicitado
Descripcion: Los datos devueltos del miembro varian segun el alcance solicitado. Con alcance minimo solo se devuelven datos basicos; con alcance maximo se incluyen ademas los datos extendidos de membresia.
Condicion: Se solicita informacion de uno o mas miembros.
Accion:
- Si el alcance es minimo: devolver solo datos basicos (nombre, identificacion, estado)
- Si el alcance es maximo: devolver datos basicos + datos extendidos de membresia
RN-002: Inclusion selectiva de relaciones
Descripcion: Las relaciones del miembro (categoria, disciplinas, productos) solo se cargan si son explicitamente solicitadas. Cada relacion puede tener su propio alcance y sub-relaciones.
Condicion: Se solicita informacion de miembros con relaciones especificas.
Accion:
- Cargar solo las relaciones solicitadas
- Aplicar el alcance especificado a cada relacion
- Propagar sub-relaciones en profundidad segun el arbol de inclusion
RN-003: Verificacion de habilitacion de disciplinas
Descripcion: Las disciplinas solo se cargan si la empresa tiene habilitada esta funcionalidad. Si no esta habilitada, se devuelve una lista vacia sin ejecutar consultas.
Condicion: Se solicita inclusion de disciplinas para miembros.
Accion:
- Verificar si la empresa tiene habilitada la funcionalidad de disciplinas
- Si esta habilitada: cargar disciplinas normalmente
- Si no esta habilitada: devolver lista vacia de disciplinas para cada miembro
RN-004: Carga por lotes para listados
Descripcion: Cuando se consultan multiples miembros, los datos relacionados se obtienen en consultas agrupadas por tipo de relacion en lugar de consultas individuales por miembro.
Condicion: Se solicita un listado de miembros con relaciones incluidas.
Accion:
- Recolectar todos los identificadores de miembros del listado
- Ejecutar una consulta agrupada por cada tipo de relacion solicitada
- Mapear los resultados a cada miembro correspondiente
RN-005: Filtros combinables
Descripcion: Los filtros de miembros son combinables entre si. Todos los filtros activos se aplican simultaneamente (operacion AND), reduciendo progresivamente los resultados.
Condicion: El usuario aplica uno o mas filtros al listado de miembros.
Accion:
- Aplicar todos los filtros activos de forma conjunta
- Paginar sobre el resultado filtrado
- Devolver el total de registros que coinciden con los filtros para la paginacion
Casos de Uso
CU-001: Consultar listado de miembros con filtros
Actor: Usuario de Membresias
Precondiciones:
- Usuario autenticado con permiso de consulta de miembros
- Existen miembros registrados en el sistema
Flujo principal:
- El usuario accede al listado de miembros
- El sistema muestra la primera pagina con todos los miembros en alcance minimo
- El usuario selecciona el filtro de estado "Activos"
- El sistema muestra solo los miembros activos
- El usuario selecciona una categoria especifica
- El sistema muestra solo los miembros activos de esa categoria
- El usuario escribe un nombre en la busqueda global
- El sistema muestra solo los miembros que coinciden con todos los filtros aplicados
- El usuario navega a la siguiente pagina de resultados
Postcondiciones:
- El listado muestra solo los miembros que coinciden con todos los filtros
- La paginacion refleja el total de resultados filtrados
Flujos alternativos:
- Sin resultados: Si no hay miembros que coincidan con los filtros, el sistema muestra un mensaje indicando que no se encontraron resultados
- Error de carga: Si hay un error al obtener los datos, el sistema muestra un mensaje de error
CU-002: Consultar detalle de miembro con datos completos
Actor: Usuario de Membresias
Precondiciones:
- Usuario autenticado con permiso de consulta de miembros
- Existe el miembro que se desea consultar
Flujo principal:
- El usuario selecciona un miembro del listado
- El sistema solicita la informacion del miembro con alcance maximo e inclusiones de categoria, disciplinas y productos
- El sistema muestra la vista de detalle con:
- Datos basicos del miembro
- Datos extendidos de membresia
- Categoria asignada con su producto base
- Disciplinas en las que participa con sus ajustes
- Productos asociados con sus ajustes de precio
Postcondiciones:
- Se muestra toda la informacion disponible del miembro en una sola vista
Flujos alternativos:
- Miembro sin categoria: Se muestra el detalle sin seccion de categoria
- Disciplinas deshabilitadas: Si la empresa no tiene habilitadas las disciplinas, la seccion de disciplinas aparece vacia o no se muestra
- Miembro sin productos: Se muestra el detalle sin seccion de productos
CU-003: Carga eficiente de listado para facturacion
Actor: Sistema (proceso de facturacion por lotes)
Precondiciones:
- El proceso de facturacion necesita los datos de multiples miembros activos con sus productos y categorias
Flujo principal:
- El proceso solicita miembros activos con inclusion de categoria y productos en alcance maximo
- El sistema obtiene el listado de miembros activos
- El sistema ejecuta consultas agrupadas para cargar categorias de todos los miembros
- El sistema ejecuta consultas agrupadas para cargar productos de todos los miembros
- El sistema mapea cada relacion a su miembro correspondiente
- El proceso recibe los miembros con toda su informacion lista para facturar
Postcondiciones:
- Todos los miembros activos estan enriquecidos con sus categorias y productos
- Se ejecutaron solo un numero fijo de consultas agrupadas, independientemente de la cantidad de miembros
Consideraciones
Seguridad
- Solo usuarios autenticados con permisos de consulta de miembros pueden acceder a los datos
- Los filtros respetan el aislamiento multi-tenant, mostrando solo miembros del schema actual
Auditoria
- Las consultas de listado no generan registros de auditoria (son operaciones de lectura)
- La consulta de detalle individual tampoco genera auditoria
Rendimiento
- La carga por lotes reduce significativamente el numero de consultas a la base de datos
- La paginacion del lado del servidor limita la cantidad de datos transferidos por solicitud
- La verificacion de habilitacion de disciplinas se realiza una sola vez por solicitud y se mantiene en memoria
- Los alcances minimo y maximo permiten ajustar la cantidad de datos segun la necesidad
Dependencias
Funcionalidades relacionadas
- Gestion de miembros: Entidad principal que se enriquece y filtra
- Categorias de membresia: Datos incluibles en el enriquecimiento
- Disciplinas: Datos incluibles en el enriquecimiento (requiere habilitacion a nivel empresa)
- Productos del miembro: Datos incluibles en el enriquecimiento
- Facturacion por lotes: Consumidor principal de la carga por lotes
- Cache de categorias: Las categorias pueden servirse desde cache cuando se consultan sin opciones especiales
Criterios de Aceptacion
- [x] AC-001: El sistema devuelve solo datos basicos del miembro cuando se solicita alcance minimo
- [x] AC-002: El sistema devuelve datos basicos y extendidos cuando se solicita alcance maximo
- [x] AC-003: Las relaciones (categoria, disciplinas, productos) solo se cargan si son explicitamente solicitadas
- [x] AC-004: Cada relacion puede tener su propio alcance y sub-relaciones
- [x] AC-005: Los datos de disciplinas no se consultan si la empresa no tiene habilitada la funcionalidad
- [x] AC-006: La carga de relaciones para multiples miembros se realiza en consultas agrupadas
- [x] AC-007: El filtro por estado permite seleccionar entre Todos, Activos, Inactivos y No socios
- [x] AC-008: Los filtros de categoria, disciplinas y productos funcionan correctamente
- [x] AC-009: La busqueda global filtra por nombre e identificacion
- [x] AC-010: El ordenamiento por columna funciona en ambos sentidos (ascendente y descendente)
- [x] AC-011: La paginacion del lado del servidor devuelve solo los registros de la pagina solicitada
- [x] AC-012: El total de registros refleja los filtros aplicados
- [x] AC-013: Todos los filtros son combinables entre si (operacion AND)
Notas Adicionales
Arbol de inclusion
El sistema soporta un arbol de inclusion donde cada nodo puede tener opciones (alcance) y nodos hijos (sub-relaciones). Esto permite solicitudes como "incluir categoria con su producto en alcance maximo" en una sola consulta estructurada.
Estados de membresia
Los estados de membresia para filtrado son:
- Todos (ALL): Muestra todos los registros sin filtrar por estado
- Activos (ACTIVE): Miembros con membresia vigente
- Inactivos (INACTIVE): Miembros dados de baja
- No socios (NON_MEMBER): Registros que no son socios del sistema de membresias
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Documentacion de funcionalidad implementada |