Transacciones

Las transacciones crean un registro de auditoría inmutable de cada movimiento de inventario, consumo, recepción y ajuste. Las transacciones no pueden ser editadas o eliminadas - las correcciones agregan nuevas transacciones de ajuste.

Tipos de Transacción

Flujo de Transacción:

Recepción         Transferencia           Consumo           Ajuste          Recogida
   ↓                   ↓                     ↓                ↓                ↓
Nuevo Stock → Sitio A → Sitio B → Trabajo Agota Stock  Corrección Manual  Retiro de Tarea
(Compra)     (Recogida QR)      (Reporte Enviado)    (Conteo de Ciclo)  (Escaneo QR de Recurso)

Página de transacciones mostrando registro de auditoría de todos los movimientos de inventario

Recepción

Nuevo inventario llega a un sitio (compras, devoluciones del campo).

Campos:

• toSite - Sitio destino
• resource - Qué llegó
• toVolume - Nuevo saldo de artículo de stock después de recepción
• uom - Unidad de medida

Ejemplo: 100m de cable llega al almacén

type: "receipt"
toSite: Almacén Central
resource: Cable Cat6
toVolume: 600m (era 500m, ahora 600m)

Transferencia

El inventario se mueve entre sitios (almacén → trabajador, trabajador → sitio de campo).

Campos:

• fromSite - Ubicación fuente
• toSite - Ubicación destino
• resource - Qué se movió
• fromVolume - Saldo fuente después de transferencia
• toVolume - Saldo destino después de transferencia
• pickupCode - JWT escaneado (si transferencia basada en QR)
• scannerUserId - Quién escaneó QR
• scanMethod - "self" (trabajador) o "staff" (personal de almacén)
• scanLocation - Coordenadas GPS donde ocurrió el escaneo

Ejemplo: Trabajador recoge 10m de cable vía escaneo QR

type: "transfer"
fromSite: Almacén Central
toSite: Inventario Personal de John
resource: Cable Cat6
fromVolume: 590m (almacén reducido de 600m)
toVolume: 10m (nuevo artículo de stock de John)
pickupCode: "eyJhbGc..." (JWT)
scannerUserId: john_id
scanMethod: "self"
scanLocation: { lat: 40.7128, lng: -74.0060 }

Consumo

El trabajo de campo agota inventario (creación automática cuando se envía reporte).

Campos:

• fromSite - De dónde se consumieron materiales (usualmente sitio personal del trabajador)
• resource - Qué se consumió
• fromVolume - Saldo restante después del consumo
• reportId - Enlace a reporte de trabajo (para cálculo de pago)

Ejemplo: Trabajador usa 8m de cable completando tarea

type: "consumption"
fromSite: Inventario Personal de John
resource: Cable Cat6
fromVolume: 2m (reducido de 10m)
reportId: report_abc123

Ajuste

Corrección manual de niveles de stock (conteos de ciclo, daño, pérdida).

Campos:

• stockItemId - Qué artículo de stock ajustado
• resource - Qué se ajustó
• fromVolume - Saldo anterior
• toVolume - Nuevo saldo
• reason - Explicación requerida (ej. "Corrección de conteo físico", "Dañado en tránsito")

Ejemplo: Conteo de ciclo encuentra discrepancia

type: "adjustment"
stockItemId: stock_xyz
resource: Cable Cat6
fromVolume: 2m (saldo registrado)
toVolume: 0m (conteo físico actual)
reason: "Conteo de ciclo 2026-02-10 - extremo de rollo descartado"

Recogida

Retiro de material en el contexto de una tarea, creado automáticamente cuando un trabajador escanea el código QR de un recurso de tarea.

Una transacción de recogida registra el recurso retirado, el volumen, el sitio de origen, la persona que escaneó (recogedor real) y un enlace a la tarea y a la línea de recurso específica dentro de esa tarea (context: { taskId, taskResourceIdx }). La recogida se diferencia de la Transferencia en que esta última mueve inventario entre sitios de forma genérica; la Recogida es una Transferencia con contexto de tarea — vincula la deducción de stock directamente a un elemento de trabajo planificado específico. El enlace de contexto permite consultar "cuánto de este recurso se ha retirado para la tarea X" agregando transacciones de recogida, en lugar de almacenar un total acumulado en la tarea en sí.

