Documentación del Sistema

Appearance

Catálogos Base ​

Esta sección documenta los catálogos maestros del sistema de membresías, que son las tablas de configuración base utilizadas por todos los demás componentes del módulo.

Descripción General ​

Los catálogos base proporcionan la estructura de datos maestra para:

  • Categorías de Membresía: Tipos de membresía (Menor, Mayor, Adulto Mayor, etc.) con rangos de edad
  • Disciplinas: Actividades deportivas disponibles (Natación, Fútbol, Gimnasio, etc.)
  • Tipos de Relación: Tipos de vínculo familiar (Principal, Cónyuge, Hijo, etc.)

Estos catálogos son prerrequisito para el funcionamiento del módulo de membresías.

Componentes Documentados ​

Categorías de Membresía ​

  • Categorías de Membresía: CRUD completo de categorías
    • Crear categoría con producto asociado
    • Configurar rango de edades para cambio automático
    • Marcar categoría por defecto
    • Editar categoría existente
    • Eliminar categoría (con validación de uso)
    • Asignar categoría a múltiples miembros (operación masiva)

Disciplinas ​

  • Disciplinas: CRUD de actividades deportivas
    • Crear disciplina con producto asociado
    • Configurar si requiere ficha médica
    • Editar disciplina existente
    • Eliminar disciplina (con validación de dependencias)

Tipos de Relación ​

  • Tipos de Relación: CRUD de tipos de relación familiar
    • Crear tipo de relación con marca de principal
    • Editar tipo de relación
    • Alternancia rápida de marca principal
    • No permite eliminación (por diseño, para preservar integridad referencial)

Reglas de Negocio Principales ​

Categorías de Membresía ​

RN-001: Categoría Defecto Única ​

Solo puede existir una categoría marcada como "por defecto". Al marcar una categoría como defecto:

  • Sistema resetea automáticamente el flag de la categoría defecto anterior
  • La nueva categoría defecto se usa para nuevos miembros sin categoría especificada

RN-002: Producto Asociado Obligatorio ​

Cada categoría debe tener un producto asociado del módulo de Ventas. Este producto se usa para:

  • Facturación mensual de la cuota de membresía
  • Precio base que puede ser ajustado por miembro

RN-003: Rango de Edades para Cambio Automático ​

Las categorías pueden tener rangos de edad configurados:

  • Edad desde y Edad hasta
  • Sistema puede cambiar automáticamente la categoría cuando el miembro cumple años
  • Útil para transiciones automáticas (ej: de Menor a Mayor al cumplir 18 años)

RN-004: Validación de Uso al Eliminar ​

No se puede eliminar una categoría que tiene miembros asignados. Sistema valida:

  • Si existen miembros con esa categoría: Rechaza eliminación
  • Si no hay miembros: Permite eliminación

RN-005: Asignación Masiva ​

La asignación masiva de categoría permite cambiar la categoría de múltiples miembros simultáneamente:

  • Selección múltiple de miembros
  • Asignación de una categoría a todos
  • Reporte de resultados detallado

Disciplinas ​

RN-001: Producto Asociado ​

Cada disciplina puede tener un producto asociado para facturación diferenciada:

  • Si tiene producto: Se factura ese producto al miembro que tiene la disciplina
  • Si no tiene producto: No genera cargo adicional

RN-002: Requerimiento de Ficha Médica ​

Las disciplinas pueden requerir ficha médica:

  • Marca: requiere_ficha_medica (S/N)
  • Alternancia rápida desde el listado
  • Útil para disciplinas de alto impacto físico

RN-003: Validación de Dependencias al Eliminar ​

No se puede eliminar una disciplina que está asignada a miembros. Sistema valida:

  • Si existen miembros con esa disciplina asignada: Rechaza eliminación
  • Si no hay asignaciones: Permite eliminación

Tipos de Relación ​

RN-001: Marca de Principal Única ​

Solo puede existir un tipo de relación marcado como "principal" (para titular del grupo). Esta marca identifica al miembro responsable de la facturación del grupo familiar.

RN-002: Tipos de Relación Predefinidos ​

El sistema NO permite eliminar tipos de relación una vez creados. Esto preserva:

  • Integridad referencial con grupos familiares existentes
  • Histórico de relaciones
  • Consistencia en reportes

Flujos de Usuario Comunes ​

1. Configurar Categoría de Membresía ​

  1. Acceder a "Bases > Categorías"
  2. Crear nueva categoría
  3. Ingresar nombre (ej: "Mayor")
  4. Seleccionar producto asociado (ej: "Cuota Mayor")
  5. Configurar rango de edad (ej: desde 18, hasta 65)
  6. Opcional: Marcar como categoría por defecto
  7. Guardar

2. Asignar Categoría a Múltiples Miembros ​

  1. Acceder a "Utilidades > Asignación de Categorías"
  2. Seleccionar categoría destino
  3. Seleccionar múltiples miembros (checkboxes)
  4. Confirmar asignación
  5. Ver reporte de resultados

