Cupon de Pago para Membresias

Modulo: CtaCte / Membresias Tipo: Process Estado: Implementado Fecha: 2026-01-21 Fecha de Implementacion: 2026-01-27

Documentacion detallada por componente:
Generacion de Cupon de Pago - Componente 1
Validacion de Cupon (Escaneo) - Componente 2
Cobro Cross-Schema (Multi-Sucursal) - Componente 3

Descripcion

Problema que resuelve

En el modulo de membresias, la empresa factura periodicamente a clientes (mensual, trimestral, etc.) por sus servicios de membresia. Cada periodo genera UNA factura por cliente. Cuando se factura la deuda de un grupo familiar, siempre se hace a un unico cliente: el titular del grupo. Actualmente, el proceso de cobro presenta los siguientes inconvenientes:

Falta de comprobante fisico: El cliente no tiene un documento que identifique su deuda del periodo con codigo de barras para facilitar el pago
Proceso de cobro manual: El cajero debe buscar manualmente al cliente, identificar la factura del periodo pendiente y cargarla en el recibo
Dificultad en sucursales multiples: Cuando el cliente desea pagar en una sucursal diferente a donde se genero su deuda, el proceso se complica por el manejo de schemas diferentes
Mayor tiempo de atencion: El proceso manual de identificacion y carga de deuda incrementa el tiempo de atencion al cliente
Riesgo de errores: La carga manual puede generar errores al identificar el cliente o la factura correspondiente

Solucion propuesta

Se implementa un sistema integral de cupones de pago con codigo de barras que consta de tres componentes:

Reporte de Cupon de Pago: Genera un documento PDF con codigo de barras para la deuda de un periodo especifico del cliente/grupo familiar (un cupon = un periodo = una factura)
Cobro mediante Escaneo: Permite escanear el codigo de barras del cupon para precargar automaticamente todos los datos del recibo (cliente, factura del periodo, monto)
Cobro Cross-Schema: Permite que un usuario de una sucursal diferente pueda cobrar la deuda de un cliente de otra sucursal, registrando correctamente la cancelacion en el schema origen y el movimiento de caja en el schema destino

Valor de negocio

Agilidad en el cobro: Reduce significativamente el tiempo de atencion al cliente mediante el escaneo automatico
Experiencia del cliente mejorada: El cliente recibe un cupon claro con toda su deuda y puede pagar en cualquier sucursal
Reduccion de errores: La precarga automatica elimina errores de carga manual
Flexibilidad operativa: El cliente puede pagar en cualquier punto de cobro de la empresa
Trazabilidad completa: El sistema registra quien cobro, donde y cuando, manteniendo la integridad de la cuenta corriente del cliente
Proceso estandarizado: Uniformiza el proceso de cobro de membresias en toda la organizacion

Contexto del sistema

Esta funcionalidad se integra con los siguientes componentes existentes:

Modulo de Membresias: Genera la facturacion periodica que alimenta los cupones
Modulo de CtaCte: Gestiona la cuenta corriente del cliente y los recibos de cobro
Modulo de Ventas: Contiene las facturas pendientes del cliente
Modulo de Tesoreria: Registra los movimientos de caja
Sistema Multi-tenant: Maneja la separacion de datos por sucursal/caja

Proceso de Negocio

Componente 1: Generacion del Cupon de Pago

El cupon de pago es un documento PDF que representa la deuda de UN periodo especifico de un cliente o grupo familiar. Cada periodo genera UNA factura y por lo tanto UN cupon.

Flujo de generacion del cupon

mermaid