Los códigos QR de recogida son de un solo uso (los intentos de reutilización se rechazan con un error de conflicto). Los códigos pueden anularse (stock devuelto mediante una transacción de return) o regenerarse (nuevo código emitido, código anterior invalidado) de forma independiente.

Campos de Transacción

Comunes a Todos los Tipos:

• type - receipt, transfer, consumption, adjustment
• resource - Referencia a definición de recurso
• uom - Unidad de medida
• createdAt - Timestamp (auto-generado)
• createdBy - Usuario que inició (auto-capturado)
• properties - JSON flexible para datos personalizados

Específicos del Tipo:

• fromSite / toSite - Puntos finales del movimiento
• fromVolume / toVolume - Cambios de saldo
• reportId - Enlace a reporte de trabajo (consumo)
• pickupCode - JWT escaneado (transferencias protegidas)
• scannerUserId - Quién escaneó (transferencias)
• scanMethod - Auto-checkout vs asistido por personal
• scanLocation - GPS en tiempo de escaneo
• reason - Explicación (ajustes)

Inmutabilidad de Transacción

No Puede Ser Editada:

• Las transacciones son solo escritura
• No hay operaciones de actualización o eliminación
• Preserva integridad del registro de auditoría

Haciendo Correcciones:

1. No intentes editar transacción incorrecta
2. Crea nueva transacción adjustment
3. Incluye razón detallada explicando corrección
4. Ambas transacciones permanecen en historial

Flujo de Corrección de Ejemplo:

Día 1: Recepción muestra 100 unidades llegaron
  → Crea transacción: toVolume = 100

Día 2: Descubre que solo 95 unidades realmente recibidas
  → Crea ajuste: fromVolume = 100, toVolume = 95
  → Razón: "Error de conteo de recepción - solo 95 unidades en envío"

Resultado: Ambas transacciones visibles en registro de auditoría

Creación Automática de Transacción

Desde Envío de Reporte

Cuando trabajador envía reporte con campo consumedFrom:

1. Sistema valida disponibilidad de stock en cada artículo de stock
2. Crea atómicamente transacciones de consumo para cada recurso
3. Enlaza transacciones a reporte vía reportId
4. Agota volúmenes de artículos de stock
5. Si stock insuficiente → rechaza reporte O solicita consumo parcial

Beneficios:

• Stock siempre preciso (no se puede olvidar registrar consumo)
• Reporte + transacción comprometidos juntos (atómico)
• Cálculo de pago tiene datos confiables

Desde Escaneo de Recogida QR

Cuando trabajador escanea QR de recogida de asignación:

1. Valida firma JWT y expiración
2. Verifica que escáner es destinatario autorizado O tiene canFacilitatePickups
3. Verifica disponibilidad de stock en sitio fuente
4. Crea transacción de transferencia automáticamente
5. Registra identidad del escáner, método, ubicación GPS

Beneficios:

• No hay entrada manual de transacción
• GPS prueba presencia física
• Registro de auditoría muestra quién autorizó transferencia

Viendo Transacciones

Registro Global de Transacciones:

• Navegar a Inventario → Transacciones
• Filtrar por tipo, rango de fecha, sitio, recurso
• Exportar para conciliación o cumplimiento

Historial de Artículo de Stock:

• Navegar a artículo de stock específico
• "Historial de Transacciones" muestra todos los movimientos que afectan este artículo
• Rastrear linaje (de dónde vinieron los materiales, a dónde fueron)

Consumo de Reporte:

• Navegar a reporte de trabajo
• Sección "Materiales Usados" enlaza a transacciones de consumo
• Verificar qué se agotó realmente del inventario

Actividad de Sitio:

• Navegar a sitio
• "Transacciones Recientes" muestra recepciones, transferencias, consumos
• Monitorear rendimiento del almacén

Casos de Uso

Auditoría de Cumplimiento

• Mostrar todos los movimientos de materiales controlados
• Probar cadena de custodia (recepción → transferencia → consumo)
• Exportar registro de transacciones para reporte regulatorio

Prevención de Pérdidas

• Comparar recepciones con consumos a lo largo del tiempo
• Identificar discrepancias que requieren investigación
• Rastrear patrones de ajuste (ajustes frecuentes = problemas potenciales)

