Trazabilidad de Movimientos de Stock con Comprobantes de Compras

Modulo: Stock Tipo: Resource Estado: Implementado (parcial — trazabilidad global planificada) Fecha: 2025-12-24 Ultima actualizacion: 2026-03-23 (v2.0 - Flujo implementado documentado)

---

Implementacion actual

Esta seccion documenta el flujo ya implementado en el modulo de compras. El mecanismo de trazabilidad global via Bridge de Compras (id_compras) es una evolucion planificada documentada mas abajo.

Cuando se registra stock desde compras

El registro de un movimiento de stock ocurre automaticamente al insertar un item de comprobante de compra, bajo las siguientes condiciones:

1. producto.maneja_stock = 'S' — el producto tiene control de inventario habilitado
2. El modulo de stock esta habilitado para la empresa (PermisosEmpresa[STOCK] === 1)

Si alguna condicion no se cumple, el item se registra sin generar movimiento de stock.

Flujo de registro

ComprobanteController::insert()
  └─ ItemComprobanteController::insert()
       └─ MovimientoStockService::insert()
            └─ MovimientoStock::insert()  →  tabla mov_sto

Campos populados en mov_sto

Campo	Valor	Fuente
posicion	'I' (Ingreso) para facturas de compra (tipo Debito)	Tipo de comprobante
posicion	'E' (Egreso) para notas de credito de compra (tipo Credito)	Tipo de comprobante
marca	MarcaOrigen::OFICIAL o MarcaOrigen::PRUEBA	Conexion activa (isPruebaConnection())
id_comprobante_compras	ID entero del comprobante en tabla subdicom	Comprobante insertado
id_compras	NULL	Reservado — ver nota abajo
importe	Total de la linea (cantidad × precio unitario)	Frontend calcula y envia; backend persiste directo

Contrato del campo importe

mov_sto.importe almacena el total de la linea (cantidad × precio unitario). Para obtener el precio unitario: importe / cantidad.

Modulo / Contexto	Calculo de importe
Compras	Frontend calcula cantidad × precio; backend persiste el valor recibido sin transformacion
Ventas	FacturaService usa item.total (= precioFinal × cantidad)
Movimiento manual (POST /mod-stock/movimiento)	Controller calcula costo × cantidad antes de persistir
Ultimo Costo (cantidad = 0)	importe = costo (unitario directo, sin multiplicacion)
updateCostoProducto()	Recibe importe / cantidad para actualizar el precio unitario del articulo
Informes con precio unitario	Dividen importe / COALESCE(NULLIF(cantidad, 0), 1) para mostrarlo

Tipos de movimiento segun comprobante

Tipo de comprobante	Posicion en subdicom	Movimiento generado	Efecto en stock
Factura de compra (proveedor)	Debito (D)	posicion = 'I' (Ingreso)	Incrementa stock
Nota de credito de compra (devolucion a proveedor)	Credito (C)	posicion = 'E' (Egreso)	Decrementa stock

Campo id_compras (reservado)

La columna id_compras (VARCHAR(36) NULL) existe en mov_sto y se inserta siempre como NULL en la implementacion actual. Su proposito es reservar espacio para la futura trazabilidad global entre movimientos de stock y comprobantes de compras mediante el Bridge de Compras (ver seccion de trazabilidad global mas abajo). Sigue el patron existente de id_ventas para la trazabilidad con comprobantes de ventas.

Relacion con marca de origen

La marca del movimiento se determina segun la conexion activa al momento del registro:

• Conexion oficial → MarcaOrigen::OFICIAL ('O')
• Conexion prueba → MarcaOrigen::PRUEBA ('P')

Ver Marca de Origen en Movimientos de Stock para el comportamiento completo.

---

Descripcion

Problema de negocio

Actualmente, los movimientos de stock generados por operaciones de compras utilizan un identificador numerico entero local para referenciar los comprobantes de compra. Debido a la arquitectura multi-sucursal del sistema (donde cada sucursal opera con su propio esquema de datos), el mismo identificador numerico puede existir en diferentes sucursales, generando los siguientes problemas operativos:

• Ambiguedad en identificacion: El identificador numerico local (por ejemplo, ID 500) puede corresponder a comprobantes de compra completamente diferentes en sucursales distintas. Cuando un movimiento de stock referencia el "comprobante 500", no es posible determinar univocamente a cual comprobante se refiere sin conocer adicionalmente la sucursal de origen.

• Falta de trazabilidad confiable: No es posible rastrear de forma directa e inequivoca que comprobante de compra genero un ingreso de stock especifico, especialmente cuando se consulta desde una sucursal diferente a la que registro la compra.

• Dificultad en operaciones a nivel empresa: Las consultas consolidadas, auditorias y reportes que abarcan multiples sucursales no pueden relacionar correctamente movimientos de stock con sus comprobantes de compra de origen.

• Reversiones imprecisas: Al eliminar o anular un comprobante de compra, no existe un mecanismo confiable para identificar todos los movimientos de stock que deben revertirse cuando la consulta se realiza desde otra sucursal.