flowchart TD
    subgraph GENERACION["GENERACION DE CUPON DE PAGO"]
        A["1. SOLICITUD DE CUPON
        - Usuario accede al modulo de membresias
        - Selecciona cliente o grupo familiar
        - Selecciona periodo especifico"]

        B["2. OBTENCION DE LA DEUDA DEL PERIODO
        - Sistema obtiene LA factura del periodo del cliente
        - Si es grupo familiar, obtiene factura del titular
        - Verifica que la factura esta pendiente"]

        C{"3. ¿HAY DEUDA
        PENDIENTE?"}

        D["4. GENERACION DE CODIGO DE BARRAS
        - Sistema codifica informacion del pago
        - Genera codigo de barras con formato establecido
        - Incluye datos de verificacion"]

        E["5. GENERACION DE PDF
        - Sistema genera documento con:
          * Datos del cliente
          * Lista de facturas pendientes
          * Monto total
          * Codigo de barras
          * Fecha de vencimiento"]

        F["6. ENTREGA AL USUARIO
        - PDF listo para imprimir o enviar
        - Usuario puede entregar al cliente"]

        G["SIN DEUDA
        - Sistema informa que no hay deuda
        - No se genera cupon"]
    end

    A --> B
    B --> C
    C -->|"SI"| D
    C -->|"NO"| G
    D --> E
    E --> F

Contenido del cupon de pago

El cupon debe mostrar la siguiente informacion:

Encabezado

Titulo del documento: "CUPON DE PAGO"
Fecha de emision del cupon
Fecha de vencimiento sugerida (si aplica)

Datos del cliente

Nombre completo o razon social
Numero de identificacion (DNI/CUIT)
Domicilio (opcional)
Si es grupo familiar: indicar "GRUPO FAMILIAR - TITULAR: [nombre]"

Detalle de la deuda

Periodo: [Mes/Año o rango de fechas]
Comprobante: [Tipo y numero de factura]
Fecha de emision: [Fecha]
Importe a pagar: $[Monto]

Codigo de barras

Codigo de barras visible y escaneable
Numero del codigo en formato legible debajo del codigo

Informacion adicional

Instrucciones de pago
Puntos de cobro disponibles
Validez del cupon

Componente 2: Cobro mediante Escaneo de Codigo de Barras

Flujo de cobro con cupon

mermaid

flowchart TD
    subgraph COBRO["PROCESO DE COBRO CON CUPON"]
        A["1. INICIO DE COBRO
        - Cajero accede a vista de carga de recibo
        - Cliente presenta cupon de pago"]

        B["2. ESCANEO DE CODIGO
        - Cajero escanea codigo de barras
        - Sistema decodifica informacion"]

        C["3. VALIDACION DEL CUPON
        - Verifica que cliente existe
        - Verifica que facturas estan pendientes
        - Verifica monto coincide"]

        D{"4. ¿VALIDACION
        EXITOSA?"}

        E["5. PRECARGA DE RECIBO
        - Sistema selecciona cliente automaticamente
        - Marca LA factura del periodo para cancelacion
        - Precarga monto de la factura
        - Campos listos para completar"]

        F["6. COMPLETAR DATOS
        - Cajero verifica informacion precargada
        - Selecciona forma de pago
        - Agrega observaciones si necesario"]

        G["7. CONFIRMACION
        - Cajero confirma el recibo
        - Sistema procesa el pago
        - Se genera comprobante de recibo"]

        H["ERROR DE VALIDACION
        - Sistema muestra mensaje explicativo
        - Cajero decide como proceder
        - Puede continuar manualmente"]

        I{"8. ¿ES COBRO
        CROSS-SCHEMA?"}

        J["9a. REGISTRO LOCAL
        - Cancela deuda en schema actual
        - Registra movimiento de caja local"]

        K["9b. REGISTRO DISTRIBUIDO
        - Cancela deuda en schema origen
        - Registra movimiento caja en schema destino
        - Genera auditoria de operacion"]
    end

    A --> B
    B --> C
    C --> D
    D -->|"SI"| E
    D -->|"NO"| H
    E --> F
    F --> G
    G --> I
    I -->|"NO"| J
    I -->|"SI"| K

Precarga de datos en el recibo

Al escanear un codigo de barras valido, el sistema precarga:

Campo	Comportamiento
Cliente	Seleccionado automaticamente
Factura a cancelar	La factura del periodo marcada para cancelacion
Monto	Monto de la factura del periodo
Fecha del recibo	Fecha actual (editable)
Forma de pago	Pendiente de seleccion por usuario
Observaciones	Vacio (editable)

El usuario solo debe:

Verificar la informacion precargada
Seleccionar la forma de pago
Agregar observaciones si es necesario
Confirmar el recibo

Componente 3: Cobro Cross-Schema (Multi-Sucursal)

Escenario de cobro entre sucursales

Cuando un cliente tiene deuda en una sucursal (Schema A) pero desea pagar en otra sucursal (Schema B), el sistema debe manejar una transaccion distribuida.

mermaid

flowchart LR
    subgraph ORIGEN["SCHEMA ORIGEN (donde esta la deuda)"]
        A1["Cuenta Corriente del Cliente"]
        A2["Facturas Pendientes"]
        A3["Registro de Cancelacion"]
    end

    subgraph DESTINO["SCHEMA DESTINO (donde se cobra)"]
        B1["Caja del Usuario"]
        B2["Movimiento de Caja"]
        B3["Registro de Ingreso"]
    end

    subgraph AUDITORIA["REGISTRO DE AUDITORIA"]
        C1["Usuario que cobro"]
        C2["Schema donde se cobro"]
        C3["Schema del cliente"]
        C4["Fecha y hora"]
        C5["Comprobantes afectados"]
    end

    A2 --> A3
    A3 --> A1
    B1 --> B2
    B2 --> B3

    A3 -.->|"referencia cruzada"| B2
    B2 -.->|"referencia cruzada"| A3

    A3 --> C5
    B2 --> C1
    B2 --> C2
    A3 --> C3
    B2 --> C4

Registro en schema origen (del cliente)

En el schema donde el cliente tiene su cuenta corriente:

Se registra la cancelacion de las facturas
Se actualiza el saldo del cliente
Se vinculan los comprobantes (facturas) al pago
Se registra referencia al schema donde se realizo el cobro

Registro en schema destino (del cajero)

En el schema donde el usuario realiza el cobro:

Se registra el ingreso de dinero en la caja del usuario
Se genera el movimiento de caja correspondiente
Se registra referencia al schema del cliente
Se indica que es un cobro por cuenta de otra sucursal

Garantias de la transaccion

Aspecto	Requisito
Atomicidad	Ambas partes de la transaccion deben completarse o revertirse juntas
Consistencia	Los saldos deben quedar consistentes en ambos schemas
Trazabilidad	Debe ser posible rastrear la operacion desde cualquier schema
Auditoria	Debe quedar registro completo de quien, donde, cuando y que se cobro

Formato del Codigo de Barras

Especificacion del formato

El codigo de barras para cupones de pago sigue un formato simple, robusto y mantenible que identifica de forma unica una factura/deuda.

IMPORTANTE: El codigo de barras NO contiene valores economicos (monto), solo identifica la factura. El importe se obtiene siempre desde la base de datos al momento del cobro.

Tipo de codigo recomendado

Interleaved 2 of 5 (ITF) - Codigo numerico compacto

Caracteristicas:

Exclusivamente numerico (perfecto para nuestro formato)
Muy compacto (alta densidad)
Ampliamente soportado por lectores estandar
Ideal para codigos cortos (menos de 30 digitos)
Menor espacio de impresion que Code 128

Alternativa: Code 128 si se requiere soporte alfanumerico en el futuro

Estructura del codigo

El codigo de barras sigue el formato definido para pago interno:

[SUCU][CLIENTE][PERIODO][DV]

Nota: Sin delimitadores. Cada campo tiene longitud fija.

Detalle de cada campo

Campo	Formato	Longitud	Descripcion	Ejemplo
SUCU	Numerico	4 digitos	Codigo de sucursal (derivado del schema `sucXXXX`)	0001
CLIENTE	Numerico	8 digitos	ID del cliente titular dentro del schema	00056789
PERIODO	Numerico	6 digitos	Periodo facturado en formato `AAAAMM`	202501
DV	Numerico	1 digito	Digito verificador (modulo 10)	4

Longitud total: 19 digitos

Ejemplo de codigo completo

Caso de uso: Cliente ID 56789, Periodo Enero 2025, Sucursal 0001

Codigo generado:

0001000567892025014

Desglose:

0001   00056789  202501  4
│      │         │       │
Sucu.  Cliente   Periodo DV

Representacion legible con espacios (solo para visualizacion):

0001 00056789 202501 4

Representacion del codigo de barras ITF:

||||| |||| ||||| ||| |
0001000567892025014

Algoritmo del digito verificador (DV)

El digito verificador se calcula para detectar errores de lectura o carga manual.

Metodo: Modulo 10 con ponderacion 3-1

Pasos del calculo:

Tomar los 18 digitos (SUCU + CLIENTE + PERIODO), de derecha a izquierda
Multiplicar cada digito alternando pesos 3 y 1 (empezando por 3)
Sumar todos los productos
Calcular: DV = (10 - (suma % 10)) % 10

Ejemplo con: Sucursal 0001, Cliente 00056789, Periodo 202501

Digitos:     0  0  0  1  0  0  0  5  6  7  8  9  2  0  2  5  0  1
Posicion:   18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1
Peso:        1  3  1  3  1  3  1  3  1  3  1  3  1  3  1  3  1  3

Productos:   0  0  0  3  0  0  0 15  6 21  8 27  2  0  2 15  0  3

Suma: 0+0+0+3+0+0+0+15+6+21+8+27+2+0+2+15+0+3 = 102

DV = (10 - (102 % 10)) % 10
   = (10 - 2) % 10
   = 8 % 10
   = 8

Codigo final: 0001000567892025018

Nota: Este algoritmo detecta el 100% de errores de un solo digito y casi todos los errores de transposicion.

Validacion al escanear

Cuando el sistema escanea el codigo de barras, realiza las siguientes validaciones:

Validar longitud: Exactamente 19 digitos
Validar caracteres: Solo digitos numericos (0-9)
Extraer campos: Por posicion fija (sin delimitadores)
- Posiciones 1-4: SUCU (sucursal)
- Posiciones 5-12: CLIENTE (id cliente)
- Posiciones 13-18: PERIODO (AAAAMM)
- Posicion 19: DV (digito verificador)
Recalcular DV: Calcular digito verificador de los primeros 18 digitos
Comparar DV: El calculado debe coincidir con el del codigo
Validar sucursal: La sucursal debe existir (schema sucXXXX)

Consultar factura: Buscar factura en la base de datos:

sql

SELECT * FROM sucXXXX.membresia_facturacion
WHERE id_cliente = :cliente AND periodo = :periodo

Validar estado: La factura debe estar PENDIENTE (no cancelada)
Obtener importe: El monto real se obtiene de la base de datos (no del codigo)

Reglas de validez del formato

Este formato es valido si se cumple:

Una sola factura por cliente y periodo: El codigo identifica univocamente una deuda
No hay pagos parciales: La factura se cobra completa
El periodo identifica la deuda: Combinacion SUCURSAL + CLIENTE + PERIODO es unica
Importe desde BD: El monto se calcula siempre desde la base de datos (no esta en el codigo)

Consideraciones de seguridad

Unicidad:

Cada combinacion de SUCU + CLIENTE + PERIODO es unica
No puede generarse dos veces el mismo codigo para el mismo periodo
El codigo identifica la factura, no contiene el monto

Expiracion:

El cupon puede tener fecha de vencimiento visual (impresa)
Al escanear, se valida la fecha pero se permite procesar incluso vencido (con advertencia)

Prevencion de fraude:

El digito verificador previene modificaciones manuales del codigo
El sistema valida que la factura aun este pendiente al momento del cobro
No contiene valores economicos en el codigo (previene alteracion de montos)

Manejo de errores en escaneo

Error	Causa	Accion del sistema
Codigo ilegible	Codigo dañado o mal impreso	Permitir ingreso manual del codigo
Checksum invalido	Codigo modificado o corrupto	Rechazar y solicitar verificacion
Cliente no encontrado	ID de cliente no existe	Error: Cliente no existe en el sistema
Factura no encontrada	ID de factura no existe	Error: Factura no existe en el sistema
Monto no coincide	Factura tiene monto diferente	Advertencia: Verificar monto manualmente
Factura ya cancelada	La factura ya fue pagada	Error: Factura ya cancelada el [fecha]
Schema no accesible	Usuario sin permiso cross-schema	Error: No tiene permisos para cobrar de otro schema

Alternativas de implementacion

Opcion 1: Interleaved 2 of 5 - ITF (Recomendada)

✅ Muy compacto para 19 digitos numericos
✅ Alta densidad, ocupa poco espacio
✅ Ampliamente soportado por lectores estandar
✅ Ideal para nuestro formato numerico
Tamaño impreso: ~4-5 cm de ancho × 1 cm alto

Opcion 2: Code 128

✅ Soporte alfanumerico (por si se agrega metadata futura)
✅ Amplio soporte de lectores
⚠️ Ocupa mas espacio que ITF para numeros
Tamaño impreso: ~5-7 cm de ancho × 1.5 cm alto

Opcion 3: QR Code

✅ Tolerancia a daños, redundancia incorporada
✅ Escaneable con celular (sin lector dedicado)
⚠️ Mas espacio vertical
⚠️ Requiere camara o lector 2D
Tamaño impreso: ~2×2 cm

Ejemplo de implementacion del codigo

Generacion del codigo:

Entrada:
- Sucursal ID: 1 (schema suc0001)
- Cliente ID: 56789
- Periodo: Enero 2025

Proceso:
1. SUCU = str_pad(1, 4, '0', STR_PAD_LEFT) = "0001"
2. CLIENTE = str_pad(56789, 8, '0', STR_PAD_LEFT) = "00056789"
3. PERIODO = "202501"  // AAAAMM
4. DATOS = "0001" + "00056789" + "202501" = "000100056789202501"
5. DV = calcularDV(DATOS) = "4"  // usando modulo 10 ponderacion 3-1

Salida:
"0001000567892025014"

Decodificacion del codigo:

Entrada: "0001000567892025014"

Proceso:
1. Validar longitud = 19 digitos → OK
2. Validar solo numeros → OK
3. Extraer campos por posicion:
   - sucu = substr(0, 4) = "0001" → sucursal 1
   - cliente = substr(4, 8) = "00056789" → cliente 56789
   - periodo = substr(12, 6) = "202501" → Enero 2025
   - dv = substr(18, 1) = "4"

4. Validar DV:
   - datos_verificar = "000100056789202501"
   - dv_calculado = calcularDV(datos_verificar) = "4"
   - dv_codigo = "4"
   - ¿Coinciden? SI → Codigo valido

5. Consultar factura en base de datos:
   - Schema: suc0001
   - Query: SELECT * FROM suc0001.membresia_facturacion
            WHERE id_cliente = 56789 AND periodo = '202501'
   - Obtener: id_factura, monto, estado
   - Verificar estado: PENDIENTE

6. Precargar recibo con:
   - Cliente: 56789 de sucursal 0001
   - Factura del periodo 2025-01
   - Monto obtenido de la BD (no del codigo)

Buenas practicas de implementacion

El codigo identifica la factura, no el importe:

No incluir valores monetarios en el codigo
El monto se obtiene siempre desde la base de datos
Esto permite ajustes de precio sin regenerar cupones

Reimpresiones:

Permitir reimprimir cupones sin cambiar el codigo
El mismo codigo siempre identifica la misma factura/periodo

Bloqueo de duplicados:

Al escanear, se valida que la factura del periodo aun este PENDIENTE
Si la factura ya fue cancelada, significa que ya fue cobrada
Mostrar informacion de la factura cancelada si se reintenta

Auditoria:

Registrar fecha y hora de cobro
Registrar usuario que proceso el cupon
Registrar schema donde se realizo el cobro (para cross-schema)

Frontend (Perspectiva de Usuario)

Vistas

Vista de generacion de cupones (Membresias)

Listado de clientes/grupos familiares con deuda pendiente
Selector de periodo especifico (mes/año) para generar cupon
Opcion de generacion individual o masiva de cupones por periodo
Previsualizacion del cupon antes de generar

Vista de carga de recibo (CtaCte) - Modificacion

Campo/boton para activar escaneo de codigo de barras
Area de lectura del codigo (manual o con lector)
Indicador visual de precarga exitosa
Mensaje de advertencia si el cupon tiene fecha vencida

Interacciones del usuario

Generacion de cupon

Seleccionar cliente o grupo familiar
Indicar periodo de facturacion a incluir
Previsualizar cupon generado
Confirmar generacion
Imprimir o descargar PDF

Cobro con cupon

Acceder a vista de carga de recibo
Activar modo escaneo de codigo de barras
Escanear codigo del cupon presentado por cliente
Verificar datos precargados en pantalla
Seleccionar forma de pago
Confirmar recibo

Permisos

Permiso	Descripcion	Acciones permitidas
Generacion de cupones de pago	Permite generar cupones para clientes	Generar cupon individual, generar cupones masivos
Cobro de recibos	Permiso existente de carga de recibos	Escanear cupon, confirmar recibo
Cobro cross-schema	Permite cobrar deuda de otro schema	Cobrar facturas de clientes de otras sucursales

Estados de UI

Durante generacion de cupon

Cargando: Mientras se consulta deuda del cliente
Generando: Mientras se crea el PDF
Exito: Cupon generado exitosamente
Error: No hay deuda pendiente o datos incompletos

Durante cobro con cupon

Esperando escaneo: Campo activo para lectura de codigo
Procesando: Decodificando codigo y consultando datos
Precargado: Datos listos, esperando confirmacion del usuario
Advertencia: Cupon vencido (permite continuar)
Error: Codigo invalido o facturas ya canceladas

Backend (Perspectiva de Datos de Negocio)

Entidades de negocio involucradas

Cupon de Pago

Representa un cupon generado para cobro de la deuda de un periodo especifico.

Dato de negocio	Descripcion
Numero de cupon	Identificador unico del cupon
Cliente	Referencia al cliente titular
Periodo	Periodo al que corresponde (mes/año)
Factura	LA factura del periodo
Fecha de emision	Cuando se genero el cupon
Fecha de vencimiento	Hasta cuando es valido sugerido
Monto	Monto de la factura del periodo
Estado	Pendiente, Cobrado, Vencido
Schema de origen	Sucursal donde esta la deuda

Cobro Cross-Schema

Registro de cobros realizados entre schemas.

Dato de negocio	Descripcion
Cupon cobrado	Referencia al cupon
Schema origen	Donde esta la cuenta corriente
Schema destino	Donde se realizo el cobro
Usuario que cobro	Quien proceso el pago
Fecha y hora	Cuando se realizo
Recibo generado	Referencia al recibo de pago
Movimiento caja	Referencia al movimiento de caja

Relaciones de negocio

Un cliente puede tener multiples cupones de pago (uno por cada periodo)
Un cupon de pago corresponde a UN periodo y contiene UNA factura del periodo
Un cupon de pago pertenece a un schema de origen
Un cobro puede ser local (mismo schema) o cross-schema (schemas diferentes)
Un cobro cross-schema genera registros en dos schemas: cancelacion y movimiento de caja

Validaciones de negocio

Validacion	Descripcion	Comportamiento si no cumple
Cliente activo	El cliente debe existir y estar activo	Error: No se puede generar cupon
Deuda del periodo pendiente	Debe existir una factura pendiente para el periodo	Mensaje: No hay deuda para este periodo
Factura vigente	La factura del periodo debe estar pendiente	Error: La factura ya fue cancelada
Digito verificador valido	El DV del codigo debe ser correcto (modulo 10)	Error: Codigo de barras invalido o corrupto
Permisos cross-schema	Usuario debe tener permiso para cobrar de otro schema	Error: No tiene permisos para esta operacion

Reglas de Negocio

RN-001: Generacion de cupon por cliente titular y periodo

Descripcion: Cuando se genera un cupon, corresponde a UN periodo especifico y por lo tanto a UNA factura. Si es para un grupo familiar, el cupon se emite a nombre del cliente titular del grupo.

Condicion: Usuario solicita cupon para un cliente y periodo especifico.

Accion:

Identificar al titular si es grupo familiar
Obtener LA factura del periodo especificado
Emitir cupon a nombre del titular con la factura del periodo

RN-002: Cupon estatico al momento de generacion

Descripcion: El cupon refleja la deuda existente al momento de su generacion. No se actualiza automaticamente si la factura es cancelada posteriormente.

Condicion: Se genera un cupon de pago.

Accion:

Capturar la factura del periodo al momento de generacion
Si posteriormente la factura es cancelada, el cupon queda desactualizado
Al escanear, el sistema verifica el estado actual de la factura

RN-003: Advertencia por cupon vencido

Descripcion: Si un cupon tiene fecha de vencimiento y esta ha pasado, el sistema advierte al usuario pero permite continuar con el cobro.

Condicion: Usuario escanea cupon con fecha de vencimiento pasada.

Accion:

Mostrar advertencia: "Este cupon tiene fecha de vencimiento [fecha]. Desea continuar?"
Permitir al usuario decidir si procede con el cobro
No bloquear la operacion

RN-004: Verificacion de factura al momento del cobro

Descripcion: Al escanear un cupon, el sistema verifica que la factura del periodo aun este pendiente de pago. Si ya fue cancelada, se informa al usuario.

Condicion: Usuario escanea cupon de pago.

Accion:

Verificar estado actual de la factura del periodo
Si esta pendiente: precargar normalmente
Si ya fue cancelada: mostrar mensaje "La factura del cupon ya fue cancelada el [fecha] con recibo [numero]"
No permitir procesar el cupon si la factura ya fue cancelada

RN-005: Transaccion atomica en cobro cross-schema

Descripcion: Cuando se realiza un cobro de deuda de un schema diferente, ambos registros (cancelacion en origen y movimiento de caja en destino) deben completarse exitosamente o revertirse ambos.

Condicion: Usuario de Schema B cobra deuda de cliente de Schema A.

Accion:

Iniciar transaccion distribuida
Registrar cancelacion en Schema A
Registrar movimiento de caja en Schema B
Si ambos exitosos: confirmar transaccion
Si alguno falla: revertir ambos y mostrar error

RN-006: Auditoria completa de cobros cross-schema

Descripcion: Todo cobro cross-schema debe quedar completamente registrado para permitir trazabilidad desde cualquier punto.

Condicion: Se completa un cobro cross-schema.

Accion:

Registrar en auditoria: usuario, fecha/hora, schema destino, schema origen
Registrar comprobantes afectados
Generar referencia cruzada entre ambos schemas
Permitir consulta desde cualquier schema involucrado

RN-007: Permiso especifico para cobro cross-schema

Descripcion: Para realizar cobros de deuda de otro schema, el usuario debe tener un permiso especifico que lo autorice.

Condicion: Usuario intenta cobrar deuda de un schema diferente al suyo.

Accion:

Verificar que el usuario tiene permiso de cobro cross-schema
Si tiene permiso: permitir la operacion
Si no tiene permiso: mostrar error y no permitir el cobro

Casos de Uso

CU-001: Generacion masiva de cupones de pago

Actor: Usuario de Membresias / Administrador

Objetivo: Generar cupones de pago para enviar a todos los clientes con deuda pendiente de un periodo

Precondiciones:

Usuario autenticado con permiso de generacion de cupones
Existen clientes con deuda pendiente en el periodo seleccionado
El formato de codigo de barras esta configurado

Flujo principal:

El usuario accede al modulo de membresias
El usuario selecciona la opcion "Generar cupones de pago"
El usuario indica el periodo especifico (ejemplo: enero 2026)
El sistema muestra la lista de clientes con factura pendiente de ese periodo
El usuario selecciona "Generar todos" o selecciona clientes especificos
El sistema genera un cupon por cada cliente seleccionado (un cupon = una factura del periodo)
El usuario puede descargar los cupones individuales o en un archivo consolidado
El usuario imprime los cupones para enviar a los clientes

Postcondiciones:

Se genera un cupon de pago por cada cliente seleccionado
Cada cupon corresponde a la factura del periodo especificado
Cada cupon tiene un codigo de barras unico
Los cupones estan listos para entrega a clientes

Flujos alternativos:

Sin deuda del periodo: Si un cliente no tiene factura pendiente del periodo, no se genera cupon
Grupo familiar: Si el cliente es parte de un grupo, el cupon se genera para el titular con la factura del periodo del grupo

CU-002: Cobro de cupon en sucursal local

Actor: Cajero / Usuario de Tesoreria

Objetivo: Cobrar la deuda de un cliente que presenta un cupon de pago, donde la deuda pertenece a la misma sucursal

Precondiciones:

Usuario autenticado con permiso de carga de recibos
Cliente presente con cupon de pago impreso
Lector de codigo de barras disponible (o ingreso manual)

Flujo principal:

El cliente se presenta en caja con cupon de pago
El cajero accede a la vista de carga de recibo
El cajero activa el modo escaneo de codigo de barras
El cajero escanea el codigo del cupon
El sistema decodifica el codigo y verifica los datos
El sistema precarga el recibo con:
- Cliente seleccionado
- Factura del periodo marcada para cancelacion
- Monto de la factura
El cajero verifica que los datos son correctos
El cajero selecciona la forma de pago (efectivo, tarjeta, etc.)
El cajero confirma el recibo
El sistema genera el recibo y actualiza la cuenta corriente del cliente
El cajero entrega comprobante de pago al cliente

Postcondiciones:

La factura del periodo incluida en el cupon queda cancelada
El saldo del cliente se actualiza
Se genera movimiento de caja

Flujos alternativos:

Cupon vencido: Sistema muestra advertencia, cajero decide si continua
Factura ya cancelada: Sistema informa que la factura ya fue cancelada, no permite procesar
Codigo ilegible: Cajero puede ingresar numero de codigo manualmente

CU-003: Cobro de cupon en sucursal diferente (Cross-Schema)

Actor: Cajero / Usuario de Tesoreria

Objetivo: Cobrar la deuda de un cliente cuya cuenta corriente esta en otra sucursal (schema diferente)

Precondiciones:

Usuario autenticado con permiso de carga de recibos
Usuario con permiso de cobro cross-schema
Cliente presente con cupon de pago de otra sucursal

Flujo principal:

El cliente se presenta en caja con cupon de pago
El cajero accede a la vista de carga de recibo
El cajero escanea el codigo del cupon
El sistema detecta que la deuda pertenece a otro schema
El sistema verifica que el usuario tiene permiso de cobro cross-schema
El sistema precarga el recibo indicando:
- "COBRO CROSS-SCHEMA: Deuda de sucursal [nombre]"
- Cliente seleccionado
- Factura del periodo marcada para cancelacion
- Monto de la factura
El cajero verifica los datos y selecciona forma de pago
El cajero confirma el recibo
El sistema ejecuta transaccion distribuida:
- En schema origen: cancela la factura y actualiza saldo del cliente
- En schema destino: registra movimiento de caja
El sistema registra auditoria completa de la operacion
El cajero entrega comprobante al cliente

Postcondiciones:

En schema origen: factura cancelada, saldo actualizado, registro de que fue cobrado en otra sucursal
En schema destino: movimiento de caja registrado, referencia al schema origen
Auditoria completa de la operacion

Flujos alternativos:

Sin permiso cross-schema: Sistema informa que no puede procesar, sugiere que el cliente vaya a la sucursal correspondiente
Error en transaccion: Sistema revierte ambos registros y muestra error

Consideraciones

Seguridad

Datos sensibles en el cupon

Identificacion del cliente
Detalle de facturas y montos adeudados
Codigo de barras que permite realizar el cobro

Control de acceso

Solo usuarios con permiso pueden generar cupones
Solo usuarios con permiso pueden procesar cobros
El permiso de cobro cross-schema debe otorgarse selectivamente
Los cupones no deben ser accesibles sin autenticacion

Prevencion de fraude

El codigo de barras debe incluir mecanismo de verificacion
El sistema debe validar que las facturas aun estan pendientes
El cupon solo puede usarse una vez
Registrar intentos de uso de cupones invalidos

Auditoria

Operaciones a registrar

Operacion	Informacion a capturar
Generacion de cupon	Usuario, fecha, cliente, periodo, factura incluida, monto
Escaneo de cupon	Usuario, fecha, resultado (exito/error)
Cobro local	Usuario, fecha, recibo generado, factura cancelada
Cobro cross-schema	Usuario, fecha, schema origen, schema destino, recibo, movimiento caja
Intento fallido	Usuario, fecha, motivo del fallo, codigo escaneado

Trazabilidad

Desde el cupon debe poder rastrearse si fue cobrado, cuando, donde y por quien
Desde el recibo debe poder rastrearse si provino de un cupon
Desde el movimiento de caja debe identificarse si es cobro cross-schema

Rendimiento

Volumenes esperados

Generacion masiva: hasta 500 cupones por ejecucion
Escaneo y precarga: respuesta en menos de 3 segundos
Confirmacion de cobro cross-schema: menos de 5 segundos

Consideraciones

La generacion masiva de PDFs puede requerir procesamiento en cola
La validacion del cupon debe ser rapida para no demorar la atencion
Las transacciones cross-schema deben optimizarse para minimizar tiempo de bloqueo

Dependencias

Funcionalidades relacionadas

Facturacion de Membresias: Genera las facturas que se incluyen en los cupones
Carga de Recibos (CtaCte): Vista que se modifica para incorporar escaneo de cupones
Grupos Familiares: Logica de consolidacion de deuda por grupo
Movimientos de Caja: Registro de ingresos por cobros

Servicios externos

Sistema de Impresion: Para generacion de PDFs
Lectores de Codigo de Barras: Hardware para escaneo en puntos de cobro

Integracion con hardware

Lectores de codigo de barras: Hardware compatible con Code 128 para escaneo en puntos de cobro
Impresoras: Capacidad de imprimir codigos de barras con resolucion suficiente (minimo 203 DPI)

Criterios de Aceptacion

Componente 1: Generacion de Cupones

[x] AC-001: El usuario puede generar un cupon de pago para un cliente individual con deuda pendiente
[x] AC-002: El usuario puede generar cupones masivamente para todos los clientes con deuda en un periodo
[x] AC-003: El cupon muestra todos los datos requeridos: datos del cliente, periodo, factura del periodo, monto, codigo de barras
[x] AC-004: Para grupos familiares, el cupon se emite a nombre del titular con la factura del periodo del grupo
[x] AC-005: El codigo de barras contiene toda la informacion necesaria para el cobro
[x] AC-006: El cupon se genera en formato PDF imprimible
[x] AC-007: Si el cliente no tiene deuda pendiente, el sistema informa y no genera cupon

Componente 2: Cobro mediante Escaneo

[x] AC-008: La vista de carga de recibo permite activar modo escaneo de codigo de barras
[x] AC-009: Al escanear un codigo valido, el sistema precarga automaticamente: cliente, factura del periodo, monto
[x] AC-010: El usuario puede verificar los datos precargados antes de confirmar
[x] AC-011: Si el cupon esta vencido, el sistema muestra advertencia pero permite continuar
[x] AC-012: Si la factura del cupon ya fue cancelada, el sistema informa y no permite procesar
[x] AC-013: Al confirmar, se genera el recibo y se cancela la factura del periodo
[x] AC-014: Si se escanea un cupon cuya factura ya esta cancelada, el sistema informa y no permite procesar

Componente 3: Cobro Cross-Schema

[x] AC-015: El sistema detecta cuando la deuda pertenece a un schema diferente al del usuario
[x] AC-016: Solo usuarios con permiso de cobro cross-schema pueden procesar estos cobros
[x] AC-017: La cancelacion de la factura se registra en el schema origen (del cliente)
[x] AC-018: El movimiento de caja se registra en el schema destino (del cajero)
[x] AC-019: Si falla alguna parte de la transaccion, se revierten ambos registros
[x] AC-020: Queda auditoria completa de quien cobro, donde, cuando y que factura
[x] AC-021: Es posible rastrear el cobro desde cualquier schema involucrado

Validaciones

[x] AC-022: El sistema valida que el cliente existe y esta activo
[x] AC-023: El sistema valida que la factura del periodo esta pendiente
[x] AC-024: El sistema valida el digito verificador (DV) del codigo de barras con modulo 10
[x] AC-025: El sistema valida permisos del usuario para cada operacion

Notas Adicionales

Formato de codigo de barras implementado

El formato definitivo implementado es ITF (Interleaved 2 of 5) con 19 digitos: [SUCU(4)][CLIENTE(8)][PERIODO(6)][DV(1)]. El codigo NO contiene valores economicos; el monto se obtiene siempre de la base de datos al momento del cobro. El digito verificador utiliza algoritmo modulo 10 con ponderacion 3-1.

Integracion con sistema de membresias

El modulo de membresias:

Gestiona la facturacion periodica de clientes (cada periodo genera UNA factura)
Maneja el concepto de grupos familiares con un titular
Cada periodo tiene un patron que determina la facturacion
La deuda se organiza por periodos (un periodo = una factura)

Documentacion detallada por componente

Cada componente del proceso esta documentado individualmente:

Generacion de Cupon de Pago - Componente 1: Generacion del PDF con codigo de barras
Validacion de Cupon (Escaneo) - Componente 2: Decodificacion y validacion del codigo de barras
Cobro Cross-Schema (Multi-Sucursal) - Componente 3: Transaccion distribuida entre sucursales

Historial de Cambios

Fecha	Version	Autor	Descripcion
2026-01-21	1.0	Sistema	Creacion del documento de requerimientos de negocio
2026-01-21	1.1	Sistema	Correccion: Un cupon corresponde a UNA deuda segun patron de periodo (no consolida multiples facturas)
2026-01-21	1.2	Sistema	Agregado: Especificacion completa del formato de codigo de barras (Code 128, 7 campos, algoritmo checksum, ejemplos de implementacion)
2026-01-21	1.3	Sistema	Optimizacion: Formato compacto de 32 caracteres con identificadores cortos (sucursal 3 chars, cliente 6 chars, factura 8 chars), checksum modulo 97 (2 chars)
2026-01-21	1.4	Sistema	FORMATO DEFINITIVO: [SUCU][CLIENTE][PERIODO][DV] - 19 digitos, modulo 10 ponderacion 3-1, ITF recomendado, SIN monto en codigo (se obtiene de BD)
2026-01-21	1.5	Sistema	Eliminadas tablas cupones_procesados y auditoria_cross_schema (innecesarias, se usa validacion de estado de factura)
2026-01-27	2.0	Sistema	Estado actualizado a IMPLEMENTADO. Criterios de aceptacion marcados como cumplidos. Agregadas referencias a documentacion detallada por componente en /features/membresias/

Fase 1 Mvp

Fase 2 Sse

Fase 3 Production

Joins

Retenciones

Ganancias

Catalogos

Extensiones

Presupuestos

Recursos Principales

Relaciones

Catalogos Base

Cupon Pago

Facturacion

Gestion Miembros

Grupos Familiares

Soporte Tecnico

Architecture

Backend

Api

Database

Migrations

Middleware

Security

Services

Deployment

Development

Testing

Frontend

Integrations

Payment Gateways

Retenciones

Cupon de Pago para Membresias ​

Descripcion ​

Problema que resuelve ​

Solucion propuesta ​

Valor de negocio ​

Contexto del sistema ​

Proceso de Negocio ​

Componente 1: Generacion del Cupon de Pago ​

Flujo de generacion del cupon ​

Contenido del cupon de pago ​

Componente 2: Cobro mediante Escaneo de Codigo de Barras ​

Flujo de cobro con cupon ​

Precarga de datos en el recibo ​

Componente 3: Cobro Cross-Schema (Multi-Sucursal) ​

Escenario de cobro entre sucursales ​

Registro en schema origen (del cliente) ​

Registro en schema destino (del cajero) ​

Garantias de la transaccion ​

Formato del Codigo de Barras ​

Especificacion del formato ​

Tipo de codigo recomendado ​

Estructura del codigo ​

Detalle de cada campo ​

Ejemplo de codigo completo ​

Algoritmo del digito verificador (DV) ​

Validacion al escanear ​

Reglas de validez del formato ​

Consideraciones de seguridad ​

Manejo de errores en escaneo ​

Alternativas de implementacion ​

Ejemplo de implementacion del codigo ​

Buenas practicas de implementacion ​

Frontend (Perspectiva de Usuario) ​

Vistas ​

Interacciones del usuario ​

Permisos ​

Estados de UI ​

Backend (Perspectiva de Datos de Negocio) ​

Entidades de negocio involucradas ​

Cupon de Pago ​

Cobro Cross-Schema ​

Relaciones de negocio ​

Validaciones de negocio ​

Reglas de Negocio ​

RN-001: Generacion de cupon por cliente titular y periodo ​

RN-002: Cupon estatico al momento de generacion ​

RN-003: Advertencia por cupon vencido ​

RN-004: Verificacion de factura al momento del cobro ​

Cupon de Pago para Membresias

Descripcion

Problema que resuelve

Solucion propuesta

Valor de negocio

Contexto del sistema

Proceso de Negocio

Componente 1: Generacion del Cupon de Pago

Flujo de generacion del cupon

Contenido del cupon de pago

Componente 2: Cobro mediante Escaneo de Codigo de Barras

Flujo de cobro con cupon

Precarga de datos en el recibo

Componente 3: Cobro Cross-Schema (Multi-Sucursal)

Escenario de cobro entre sucursales

Registro en schema origen (del cliente)

Registro en schema destino (del cajero)

Garantias de la transaccion

Formato del Codigo de Barras

Especificacion del formato

Tipo de codigo recomendado

Estructura del codigo

Detalle de cada campo

Ejemplo de codigo completo

Algoritmo del digito verificador (DV)

Validacion al escanear

Reglas de validez del formato

Consideraciones de seguridad

Manejo de errores en escaneo

Alternativas de implementacion

Ejemplo de implementacion del codigo

Buenas practicas de implementacion

Frontend (Perspectiva de Usuario)

Vistas

Interacciones del usuario

Permisos

Estados de UI

Backend (Perspectiva de Datos de Negocio)

Entidades de negocio involucradas

Cupon de Pago

Cobro Cross-Schema

Relaciones de negocio

Validaciones de negocio

Reglas de Negocio

RN-001: Generacion de cupon por cliente titular y periodo

RN-002: Cupon estatico al momento de generacion

RN-003: Advertencia por cupon vencido

RN-004: Verificacion de factura al momento del cobro

RN-005: Transaccion atomica en cobro cross-schema

RN-006: Auditoria completa de cobros cross-schema

RN-007: Permiso especifico para cobro cross-schema

Casos de Uso

CU-001: Generacion masiva de cupones de pago

CU-002: Cobro de cupon en sucursal local

CU-003: Cobro de cupon en sucursal diferente (Cross-Schema)

Consideraciones

Seguridad

Auditoria

Rendimiento

Dependencias

Funcionalidades relacionadas

Servicios externos

Integracion con hardware

Criterios de Aceptacion

Componente 1: Generacion de Cupones

Componente 2: Cobro mediante Escaneo

Componente 3: Cobro Cross-Schema

Validaciones

Notas Adicionales

Formato de codigo de barras implementado

Integracion con sistema de membresias

Documentacion detallada por componente

Historial de Cambios