Identificadores Globales para Comprobantes de Venta

Modulo: Ventas Tipo: Resource Estado: Implementado Fecha: 2025-12-26 Version: 1.3

---

Descripcion

Problema de negocio

En un sistema multi-sucursal con arquitectura de esquemas separados por sucursal, cada sucursal genera sus propios comprobantes de venta con identificadores numericos locales (secuenciales dentro de cada sucursal). Esta arquitectura genera el siguiente problema critico:

Superposicion de identificadores: El mismo numero de identificador puede existir en diferentes sucursales. Por ejemplo:

• Sucursal 1 puede tener una factura de venta con identificador 1000
• Sucursal 2 puede tener una factura de venta diferente tambien con identificador 1000
• Cuando se requiere referenciar un comprobante desde otro modulo a nivel empresa, no es posible determinar univocamente a cual comprobante se refiere el identificador 1000

Este problema afecta las siguientes operaciones de negocio:

• Consolidacion de informacion: Los reportes y consultas a nivel empresa no pueden relacionar correctamente operaciones con comprobantes de diferentes sucursales
• Auditoria centralizada: No es posible auditar relaciones entre modulos cuando los identificadores se superponen entre sucursales
• Integraciones externas: Los sistemas externos que consumen informacion del ERP no pueden referenciar comprobantes de forma univoca

Necesidad del negocio

El sistema requiere implementar un mecanismo de identificacion global que resuelva la superposicion de identificadores locales, proporcionando:

1. Identificadores unicos a nivel empresa: Cada comprobante de venta debe tener un identificador unico que lo distinga de cualquier otro comprobante de la empresa, independientemente de la sucursal que lo genero

2. Mapeo transparente: El sistema debe mantener un mapeo entre el identificador local de cada sucursal y el identificador global de la empresa

3. Compatibilidad retroactiva: Los comprobantes existentes deben incorporarse al nuevo esquema de identificacion sin perdida de datos ni interrupcion del servicio

Valor de negocio

La implementacion de identificadores globales aportara los siguientes beneficios:

1. Trazabilidad inequivoca: Cada referencia a un comprobante de venta sera unica e irrepetible en toda la empresa, eliminando ambiguedades

2. Integridad de datos a nivel empresa: Las operaciones que referencian comprobantes de venta tendran relaciones correctas independientemente de la sucursal de origen

3. Consolidacion confiable: Los reportes consolidados a nivel empresa podran relacionar informacion de forma precisa

4. Auditoria simplificada: Los procesos de verificacion y control podran rastrear relaciones entre modulos sin ambiguedades

5. Preparacion para integraciones: El sistema estara preparado para exponer identificadores unicos a sistemas externos

6. Escalabilidad: La solucion permite agregar nuevas sucursales sin riesgo de conflictos de identificadores

Contexto en el proceso de negocio

Esta funcionalidad se integra en los siguientes flujos:

Flujo de ventas:

1. El usuario registra un comprobante de ventas en su sucursal
2. El sistema asigna el identificador local secuencial de la sucursal
3. [Esta funcionalidad] El sistema genera y registra un identificador global unico para el comprobante
4. El sistema registra el mapeo: identificador local + tipo de comprobante + sucursal -> identificador global
5. Otros modulos pueden utilizar el identificador global para referenciar el comprobante de forma univoca

Flujo de migracion de datos existentes:

1. El administrador ejecuta el proceso de migracion
2. El sistema recorre todos los comprobantes de venta existentes en todas las sucursales
3. Por cada comprobante, el sistema genera un identificador global unico
4. El sistema registra el mapeo correspondiente
5. El proceso valida la integridad de los datos migrados

---

Frontend

Vistas

Esta funcionalidad es principalmente de infraestructura y no requiere vistas especificas de usuario.

Interacciones del usuario

• Los usuarios no interactuan directamente con los identificadores globales
• El proceso de generacion de identificadores globales es automatico y transparente
• Los usuarios continuan trabajando con los numeros de comprobante habituales
• En reportes consolidados, el sistema utiliza internamente los identificadores globales para garantizar precision

Estados de UI