Cálculo de Pago

• Consumos enlazados a reportes vía reportId
• Calcular costos de materiales para trabajo completado
• Verificar que trabajador usó materiales asignados (no stock personal)

Conciliación de Inventario

• Comparar saldos basados en transacciones con conteos físicos
• Identificar contracción o errores de conteo
• Crear ajustes para corregir discrepancias

Responsabilidad del Trabajador

• Ver historial de recogida y consumo de trabajador individual
• Identificar quién escaneó inventario protegido
• Validación GPS muestra dónde se transfirieron materiales

Mejores Prácticas

Siempre Incluir Razón para Ajustes:

• "Corrección de conteo físico" es mejor que sin razón
• "Materiales dañados descartados - evento de tormenta 2026-02-08" aún mejor
• Ayuda a auditores futuros a entender correcciones

Usar Tipos de Transacción Más Pequeños:

• No usar ajustes cuando recepción/transferencia apropiada
• Los ajustes deberían ser excepción, no rutina
• Recepciones/transferencias preservan contexto más rico

Conciliación Regular:

• Semanal: Revisar ajustes (deberían ser raros)
• Mensual: Conteo de ciclo de artículos de stock principales
• Trimestral: Conciliación completa de almacén

Aprovechar GPS para Transferencias:

• Revisar scanLocation para inventario protegido
• Detectar anomalías (escaneo 100km del almacén)
• Validación de geocerca previene compartir QR remoto

Monitorear Volumen de Transacción:

• Tasa alta de ajuste = problemas de proceso
• Consumo bajo con recogidas altas = acaparamiento o robo
• Desajuste recepción/consumo = problemas de pronóstico de demanda

Permisos de Transacción

Creando Transacciones:

• transactionsCreate - Puede crear recepciones, ajustes
• Transacciones auto-creadas (de reportes, escaneos QR) no requieren permiso
• Permisos específicos del sitio pueden limitar quién crea recepciones en qué sitios

Viendo Transacciones:

• Todos los usuarios pueden ver transacciones para sus propios artículos de stock
• Restricciones de rol pueden ocultar transacciones para ciertos recursos/sitios
• viewDeleted permite ver transacciones soft-deleted (si alguna vez implementado)

Sin Permiso de Eliminar:

• Las transacciones no pueden ser eliminadas por nadie
• Mantiene integridad del registro de auditoría
• Solo administrador de base de datos podría eliminar (emergencia operacional solo)

Entrada de Transacción Manual con Escaneo de Código QR

Para envíos que llegan a sitios donde los artículos no tienen códigos QR existentes, el personal de campo puede usar el Formulario de Transacción Manual con escaneo QR integrado para aceptar rápidamente inventario usando un libro de referencia físico de códigos QR de recursos.

Creación de un Libro de Referencia Física de Recursos

Configuración de Admin (Una Vez):

1. Navegar a Admin → Códigos QR de Recursos (/admin/resource-qr-codes)
2. Filtrar por tipo de recurso si es necesario (Material, Mano de obra, Equipo)
3. Buscar recursos específicos a incluir
4. Hacer clic en Imprimir para generar hoja de códigos QR imprimible
5. Imprimir en papel estándar carta/A4
6. Laminar páginas y encuadernar en libro de referencia
7. Colocar libro en muelle de recepción o estación de almacén

Formato de Código QR: Cada código QR contiene datos JSON:

{
  "type": "resource",
  "id": "resource_id_123",
  "name": "Cable Cat6",
  "defaultUom": "m",
  "resourceType": "material"
}

Flujo Móvil para Aceptación de Envíos

Proceso del Personal de Campo:

1. Abrir Formulario de Transacción Manual
   • Navegar a Inventario → Transacciones
   • Hacer clic en botón "Agregar Transacción Manual"
   • Requiere permiso canFacilitatePickups
2. Habilitar Modo Lote (Opcional pero Recomendado)
   • Cambiar interruptor "Modo Lote" en la parte superior del formulario
   • Permite escanear e ingresar múltiples artículos antes de envío final
   • Ahorra tiempo cuando envío contiene 5+ artículos diferentes