• Inconsistencia de datos: Pueden quedar movimientos de stock "huerfanos" cuando se eliminan comprobantes sin revertir adecuadamente el inventario, debido a la imposibilidad de localizar los movimientos relacionados de forma univoca.

• Complejidad en procesos de pago: Las operaciones de tesoreria y cuentas corrientes que necesitan verificar el estado de stock de comprobantes de compra enfrentan dificultades cuando los comprobantes son de sucursales diferentes.

Necesidad del negocio

El sistema requiere establecer una relacion trazable y univoca entre los movimientos de stock y los comprobantes de compras que los originan, utilizando el identificador global proporcionado por el servicio de Identificadores Globales de Comprobantes de Compra (Bridge de Compras). Esta relacion debe cumplir las siguientes caracteristicas:

• Identificacion global del origen: Cada movimiento de stock generado por una compra debe registrar el identificador global del comprobante, que es unico a nivel empresa independientemente de la sucursal que registro la compra.

• Relacion univoca: El identificador global por si solo debe ser suficiente para determinar inequivocamente el comprobante de compra origen, sin necesidad de datos adicionales como tipo de comprobante o sucursal.

• Flexibilidad arquitectonica: La relacion no debe depender de restricciones de integridad referencial rigidas, permitiendo flexibilidad en el manejo de datos historicos y procesos de migracion.

• Integridad por logica de negocio: La consistencia entre movimientos de stock y comprobantes debe mantenerse mediante validaciones y procesos de negocio.

Tipos de comprobantes de compra involucrados:

• Facturas de proveedores (generan ingreso de stock)
• Notas de credito de proveedores (pueden generar egreso de stock por devolucion al proveedor)
• Otros comprobantes de compra que afecten inventario

Valor de negocio

La implementacion de esta funcionalidad aportara los siguientes beneficios:

1. Trazabilidad inequivoca: Permite rastrear el origen de cada movimiento de stock generado por compras con certeza absoluta, sin importar la sucursal que registro el comprobante ni la sucursal desde donde se realiza la consulta.

2. Reversiones precisas: Al eliminar un comprobante de compra, el sistema puede identificar exactamente que movimientos de stock deben revertirse usando el identificador global.

3. Integridad de inventario: Garantiza que no queden movimientos de stock sin revertir cuando se elimina un comprobante, ya que el identificador global permite localizar todos los movimientos relacionados sin ambiguedad.

4. Auditoria eficiente: Simplifica los procesos de control al tener una relacion directa y univoca entre compras y movimientos de inventario a nivel empresa.

5. Soporte a compliance: Facilita el cumplimiento de requisitos de control interno y regulatorios relacionados con trazabilidad de operaciones de compra e inventario.

6. Reduccion de errores: Minimiza la posibilidad de inconsistencias entre el modulo de compras y el modulo de stock en entornos multi-sucursal.

7. Consultas simplificadas: Permite localizar el comprobante de compra origen de un movimiento de stock sin necesidad de conocer la sucursal donde se registro.

8. Preparacion para integraciones: El sistema estara preparado para exponer trazabilidad completa a sistemas externos de auditoria o gestion de inventario.

Contexto en el proceso de negocio

Esta funcionalidad se integra en el flujo de compras de la siguiente manera:

Flujo de registro de compra (implementado):

1. El usuario registra un comprobante de compra (factura de proveedor) en su sucursal
2. El sistema inserta el comprobante en subdicom y obtiene su ID entero local
3. Por cada item del comprobante donde producto.maneja_stock = 'S' y el modulo stock esta habilitado:
   • El sistema invoca MovimientoStockService::insert() con id_comprobante_compras, posicion, y marca
   • El movimiento queda registrado en mov_sto con id_compras = NULL (campo reservado)
4. La relacion por ID local queda disponible para reversiones dentro de la misma sucursal

Flujo de registro de compra (planificado — trazabilidad global):

1. El usuario registra un comprobante de compra (factura de proveedor) en su sucursal
2. El sistema asigna el identificador local de la sucursal al comprobante
3. El servicio de Identificadores Globales genera y registra un identificador global unico para el comprobante (ver Identificadores Globales de Comprobantes de Compra)
4. El sistema genera los movimientos de stock de ingreso correspondientes segun los items del comprobante
5. [Esta funcionalidad] El sistema registra en cada movimiento de stock el identificador global del comprobante de compra en el campo id_compras
6. La relacion queda disponible para consultas cross-sucursal y para el proceso de reversion

Flujo de eliminacion de compra:

Esta funcionalidad es fundamental para el correcto funcionamiento del proceso de eliminacion de comprobantes de compra. Al eliminar un comprobante:

1. El sistema obtiene el identificador global del comprobante a eliminar
2. Busca todos los movimientos de stock relacionados mediante el identificador global
3. Por cada movimiento de stock encontrado:
   • Revierte el efecto en el stock del producto (decrementa para ingresos, incrementa para egresos)
   • Elimina el registro de movimiento de stock