• No aplica - La funcionalidad opera de forma transparente al usuario

---

Backend

Entidades de negocio

Identificador Global de Comprobante de Venta

Representa el mapeo entre el identificador local de un comprobante de venta en una sucursal y su identificador unico a nivel empresa.

Proposito: Proporcionar un identificador univoco que permita referenciar cualquier comprobante de venta de la empresa sin ambiguedad, independientemente de la sucursal que lo genero.

Caracteristicas de negocio:

• Cada combinacion de identificador local + tipo de comprobante + sucursal tiene exactamente un identificador global
• El identificador global es unico en toda la empresa
• El registro incluye la sucursal de origen para trazabilidad
• Una vez creado, el identificador global no puede modificarse

Datos necesarios

Para el identificador global de comprobantes de venta

Dato	Descripcion	Obligatoriedad
Identificador del registro	Identificador unico del registro de mapeo	Obligatorio (generado por el sistema)
Identificador local de venta	Numero identificador del comprobante dentro de la sucursal	Obligatorio
Identificador global	Identificador unico del comprobante a nivel empresa	Obligatorio (generado automaticamente por el sistema)
Tipo de comprobante	Codigo numerico del tipo de comprobante segun clasificacion fiscal (codigo AFIP)	Obligatorio
Sucursal de origen	Identificador de la sucursal que registro el comprobante	Obligatorio
Fecha de creacion	Marca temporal de cuando se creo el registro de mapeo	Obligatorio (generado automaticamente por el sistema)

Nota sobre tipos de comprobante: El tipo de comprobante se almacena como codigo numerico siguiendo la clasificacion fiscal oficial (AFIP). Esta representacion permite un manejo estandarizado y compatible con los requerimientos fiscales argentinos. Los usuarios continuan viendo la descripcion amigable (Factura A, Nota de Credito, etc.) en la interfaz.

Relaciones de negocio

Comprobante de Venta (Sucursal) ---- (1:1) ---- Identificador Global de Venta

Cardinalidades:

• Un comprobante de venta tiene exactamente un identificador global
• Un identificador global de venta corresponde a exactamente un comprobante

Validaciones de negocio

Para el registro de identificadores globales de venta

1. Unicidad del identificador global:

   • El identificador global generado debe ser unico en toda la empresa
   • No puede existir otro comprobante de venta (de ninguna sucursal) con el mismo identificador global

2. Unicidad del mapeo:

   • La combinacion de identificador local + tipo de comprobante + schema principal debe ser unica
   • No puede existir mas de un identificador global para el mismo comprobante

3. Existencia del comprobante:

   • Al crear el registro de mapeo, el comprobante de venta referenciado debe existir en el schema principal indicado

4. Validez del schema:

   • El schema principal de origen debe ser un schema valido y activo en el sistema

5. Inmutabilidad del identificador global:

   • Una vez asignado, el identificador global no puede modificarse
   • Se elimina junto con el comprobante si este es eliminado

---

Reglas de Negocio

RN-001: Generacion automatica de identificador global al registrar comprobante de venta

Descripcion: Cuando se registra un nuevo comprobante de venta, el sistema debe generar y registrar automaticamente su identificador global unico.

Condicion: Se esta registrando un nuevo comprobante de venta (factura, nota de credito, nota de debito) o carga manual de los mismos en cualquier sucursal.

Accion:

• El sistema genera un identificador global unico para el comprobante
• El sistema crea el registro de mapeo con: identificador local, identificador global, tipo de comprobante, schema principal de origen
• La generacion del identificador global es atomica con el registro del comprobante

Fundamento: Garantiza que todo nuevo comprobante de venta (factura, nota de credito, nota de debito) tenga un identificador unico a nivel empresa desde el momento de su creacion. Esto incluye tanto comprobantes electrónicos como cargas manuales.

---

RN-002: Unicidad del identificador global a nivel empresa

Descripcion: Cada identificador global debe ser unico en toda la empresa, sin posibilidad de duplicados entre sucursales ni entre tipos de comprobantes.

Condicion: Se genera un nuevo identificador global para cualquier comprobante de venta.

Accion:

• El sistema valida que el identificador global no exista previamente
• Si existe conflicto (extremadamente improbable con UUID), el sistema genera un nuevo identificador
• El identificador queda reservado de forma exclusiva para ese comprobante

Fundamento: Garantiza que el identificador global cumpla su proposito de identificacion univoca.

---

RN-003: Registro obligatorio de schema principal de origen

Descripcion: Todo registro de identificador global debe incluir el schema principal de PostgreSQL que genero el comprobante original.

Condicion: Se crea un registro de mapeo de identificador global.

Accion:

• El sistema registra automaticamente el identificador del schema principal donde se esta creando el comprobante
• Esta informacion no puede modificarse posteriormente

Fundamento: Permite mantener la trazabilidad del origen de cada comprobante para auditorias y consultas. El schema principal identifica univocamente la sucursal en la arquitectura multi-tenant.

---

RN-004: Inmutabilidad del identificador global

Descripcion: Una vez asignado un identificador global a un comprobante, este no puede modificarse.

Condicion: Existe un registro de mapeo de identificador global.

Accion:

• El sistema rechaza cualquier intento de modificar el identificador global
• El sistema rechaza cualquier intento de modificar la sucursal de origen
• El registro se elimina unicamente cuando el comprobante asociado es eliminado

Fundamento: Garantiza la integridad de las referencias que utilizan el identificador global.

---

RN-005: Migracion obligatoria de comprobantes existentes

Descripcion: Todos los comprobantes de venta existentes en el sistema deben tener asignado un identificador global antes de la puesta en produccion de esta funcionalidad.

Condicion: Existen comprobantes de venta sin identificador global asignado.

Accion:

• El proceso de migracion recorre todos los comprobantes existentes de venta
• Por cada comprobante sin identificador global, genera uno nuevo
• Registra el mapeo correspondiente
• Valida la integridad de los datos migrados

Fundamento: Garantiza que el sistema funcione de forma consistente para comprobantes nuevos y existentes.

---

RN-006: Eliminacion del mapeo al eliminar comprobante

Descripcion: Cuando se elimina un comprobante de venta, su registro de identificador global debe eliminarse tambien.

Condicion: Se elimina un comprobante de venta.

Accion:

• El sistema elimina el registro de mapeo de identificador global asociado al comprobante
• El identificador global queda liberado (aunque por ser UUID, no se reutiliza)
• Se elimina toda la trazabilidad del comprobante

Fundamento: Mantiene la consistencia de datos - si el comprobante no existe, su mapeo de identificador global tampoco debe existir.

---

RN-007: Consulta de comprobante por identificador global

Descripcion: El sistema debe permitir localizar un comprobante de venta utilizando su identificador global, independientemente de la sucursal actual del usuario.

Condicion: Se solicita consultar un comprobante mediante su identificador global.

Accion:

• El sistema busca el registro de mapeo por identificador global
• Obtiene el identificador local, tipo de comprobante y schema principal de origen
• Recupera el comprobante del schema correspondiente
• Retorna la informacion del comprobante

Fundamento: Permite operaciones a nivel empresa que requieren localizar comprobantes de cualquier sucursal.

---

RN-008: Registro del tipo de comprobante

Descripcion: El registro de identificador global debe incluir el tipo de comprobante de venta para distinguir entre diferentes documentos.

Condicion: Se crea un registro de mapeo de identificador global.

Accion:

• El sistema registra el tipo de comprobante (factura, recibo, nota de credito, nota de debito)
• Esta informacion permite identificar el tipo de documento sin necesidad de consultar el comprobante

Fundamento: Facilita la identificacion del tipo de documento y permite filtros por tipo en consultas.

---

RN-009: Determinacion del schema de origen basado en ubicacion real de la tabla

Descripcion: El schema registrado en el mapeo de identificador global debe ser el schema donde reside fisicamente la tabla del comprobante, no el schema del usuario que realiza la operacion.

Condicion: Se crea un registro de mapeo de identificador global para un comprobante de venta.

Contexto tecnico: En la arquitectura multi-tenant del sistema, PostgreSQL utiliza un search_path que puede incluir multiples schemas. Por ejemplo:

• Un usuario operando desde una caja tiene schema suc0001caja001
• El search_path se configura como: suc0001caja001, suc0001, public
• Las tablas de comprobantes de venta (factura, credito, debito) residen en el schema de sucursal (suc0001), no en el schema de caja

Accion:

• El sistema debe determinar el schema donde reside fisicamente la tabla del comprobante, no usar directamente el schema del usuario
• Para tablas de comprobantes de venta, se debe extraer el schema de sucursal
• Si el schema del usuario es de caja (sucXXXXcajaXXXX), el sistema debe registrar el schema de sucursal (sucXXXX) como origen
• Si el schema del usuario ya es de sucursal (sucXXXX), se utiliza directamente

Fundamento: Garantiza que el mapeo de identificadores globales refleje correctamente la ubicacion real del comprobante en la base de datos. Registrar el schema del usuario en lugar del schema de la tabla causaria inconsistencias en las consultas inversas y en la migracion de datos historicos.

---

Casos de Uso

CU-001: Registrar comprobante de venta con identificador global

Actor: Usuario de Ventas

Objetivo: Registrar un nuevo comprobante de venta que automaticamente recibe un identificador global unico

Precondiciones:

• Usuario autenticado con permisos de facturacion
• Usuario operando en una sucursal especifica

Flujo principal:

1. El usuario completa los datos del comprobante de venta (factura, nota de credito, etc.)
2. El usuario confirma el registro del comprobante
3. El sistema valida y registra el comprobante de venta con su identificador local
4. El sistema genera automaticamente un identificador global unico
5. El sistema crea el registro de mapeo: identificador local + tipo + schema principal -> identificador global
6. El sistema confirma la operacion exitosa al usuario

Postcondiciones:

• El comprobante de venta queda registrado con su identificador local habitual
• Existe un identificador global unico asociado al comprobante
• El registro de mapeo esta disponible para consultas y referencias

Flujos alternativos:

• Error en generacion de identificador global: Si ocurre un error al generar el identificador global, se revierte toda la operacion incluyendo el comprobante

---

CU-002: Migrar comprobantes de venta existentes a identificadores globales

Actor: Administrador del Sistema

Objetivo: Asignar identificadores globales a todos los comprobantes de venta existentes que no tienen uno

Precondiciones:

• Usuario con permisos de administracion del sistema
• Existen comprobantes de venta sin identificador global asignado
• El sistema esta en un estado que permite ejecutar la migracion

Flujo principal:

1. El administrador inicia el proceso de migracion
2. El sistema identifica todas las sucursales de la empresa
3. Por cada sucursal:
   • El sistema identifica todos los comprobantes de venta sin identificador global
   • Por cada comprobante encontrado:
     • El sistema determina el tipo de comprobante
     • El sistema genera un identificador global unico
     • El sistema crea el registro de mapeo
4. El sistema valida la integridad de los datos migrados
5. El sistema genera un reporte de la migracion realizada
6. El sistema confirma la migracion exitosa

Postcondiciones:

• Todos los comprobantes de venta tienen identificador global asignado
• No hay registros duplicados de identificadores globales
• El reporte de migracion esta disponible para revision

Flujos alternativos:

• Error durante migracion: Si ocurre un error, el sistema puede reiniciar la migracion desde el punto de fallo (proceso idempotente)
• Comprobante sin sucursal identificable: El sistema registra el caso para revision manual y continua con los demas

---

CU-003: Consultar comprobante por identificador global

Actor: Usuario con permisos de consulta / Auditor

Objetivo: Localizar un comprobante de venta utilizando su identificador global, independientemente de la sucursal

Precondiciones:

• Usuario autenticado con permisos de consulta en el modulo de ventas
• Se dispone de un identificador global de un comprobante de venta

Flujo principal:

1. El usuario proporciona el identificador global del comprobante
2. El sistema utiliza el identificador global para localizar el registro de mapeo
3. El sistema obtiene la sucursal de origen y el identificador local del comprobante
4. El sistema recupera y muestra la informacion del comprobante de venta