3. Escanear Código QR de Recurso
   • Hacer clic en botón de escaneo (📷 icono) junto al campo Nombre de Recurso
   • Cámara se abre en dispositivo móvil
   • Apuntar cámara al código QR en el libro de referencia
   • Datos QR se auto-completan: Nombre de Recurso, ID de Recurso, UOM Predeterminado
4. Ingresar Detalles de Cantidad
   • Campo Volumen: Ingresar cantidad recibida (ej. "50")
   • Campo UOM: Pre-llenado desde QR, ajustar si necesario (ej. "m" para metros)
   • Sitio: Arrastrar y soltar sitio de destino o usar ubicación actual
5. Agregar al Lote (Si Modo Lote Habilitado)
   • Hacer clic en botón "Agregar al Lote"
   • Artículo aparece en lista de lote abajo
   • Formulario se vacía para el siguiente artículo
   • Repetir pasos 3-5 para cada artículo en el envío
6. Enviar Transacción(es)
   • Modo único: Hacer clic en "Enviar" (crea una transacción)
   • Modo lote: Hacer clic en "Enviar Lote (N artículos)" (crea N transacciones atómicamente)
   • Notificación de éxito muestra cuántos artículos fueron aceptados
   • Si algunos artículos fallan, sistema reporta conteo pero no hace rollback de otros

Ejemplo de Flujo de Lote:

Envío llega con 5 materiales diferentes:
1. Escanear "Cable Cat6" QR → Ingresar 50m → Agregar al Lote
2. Escanear "Conducto 1in" QR → Ingresar 20 unidades → Agregar al Lote
3. Escanear "Caja de Empalme" QR → Ingresar 15 unidades → Agregar al Lote
4. Escanear "Abrazadera de Cable" QR → Ingresar 500 unidades → Agregar al Lote
5. Escanear "Cable de Tierra" QR → Ingresar 100m → Agregar al Lote
6. Enviar Lote (5 artículos)
→ Crea 5 artículos de stock + 5 transacciones de recepción instantáneamente

Manejo de Recursos Desconocidos

Si envío contiene artículos no en el libro de referencia:

1. Ingresar Nombre de Recurso Manualmente
   • Ingresar nombre en campo Nombre de Recurso (sin escaneo QR)
   • Sistema busca recurso existente por nombre
   • Si no encontrado → coloca automáticamente en recurso "Holding/Staging"
2. Flujo Holding/Staging
   • Propiedades de transacción incluyen originalResourceName (lo que usted escribió)
   • Toast de advertencia: "Recurso no encontrado. Colocado en Holding/Staging"
   • Artículo de stock creado con recurso Holding/Staging
   • Después: Personal de oficina asigna a recurso apropiado (ver Asignación de Inventario en Espera abajo)
3. Ventajas del Auto-Staging
   • Aceptación del personal de campo nunca se bloquea
   • Inventario se acepta físicamente y rastrea inmediatamente
   • Categorización de recursos ocurre de manera asíncrona
   • Sin demoras bloqueantes para envíos urgentes

Funciones del Modo Lote

Tabla de Artículos en Línea:

• Muestra todos los artículos escaneados antes de envío
• Muestra: Nombre de Recurso, Volumen, UOM
• Remover artículos individuales con botón X
• Vista visual clara de lo que se comprometerá

Envío:

• Procesamiento de lote atómico (todo-o-nada donde posible)
• Fallos de artículos individuales reportados pero no bloquean otros
• Conteo de éxito: "5 transacciones creadas exitosamente"
• Manejo de fallos parciales: "2 artículos no pudieron procesarse"

Optimización Móvil:

• Gran botón de escaneo táctil
• Acceso a cámara con alternancia de flash
• Funciona sin conexión con almacenamiento en caché PWA
• Guardado automático de lote en localStorage (sobrevive refresco de página)

Asignación de Inventario en Espera

Después de que personal de campo acepta recursos desconocidos en Holding/Staging:

1. Navegar a Artículos de Stock
   • Filtrar por "Sitio: Holding/Staging" (si implementado)
   • Buscar artículos con isHoldingResource: true
2. Abrir Modal de Asignación
   • Hacer clic en botón "Asignar Inventario en Espera" en artículo de stock
   • Muestra: Volumen actual, Nombre original ingresado por personal de campo