4. Garantiza que no queden movimientos de stock huerfanos
5. Continua con las siguientes etapas de la eliminacion (cuenta corriente, contabilidad, etc.)

Flujo de consulta de trazabilidad:

1. El usuario consulta el detalle de un movimiento de stock
2. El sistema identifica que el movimiento tiene un identificador global de compra asociado
3. El sistema utiliza el identificador global para localizar el comprobante de compra (a traves del Bridge de Compras)
4. El sistema muestra la informacion del comprobante origen, independientemente de la sucursal donde fue registrado

---

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 asignacion del identificador global es automatico y transparente
• Los usuarios continuan trabajando con los numeros de comprobante habituales (punto de venta, tipo, numero)
• Al consultar movimientos de stock, los usuarios pueden ver de que comprobante de compra proviene cada ingreso
• La referencia al comprobante de compra funciona correctamente aunque este sea de otra sucursal

Estados de UI

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

---

Backend

Entidades de negocio

Movimiento de Stock (entidad existente - enriquecida)

Entidad que representa cada movimiento de entrada o salida de inventario de un producto. Se enriquece con la capacidad de registrar su relacion con comprobantes de compras mediante el identificador global.

Datos existentes relevantes:

Dato	Campo en mov_sto	Descripcion	Proposito
Identificador del movimiento	id	Identificador unico del movimiento de stock	Identifica el registro
Producto	id_producto	Producto afectado por el movimiento	Indica que producto se movio
Cantidad	cantidad	Cantidad del movimiento	Indica cuanto se movio
Importe (total de linea)	importe	Total de linea = cantidad × precio unitario. Ver contrato completo en seccion de campos	Almacena el valor total; el precio unitario se obtiene dividiendo importe / cantidad
Posicion (tipo de movimiento)	posicion	'I' Ingreso o 'E' Egreso	Indica la direccion del movimiento
Fecha	fecha	Fecha del movimiento	Indica cuando ocurrio
Marca de origen	marca	'O' Oficial o 'P' Prueba segun conexion activa	Ver Marca de Origen en Movimientos de Stock

Datos de trazabilidad (implementados):

Dato	Campo en mov_sto	Descripcion	Estado
ID comprobante compras (local)	id_comprobante_compras	ID entero del comprobante en tabla subdicom de la sucursal	Implementado — permite trazabilidad intra-sucursal
ID compras (global)	id_compras	VARCHAR(36) NULL — reservado para identificador global via Bridge de Compras	Planificado — actualmente siempre NULL

Datos necesarios

Para el registro de movimientos de stock desde compras, el sistema utiliza los siguientes datos:

Dato	Campo	Descripcion	Obligatoriedad	Estado
Posicion	posicion	'I' para facturas (Debito), 'E' para notas de credito (Credito)	Obligatorio	Implementado
Marca de origen	marca	MarcaOrigen::OFICIAL u MarcaOrigen::PRUEBA segun conexion	Obligatorio	Implementado
ID comprobante compras (local)	id_comprobante_compras	ID entero del comprobante insertado en subdicom	Obligatorio	Implementado
ID compras (global)	id_compras	Identificador global via Bridge de Compras	Opcional (futura trazabilidad cross-sucursal)	Planificado — actualmente NULL

Notas importantes:

• Los movimientos de stock generados por compras registran id_comprobante_compras con el ID local de la sucursal
• El campo id_compras existe en la tabla pero se inserta como NULL hasta que el Bridge de Compras sea implementado
• Los movimientos de otros origenes (ventas, ajustes manuales, transferencias) no utilizan estos campos de compras
• La determinacion de posicion ('I'/'E') se basa en el tipo del comprobante (Debito/Credito en subdicom)

Relaciones de negocio

Comprobante de Compra (1) ---- (N) Movimientos de Stock

• Comprobante a Movimientos: Un comprobante de compra puede generar multiples movimientos de stock (uno por cada item del comprobante que afecte inventario)
• Movimiento a Comprobante: Cada movimiento de stock generado por una compra esta relacionado con exactamente un comprobante de compra
• Identificacion de relacion: El identificador global de compra por si solo identifica univocamente al comprobante de compra relacionado, sin necesidad de datos adicionales como sucursal o tipo de comprobante

Efecto en stock segun tipo de operacion:

Tipo de operacion de compra	Efecto en stock	Tipo de movimiento
Factura de proveedor	Entrada de productos adquiridos	Ingreso
Nota de credito de proveedor	Salida de productos devueltos	Egreso

Validaciones de negocio

1. Existencia del identificador global:

   • Al crear un movimiento de stock desde una compra, el identificador global del comprobante debe existir en el servicio de Identificadores Globales (Bridge de Compras)
   • El sistema debe validar que el identificador global corresponda a un comprobante de compra valido

2. Movimientos sin relacion a compras:

   • Los movimientos de stock que no provienen de compras (ventas, ajustes manuales, transferencias) no deben tener identificador global de compra
   • Este campo debe permanecer sin valor para ese tipo de movimientos

