Grupos Familiares

Esta sección documenta la gestión de grupos familiares en el sistema de membresías, permitiendo agrupar miembros relacionados para consolidar su facturación y gestionar beneficios compartidos.

Descripción General

El sistema de grupos familiares permite:

• Agrupación de miembros: Vincular miembros relacionados (titular, cónyuge, hijos, etc.)
• Consolidación de facturación: Generar una única factura por grupo familiar
• Gestión de titularidad: Designar y cambiar el miembro principal del grupo
• Resumen consolidado: Visualizar categoría, disciplinas y productos de todo el grupo
• Tipos de relación: Definir el tipo de relación de cada miembro (Principal, Cónyuge, Hijo, etc.)

Componentes Documentados

Gestión de Grupos Familiares

• Grupos Familiares: CRUD completo de grupos familiares
  • Crear grupo designando miembro principal
  • Ver listado de miembros del grupo con tipo de relación
  • Ver resumen consolidado (categoría, disciplinas, productos)
  • Obtener grupo por miembro
  • Agregar miembro al grupo con tipo de relación
  • Editar tipo de relación de miembro
  • Eliminar miembro del grupo (con designación de nuevo titular si aplica)

Reglas de Negocio Principales

RN-001: Miembro Principal Único

Solo puede existir un miembro marcado como "Principal" (titular) por grupo familiar. Al intentar agregar un segundo miembro principal, el sistema lo rechaza.

RN-002: Grupo Sin Titular Inválido

Un grupo familiar siempre debe tener un miembro principal. Si se intenta eliminar al único titular sin designar reemplazo, la operación se rechaza.

RN-003: Designación de Nuevo Titular al Eliminar

Cuando se elimina el miembro principal del grupo:

• El sistema requiere designar un nuevo titular entre los miembros restantes
• El nuevo titular pasa a tener tipo de relación "Principal"
• La facturación futura se generará a nombre del nuevo titular

RN-004: Consolidación de Datos

El resumen del grupo familiar consolida:

• Categoría: La categoría del miembro principal determina la categoría del grupo
• Disciplinas: Unión de todas las disciplinas de todos los miembros
• Productos: Unión de todos los productos de todos los miembros

RN-005: Facturación al Titular

La facturación por lotes genera una única factura por grupo familiar, emitida a nombre del miembro principal. Los items incluyen:

• Producto de categoría del titular
• Productos y disciplinas de todos los miembros del grupo

RN-006: Consulta por Miembro

Cada miembro puede consultar su grupo familiar. Si no pertenece a ningún grupo, retorna null.

Flujos de Usuario Comunes

1. Crear Grupo Familiar

1. Desde la vista de un miembro, seleccionar "Crear Grupo Familiar"
2. El sistema designa automáticamente al miembro actual como Principal
3. Opcionalmente agregar más miembros inmediatamente

2. Agregar Miembro a Grupo Existente

1. Desde la vista del grupo, seleccionar "Agregar Miembro"
2. Buscar y seleccionar el miembro a agregar
3. Seleccionar tipo de relación (Cónyuge, Hijo, Padre, Hermano, Otro)
4. Confirmar
5. Validación: No puede haber dos miembros "Principal"

3. Cambiar Titular del Grupo

1. Desde el listado de miembros del grupo, seleccionar "Editar" en el nuevo titular
2. Cambiar tipo de relación a "Principal"
3. Sistema valida que el principal anterior cambie a otro tipo de relación
4. Confirmar cambio

4. Eliminar Miembro del Grupo

1. Desde el listado de miembros del grupo, seleccionar "Eliminar"
2. Si es miembro principal:
   • Sistema solicita designar nuevo titular
   • Seleccionar miembro del grupo que será el nuevo principal
3. Si no es principal: Confirmar eliminación directamente
4. Sistema elimina la relación del miembro con el grupo

5. Ver Resumen Consolidado

1. Desde la vista del grupo, seleccionar "Ver Resumen"
2. Sistema muestra:
   • Categoría (del titular)
   • Listado de disciplinas de todos los miembros
   • Listado de productos de todos los miembros
3. Información útil para entender qué se facturará al grupo

Vistas Frontend

No hay vistas dedicadas para grupos familiares. La gestión se realiza desde:

• Vista de detalle de miembro (/bases/miembros/:id/editar)
• Modales especializados