Postcondiciones:

• El usuario visualiza la informacion del comprobante solicitado
• La consulta funciona correctamente aunque el comprobante sea de otra sucursal

Flujos alternativos:

• Identificador global no encontrado: Si el identificador global no existe, el sistema informa que no se puede localizar el comprobante
• Comprobante eliminado: Si el comprobante fue eliminado, el sistema informa que el comprobante ya no existe

---

CU-004: Registrar factura de venta

Actor: Usuario de Ventas

Objetivo: Registrar una factura de venta con identificador global automatico

Precondiciones:

• Usuario autenticado con permisos de facturacion
• Usuario operando en una sucursal especifica

Flujo principal:

1. El usuario completa los datos de la factura de venta
2. El usuario confirma el registro de la factura
3. El sistema valida y registra la factura con su identificador local
4. El sistema genera automaticamente un identificador global unico
5. El sistema registra el mapeo con tipo de comprobante "Factura"
6. El sistema confirma la operacion exitosa

Postcondiciones:

• La factura queda registrada con identificador local e identificador global
• El tipo de comprobante en el mapeo es "Factura"

---

CU-005: Registrar nota de credito de venta

Actor: Usuario de Ventas

Objetivo: Registrar una nota de credito de venta con identificador global automatico

Precondiciones:

• Usuario autenticado con permisos de notas de credito
• Usuario operando en una sucursal especifica

Flujo principal:

1. El usuario completa los datos de la nota de credito
2. El usuario confirma el registro de la nota de credito
3. El sistema valida y registra la nota de credito con su identificador local
4. El sistema genera automaticamente un identificador global unico
5. El sistema registra el mapeo con tipo de comprobante "Nota de Credito"
6. El sistema confirma la operacion exitosa

Postcondiciones:

• La nota de credito queda registrada con identificador local e identificador global
• El tipo de comprobante en el mapeo es "Nota de Credito"

---

CU-006: Registrar nota de debito de venta

Actor: Usuario de Ventas

Objetivo: Registrar una nota de debito de venta con identificador global automatico

Precondiciones:

• Usuario autenticado con permisos de notas de debito
• Usuario operando en una sucursal especifica

Flujo principal:

1. El usuario completa los datos de la nota de debito
2. El usuario confirma el registro de la nota de debito
3. El sistema valida y registra la nota de debito con su identificador local
4. El sistema genera automaticamente un identificador global unico
5. El sistema registra el mapeo con tipo de comprobante "Nota de Debito"
6. El sistema confirma la operacion exitosa

Postcondiciones:

• La nota de debito queda registrada con identificador local e identificador global
• El tipo de comprobante en el mapeo es "Nota de Debito"

---

Consideraciones

Seguridad

Proteccion de datos:

• Los identificadores globales son datos de auditoria que no deben poder modificarse por ningun usuario
• El acceso a la informacion de mapeo hereda los permisos del modulo de ventas
• Los registros de mapeo deben estar protegidos contra modificaciones no autorizadas

Control de acceso:

• La consulta de identificadores globales esta disponible para usuarios con permisos de consulta en el modulo de ventas
• El proceso de migracion solo puede ejecutarse por usuarios con rol de administrador
• No existe funcionalidad para modificar identificadores globales manualmente

Auditoria

Operaciones que se auditan:

Operacion	Datos auditados	Motivo
Generacion de identificador global	Comprobante, identificador global, schema principal, tipo	Trazabilidad de asignacion
Migracion de comprobantes	Cantidad migrada, errores, schemas	Control del proceso de migracion

Informacion preservada:

• Identificador global asignado a cada comprobante
• Schema principal de origen del comprobante
• Tipo de comprobante
• Fecha y hora de creacion del mapeo
• Usuario que genero la operacion que origino el comprobante

Rendimiento

Volumenes esperados:

• Un registro de mapeo por cada comprobante de venta registrado en el sistema
• El volumen crece proporcionalmente con la cantidad de comprobantes emitidos
• Se esperan cientos de comprobantes por dia por sucursal

Expectativas de tiempo de respuesta:

• La generacion del identificador global no debe agregar latencia perceptible al registro de comprobantes
• La consulta de comprobante por identificador global debe ser rapida (menos de 100 milisegundos)
• El proceso de migracion puede ejecutarse en horario de baja actividad

Consideraciones de busqueda:

• Las busquedas por identificador global son frecuentes y deben ser eficientes
• Las busquedas inversas (de identificador local a global) tambien son comunes

Migracion de datos

Comprobantes existentes:

• Todos los comprobantes de venta existentes deben tener identificador global antes de la puesta en produccion
• El proceso de migracion debe ser idempotente (puede ejecutarse multiples veces sin duplicar datos)
• Se debe generar un reporte de migracion para validacion

Compatibilidad:

• El sistema debe seguir funcionando durante la migracion
• Las funcionalidades existentes no deben verse afectadas
• La transicion debe ser transparente para los usuarios

---

Dependencias

Funcionalidades relacionadas

• Registro de Comprobantes de Ventas: El proceso de registro de facturas, notas de credito y notas de debito (electrónicas y cargas manuales) debe extenderse para generar automaticamente el identificador global.

• Baja de Comprobantes de Venta (Ver documento): El proceso de baja debe eliminar el registro de identificador global junto con el comprobante.

Modulos de negocio involucrados

Modulo	Rol en esta funcionalidad
Ventas	Genera comprobantes de venta y dispara la creacion de identificadores globales
Configuracion	Almacena la entidad de mapeo a nivel empresa (compartida entre sucursales)

Impacto en otros procesos

Proceso	Impacto
Registro de factura de venta	Genera automaticamente identificador global
Registro de nota de credito de venta	Genera automaticamente identificador global
Registro de nota de debito de venta	Genera automaticamente identificador global
Carga manual de comprobantes	Genera automaticamente identificador global
Baja de comprobantes	Elimina registro de identificador global
Reportes consolidados	Pueden utilizar identificador global para referencias precisas

---

Criterios de Aceptacion

La funcionalidad se considera completa cuando se cumplan los siguientes criterios:

Criterios para generacion de identificadores

• [x] AC-001: Al registrar una nueva factura de venta, el sistema genera automaticamente un identificador global unico

• [x] AC-002: Al registrar una nueva nota de credito de venta, el sistema genera automaticamente un identificador global unico

• [x] AC-003: Al registrar una nueva nota de debito de venta, el sistema genera automaticamente un identificador global unico

• [x] AC-004: Al registrar una carga manual de comprobante de venta, el sistema genera automaticamente un identificador global unico

• [x] AC-005: El identificador global de venta es unico en toda la empresa (no se repite entre schemas)

• [x] AC-006: El registro de mapeo de venta incluye: identificador local, identificador global, tipo de comprobante, schema principal de origen

Criterios de migracion

• [ ] AC-007: El proceso de migracion asigna identificadores globales a todas las facturas de venta existentes

• [ ] AC-008: El proceso de migracion asigna identificadores globales a todas las notas de credito de venta existentes

• [ ] AC-009: El proceso de migracion asigna identificadores globales a todas las notas de debito de venta existentes

• [ ] AC-010: El proceso de migracion asigna identificadores globales a todas las cargas manuales existentes

• [ ] AC-011: La migracion no genera duplicados de identificadores globales

• [ ] AC-012: La migracion no causa perdida de datos

Criterios de integridad

• [x] AC-013: El identificador global no puede modificarse una vez asignado

• [x] AC-014: El schema principal de origen no puede modificarse una vez registrado

• [ ] AC-015: Al eliminar un comprobante, se elimina el registro de identificador global

• [x] AC-016: La combinacion de identificador local + tipo + schema principal tiene exactamente un identificador global (sin duplicados)

• [x] AC-017: El mismo identificador local puede existir en diferentes schemas con diferentes identificadores globales

Criterios de unicidad del mapeo

• [x] AC-018: El identificador global (UUID) es unico en toda la empresa (indice unico en la base de datos)

• [x] AC-019: La combinacion de identificador local + tipo + schema principal es unica (indice unico compuesto)

• [x] AC-020: El sistema genera el UUID automaticamente mediante funciones nativas del motor de base de datos