3. Unicidad del identificador global:

   • El identificador global de compra es unico a nivel empresa
   • No puede haber ambiguedad sobre cual comprobante se referencia

4. Inmutabilidad de la relacion:

   • Una vez creada, la relacion entre un movimiento de stock y su comprobante de compra no puede modificarse
   • Solo puede eliminarse la relacion cuando se elimina el movimiento de stock completo

5. Consistencia con marca de origen:

   • Los movimientos de stock de compras deben tener la marca de origen asignada segun el caracter de la compra (oficial o prueba)
   • Ver validaciones de marca en Marca de Origen en Movimientos de Stock

---

Reglas de Negocio

RN-001: Registro automatico de movimiento de stock al insertar item de comprobante de compra

Descripcion: Cuando el sistema inserta un item de comprobante de compra, genera automaticamente un movimiento de stock si el producto tiene stock habilitado y el modulo stock esta activo para la empresa.

Condicion:

• producto.maneja_stock = 'S'
• PermisosEmpresa[STOCK] === 1

Accion:

• Por cada item del comprobante que cumple las condiciones, el sistema invoca MovimientoStockService::insert() con:
  • posicion: 'I' para facturas de compra (Debito), 'E' para notas de credito de compra (Credito)
  • marca: MarcaOrigen::OFICIAL u MarcaOrigen::PRUEBA segun isPruebaConnection()
  • id_comprobante_compras: ID entero del comprobante en subdicom
  • id_compras: NULL (campo reservado para futura trazabilidad global)
• El movimiento se registra atomicamente en mov_sto

Aplica a:

• Facturas de proveedores (tipo Debito → posicion 'I' Ingreso)
• Notas de credito de proveedores (tipo Credito → posicion 'E' Egreso)

Fundamento: Garantiza que cada item de compra con stock habilitado genere su correspondiente movimiento de inventario, manteniendo la consistencia entre el modulo de compras y el modulo de stock.

---

RN-002: Unicidad de identificacion del comprobante origen

Descripcion: El identificador global de compra debe ser suficiente por si solo para identificar de manera univoca el comprobante de compra origen.

Condicion: Al consultar o buscar el comprobante origen de un movimiento de stock de compra.

Accion:

• El sistema debe utilizar unicamente el identificador global para determinar el comprobante origen
• No debe requerirse informacion adicional como sucursal, tipo de comprobante o identificador local
• No debe haber ambiguedad en la identificacion del comprobante

Fundamento: A diferencia de los identificadores locales que pueden repetirse entre sucursales, el identificador global es unico a nivel empresa, garantizando una identificacion sin ambiguedades.

---

RN-003: Identificacion y reversion de movimientos al eliminar comprobante de compra

Descripcion: Al eliminar un comprobante de compra, el sistema debe identificar todos los movimientos de stock relacionados mediante el identificador global y revertirlos.

Condicion: Se esta ejecutando el proceso de eliminacion de un comprobante de compra.

Accion:

1. El sistema obtiene el identificador global del comprobante de compra a eliminar
2. El sistema busca todos los movimientos de stock que tengan ese identificador global de compra
3. Para cada movimiento encontrado:
   • Si era tipo "Ingreso": decrementa el stock del producto (revierte el ingreso)
   • Si era tipo "Egreso": incrementa el stock del producto (revierte el egreso)
   • Elimina el registro del movimiento de stock
4. Si no se encuentran movimientos (comprobante que no afecto stock), el proceso continua normalmente

Fundamento: Garantiza que la eliminacion de un comprobante de compra no deje movimientos de stock huerfanos y que el inventario refleje correctamente la reversion de la operacion. El uso del identificador global permite encontrar todos los movimientos sin importar desde que sucursal se ejecute la eliminacion.

---

RN-004: Movimientos no relacionados con compras

Descripcion: Los movimientos de stock que no provienen de operaciones de compras no deben tener datos de identificador global de compra.

Condicion: Se esta registrando un movimiento de stock por:

• Venta de productos (factura de venta, nota de credito de venta)
• Ajuste manual de inventario
• Transferencia entre depositos
• Otros motivos no relacionados con compras a proveedores

Accion:

• El sistema no debe registrar identificador global de compra
• Este campo debe permanecer sin valor

Fundamento: Permite distinguir claramente los movimientos originados por compras de aquellos originados por otras operaciones, manteniendo la integridad semantica de los datos.

---

RN-005: Compatibilidad con datos historicos

Descripcion: Los movimientos de stock historicos que no tienen el identificador global de compra registrado deben seguir funcionando correctamente en el sistema.

Condicion: Existen movimientos de stock creados antes de la implementacion de esta funcionalidad.

Accion:

• El sistema debe manejar correctamente movimientos sin identificador global de compra
• Las funcionalidades existentes no deben verse afectadas por la ausencia de estos datos
• Las nuevas funcionalidades de trazabilidad deben indicar "Relacion no disponible" o similar para estos movimientos

