🧭 SOL · README Técnico de Base de Datos

Última actualización: 2025-10-05 — Alcance: sys* (referencias), para_* (parámetros), wh_* (depósito), pl_* (packing list), ope_* (operaciones) y procedimientos/vistas.

1) Mapa de módulos y flujo

2) Catálogos y Parámetros (para_*)

Tablas base para normalizar entidades, productos y logística.

Tabla	Propósito	Columnas clave
para_clientes	Maestro de clientes/tenants.	id, razon_social, ruc, activo, timestamps.
para_productos	Catálogo de productos (SKU interno).	id, sku, denominacion, clase_id, grupo_id, metodo_rotacion_id, flags de vencimiento/estadia, imágenes, timestamps.
para_producto_codigos	Códigos alternativos (EAN/UPC/QR/código de proveedor) por producto (y por cliente opcional).	producto_id, tipo_codigo_id, valor, cliente_id.
para_pack_tipos, para_producto_pack	Tipologías UC/UV y datos físicos (dimensiones, pesos, unidades por UV).	Pack: producto_id, tipo_pack_id, volumen_m3 (GENERATED), unidades_por_uv.
para_producto_paletizado	Parámetros de paletización (cajas por capa, capas, altura, pesos).	cajas_por_pallet (GENERATED), altura_pallet_cm, límites de peso.
para_clases, para_grupos, para_metodos_rotacion	Taxonomía de productos y método FEFO/FIFO/LIFO.	Campos nombre, descripcion, activo, timestamps.
para_transportadoras, para_movil_tipos, para_moviles, para_choferes	Logística de arribo: transportes, móviles/camiones, choferes.	Móviles: id, chapa, tipo_id, transportadora_id, activo.
para_ciudades, para_destinatarios	Direcciones y destinatarios de salida (distribución).	Destinatarios: cliente_id, datos fiscales y de contacto.

3) Warehouse / Depósito (wh_*)

Núcleo de posiciones 3D, pallets, lotes y stock.

Tabla	Propósito	Claves / Notas
wh_ambiente	Áreas: CUARENTENA, SECO, FRIO, PICKING, PISO.	Unique code.
wh_pallet_estado	Estados de pallet: RECIBIDO, CUARENTENA, POS_ENTERO, POS_PICKEADO, RESERVADO, REMANEJO, AVERIADO, EMBARCADO.	Unique code, orden.
wh_deposito	Depósitos (p.ej. DEP1).	Unique code.
wh_posicion	Rejilla 3D: depósito → rack → columna → nivel → fondo (+lado/orientación).	Unique geométrica (deposito_id,rack,columna,nivel,fondo,lado) y códigos (code/code_full, etc.). Flags ocupado/picked.
wh_lote	Trazabilidad por producto+lote (fechas prod/venc).	Unique (producto_id,codigo).
wh_pallet + wh_pallet_item	Pallets y su contenido por SKU/Lote (UV/UC). Soporta pallets mixtos.	estado_id, posicion_id (nullable si en tránsito); items con UNIQUE (pallet_id, producto_id, lote_id).
wh_move	Movimientos IN/MOVE/OUT con referencia a posiciones/lote.	Índice (deposito_id,pallet_id,producto_id,lote_id,created_at).
wh_stock	Stock resumido por posición+producto+lote(+pallet opcional) con UV/UC y flag pickeado.	UNIQUE compuesto con normalizaciones (posicion_id_norm, pallet_id_norm) para soportar NULL.

4) Packing List e Importación (pl_*)

Captura de PL cliente, conciliación y vinculación con recepciones físicas.