• [x] AC-021: El sistema es idempotente: solicitar el identificador global del mismo comprobante multiples veces devuelve siempre el mismo UUID

• [x] AC-022: La busqueda por identificador global permite localizar comprobantes de cualquier schema

Criterios de determinacion del schema de origen (RN-009)

• [x] AC-026: Cuando un usuario opera desde una caja (schema sucXXXXcajaXXXX), el sistema registra el schema de sucursal (sucXXXX) como origen del comprobante

• [x] AC-027: Cuando un usuario opera desde una sucursal (schema sucXXXX), el sistema registra ese schema directamente como origen

• [x] AC-028: El sistema extrae correctamente el schema de sucursal del patron ^suc\d+caja\d+$

• [x] AC-029: La migracion de datos historicos utiliza el schema correcto donde reside la tabla del comprobante

• [x] AC-030: Las consultas inversas (de UUID a comprobante) funcionan correctamente independientemente del schema desde el cual se registró el comprobante

Criterios de rendimiento

• [ ] AC-023: La generacion del identificador global no agrega latencia perceptible al registro de comprobantes

• [ ] AC-024: La consulta por identificador global responde en menos de 100 milisegundos

• [ ] AC-025: El sistema continua funcionando normalmente despues de la migracion

---

Notas adicionales

Diferencia entre identificador local e identificador global

Aspecto	Identificador Local	Identificador Global
Alcance	Unico dentro de la sucursal	Unico en toda la empresa
Generacion	Secuencial por sucursal/tipo	Generado automaticamente por el sistema
Uso actual	Numero de comprobante visible al usuario	Uso interno para referencias entre modulos
Puede repetirse	Si, entre sucursales	No, nunca
Formato	Numerico secuencial	Identificador unico universal

Tipos de comprobantes de venta soportados

Tipo de comprobante	Genera identificador global
Factura	Si
Nota de Credito	Si
Nota de Debito	Si
Carga Manual	Si (mismo tratamiento que comprobantes electrónicos)

Consideraciones de implementacion (v1.3)

La implementacion del sistema de identificadores globales se realizo con las siguientes caracteristicas:

Generacion del identificador global:

• El identificador global es generado automaticamente por el sistema al momento de registrar el comprobante
• Esta decision garantiza unicidad a nivel de base de datos y elimina dependencias externas

Representacion del tipo de comprobante:

• El tipo de comprobante se almacena como codigo numerico (codigo AFIP) en lugar de texto descriptivo
• Esto permite compatibilidad con los requerimientos fiscales y estandariza la representacion
• La capa de presentacion traduce el codigo a descripcion amigable para el usuario

Identificacion del schema de origen:

• Se almacena el identificador del schema (ej: "suc0001") que identifica univocamente la sucursal
• Esta decision facilita las operaciones de base de datos y consultas directas

Determinacion correcta del schema de origen (RN-009 - Implementado v1.3):

• El sistema determina automaticamente el schema donde reside fisicamente la tabla del comprobante
• Si el usuario opera desde una caja (sucXXXXcajaXXXX), se extrae el schema de sucursal (sucXXXX) internamente
• Si el usuario opera desde una sucursal (sucXXXX), se usa directamente
• La extraccion del schema es transparente para los servicios de facturacion

Sin eliminacion logica:

• Esta entidad no implementa soft-delete (no tiene campo deleted_at)
• Los registros de mapeo son permanentes mientras el comprobante exista
• La eliminacion del mapeo solo ocurre cuando se elimina el comprobante origen

Idempotencia del servicio:

• Solicitar el identificador global del mismo comprobante multiples veces devuelve siempre el mismo UUID
• El sistema verifica si ya existe un mapeo antes de intentar crear uno nuevo
• Esto permite reintentos seguros en caso de fallos de comunicacion

Consideraciones para integraciones externas

Si en el futuro se exponen identificadores de comprobantes a sistemas externos (APIs, integraciones, etc.), se recomienda:

1. Utilizar el identificador global como referencia externa
2. No exponer el identificador local para evitar ambiguedades
3. El identificador global es autosuficiente para localizar cualquier comprobante de venta