Fundamento: Garantiza compatibilidad hacia atras y permite una migracion gradual sin afectar la operacion del sistema.

---

RN-006: Integridad de datos por logica de negocio

Descripcion: La consistencia entre movimientos de stock y comprobantes de compras debe mantenerse mediante logica de negocio, no mediante restricciones de base de datos.

Condicion: En cualquier operacion que involucre movimientos de stock relacionados con compras.

Accion:

• Las validaciones de existencia del identificador global se realizan en el momento de la operacion
• No se impiden operaciones de mantenimiento o correccion de datos por restricciones rigidas
• Los procesos de negocio garantizan la consistencia de las relaciones

Fundamento: Permite flexibilidad para manejar situaciones especiales (migracion de datos, correccion de inconsistencias historicas) sin que las restricciones de base de datos bloqueen operaciones legitimas.

---

RN-007: Inmutabilidad del identificador global una vez asignado

Descripcion: Una vez asignado el identificador global de compra a un movimiento de stock, este no puede modificarse.

Condicion: Existe un movimiento de stock con identificador global de compra asignado.

Accion:

• El sistema rechaza cualquier intento de modificar el identificador global de compra
• Solo puede eliminarse el movimiento completo

Fundamento: El identificador global es un dato de trazabilidad que refleja una condicion del momento de creacion. Modificarlo alteraria la integridad historica del movimiento y afectaria auditorias y reportes.

---

RN-008: Preservacion del mapeo para auditoria

Descripcion: Si un comprobante de compra es eliminado, el registro de movimiento de stock se elimina pero la auditoria preserva la informacion de la relacion para trazabilidad historica.

Condicion: Se elimina un comprobante de compra que tiene movimientos de stock asociados.

Accion:

• Los movimientos de stock se eliminan como parte del proceso de reversion
• El sistema de auditoria registra la eliminacion incluyendo el identificador global del comprobante eliminado
• La informacion queda disponible para consultas de auditoria historica

Fundamento: Permite mantener la trazabilidad historica y cumplir con requisitos de auditoria incluso cuando se eliminan comprobantes de compra.

---

Casos de Uso

CU-001: Registrar movimiento de stock desde factura de proveedor

Actor: Sistema (proceso automatico al registrar compra)

Objetivo: Generar movimientos de stock de ingreso al registrar una factura de compra

Precondiciones:

• Usuario esta registrando una factura de compra (tipo Debito en subdicom)
• La factura contiene items de productos con maneja_stock = 'S'
• El modulo stock esta habilitado para la empresa (PermisosEmpresa[STOCK] === 1)

Flujo principal:

1. El usuario confirma el registro de la factura de compra
2. ComprobanteController::insert() registra el comprobante en subdicom y obtiene su ID entero
3. Por cada item de la factura donde producto.maneja_stock = 'S':
   • ItemComprobanteController::insert() invoca MovimientoStockService::insert()
   • El sistema crea un movimiento con posicion = 'I' (Ingreso)
   • El sistema asigna la marca segun la conexion activa ('O' u 'P')
   • El sistema registra id_comprobante_compras con el ID del comprobante
   • El sistema registra id_compras = NULL (campo reservado)
   • El sistema actualiza el stock del producto (incrementa)
4. El sistema confirma la operacion exitosa al usuario

Postcondiciones:

• La factura de compra queda registrada en subdicom
• Los movimientos de stock quedan registrados en mov_sto con posicion = 'I', marca correcta e id_comprobante_compras
• El stock de los productos queda incrementado

Flujos alternativos:

• Items sin afectacion de stock: Si un item tiene maneja_stock != 'S' o el modulo stock esta deshabilitado, no se genera movimiento para ese item
• Error en creacion de movimiento: Si ocurre un error al crear algun movimiento de stock, se revierte toda la operacion

---

CU-002: Revertir movimientos de stock al eliminar comprobante de compra

Actor: Sistema (proceso automatico durante eliminacion de comprobante)

Objetivo: Identificar y revertir todos los movimientos de stock asociados a un comprobante de compra que se esta eliminando, utilizando el identificador global

Precondiciones:

• Un usuario con permisos esta ejecutando el proceso de eliminacion de un comprobante de compra
• El comprobante cumplio todas las validaciones para poder ser eliminado
• El proceso de eliminacion esta en ejecucion

Flujo principal:

1. El proceso de eliminacion obtiene el identificador global del comprobante de compra
2. El sistema busca todos los movimientos de stock donde el identificador global de compra coincida
3. El sistema encuentra N movimientos de stock relacionados
4. Por cada movimiento encontrado:
   • Si era tipo "Ingreso": decrementa el stock del producto (revierte la entrada)
   • Si era tipo "Egreso": incrementa el stock del producto (revierte la salida)
   • Registra en auditoria la eliminacion del movimiento con su identificador global
   • Elimina el registro del movimiento de stock
