Appearance
Eventos de Dominio del Modulo de Membresias
Modulo: Membresias Tipo: Process Estado: Implementado Fecha: 2026-01-27
Descripcion
Problema que resuelve
El modulo de membresias gestiona operaciones que tienen efectos colaterales en multiples areas del sistema. Cuando un miembro es dado de baja, cuando se reactiva o cuando se completa un proceso de facturacion por lotes, existen acciones derivadas que deben ejecutarse automaticamente:
- Baja de miembro: Si el miembro pertenece a un grupo familiar, debe ser removido automaticamente del grupo. Si es el titular principal, se requiere designar un nuevo titular
- Reactivacion de miembro: Los sistemas externos que consumen datos de membresia deben ser notificados del cambio de estado
- Facturacion por lotes completada: Se deben enviar notificaciones (email/SMS) a los socios facturados y sincronizar los datos con sistemas externos (ERP, sistemas de cobro)
Sin un mecanismo de eventos, estas acciones colaterales estarian acopladas directamente en cada operacion, generando:
- Dificultad para agregar nuevas reacciones sin modificar la logica existente
- Riesgo de que una falla en una accion secundaria impida la operacion principal
- Complejidad creciente en los servicios que realizan las operaciones
Solucion implementada
Se implementa un sistema de eventos de dominio donde las operaciones principales emiten eventos que son procesados por oyentes (listeners) desacoplados. Cada evento puede tener multiples oyentes que reaccionan de forma independiente.
Valor de negocio
- Automatizacion de procesos derivados: Las acciones colaterales se ejecutan automaticamente sin intervencion del usuario
- Consistencia de datos: Se garantiza que las acciones derivadas (como remover del grupo familiar) se ejecuten siempre que ocurre la operacion principal
- Extensibilidad: Se pueden agregar nuevas reacciones a eventos existentes sin modificar la logica del proceso principal
- Integracion con sistemas externos: Los eventos permiten mantener sincronizados los sistemas externos con el estado actual de los miembros
Contexto del sistema
Los eventos de dominio se integran con:
- Gestion de miembros: Emision de eventos de baja y reactivacion
- Grupos familiares: Reaccion automatica ante baja de miembro del grupo
- Facturacion por lotes: Emision de evento al completar el procesamiento
- Sistemas externos: Sincronizacion de datos con ERP y sistemas de cobro
- Notificaciones: Envio de comunicaciones a socios (email/SMS)
Proceso de Negocio
Evento 1: Baja de Miembro
Cuando un miembro es dado de baja del sistema de membresias, se dispara automaticamente un conjunto de acciones derivadas.
Informacion del evento
| Dato | Descripcion |
|---|---|
| Miembro | Identificacion del miembro que se da de baja |
| Fecha de baja | Fecha en que se efectua la baja |
| Motivo de baja | Razon de la baja (opcional) |
| Nuevo titular | Datos del nuevo titular del grupo familiar (si aplica) |
Reaccion: Remocion del grupo familiar
Cuando un miembro dado de baja pertenece a un grupo familiar, se ejecuta automaticamente:
- El sistema verifica si el miembro pertenece a un grupo familiar
- Si no pertenece a ningun grupo: no se realiza ninguna accion adicional
- Si pertenece a un grupo familiar: a. Si se proporcionaron datos de nuevo titular (porque el miembro era el principal): se realiza el reemplazo de titular y luego la remocion b. Si no se proporcionaron datos de nuevo titular: se remueve al miembro del grupo directamente
- Se registra la operacion en el log del sistema
Comportamiento ante errores
Si la remocion del grupo familiar falla, el error se propaga para provocar la reversion completa de la operacion de baja. Esto garantiza que un miembro no quede dado de baja pero aun asociado a un grupo familiar en estado inconsistente.
Evento 2: Reactivacion de Miembro
Cuando un miembro previamente dado de baja es reactivado, se notifica a los sistemas externos para mantener la sincronizacion.
Informacion del evento
| Dato | Descripcion |
|---|---|
| Miembro | Identificacion del miembro que se reactiva |
Reaccion: Actualizacion de sistemas externos
Al reactivarse un miembro, el sistema notifica a los servicios externos que consumen datos de membresia para que actualicen el estado del miembro en sus registros. Actualmente esta reaccion registra la actividad en el log del sistema y esta preparada para integracion futura con servicios externos especificos.
Evento 3: Facturacion por Lotes Procesada
Cuando se completa un proceso de facturacion por lotes (exitosamente o con errores parciales), se emite un evento con el resumen del procesamiento.
Informacion del evento
| Dato | Descripcion |
|---|---|
| Comprobantes generados | Listado de identificadores de comprobantes creados |
| Total procesados | Cantidad total de socios procesados en el lote |
| Periodo | Periodo de facturacion procesado (mes/ano) |
| Punto de venta | Punto de venta utilizado para la emision |
| Metadatos | Informacion adicional del procesamiento |
Reaccion 1: Envio de notificaciones
Al completarse la facturacion, se dispara el envio de notificaciones a los socios:
- Registro de la actividad de facturacion completada
- Preparacion para envio de emails y/o SMS a socios facturados (funcionalidad extensible)
Reaccion 2: Actualizacion de sistemas externos
Simultameamente, se dispara la sincronizacion con sistemas externos:
- Registro de la actividad para el ERP externo
- Preparacion para sincronizacion de datos de facturacion con sistemas de cobro (funcionalidad extensible)
Orden de ejecucion
Las reacciones se ejecutan en orden definido:
- Primero: envio de notificaciones
- Segundo: actualizacion de sistemas externos
Frontend (Perspectiva de Usuario)
Vistas
Los eventos de dominio son procesos internos del sistema que no tienen interfaz de usuario directa. Sin embargo, sus efectos son visibles en:
- Vista de baja de miembro: Al confirmar la baja, el miembro es automaticamente removido de su grupo familiar sin accion adicional del usuario
- Vista de grupo familiar: Tras la baja de un miembro, el grupo familiar refleja automaticamente la remocion
- Vista de resultados de facturacion: Tras completar la facturacion, las notificaciones se envian sin intervencion del usuario
Interacciones del usuario
- Dar de baja un miembro con grupo familiar: El usuario confirma la baja e indica el nuevo titular si corresponde. El sistema remueve automaticamente al miembro del grupo y gestiona el reemplazo de titular
- Reactivar un miembro: El usuario confirma la reactivacion. El sistema notifica automaticamente a los sistemas externos
- Ejecutar facturacion por lotes: El usuario inicia la facturacion. Al completarse, el sistema envia automaticamente las notificaciones y sincroniza con sistemas externos
Estados de UI
- Procesando baja: Indicador de que se esta procesando la baja y sus efectos colaterales
- Error en baja: Si falla la remocion del grupo familiar, se muestra error y la baja se revierte
- Exito en baja: Confirmacion de que la baja y todas las acciones derivadas se completaron
Backend (Perspectiva de Datos de Negocio)
Entidades de negocio involucradas
Evento de Baja de Miembro
Representa la notificacion de que un miembro ha sido dado de baja.
| Dato de negocio | Descripcion |
|---|---|
| Miembro afectado | Identificacion del miembro dado de baja |
| Fecha de baja | Cuando se efectuo la baja |
| Motivo | Razon de la baja |
| Datos de nuevo titular | Si el miembro era titular de grupo familiar, datos del reemplazo |
Evento de Reactivacion de Miembro
Representa la notificacion de que un miembro ha sido reactivado.
| Dato de negocio | Descripcion |
|---|---|
| Miembro afectado | Identificacion del miembro reactivado |
Evento de Facturacion por Lotes Procesada
Representa la notificacion de que un proceso de facturacion masiva ha finalizado.
| Dato de negocio | Descripcion |
|---|---|
| Comprobantes | Listado de comprobantes generados |
| Total procesados | Cantidad de socios procesados |
| Periodo | Periodo facturado |
| Punto de venta | Punto de venta utilizado |
| Metadatos | Informacion adicional del proceso |
Relaciones de negocio
- Un evento de baja puede derivar en la remocion del miembro de su grupo familiar
- Un evento de baja puede requerir el reemplazo de titular si el miembro era el principal del grupo
- Un evento de facturacion deriva en el envio de notificaciones y la sincronizacion con sistemas externos
- Cada evento puede tener multiples oyentes que reaccionan de forma independiente
Validaciones de negocio
| Validacion | Descripcion | Comportamiento si no cumple |
|---|---|---|
| Pertenencia a grupo | Se verifica si el miembro dado de baja pertenece a un grupo familiar | Si no pertenece, no se ejecuta la remocion |
| Propagacion de errores | Si falla una accion critica (remocion de grupo), se propaga el error | Se revierte toda la operacion de baja |
| Tolerancia a fallos en notificaciones | Si falla el envio de notificaciones o la sincronizacion externa, se registra advertencia | La operacion principal NO se revierte |
Reglas de Negocio
RN-001: Remocion automatica del grupo familiar en baja
Descripcion: Cuando un miembro es dado de baja, si pertenece a un grupo familiar, debe ser removido automaticamente del grupo como parte de la misma operacion.
Condicion: Se da de baja un miembro que pertenece a un grupo familiar.
Accion:
- Verificar pertenencia a grupo familiar
- Si tiene grupo: remover del grupo (con reemplazo de titular si aplica)
- Si no tiene grupo: no ejecutar accion adicional
RN-002: Atomicidad de baja con remocion de grupo
Descripcion: La baja del miembro y la remocion del grupo familiar deben ser una operacion atomica. Si la remocion del grupo falla, la baja completa debe revertirse.
Condicion: Se intenta dar de baja un miembro con grupo familiar y la remocion falla.
Accion:
- Propagar el error de remocion
- Revertir la operacion de baja completa
- Informar al usuario del error
RN-003: Reemplazo de titular en baja
Descripcion: Si el miembro que se da de baja es el titular principal del grupo familiar, se deben proporcionar los datos del nuevo titular. La remocion incluye el reemplazo de titular.
Condicion: Se da de baja al titular principal de un grupo familiar.
Accion:
- Ejecutar reemplazo de titular con los datos proporcionados
- Remover al miembro anterior del grupo
- El grupo mantiene un titular principal vigente
RN-004: Tolerancia a fallos en notificaciones
Descripcion: Los fallos en el envio de notificaciones o la sincronizacion con sistemas externos no deben impedir ni revertir la operacion principal.
Condicion: Falla el envio de notificacion tras facturacion o reactivacion.
Accion:
- Registrar advertencia en el log del sistema
- La operacion principal (facturacion o reactivacion) permanece completada exitosamente
- No se revierte ninguna operacion
RN-005: Orden de ejecucion de reacciones a facturacion
Descripcion: Las reacciones al evento de facturacion completada se ejecutan en un orden predefinido: primero notificaciones, luego sincronizacion externa.
Condicion: Se completa un proceso de facturacion por lotes.
Accion:
- Enviar notificaciones (email/SMS)
- Sincronizar con sistemas externos
Casos de Uso
CU-001: Baja de miembro con remocion automatica de grupo familiar
Actor: Usuario de Membresias
Precondiciones:
- Usuario autenticado con permiso de baja de miembros
- El miembro existe y esta activo
- El miembro pertenece a un grupo familiar
Flujo principal:
- El usuario solicita la baja del miembro
- El sistema procesa la baja del miembro
- El sistema emite el evento de baja
- El oyente de remocion de grupo detecta que el miembro pertenece a un grupo familiar
- El sistema remueve automaticamente al miembro del grupo familiar
- El sistema registra la actividad en el log
- El usuario recibe confirmacion de la baja exitosa
Postcondiciones:
- El miembro esta dado de baja
- El miembro ya no pertenece al grupo familiar
- El log del sistema registra la remocion del grupo
Flujos alternativos:
- Miembro es titular: Se requieren datos de nuevo titular; el sistema reemplaza al titular y luego remueve al miembro
- Miembro sin grupo: No se ejecuta ninguna accion adicional; la baja se procesa normalmente
- Error en remocion: Se revierte toda la operacion de baja y se informa al usuario
CU-002: Facturacion completada con notificaciones automaticas
Actor: Sistema (proceso automatico tras facturacion por lotes)
Precondiciones:
- Se ha ejecutado un proceso de facturacion por lotes
- El proceso ha finalizado (con o sin errores parciales)
Flujo principal:
- El proceso de facturacion finaliza y emite el evento con el resumen
- El oyente de notificaciones recibe el evento con los datos del lote procesado
- El sistema registra la actividad de facturacion completada
- El oyente de sistemas externos recibe el mismo evento
- El sistema registra la actividad de sincronizacion externa
Postcondiciones:
- Las notificaciones fueron procesadas (o registradas para envio posterior)
- Los sistemas externos fueron notificados del procesamiento
- El log del sistema contiene los registros de ambas reacciones
Flujos alternativos:
- Error en notificacion: Se registra advertencia pero la facturacion permanece completada
- Error en sincronizacion externa: Se registra advertencia pero la facturacion permanece completada
CU-003: Reactivacion de miembro con notificacion a externos
Actor: Usuario de Membresias
Precondiciones:
- Usuario autenticado con permiso de reactivacion de miembros
- El miembro existe y esta dado de baja
Flujo principal:
- El usuario solicita la reactivacion del miembro
- El sistema procesa la reactivacion
- El sistema emite el evento de reactivacion
- El sistema notifica a los servicios externos del cambio de estado
- El usuario recibe confirmacion de la reactivacion exitosa
Postcondiciones:
- El miembro esta activo nuevamente
- Los sistemas externos han sido notificados
Consideraciones
Seguridad
- Los eventos se procesan dentro del mismo contexto de seguridad de la operacion principal
- Solo las operaciones autorizadas pueden generar eventos (la seguridad se valida antes de emitir)
Auditoria
| Operacion | Informacion registrada |
|---|---|
| Remocion de grupo por baja | Miembro removido, grupo afectado, resultado |
| Notificacion de facturacion | Total procesados, periodo, punto de venta, cantidad de comprobantes |
| Sincronizacion externa | Total procesados, periodo, punto de venta, cantidad de comprobantes |
| Error en reaccion | Mensaje de error, evento que lo provoco |
Rendimiento
- Los eventos se procesan de forma sincrona dentro de la misma transaccion (para garantizar atomicidad en bajas)
- Las notificaciones de facturacion se procesan tras completar el lote completo, no por cada socio individual
- Los errores en reacciones no criticas (notificaciones) no bloquean la operacion principal
Dependencias
Funcionalidades relacionadas
- Gestion de miembros: Emisor de eventos de baja y reactivacion
- Grupos familiares: Receptor de eventos de baja para remocion automatica
- Facturacion por lotes: Emisor de evento de facturacion completada
- Cache de membresias: Los eventos pueden derivar en invalidacion de cache
Servicios externos
- Sistema de notificaciones: Para envio de email/SMS tras facturacion (preparado para integracion futura)
- ERP externo: Para sincronizacion de datos de miembros y facturacion (preparado para integracion futura)
Criterios de Aceptacion
- [x] AC-001: Al dar de baja un miembro con grupo familiar, el miembro es automaticamente removido del grupo
- [x] AC-002: Si la remocion del grupo falla, la operacion de baja completa se revierte
- [x] AC-003: Si el miembro dado de baja es titular, se realiza el reemplazo de titular antes de la remocion
- [x] AC-004: Si el miembro dado de baja no pertenece a ningun grupo, no se ejecuta accion adicional
- [x] AC-005: Al completar la facturacion por lotes, se emiten notificaciones automaticamente
- [x] AC-006: Al completar la facturacion por lotes, se sincroniza con sistemas externos automaticamente
- [x] AC-007: Los errores en notificaciones no revierten la facturacion
- [x] AC-008: Los errores en sincronizacion externa no revierten la facturacion
- [x] AC-009: Las reacciones a facturacion se ejecutan en orden: primero notificaciones, luego sistemas externos
- [x] AC-010: Al reactivar un miembro, se notifica a los sistemas externos
Notas Adicionales
Extensibilidad
El sistema de eventos esta disenado para ser extensible. Se pueden agregar nuevos oyentes a cada evento sin modificar el codigo de las operaciones principales. Por ejemplo:
- Evento de baja: Se podria agregar un oyente para enviar email de despedida al miembro
- Evento de facturacion: Se podria agregar un oyente para generar reportes automaticos o actualizar dashboards
- Evento de reactivacion: Se podria agregar un oyente para enviar email de bienvenida
Estado actual de integraciones
Las reacciones de notificaciones y sincronizacion externa estan implementadas en su estructura base con registro de actividad. La integracion especifica con servicios de email/SMS y con el ERP externo esta preparada para desarrollo futuro sobre esta base.
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Documentacion de funcionalidad implementada |