Captura de Movimientos Kardex

import { Badge } from ‘@astrojs/starlight/components’;

La automatización kardex está diseñada para entornos de alta exigencia operativa donde se requiere capturar múltiples movimientos de almacén (entradas, salidas, traspasos, ajustes) en una sola transacción, garantizando la trazabilidad histórica mediante un saldo resultante inmutable (snapshot) estampado en cada fila.

¿Cuándo usar la automatización Kardex?

Utiliza kardex cuando tu operación cumpla con estas características:

Captura en Lote: Necesitas capturar varios productos distintos que comparten una misma cabecera documental (mismo Almacén, Tipo de Movimiento, Proveedor, Folio o Fecha).
Historial con Saldo Exacto (Snapshot): Requieres que cada fila de la tabla de movimientos guarde físicamente el stock exacto que quedó tras dicha operación (balance_field).
Control de Existencias en Vivo: Deseas evitar errores humanos impidiendo salidas de mercancía si el stock disponible es insuficiente, visualizando el saldo actual directamente en pantalla.

flowchart LR
    A[Cabecera Común<br/>Almacén, Folio, Tipo] --> B[Captura Multi-Producto<br/>Lista de partidas y cantidades]
    B --> C{Validación de Stock}
    C -->|Stock Suficiente| D[Cálculo Snapshot Saldo<br/>Saldo Anterior ± Cantidad]
    D --> E[Guardado Masivo Atómico<br/>Insert en BD]
    C -->|Insuficiente| F[Alerta en Pantalla<br/>Bloqueo de salida]

Experiencia de Usuario en la Pantalla de Captura (`InOutView`)

Al activar un botón de automatización configurado como Kardex, se despliega una interfaz especializada tipo hoja de cálculo:

1. Campos de Cabecera (Bulk Properties)

En la parte superior se presentan los datos comunes de la transacción. Lo que captures en estos campos se replicará de forma instantánea a todas las partidas de la cuadrícula:

Selector de Almacén (con búsqueda asistida de referencias).
Tipo de Operación (Entrada por compra, Salida por venta, Ajuste, Merma).
Folio de documento o referencia de remisión.

2. Cuadrícula Rápida de Partidas

Una tabla interactiva optimizada para captura de alto volumen:

Asistente de Existencias (stock_selector): Al seleccionar un producto en la grilla, el selector consulta el saldo actual en ese almacén y muestra una columna con el Stock Actual. Si el movimiento es de salida, el catálogo oculta automáticamente los artículos sin existencias disponibles.
Cálculo en Vivo del Saldo: Conforme escribes la cantidad en cada fila, el sistema calcula de inmediato el nuevo saldo en la columna de balance resultante.
Consolidación Automática (merge_on_match): Si agregas el mismo producto dos veces en distintas filas por error, la aplicación las consolida sumando sus cantidades en una sola partida al momento de guardar.

3. Navegación por Atajos de Teclado

Para maximizar la velocidad sin despegar las manos del teclado:

Enter: Entra y sale del modo de edición de una celda seleccionada.
Shift + Enter: Confirma el valor actual, salta a la celda de la fila inferior y, si estás en la última fila, crea una nueva fila automáticamente manteniendo el foco en la misma columna.
Ctrl + Enter: Guarda toda la transacción si las validaciones son correctas.

Reglas de Configuración JSON (`automations.rules`)

A continuación se muestra un ejemplo completo de configuración en el campo rules:

{
  "type": "kardex",
  "qty_field": "t10c4",
  "balance_field": "t10c5",
  "type_field": "t10c3",
  "op_mapping": {
    "ENTRADA": "+",
    "COMPRA": "+",
    "DEVOLUCION": "+",
    "SALIDA": "-",
    "VENTA": "-",
    "MERMA": "-"
  },
  "match_columns": [
    "t10c1",
    "t10c2"
  ],
  "merge_on_match": true,
  "bulk_properties": [
    {
      "column": "t10c2",
      "reference_view": "{t0c0} - {t0c1}"
    },
    "t10c3"
  ],
  "stock_selector": {
    "source": "t10c1",
    "match": "t10c2",
    "filter_positive_on_out": true,
    "column_label": "Stock Actual"
  },
  "auto_create_target": {
    "target_table": "tabla_existencias",
    "match_columns": [
      { "source": "t10c1", "target": "id_producto" },
      { "source": "t10c2", "target": "id_almacen" }
    ],
    "default_values": {
      "estado": "ACTIVO"
    },
    "only_positive": true
  },
  "meta": [
    {
      "column": "t10c6",
      "data": "sequence",
      "prefix": "MOV-",
      "padding": 6
    },
    {
      "column": "t10c7",
      "data": "user.name"
    }
  ],
  "validation_save": [
    {
      "catch": "El stock disponible es insuficiente para cubrir la salida de este producto",
      "logic": "gte",
      "value": "balance_field",
      "target": 0
    }
  ]
}

Descripción de Parámetros y Llaves

Parámetro	Tipo	Requerido	Descripción
`qty_field`	Texto	Sí	Columna numérica en la tabla de movimientos donde se guarda la cantidad capturada.
`balance_field`	Texto	Sí	Columna física donde se estampa el saldo acumulado tras la operación (snapshot). En pantalla aparece bloqueada como campo calculado.
`type_field`	Texto	Sí	Columna que indica el concepto del movimiento (ej. `"COMPRA"`, `"VENTA"`).
`op_mapping`	Objeto	Sí	Mapea cada concepto con el operador aritmético correspondiente (`"+"` para entradas, `"-"` para salidas).
`match_columns`	Lista	Sí	Columnas clave que identifican la unicidad del ítem (típicamente `["producto", "almacen"]`).
`merge_on_match`	Booleano	Opcional	Activo por defecto (`true`). Fusiona filas duplicadas sumando sus cantidades antes de guardar.
`bulk_properties`	Lista	Opcional	Lista de campos que se muestran en la cabecera unificada. Admite identificadores simples o configuración con formato de referencia (`reference_view`).
`stock_selector`	Objeto	Opcional	Habilita la columna virtual de stock en tiempo real en los selectores de productos y filtra ítems agotados en salidas.
`auto_create_target`	Objeto	Opcional	Crea automáticamente el registro en la tabla física de existencias de destino si aún no existe.
`meta`	Lista	Opcional	Inyecta automáticamente folios secuenciales correlativos (`data: "sequence"`) o el nombre del usuario conectado (`data: "user.name"`).
`validation_save`	Lista	Opcional	Condiciones en memoria que deben cumplirse para permitir guardar (ej. impedir que `balance_field` sea menor a cero).