5. El proceso de eliminacion continua con las siguientes etapas (cuenta corriente, contabilidad, comprobante)

Postcondiciones:

• Todos los movimientos de stock relacionados al comprobante han sido eliminados
• El stock de los productos afectados ha sido revertido correctamente
• No quedan movimientos de stock huerfanos relacionados al comprobante eliminado
• La auditoria preserva la informacion de las relaciones eliminadas

Flujos alternativos:

• Comprobante sin movimientos de stock: Si el comprobante no tiene movimientos de stock asociados (items sin control de inventario), el proceso continua sin errores
• Error en reversion: Si ocurre un error al revertir algun movimiento, el sistema revierte toda la operacion de eliminacion (rollback transaccional)

---

CU-003: Consultar comprobante de compra desde movimiento de stock

Actor: Usuario consultando trazabilidad de inventario

Objetivo: Localizar el comprobante de compra origen de un movimiento de stock, independientemente de la sucursal donde fue registrado

Precondiciones:

• Usuario tiene permiso de consulta de movimientos de stock y comprobantes de compra
• Existe un movimiento de stock con identificador global de compra asociado

Flujo principal:

1. El usuario consulta el detalle de un movimiento de stock
2. El sistema detecta que el movimiento tiene un identificador global de compra asociado
3. El usuario solicita ver el comprobante de compra origen
4. El sistema utiliza el identificador global para consultar el Bridge de Compras
5. El sistema obtiene la ubicacion del comprobante (sucursal e identificador local)
6. El sistema recupera y muestra la informacion del comprobante de compra al usuario

Postcondiciones:

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

Flujos alternativos:

• Movimiento sin identificador global: Si el movimiento no tiene identificador global de compra (movimiento historico o de otro origen), el sistema informa que la trazabilidad no esta disponible
• Comprobante eliminado: Si el comprobante fue eliminado, el sistema informa que el comprobante ya no esta disponible pero puede mostrar datos de auditoria

---

CU-004: Generar reporte de ingresos de stock por compras

Actor: Usuario con permiso de reportes de stock

Objetivo: Generar un reporte de movimientos de stock de ingreso que muestre la relacion con los comprobantes de compra origen

Precondiciones:

• Usuario tiene permiso de generacion de reportes de stock
• Existen movimientos de stock con identificador global de compra registrado

Flujo principal:

1. El usuario accede a la generacion de reportes de movimientos de stock
2. El usuario selecciona el tipo de reporte: movimientos de ingreso por compras
3. El usuario configura los filtros (periodo, productos, proveedores, sucursales)
4. El sistema genera el reporte incluyendo:
   • Datos del movimiento de stock (fecha, producto, cantidad)
   • Referencia al comprobante de compra origen (usando el identificador global)
   • Datos del comprobante de compra (proveedor, numero de comprobante, fecha)
5. El usuario puede visualizar, imprimir o exportar el reporte

Postcondiciones:

• El reporte muestra la trazabilidad entre movimientos de stock y comprobantes de compra
• Las referencias a comprobantes funcionan correctamente para compras de cualquier sucursal

Flujos alternativos:

• Movimientos sin trazabilidad: Los movimientos historicos sin identificador global de compra se muestran con la indicacion "Trazabilidad no disponible"

---

Consideraciones

Seguridad

Control de acceso:

• La consulta de relaciones entre movimientos de stock y comprobantes de compras requiere permisos de visualizacion en ambos modulos
• Solo usuarios con permiso de eliminacion de comprobantes de compra pueden ejecutar la reversion de movimientos de stock
• Los datos de relacion (identificador global de compra) no deben ser modificables manualmente por usuarios

Integridad de datos:

• Las relaciones solo se crean y eliminan mediante procesos automaticos del sistema
• No existe funcionalidad para modificar manualmente la relacion entre un movimiento y su comprobante de compra
• Los identificadores globales estan protegidos contra modificaciones

Auditoria

Operaciones que se auditan:

• Creacion de movimientos de stock con relacion a comprobantes de compras
• Eliminacion de movimientos de stock como parte del proceso de eliminacion de comprobantes
• Reversiones de stock ejecutadas

Informacion preservada:

• Identificador global del comprobante de compra en cada movimiento
• Datos completos en el log de auditoria cuando se eliminan movimientos
• Usuario y fecha/hora de las operaciones
• Relacion entre movimiento eliminado y comprobante origen

Rendimiento

Volumenes esperados:

• Un movimiento de stock por cada item de producto en cada comprobante de compra
• El numero de movimientos crece proporcionalmente con el volumen de compras

Expectativas de tiempo de respuesta:

• La busqueda de movimientos por identificador global de compra debe ser rapida (menos de 100 milisegundos)
• La creacion de relaciones no debe agregar latencia perceptible al registro de comprobantes
• La identificacion de movimientos durante el proceso de eliminacion debe ser eficiente

Consideraciones de busqueda:

• Las consultas frecuentes por identificador global de compra deben ser optimizadas
• La busqueda inversa (desde comprobante hacia movimientos) es un caso de uso comun