Tabla	Propósito	Notas
pl_import_batch / pl_import_row	Staging JSON de filas importadas desde Excel (por hoja/archivo).	raw JSON, status, error_msg, conteos (rows_ok/error) en batch.
pl_packinglist	Cabecera del PL (código, cliente_ref, fecha, estado).	Estados típicos: IMPORTADO → EN_DESCARGA → DESCARGADO/VALIDADO → CERRADO.
pl_packinglist_item	Líneas esperadas (SKU cliente, producto_id, lote, fechas, cantidades esperadas vs. recibidas).	Conciliación campo a campo; soporta checked_item y checked_all en cabecera.
pl_producto_alias	Alias SKU del cliente → producto_id interno.	Se crea/actualiza automáticamente en la importación.
pl_rcv_link	Vínculo de cada ítem de PL con la recepción física: pallet/move/lote.	Trazabilidad cruzada PL ↔ WH.
pl_ingreso	Arribo/descarga por PL (camión, chofer, operarios, tiempos y documentos).	Se autocrea al cerrar si faltara (ver SP sp_pl_cerrar_ingreso).

5) Operaciones de ingreso (ope_*)

Estructuras tradicionales de operación (compatibilidad con módulos existentes).

Tabla	Propósito	Notas
ope_ingresos	Registro de ingresos (fecha, móvil, chofer, responsables, tiempos inicio/fin, documentos).	estado_id 0/1 (abierto/cerrado).
ope_ingreso_operarios	Detalle de operarios por ingreso (roles y horas).	Permite calcular productividad.

6) Procedimientos almacenados (SPs)

SPs principales que encadenan integridad, stock y trazabilidad.

Procedimiento	Rol	Entradas (resumen)	Salida
sp_pl_import_packinglist_from_batch	Convierte pl_import_row → pl_packinglist/items, crea productos/lotes si faltan y alias SKU cliente.	p_batch_id, p_cliente_ref, p_cliente_id, p_packinglist_codigo, p_fecha, p_overwrite_if_exists	o_packinglist_id
sp_pl_recibir_desde_pl	Recepción a CUARENTENA desde PL (AUTO por pendientes o PLAN JSON por pallets).	p_packinglist_codigo, p_deposito_code, p_pos_code, p_plan_json, p_check_items, p_check_all_if_full	Resumen por pallet (tabla temporal devuelta).
sp_pl_cerrar_ingreso	Cierra el ingreso del PL (autocrea pl_ingreso si faltara e infiere depósito/tiempos).	p_packinglist_codigo, p_descarga_fin_at, p_operarios_cant, p_check_all_if_full	o_estado + select de estado/ingreso/fin.
sp_wh_ingreso_create	Crea o reutiliza un wh_pallet con sus items desde JSON y registra wh_move IN.	p_deposito_code, p_pallet_codigo, p_pos_code, p_estado_code, p_items_json, p_overwrite_if_exists	IDs resultantes (pallet, move, posición).
sp_wh_reposicion	Move pallet completo entre posiciones (valida capacidad, estado destino).	p_deposito_code, p_pallet_codigo, p_to_pos_code, p_motivo, p_estado_dest	Datos del movimiento.
sp_wh_salida_parcial	Salida parcial por producto/lote (marca pallet pickeado).	p_deposito_code, p_pallet_codigo, p_producto_id, p_lote_codigo, p_delta_uv, p_delta_uc, p_referencia	Datos del movimiento OUT.
sp_wh_salida_total	Salida total de pallet (estado EMBARCADO, posición NULL).	p_deposito_code, p_pallet_codigo, p_referencia	Datos del movimiento OUT.
sp_wh_move_apply	Motor de stock para IN/MOVE/OUT (pallet completo o parcial).	Parámetros detallados del movimiento.	—
sp_wh_stock_apply	UPSERT de wh_stock (control de negativos y flag pickeado), refresca flags de posición.	Clave Posición+Producto+Lote(+Pallet) y deltas.	—
sp_wh_pos_refresh_flags	Recalcula ocupado/picked en wh_posicion a partir de wh_stock.	p_posicion_id	—

7) Vistas operativas y KPI

Vistas útiles para UI/validaciones rápidas (se entregaron en pasos previos):

• v_wh_posiciones_dep1: posiciones existentes en DEP1 (layout).
• v_wh_cuarentena_pallets: pallets actualmente en estado CUARENTENA (con posición).
• v_wh_moves_recent50: últimos 50 movimientos con info clave.
• v_wh_stock_dep1: stock resumido de DEP1 (posición/producto/lote/pallet).
• v_kpi_ingresos_descarga, v_kpi_ingreso_detalle: KPIs de tiempos y conciliación por PL (si están desplegadas en tu instancia).