Preguntas frecuentes

1. Los usuarios veran el identificador global?

   • No directamente. Los usuarios siguen trabajando con los numeros de comprobante habituales. El identificador global es de uso interno del sistema.

2. Que pasa si se agrega una nueva sucursal?

   • La nueva sucursal funcionara normalmente. Sus comprobantes recibiran identificadores globales unicos que no conflictuaran con ninguna otra sucursal.

3. Se puede migrar en etapas?

   • Si. El proceso de migracion puede ejecutarse en etapas por tipo de comprobante.

4. Que pasa con los reportes existentes?

   • Los reportes existentes no se ven afectados. La funcionalidad opera de forma transparente. Internamente las referencias seran mas robustas.

5. Por que usar UUID y no otro tipo de identificador?

   • UUID garantiza unicidad global sin coordinacion centralizada entre sucursales, lo que es ideal para arquitecturas distribuidas multi-tenant.

---

Historial de cambios

Fecha	Version	Autor	Descripcion
2025-12-26	1.3	Sistema	CORRECCION IMPLEMENTADA EXITOSAMENTE: (1) Estado cambiado a "Implementado"; (2) Implementada RN-009 para extraccion automatica del schema correcto; (3) Cuando el usuario opera desde una caja (suc0001caja001), se extrae el schema de sucursal (suc0001) donde residen las tablas; (4) Criterios AC-026 a AC-030 marcados como cumplidos; (5) Agregados tests unitarios que validan la extraccion correcta; (6) La correccion es transparente para los servicios de facturacion; (7) Sin cambios en migraciones - ya funcionaban correctamente
2025-12-26	1.2	Sistema	CORRECCION CRITICA IDENTIFICADA: (1) Estado cambiado a "En correccion"; (2) Agregada nueva regla de negocio RN-009: Determinacion del schema de origen basado en ubicacion real de la tabla - el sistema debe registrar el schema donde reside fisicamente la tabla del comprobante (sucursal), no el schema del usuario (que puede ser caja); (3) Agregados nuevos criterios de aceptacion AC-026 a AC-030 para validar la determinacion correcta del schema; (4) Documentado el problema: cuando un usuario opera desde suc0001caja001, el sistema registraba ese schema en lugar de suc0001 donde realmente reside la tabla; (5) Se requiere implementar extraccion del schema de sucursal del patron sucXXXXcajaXXXX -> sucXXXX; (6) La migracion de datos historicos ya utiliza el schema correcto (ejecuta a nivel SUCURSAL)
2025-12-24	1.1	Sistema	IMPLEMENTADO: Funcionalidad completada exitosamente. Actualizaciones de documentacion: (1) Estado cambiado a "Implementado"; (2) Aclarado que "sucursal" se refiere al schema principal de PostgreSQL en todas las secciones; (3) Eliminadas referencias a recibos - el bridge solo aplica a facturas, notas de credito, notas de debito y sus cargas manuales; (4) Seccion "Datos necesarios" actualizada - tipo de comprobante como codigo AFIP numerico, schema principal como identificador, agregado campo fecha de creacion; (5) Criterios de aceptacion AC-001 a AC-006, AC-013, AC-014, AC-016 a AC-022 marcados como cumplidos; (6) Agregados nuevos criterios AC-018 a AC-022 para unicidad del mapeo; (7) Nueva seccion "Consideraciones de implementacion" documentando decisiones tecnicas: generacion de UUID por PostgreSQL, tipo comprobante como codigo AFIP, schema principal como identificador de sucursal, sin soft-delete, idempotencia del servicio. Los criterios de migracion de datos historicos (AC-007 a AC-012) y rendimiento (AC-023 a AC-025) quedan pendientes de validacion en produccion
2025-12-24	1.0	Sistema	Creacion del documento de requerimientos de negocio para mapeo de identificadores globales de comprobantes de venta. Al eliminar un comprobante, se elimina el registro bridge. El documento se enfoca exclusivamente en el mapeo de identificadores - el uso del bridge por otros modulos se documenta en sus respectivos documentos