Appearance
Cobro Cross-Schema (Multi-Sucursal)
Modulo: Membresias / CtaCte / Tesoreria Tipo: Process Estado: Implementado Fecha: 2026-01-27 Fecha de Implementacion: 2026-01-27
Documento de referencia integral: Cupon de Pago - Proceso Integral
Este documento describe la funcionalidad especifica de cobro de deuda entre sucursales (cross-schema). Para el proceso completo (generacion, validacion y cobro cross-schema), consultar el documento de referencia.
Descripcion
Problema que resuelve
En un sistema multi-sucursal, la deuda de un cliente se registra en la sucursal (schema) donde fue facturada. Cuando el cliente desea pagar en una sucursal diferente a donde se genero su deuda, el proceso se complica porque los datos de la cuenta corriente del cliente y los datos de la caja del cobrador estan en schemas diferentes. Sin un mecanismo adecuado, se podria cancelar la deuda en un schema sin registrar el ingreso de dinero en la caja del otro schema, generando inconsistencias contables.
Solucion
Se implementa un mecanismo de cobro cross-schema que ejecuta una transaccion atomica distribuida en dos schemas:
- Schema origen (donde esta la deuda del cliente): Se cancela la factura y se actualiza el saldo de la cuenta corriente del cliente
- Schema destino (donde esta el cajero): Se registra el movimiento de ingreso de dinero en la caja
Ambas operaciones deben completarse exitosamente o revertirse ambas, garantizando la consistencia de datos en todo momento.
Valor de negocio
- Flexibilidad para el cliente: El cliente puede pagar en cualquier sucursal de la empresa, no solo donde fue facturado
- Mayor recaudacion: Se eliminan barreras de cobro por ubicacion, facilitando el pago oportuno
- Operacion unificada: La empresa opera como una sola entidad de cobro, independientemente de la sucursal
- Trazabilidad completa: El sistema registra exactamente quien cobro, donde cobro y a que sucursal pertenecia la deuda
- Integridad contable: La transaccion atomica garantiza que no haya desbalances entre sucursales
Frontend (Perspectiva de Usuario)
Vistas
Vista de carga de recibo (CtaCte) - Indicador cross-schema
- Cuando se detecta un cobro cross-schema (tras escanear cupon de otra sucursal), la vista muestra claramente:
- Indicacion destacada: "COBRO CROSS-SCHEMA: Deuda de sucursal [nombre]"
- Datos del cliente precargados (provenientes del schema origen)
- Factura del periodo y monto (obtenidos del schema origen)
- Formulario de recibo con campos habituales (forma de pago, observaciones)
Interacciones del usuario
Cobro de deuda de otra sucursal
- El cajero escanea un cupon de pago (el proceso de validacion detecta automaticamente que es cross-schema; ver Validacion de Cupon)
- El sistema muestra la indicacion de cobro cross-schema con datos precargados
- El cajero verifica la informacion: cliente, factura, monto, sucursal de origen
- El cajero selecciona la forma de pago
- El cajero confirma el recibo
- El sistema ejecuta la transaccion distribuida (cancelacion en origen + movimiento de caja en destino)
- El sistema confirma la operacion exitosa o informa del error con rollback automatico
- El cajero entrega comprobante de pago al cliente
Permisos
| Permiso | Descripcion | Acciones permitidas |
|---|---|---|
| Cobro de recibos | Permiso base de carga de recibos | Escanear cupon, ver datos, confirmar recibo |
| Cobro cross-schema | Permiso especifico para cobros entre sucursales | Procesar cobros de deuda de otra sucursal |
IMPORTANTE: El permiso de cobro cross-schema debe otorgarse selectivamente. No todos los usuarios que pueden cobrar recibos locales necesariamente deben poder cobrar deuda de otras sucursales.
Estados de UI
- Precargado cross-schema: Datos listos con indicacion destacada de que es cobro entre sucursales
- Procesando transaccion: Ejecutando la operacion distribuida en ambos schemas
- Exito: Transaccion completada exitosamente en ambos schemas; comprobante generado
- Error - Sin permiso: El usuario no tiene permiso de cobro cross-schema; se sugiere que el cliente acuda a la sucursal correspondiente
- Error - Transaccion fallida: Error en alguno de los schemas; se informa que la operacion fue revertida completamente y se debe reintentar
Backend (Perspectiva de Datos de Negocio)
Proceso de Cobro Cross-Schema
El cobro cross-schema involucra una transaccion distribuida que afecta dos schemas simultaneamente:
Operaciones en el Schema Origen (donde esta la deuda del cliente):
- Cancelacion de la factura del periodo
- Actualizacion del saldo de la cuenta corriente del cliente
- Registro de que la factura fue cobrada en otra sucursal
- Referencia cruzada al schema donde se realizo el cobro
Operaciones en el Schema Destino (donde esta el cajero):
- Registro del movimiento de ingreso de dinero en la caja del usuario
- Indicacion de que es un cobro por cuenta de otra sucursal
- Referencia cruzada al schema de origen del cliente
Entidades de negocio involucradas
Registro de cobro cross-schema Informacion asociada a una operacion de cobro entre sucursales.
| Dato de negocio | Descripcion |
|---|---|
| Schema origen | Sucursal donde esta la cuenta corriente del cliente y la deuda |
| Schema destino | Sucursal donde se realiza el cobro (donde esta el cajero) |
| Cliente | Referencia al cliente titular de la deuda |
| Factura cancelada | La factura del periodo que se cancela |
| Monto cobrado | Importe del cobro |
| Recibo generado | Comprobante de pago emitido |
| Movimiento de caja | Registro de ingreso en la caja del cajero |
| Usuario que cobro | Identificacion del cajero que proceso el pago |
| Fecha y hora | Momento exacto de la operacion |
Cuenta corriente del cliente (Schema origen)
| Dato de negocio | Descripcion |
|---|---|
| Saldo del cliente | Se actualiza al cancelar la factura |
| Factura del periodo | Cambia de estado pendiente a cancelada |
| Referencia de cobro externo | Indicacion de que fue cobrado en otra sucursal |
Caja del cajero (Schema destino)
| Dato de negocio | Descripcion |
|---|---|
| Movimiento de caja | Nuevo ingreso por cobro cross-schema |
| Referencia de cobro externo | Indicacion de que la deuda pertenece a 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 |
Relaciones de negocio
- Un cobro cross-schema genera registros en dos schemas: cancelacion en origen y movimiento de caja en destino
- El recibo en el schema origen tiene referencia cruzada al movimiento de caja en el schema destino
- El movimiento de caja en el schema destino tiene referencia cruzada a la cancelacion en el schema origen
- Un cobro cross-schema siempre esta asociado a un cupon de pago escaneado
Validaciones de negocio
| Validacion | Descripcion | Comportamiento si no cumple |
|---|---|---|
| Permiso de cobro cross-schema | El usuario debe tener permiso especifico | Error: "No tiene permisos para cobrar deuda de otra sucursal" |
| Schema origen accesible | El schema de la sucursal del cliente debe ser accesible | Error: "No se puede acceder a la sucursal de origen" |
| Factura aun pendiente | La factura debe seguir pendiente al momento de ejecutar la transaccion | Error: "La factura ya fue cancelada" (evita doble cobro) |
| Caja abierta | El cajero debe tener una caja abierta en el schema destino | Error: "No hay caja abierta para registrar el cobro" |
| Transaccion atomica | Ambos registros deben completarse exitosamente | Rollback automatico de ambos schemas si alguno falla |
Reglas de Negocio
RN-001: Transaccion atomica en cobro cross-schema
Descripcion: Cuando se realiza un cobro de deuda de un schema diferente, ambos registros (cancelacion de factura en schema origen y movimiento de caja en schema destino) deben completarse exitosamente o revertirse ambos. No puede quedar una operacion sin la otra.
Condicion: El usuario confirma un cobro cross-schema.
Accion:
- Iniciar transaccion distribuida en ambos schemas
- Registrar cancelacion de factura y actualizacion de saldo en schema origen
- Registrar movimiento de caja en schema destino
- Si ambos exitosos: confirmar transaccion completa
- Si alguno falla: revertir ambos schemas y mostrar error al usuario
RN-002: Auditoria completa de cobros cross-schema
Descripcion: Todo cobro cross-schema debe quedar completamente registrado para permitir trazabilidad desde cualquier punto. La auditoria debe capturar todos los datos relevantes de la operacion.
Condicion: Se completa exitosamente un cobro cross-schema.
Accion:
- Registrar en auditoria: usuario que cobro, fecha y hora, schema origen, schema destino
- Registrar los comprobantes afectados (factura cancelada, recibo generado, movimiento de caja)
- Generar referencia cruzada entre ambos schemas
- Permitir consulta y rastreo de la operacion desde cualquier schema involucrado
RN-003: Permiso especifico para cobro cross-schema
Descripcion: Para realizar cobros de deuda de otra sucursal, el usuario debe tener un permiso especifico que lo autorice. Este permiso es independiente del permiso general de cobro de recibos.
Condicion: El 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: rechazar la operacion con mensaje claro; sugerir que el cliente acuda a la sucursal correspondiente
RN-004: Referencia cruzada entre schemas
Descripcion: En un cobro cross-schema, cada schema debe mantener una referencia al otro para permitir la trazabilidad bidireccional. Desde el schema origen debe poder identificarse donde se cobro, y desde el schema destino debe poder identificarse de donde proviene la deuda.
Condicion: Se registra un cobro cross-schema.
Accion:
- En schema origen: registrar referencia al schema destino donde se realizo el cobro
- En schema destino: registrar referencia al schema origen de donde proviene la deuda
- Ambas referencias deben permitir la consulta cruzada
RN-005: Rollback automatico en caso de error
Descripcion: Si durante la ejecucion de la transaccion distribuida ocurre un error en cualquiera de los dos schemas, el sistema debe revertir automaticamente todas las operaciones realizadas en ambos schemas, dejando los datos en el estado previo a la operacion.
Condicion: Error durante la ejecucion de la transaccion distribuida.
Accion:
- Detectar el error en cualquiera de los schemas
- Revertir todas las operaciones en el schema origen
- Revertir todas las operaciones en el schema destino
- Informar al usuario que la operacion no pudo completarse
- Registrar el error en auditoria para investigacion
Casos de Uso
CU-001: Cobro exitoso de cupon en sucursal diferente
Actor: Cajero / Usuario de Tesoreria
Objetivo: Cobrar la deuda de un cliente cuya cuenta corriente esta en otra sucursal
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
- Caja abierta en la sucursal del cajero
- El cupon ya fue validado exitosamente (ver Validacion de Cupon)
Flujo principal:
- El sistema presenta los datos precargados indicando "COBRO CROSS-SCHEMA: Deuda de sucursal [nombre]"
- El cajero verifica los datos: cliente, factura del periodo, monto, sucursal de origen
- El cajero selecciona la forma de pago (efectivo, tarjeta, etc.)
- El cajero confirma el recibo
- El sistema ejecuta la transaccion distribuida:
- En schema origen: cancela la factura del periodo y actualiza el saldo del cliente
- En schema destino: registra el movimiento de ingreso en la caja del cajero
- El sistema genera referencias cruzadas entre ambos schemas
- El sistema registra la auditoria completa de la operacion
- El sistema confirma el exito de la operacion
- El cajero entrega comprobante de pago al cliente
Postcondiciones:
- En schema origen: factura del periodo cancelada, saldo del cliente actualizado, registro de cobro externo con referencia al schema destino
- En schema destino: movimiento de caja registrado con referencia al schema origen
- Auditoria completa de la operacion (usuario, fecha/hora, schemas, comprobantes)
- Comprobante de pago entregado al cliente
Flujos alternativos:
- Error en transaccion: El sistema revierte automaticamente ambos registros, informa al usuario que la operacion no pudo completarse, y sugiere reintentar
- Factura cancelada entre validacion y cobro: Si entre el momento de la validacion y la confirmacion del cobro la factura fue cancelada por otro medio, el sistema detecta el cambio y rechaza la operacion
CU-002: Intento de cobro cross-schema sin permisos
Actor: Cajero / Usuario de Tesoreria
Objetivo: Detectar y rechazar cobros cross-schema cuando el usuario no tiene permiso
Precondiciones:
- Usuario autenticado con permiso de carga de recibos (pero SIN permiso de cobro cross-schema)
- El cupon escaneado pertenece a otra sucursal
Flujo principal:
- El sistema detecta que el cupon pertenece a una sucursal diferente (durante la validacion)
- El sistema verifica los permisos del usuario
- El sistema detecta que el usuario NO tiene permiso de cobro cross-schema
- El sistema muestra mensaje: "No tiene permisos para cobrar deuda de otra sucursal. Sugiera al cliente acudir a la sucursal [nombre]"
- El sistema no permite procesar el cobro
Postcondiciones:
- El cobro no se procesa
- Se registra en auditoria el intento fallido por falta de permisos
CU-003: Cobro cross-schema con error en transaccion
Actor: Cajero / Usuario de Tesoreria
Objetivo: Manejar errores durante la transaccion distribuida garantizando la integridad de datos
Precondiciones:
- Usuario autenticado con todos los permisos necesarios
- Cupon validado exitosamente como cross-schema
- Cajero confirma el cobro
Flujo principal:
- El sistema inicia la transaccion distribuida
- El sistema ejecuta la cancelacion de factura en el schema origen
- El sistema intenta registrar el movimiento de caja en el schema destino
- Ocurre un error (conexion, conflicto, etc.)
- El sistema detecta el error y ejecuta rollback automatico en ambos schemas
- El sistema muestra mensaje: "La operacion no pudo completarse. Se revirtieron todos los cambios. Por favor reintente"
- El sistema registra el error en auditoria para investigacion
Postcondiciones:
- Ambos schemas quedan en el estado previo a la operacion (sin cambios)
- No hay datos inconsistentes entre schemas
- Se registra el error en auditoria con detalles para investigacion
- El usuario puede reintentar la operacion
Consideraciones
Seguridad
Control de acceso
- El permiso de cobro cross-schema debe otorgarse selectivamente y no estar incluido en perfiles basicos de cajero
- Solo usuarios expresamente autorizados pueden procesar cobros de deuda de otra sucursal
- El sistema verifica permisos antes de iniciar cualquier operacion cross-schema
Prevencion de fraude
- El cupon solo puede usarse una vez (la factura queda cancelada)
- La transaccion atomica impide estados inconsistentes que podrian ser explotados
- La auditoria completa permite detectar patrones anomalos de cobros entre sucursales
Integridad de datos
- La transaccion distribuida garantiza que no queden operaciones a medias
- Las referencias cruzadas permiten verificar la consistencia entre schemas
- El rollback automatico protege contra corrupcion de datos
Auditoria
| Operacion | Informacion a capturar |
|---|---|
| Cobro cross-schema exitoso | Usuario que cobro, fecha/hora, schema origen, schema destino, factura cancelada, recibo generado, movimiento de caja, monto cobrado |
| Intento fallido por permisos | Usuario, fecha/hora, schema origen detectado, motivo del rechazo |
| Error en transaccion | Usuario, fecha/hora, schemas involucrados, tipo de error, confirmacion de rollback |
Trazabilidad bidireccional
- Desde la cuenta corriente del cliente (schema origen): se puede identificar que la factura fue cobrada en otra sucursal, cuando, por quien
- Desde el movimiento de caja (schema destino): se puede identificar que el ingreso corresponde a deuda de otra sucursal, de que cliente
- Desde cualquier schema involucrado: se puede reconstruir la operacion completa
Rendimiento
- Confirmacion de cobro cross-schema: Respuesta esperada en menos de 5 segundos
- La transaccion distribuida involucra operaciones en dos schemas, por lo que requiere mas tiempo que un cobro local
- Se debe minimizar el tiempo de bloqueo de recursos en ambos schemas para evitar contenciones
Dependencias
Funcionalidades relacionadas
- Validacion de Cupon (Escaneo): cupon-validacion-process.md - La deteccion de cobro cross-schema se realiza durante la validacion del cupon
- Generacion de Cupon de Pago: cupon-generacion-process.md - El cupon contiene la informacion de sucursal que permite identificar el cobro cross-schema
- Carga de Recibos (CtaCte): Vista que se utiliza para el cobro y que muestra la indicacion de cross-schema
- Movimientos de Caja (Tesoreria): Registro del ingreso de dinero en la caja del cajero
- Sistema Multi-tenant: Infraestructura de separacion de datos por sucursal que hace posible y necesario este proceso
Servicios externos
- Sistema multi-tenant: Acceso simultaneo a dos schemas diferentes dentro de una misma transaccion
- Lectores de codigo de barras: Para escaneo del cupon que inicia el proceso
Criterios de Aceptacion
- [x] AC-001: El sistema detecta automaticamente cuando la deuda del cupon pertenece a una sucursal diferente a la del cajero
- [x] AC-002: Solo usuarios con permiso de cobro cross-schema pueden procesar estos cobros
- [x] AC-003: Al confirmar, la cancelacion de la factura se registra en el schema origen (del cliente)
- [x] AC-004: Al confirmar, el movimiento de caja se registra en el schema destino (del cajero)
- [x] AC-005: La transaccion es atomica: si falla alguna parte, se revierten ambos registros automaticamente
- [x] AC-006: Queda auditoria completa de quien cobro, donde cobro, cuando y que factura fue cancelada
- [x] AC-007: Es posible rastrear el cobro desde cualquier schema involucrado (trazabilidad bidireccional)
- [x] AC-008: Se generan referencias cruzadas entre ambos schemas para mantener la integridad referencial logica
- [x] AC-009: Si el usuario no tiene permiso de cobro cross-schema, el sistema rechaza la operacion con mensaje claro
- [x] AC-010: El sistema muestra claramente al cajero que se trata de un cobro cross-schema antes de confirmar
- [x] AC-011: Los errores en la transaccion resultan en rollback completo con mensaje informativo al usuario
Notas Adicionales
Relacion con el documento de proceso integral
Este documento cubre especificamente la funcionalidad de cobro cross-schema (Componente 3 del proceso integral). Para el proceso completo, consultar el documento de proceso integral.
Escenario operativo tipico
El escenario mas comun de cobro cross-schema se presenta cuando:
- La empresa tiene multiples sucursales (cada una con su propio schema)
- Un cliente es facturado en su sucursal asignada (schema A)
- El cliente recibe un cupon de pago impreso
- El cliente se presenta a pagar en una sucursal diferente (schema B), mas cercana o conveniente
- El cajero de schema B escanea el cupon y el sistema gestiona automaticamente la transaccion distribuida
Consideraciones multi-tenant
El cobro cross-schema es una consecuencia directa de la arquitectura multi-tenant basada en schemas de la empresa. Los aspectos clave son:
- Cada sucursal mantiene sus propios datos (cuenta corriente, caja) en schemas separados
- El cobro cross-schema coordina operaciones entre dos schemas distintos
- Las referencias cruzadas permiten mantener la integridad logica sin romper el aislamiento de schemas
- La atomicidad de la transaccion garantiza la consistencia contable entre sucursales
Historial de Cambios
| Fecha | Version | Autor | Descripcion |
|---|---|---|---|
| 2026-01-27 | 1.0 | Sistema | Creacion del documento - Funcionalidad YA IMPLEMENTADA en produccion |