8) Consultas y ejemplos prácticos

A) Importación de PL (desde staging JSON)

-- 1) Registrar el batch y filas JSON en pl_import_batch / pl_import_row
INSERT INTO pl_import_batch (tipo, filename, sheet_name) VALUES ('PACKINGLIST','PL_0002.xlsx','Hoja1');
SET @batch := LAST_INSERT_ID();

INSERT INTO pl_import_row (batch_id,rownum,raw) VALUES
(@batch,1, JSON_OBJECT('sku_cliente','SKU-NEW-001','descripcion','Producto A','expected_uv',12,'lote_codigo','L-A','fecha_produccion','2025-09-01','fecha_vencimiento','2026-09-01')),
(@batch,2, JSON_OBJECT('sku_cliente','SKU-ACME-002','descripcion','Producto B','uv',5,'uc',12));

-- 2) Convertir a pl_packinglist (crea productos/alias/lotes si no existen)
CALL sp_pl_import_packinglist_from_batch(@batch, 'ACME', 'PL-0002', CURDATE(), 1, @pl_id);
SELECT @pl_id;

B) Recepción (AUTO) a CUARENTENA

-- Crea pallets por cada ítem pendiente del PL y los ubica en CUARENTENA
CALL sp_pl_recibir_desde_pl('PL-0002','DEP1', NULL, NULL, 1, 1);

C) Recepción (PLAN JSON) detallada por pallet

-- Plan con pallets predefinidos y, opcionalmente, posiciones distintas
SET @plan = JSON_ARRAY(
  JSON_OBJECT('pallet_codigo','PAL-PL-0002-001','pos_code','CUAR-01',
    'items', JSON_ARRAY(
      JSON_OBJECT('pl_item_id', 101, 'uv', 10, 'uc', 0),
      JSON_OBJECT('pl_item_id', 102, 'uv',  0, 'uc', 5)
  )),
  JSON_OBJECT('pallet_codigo','PAL-PL-0002-002',
    'items', JSON_ARRAY(
      JSON_OBJECT('sku_cliente','SKU-NEW-001','uv',2,'uc',0)
  ))
);
CALL sp_pl_recibir_desde_pl('PL-0002','DEP1', NULL, @plan, 1, 1);

D) Reposición a ubicación definitiva

-- Mover pallet completo desde CUARENTENA a posición de rack
CALL sp_wh_reposicion('DEP1','PAL-PL-0002-001','DEP1-R01-C01-N01-F1','UBICACION', NULL);

E) Salida parcial (picking)

-- Descontar parcialmente por SKU/lote desde la posición actual del pallet
CALL sp_wh_salida_parcial('DEP1','PAL-PL-0002-001', /* producto_id */ 1, /* lote */ 'L-A', 1, 4, 'PICKING');

F) Salida total (embarque)

CALL sp_wh_salida_total('DEP1','PAL-PL-0002-002','DESPACHO');

G) Cierre del ingreso (PL)

-- Si no existiera pl_ingreso, el SP lo autocrea e infiere depósito/tiempos
CALL sp_pl_cerrar_ingreso('PL-0002', NOW(), 4, 1, @estado);
SELECT @estado AS estado_final;

9) Convenciones, integridad y auditoría

• UTC/Timezone: usar TIMEZONE del .env en la app PHP; la DB guarda DATETIME en local del servidor.
• Estados: wh_pallet.estado_id sincronizado por SPs (ingreso, reposición, salida).
• Stock: wh_stock es la verdad resumida. No permitir negativos; los SPs validan.
• Posiciones: flags ocupado/picked se recalculan con sp_wh_pos_refresh_flags.
• Auditoría: columnas created_at/updated_at/deleted_at en casi todas las tablas; futuros FKs a sys_users para created_by/updated_by.
• Nomenclatura: prefijos para_*, wh_*, pl_*, ope_* y futuros sys_*.

Contacto: Equipo SOL · Arquitectura & Dev Lead.