Migracion de datos

Movimientos historicos:

• Los movimientos de stock existentes antes de la implementacion no tendran el identificador global de compra
• El sistema debe manejar correctamente estos movimientos sin la relacion
• Se puede evaluar una migracion retroactiva si es necesario y factible

Compatibilidad:

• Las funcionalidades existentes del modulo de stock no deben verse afectadas
• La ausencia de datos de relacion no debe generar errores en el sistema

---

Dependencias

Funcionalidades relacionadas

• Identificadores Globales de Comprobantes de Compra (Bridge de Compras) (Ver documento): Proporciona los identificadores globales unicos para comprobantes de compra. Esta funcionalidad es un prerequisito, ya que los movimientos de stock utilizan estos identificadores para establecer la trazabilidad.

• Marca de Origen en Movimientos de Stock (Ver documento): La marca de origen es un requisito complementario a la trazabilidad. Todos los movimientos de compras deben registrar la marca correspondiente: 'O' para oficiales, 'P' para prueba.

• Registro de Comprobantes de Compra: Esta funcionalidad se integra en el proceso de registro de facturas de proveedores. El identificador global se obtiene del Bridge de Compras y se registra automaticamente en los movimientos de stock.

• Eliminacion de Comprobantes de Compra: El proceso de eliminacion debe utilizar el identificador global para identificar y revertir los movimientos de stock asociados al comprobante eliminado.

• Gestion de Stock: El modulo de stock recibe las modificaciones de esta funcionalidad para soportar la trazabilidad con compras. Las consultas de movimientos se enriquecen con la informacion del comprobante de compra origen.

• Trazabilidad de Movimientos de Stock con Comprobantes de Ventas (Ver documento): Funcionalidad hermana que implementa el mismo concepto para comprobantes de venta. Ambas funcionalidades coexisten: los movimientos de ventas tendran trazabilidad con comprobantes de venta, y los movimientos de compras tendran trazabilidad con comprobantes de compra.

Modulos de negocio involucrados

Modulo	Rol en esta funcionalidad
Compras	Proporciona los comprobantes (facturas de proveedor, NC de proveedor) que originan los movimientos de stock. Proporciona los identificadores globales via Bridge de Compras
Stock	Recibe la mejora para registrar y consultar la relacion con comprobantes de compras usando identificadores globales
Auditoria	Registra las operaciones de creacion y eliminacion de movimientos con sus relaciones

Impacto en otros procesos

Proceso	Impacto
Registro de factura de proveedor	Los movimientos de stock de ingreso registraran el identificador global del comprobante de compra
Registro de nota de credito de proveedor	Los movimientos de stock de egreso registraran el identificador global del comprobante de compra
Eliminacion de comprobantes de compra	Utilizara el identificador global para identificar y revertir movimientos de stock
Consulta de movimientos de stock	Mostrara el comprobante de compra origen para movimientos generados por compras
Reportes de inventario	Podran mostrar la relacion entre ingresos de stock y comprobantes de compra

---

Criterios de Aceptacion

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

Criterios de registro de trazabilidad

• [ ] AC-001: Al registrar una factura de compra con items que afectan stock, cada movimiento de stock de ingreso generado registra el identificador global del comprobante de compra

• [ ] AC-002: Al registrar una nota de credito de proveedor con items que afectan stock, cada movimiento de stock de egreso generado registra el identificador global del comprobante de compra

• [ ] AC-003: El identificador global de compra por si solo permite identificar univocamente el comprobante de compra origen (sin necesidad de datos adicionales como sucursal)

Criterios de eliminacion y reversion

• [ ] AC-004: Al ejecutar la eliminacion de un comprobante de compra, el sistema identifica todos los movimientos de stock relacionados mediante el identificador global

• [ ] AC-005: Al ejecutar la eliminacion de un comprobante de compra, el sistema revierte correctamente el stock de cada producto afectado (decrementa para ingresos, incrementa para egresos)

• [ ] AC-006: Al ejecutar la eliminacion de un comprobante de compra, se eliminan todos los movimientos de stock relacionados sin dejar registros huerfanos

• [ ] AC-007: La identificacion de movimientos para reversion funciona correctamente aunque el comprobante sea de una sucursal diferente a la actual

Criterios de movimientos no relacionados con compras

• [ ] AC-008: Los movimientos de stock generados por ventas no tienen identificador global de compra

• [ ] AC-009: Los movimientos de stock generados por ajustes manuales no tienen identificador global de compra

• [ ] AC-010: Los movimientos de stock generados por transferencias entre depositos no tienen identificador global de compra

Criterios de compatibilidad y datos historicos

• [ ] AC-011: Los movimientos de stock historicos (sin identificador global de compra) siguen funcionando correctamente en todas las funcionalidades existentes

• [ ] AC-012: Las nuevas funcionalidades de trazabilidad indican claramente cuando la relacion no esta disponible para movimientos historicos

Criterios de inmutabilidad e integridad