3. Configurar Disciplina ​

  1. Acceder a "Bases > Disciplinas"
  2. Crear nueva disciplina
  3. Ingresar nombre (ej: "Natación")
  4. Seleccionar producto asociado (ej: "Natación Mensual")
  5. Marcar si requiere ficha médica
  6. Guardar

4. Cambiar Estado de Ficha Médica (Alternancia Rápida) ​

  1. Desde listado de disciplinas
  2. Click en indicador de ficha médica
  3. Sistema alterna S/N con actualización optimista
  4. No requiere modal de confirmación

5. Crear Tipo de Relación ​

  1. Acceder a "Bases > Tipos de Relación"
  2. Crear nuevo tipo
  3. Ingresar nombre (ej: "Cónyuge")
  4. Marcar si es principal (solo para "Titular")
  5. Guardar

Vistas Frontend ​

  • /bases/categorias - CRUD de categorías de membresía
  • /bases/disciplinas - CRUD de disciplinas
  • /bases/tipos - CRUD de tipos de relación
  • /utilidades/asignacion-categorias - Asignación masiva de categorías

Modales ​

Categorías ​

  • DeleteCategoriaMembresiaModal - Confirmar eliminación de categoría

Disciplinas ​

  • (No requiere modales, CRUD en la misma vista)

Tipos de Relación ​

  • (No requiere modales, CRUD en la misma vista)

Endpoints API ​

Categorías de Membresía ​

  • GET /mod-membresia/categorias - Listar
  • GET /mod-membresia/categorias/{id} - Ver
  • POST /mod-membresia/categorias - Crear
  • PUT /mod-membresia/categorias/{id} - Actualizar
  • PATCH /mod-membresia/categorias/{id} - Actualizar parcial
  • DELETE /mod-membresia/categorias/{id} - Eliminar
  • POST /mod-membresia/categorias/{id}/miembros - Asignar a múltiples miembros

Disciplinas ​

  • GET /mod-membresia/disciplinas - Listar
  • GET /mod-membresia/disciplinas/{id} - Ver
  • POST /mod-membresia/disciplinas - Crear
  • PUT /mod-membresia/disciplinas/{id} - Actualizar
  • PATCH /mod-membresia/disciplinas/{id} - Actualizar parcial
  • DELETE /mod-membresia/disciplinas/{id} - Eliminar

Tipos de Relación ​

  • GET /mod-membresia/tipo-relacion - Listar
  • GET /mod-membresia/tipo-relacion/{id} - Ver
  • POST /mod-membresia/tipo-relacion - Crear
  • PUT /mod-membresia/tipo-relacion/{id} - Actualizar
  • PATCH /mod-membresia/tipo-relacion/{id} - Actualizar parcial
  • DELETE /mod-membresia/tipo-relacion/{id} - No implementado (por diseño)

Caché y Optimizaciones ​

Caché de Categorías y Disciplinas ​

Sistema de caché tenant-aware:

  • TTL: Configurable
  • Invalidación automática: En operaciones CUD (Create, Update, Delete)
  • Aislamiento multi-tenant: Caché separada por schema

Ver Caché y Optimizaciones para más detalles.

Dependencias ​

Funcionalidades que Usan estos Catálogos ​

Categorías de Membresía:

  • Gestión de Miembros (cada miembro tiene una categoría)
  • Grupos Familiares (categoría del titular determina categoría del grupo)
  • Facturación por Lotes (producto de categoría se factura)
  • Cambio automático por edad (proceso batch)

Disciplinas:

  • Disciplinas del Miembro (asignación de disciplinas a miembros)
  • Facturación por Lotes (disciplinas con producto generan cargo)
  • Control de ficha médica

Tipos de Relación:

  • Grupos Familiares (cada miembro del grupo tiene un tipo de relación)
  • Reportes de grupos familiares

Módulos Externos ​

  • Ventas: Los productos asociados a categorías y disciplinas provienen del módulo de Ventas

Orden de Configuración Recomendado ​

Para una implementación nueva del módulo de membresías:

  1. Primero: Tipos de Relación

    • Crear al menos: Principal, Cónyuge, Hijo
    • Marcar "Principal" como principal

  2. Segundo: Productos en Ventas

    • Crear productos para categorías (ej: Cuota Menor, Cuota Mayor)
    • Crear productos para disciplinas (ej: Natación, Fútbol)

  3. Tercero: Categorías de Membresía

    • Crear categorías asociando productos
    • Configurar rangos de edad
    • Marcar una como defecto

  4. Cuarto: Disciplinas

    • Crear disciplinas asociando productos
    • Configurar requerimiento de ficha médica

  5. Quinto: Miembros

    • Ahora se pueden dar de alta miembros seleccionando categoría

Consideraciones Multi-Tenant ​

  • Todos los catálogos están aislados por schema/tenant
  • Cada tenant tiene su propia configuración de categorías, disciplinas y tipos de relación
  • Los productos asociados también deben existir en el mismo schema

Estadísticas ​

  • 3 documentos de requisitos de negocio
  • 25 criterios de aceptación (todos implementados)
  • 10 reglas de negocio
  • 9 casos de uso detallados
  • 18 endpoints API
  • 1 modal de interfaz

Estado ​

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

Última actualización: 2026-01-27