3. Seleccionar Recurso Apropiado
   • Opción A: Arrastrar recurso existente desde tabla de recursos
   • Opción B: Cambiar "Crear Nuevo Recurso" e ingresar detalles
   • Ingresar razón de asignación (ej. "Identificado como cable Cat6A, no Cat6")
4. Enviar Asignación
   • Actualiza atómicamente:
     • Campo recurso del artículo de stock (Holding → Apropiado)
     • Crea transacción de ajuste con razón de asignación
     • Preserva originalResourceName en propiedades de transacción

Ventajas:

• Aceptación en campo nunca se bloquea
• Categorización de oficina preserva registro de auditoría
• Ningún inventario "desaparece" durante transición
• Notas originales del trabajador de campo se preservan

Viendo Transacciones

Registro Global de Transacciones:

• Navegar a Inventario → Transacciones
• Filtrar por tipo, rango de fechas, sitio, recurso
• Exportar para reconciliación o cumplimiento

Historia de Artículo de Stock:

• Navegar a artículo de stock específico
• "Historia de Transacciones" muestra todos los movimientos afectando este artículo
• Rastrear linaje (de dónde vinieron los materiales, a dónde van)

Consumo de Reporte:

• Navegar a reporte de trabajo
• Sección "Materiales Usados" enlaza a transacciones de consumo
• Verificar qué se consumió realmente del inventario

Actividad del Sitio:

• Navegar a sitio
• "Transacciones Recientes" muestra recepciones, transferencias, consumos
• Monitorear rendimiento de almacén

Casos de Uso

Auditoría de Cumplimiento

• Mostrar todos los movimientos de materiales controlados
• Probar cadena de custodia (recepción → transferencia → consumo)
• Exportar registro de transacciones para reporte regulatorio

Prevención de Pérdidas

• Comparar recepciones con consumos a lo largo del tiempo
• Identificar discrepancias requiriendo investigación
• Crear ajustes para corregir discrepancias

Cálculo de Pagos

• Consumos enlazados a reportes vía reportId
• Calcular costos de materiales para trabajo completado
• Verificar que trabajador usó materiales asignados (no stock personal)

Reconciliación de Inventario

• Comparar saldos basados en transacciones con conteos físicos
• Identificar contracción o errores de conteo
• Crear ajustes para corregir discrepancias

Responsabilidad de Trabajador

• Ver historial de retiro y consumo individual de trabajador
• Identificar quién escaneó inventario protegido
• Validación GPS muestra dónde se transfirieron materiales

Mejores Prácticas

Siempre Incluir Razón para Ajustes:

• "Corrección de conteo físico" es mejor que ninguna razón
• "Materiales dañados descartados - evento de tormenta 2026-02-08" aún mejor
• Ayuda a auditores futuros entender correcciones

Usar Tipos de Transacción Más Pequeños:

• No usar ajustes cuando recepción/transferencia apropiada
• Ajustes deberían ser excepción, no rutina
• Recepciones/transferencias preservan contexto más rico

Reconciliación Regular:

• Semanal: Revisar ajustes (deberían ser raros)
• Mensual: Conteo de ciclo de artículos de stock mayores
• Trimestral: Reconciliación completa de almacén

Aprovechar GPS para Transferencias:

• Revisar scanLocation para inventario protegido
• Detectar anomalías (escaneo 100km del almacén)
• Validación de geofence previene compartir QR remoto

Monitorear Volumen de Transacciones:

• Alto volumen de ajuste = problemas de proceso
• Bajo consumo con retiros altos = acaparamiento o robo
• Desajuste recepción/consumo = problemas de pronóstico de demanda

Permisos de Transacción

Creando Transacciones:

• transactionsCreate - Puede crear recepciones, ajustes
• Transacciones auto-creadas (de reportes, escaneos QR) no requieren permiso
• Permisos específicos del sitio pueden limitar quién crea recepciones en qué sitios

Viendo Transacciones:

• Todos los usuarios pueden ver transacciones para sus propios artículos de stock
• Restricciones de rol pueden ocultar transacciones para ciertos recursos/sitios
• viewDeleted permite ver transacciones soft-deleted (si alguna vez implementado)

Sin Permiso de Eliminar:

• Las transacciones no pueden ser eliminadas por nadie
• Mantiene integridad del registro de auditoría
• Solo administrador de base de datos podría eliminar (emergencia operacional solo)