• [ ] AC-013: El identificador global de compra no puede modificarse una vez asignado a un movimiento de stock

• [ ] AC-014: La auditoria registra correctamente la creacion de movimientos de stock con su identificador global de compra

• [ ] AC-015: La auditoria registra correctamente la eliminacion de movimientos de stock como parte del proceso de eliminacion de comprobantes, preservando la informacion de la relacion

Criterios de consulta y rendimiento

• [ ] AC-016: Es posible consultar el comprobante de compra origen de un movimiento de stock utilizando el identificador global

• [ ] AC-017: La consulta del comprobante origen funciona correctamente aunque el comprobante sea de una sucursal diferente a la actual

• [ ] AC-018: La busqueda de movimientos por identificador global de compra tiene un tiempo de respuesta aceptable (menos de 100 milisegundos)

• [ ] AC-019: El rendimiento de creacion de movimientos de stock no se ve afectado significativamente por el registro del identificador global

---

Notas adicionales

Diferencia con trazabilidad de ventas

Esta funcionalidad es complementaria a la trazabilidad de movimientos de stock con comprobantes de ventas:

Aspecto	Trazabilidad con Ventas	Trazabilidad con Compras
Identificador local utilizado	id_ventas (ID local) + tipo_comprobante	id_comprobante_compras (ID entero local en subdicom)
Identificador global	No aplica en esta version	id_compras (VARCHAR(36)) — reservado, actualmente NULL
Unicidad cross-sucursal	Requiere combinacion de datos	Planificada via id_compras (Bridge de Compras)
Efecto tipico en stock	Egreso (ventas), Ingreso (NC)	Ingreso (facturas proveedor), Egreso (NC proveedor)
Campo de posicion	posicion	posicion — 'I'/'E' segun tipo Debito/Credito
Tipos de comprobantes	Factura venta, NC venta, ND venta	Factura proveedor (D), NC proveedor (C)
Documento de referencia	movimiento-stock-ventas-resource.md	Este documento

Relacion con el Bridge de Compras

Esta funcionalidad depende del servicio de Identificadores Globales de Comprobantes de Compra (Bridge de Compras):

Aspecto	Bridge de Compras	Esta funcionalidad
Proposito	Generar y gestionar identificadores globales para comprobantes de compra	Utilizar identificadores globales para trazabilidad de stock
Momento de ejecucion	Al registrar comprobante de compra	Al generar movimientos de stock desde compra
Dependencia	Independiente	Requiere que Bridge de Compras este implementado

Preguntas resueltas

1. Se necesita tipo de comprobante adicional al identificador global?

   • No. A diferencia de la trazabilidad con ventas (que requiere ID + tipo), el identificador global de compra (via Bridge de Compras) sera autosuficiente para identificar univocamente el comprobante.

2. Que pasa con movimientos historicos?

   • Siguen funcionando correctamente. El sistema indica cuando la relacion no esta disponible.

3. Como se identifica el comprobante de compra en la implementacion actual?

   • Mediante id_comprobante_compras (ID entero local en subdicom). Esta identificacion es valida dentro de la misma sucursal. La trazabilidad cross-sucursal via id_compras (UUID) es una evolucion planificada.

4. Que tipos de comprobantes de compra generan movimiento de stock?

   • Facturas de proveedores (tipo Debito → posicion 'I') y notas de credito de proveedores (tipo Credito → posicion 'E') que afecten inventario.

5. Esta funcionalidad afecta a la trazabilidad de ventas?

   • No. Ambas funcionalidades coexisten de forma independiente. Los movimientos de ventas usan id_ventas + tipo_comprobante, y los movimientos de compras usan id_comprobante_compras.

6. Por que id_compras es NULL en la implementacion actual?

   • El campo fue creado como reserva para la futura trazabilidad via Bridge de Compras (identificadores globales UUID). Actualmente la logica de obtencion del identificador global no esta implementada, por lo que se inserta NULL. Al implementarse el Bridge, se completara este campo.

7. Como se determina si un movimiento es de compra oficial o de prueba?

   • La marca se asigna segun la conexion activa: si isPruebaConnection() retorna true, la marca es MarcaOrigen::PRUEBA ('P'); en caso contrario es MarcaOrigen::OFICIAL ('O').

---

Historial de cambios

Fecha	Version	Autor	Descripcion
2025-12-24	1.0	Sistema	Creacion del documento de requerimientos de negocio
2026-03-23	2.1	Sistema	Documentacion del contrato del campo importe como total de linea (cantidad × precio unitario); agregada seccion "Contrato del campo importe" con tabla de calculos por modulo; referencia en tabla de datos existentes relevantes
2026-03-23	2.0	Sistema	Documentacion del flujo implementado: MovimientoStockService, campos posicion, marca, id_comprobante_compras; id_compras marcado como reservado (NULL); condiciones de activacion (maneja_stock, PermisosEmpresa[STOCK]); distincion flujo implementado vs planificado (Bridge de Compras)