Modales

• CreateGrupoFamiliarModal - Crear nuevo grupo familiar
• GrupoFamiliarListModal - Listar miembros del grupo
• GrupoFamiliarResumenModal - Ver resumen consolidado
• AddMiembroGrupoModal - Agregar miembro al grupo
• EditMiembroGrupoModal - Editar tipo de relación
• ConfirmDeleteMiembroGrupoModal - Eliminar miembro del grupo

Endpoints API

• GET /mod-membresia/grupo-familiar/{id} - Ver grupo
• GET /mod-membresia/grupo-familiar/{id}/resumen - Ver resumen consolidado
• GET /mod-membresia/grupo-familiar/by-miembro/{id} - Ver por miembro
• POST /mod-membresia/grupo-familiar - Crear grupo
• POST /mod-membresia/grupo-familiar/{id} - Agregar miembro
• PUT /mod-membresia/grupo-familiar/{id}/{socio} - Actualizar tipo de relación
• DELETE /mod-membresia/grupo-familiar/{id}/{socio} - Eliminar miembro

Tipos de Relación Disponibles

Los tipos de relación se gestionan como catálogo base independiente:

• Principal - Titular del grupo (único)
• Cónyuge - Pareja del titular
• Hijo - Hijo del titular
• Padre - Padre del titular
• Hermano - Hermano del titular
• Otro - Otra relación

Ver documentación de Tipos de Relación para más detalles.

Integración con Facturación

Agrupación Automática

El proceso de facturación por lotes agrupa automáticamente a los miembros por grupo familiar:

• RealGroupProvider: Agrupa miembros que pertenecen al mismo grupo familiar
• SymbolicGroupProvider: Trata como grupo individual a miembros sin grupo familiar

Cálculo de Deuda Consolidada

El DeudaMembresiaCalculator (Domain Layer) calcula la deuda total del grupo:

1. Producto de categoría del titular
2. Productos individuales de cada miembro con sus ajustes de precio
3. Disciplinas de cada miembro

Factura Única

Se genera una única factura por grupo familiar:

• Cliente: Miembro principal (titular)
• Items: Consolidación de todos los productos y disciplinas del grupo
• Condición de venta: Cuenta Corriente a 30 días

Ver documentación de Facturación por Lotes para más detalles.

Eventos de Dominio Relacionados

MiembroBajaEvent

Cuando un miembro se da de baja:

• Listener: RemoveMiembroFromGrupoListener
• Acción: Elimina automáticamente al miembro del grupo familiar
• Validación: Si es el titular, requiere designar nuevo titular primero

Dependencias

Funcionalidades Relacionadas

• Gestión de Miembros: Los miembros del grupo provienen del ABM de miembros
• Tipos de Relación: Los tipos de relación se gestionan como catálogo base
• Facturación por Lotes: Utiliza grupos familiares para consolidar facturación
• Categorías de Membresía: La categoría del titular determina la categoría del grupo

Módulos Externos

• Ventas: Los productos asignados a cada miembro del grupo

Consideraciones Multi-Tenant

• Los grupos familiares están aislados por schema/tenant
• Un miembro solo puede pertenecer a un grupo familiar dentro de su tenant
• La facturación consolidada respeta el aislamiento del schema

Validaciones Importantes

Al Crear Grupo

• El miembro principal no puede pertenecer a otro grupo familiar
• El grupo debe tener al menos un miembro (el principal)

Al Agregar Miembro

• El miembro a agregar no puede pertenecer a otro grupo familiar
• No puede haber dos miembros principales en el mismo grupo
• El tipo de relación debe ser válido

Al Eliminar Miembro

• Si es el único miembro, se elimina todo el grupo familiar
• Si es el titular y hay más miembros, requiere designar nuevo titular
• Si no es el titular, se elimina directamente

Al Cambiar Titular

• El nuevo titular debe ser miembro del grupo
• Solo puede haber un miembro principal
• El cambio actualiza automáticamente el tipo de relación del principal anterior

Estadísticas

• 1 documento de requisitos de negocio
• 16 criterios de aceptación (todos implementados)
• 6 reglas de negocio
• 3 casos de uso detallados
• 7 endpoints API
• 6 modales de interfaz

Estado

✅ Implementado - Todas las funcionalidades están en producción

---

Última actualización: 2026-01-27