Procedimiento: Almacen e Inventario

Estado del documento

Esta guia describe el flujo v1 de stock, despacho y prestamo de herramientas.

Para la implementacion del epic simsa-1hz, la funcion de almacen tambien participa en:

• verificacion de stock previa a compra
• recepcion de material de proveedores
• discrepancias y recepcion parcial
• asignacion directa a OS o ingreso a stock

Mientras se actualiza la interfaz final, usar el contrato autoritativo para decisiones de arquitectura y esta guia solo como referencia del flujo v1.

Proposito

Esta intervencion permite al almacenista controlar los niveles de stock de productos, despachar consumibles contra ordenes de servicio activas y gestionar el prestamo y devolucion de herramientas a mecanicos. Cada despacho genera un movimiento en la tabla canonica _movimientos_inventario y cada prestamo se registra en _prestamos_herramienta.

El objetivo es que el almacen mantenga visibilidad sobre el inventario en tiempo real, detecte productos en nivel critico para coordinar reorden con Compras (INT-4), y asegure que las herramientas prestadas se devuelvan oportunamente.

Vista: Almacen

La pestana vista_almacen es una vista de solo lectura (Capa 3a) que muestra todos los productos activos con sus niveles de stock actuales. Se actualiza automaticamente cada vez que se procesan cambios.

Columnas de la vista

Columna	Descripcion
Folio Producto	Identificador unico del producto
Descripcion	Nombre o descripcion del producto
Categoria	Categoria del producto (segun _categorias_producto)
Unidad	Unidad de medida (piezas, litros, etc.)
Stock Actual	Cantidad disponible actualmente en almacen
Stock Minimo	Cantidad minima requerida antes de reordenar
Precio Unitario	Precio por unidad del producto
Ultimos Movimientos	Resumen de los 3 movimientos mas recientes del producto
Nivel Stock	Semaforo de nivel de stock (ver abajo)

Semaforo de nivel de stock

El semaforo indica la urgencia de reorden para cada producto:

Color	Etiqueta	Significado
Verde	Suficiente	El stock actual es mayor a 1.5 veces el stock minimo. No requiere accion.
Amarillo	Bajo — reordenar pronto	El stock actual esta por encima del minimo pero por debajo de 1.5 veces el minimo. Planificar reorden.
Rojo	Critico — reordenar ahora	El stock actual es menor o igual al stock minimo. Reordenar de inmediato y coordinar con Compras (INT-4).

Importante: Verificar diariamente los productos en rojo. Cada producto en nivel critico debe tener una solicitud de compra asociada o una justificacion documentada.

Filtros

Solo aparecen productos con activo = true. Los productos dados de baja o descontinuados no aparecen en esta vista.

Ordenamiento

Los productos se muestran ordenados por severidad del semaforo (rojo primero, luego amarillo, luego verde) y dentro de cada nivel por descripcion en orden alfabetico. Esto prioriza los productos que requieren atencion inmediata.

Vista: Prestamo de Herramientas

La pestana vista_almacen_herramientas es una vista complementaria de solo lectura (Capa 3a) que muestra el estado actual de todas las herramientas registradas.

Columnas de la vista

Columna	Descripcion
Codigo Herramienta	Identificador unico de la herramienta
Descripcion	Nombre o descripcion de la herramienta
Estado	Estado actual (disponible, prestada)
Ubicacion	Ubicacion fisica de la herramienta
Mecanico	Nombre del mecanico que tiene la herramienta (si aplica)
Folio OS	Orden de servicio asociada al prestamo (si aplica)
Fecha Prestamo	Fecha en que se presto la herramienta
Dias Prestado	Dias transcurridos desde el prestamo
Alerta Prestamo	Semaforo de alerta (ver abajo)

Semaforo de alerta de prestamo

Color	Etiqueta	Significado
Verde	Disponible	La herramienta esta disponible o ya fue devuelta.
Amarillo	Prestada > 3 dias	La herramienta lleva mas de 3 dias prestada. Dar seguimiento con el mecanico.
Rojo	Prestada > 7 dias — escalar	La herramienta lleva mas de 7 dias prestada. Escalar a Jefe de Taller.

Filtros y ordenamiento

Solo aparecen herramientas con activo = true. Se ordenan por severidad del semaforo (rojo primero) y luego por codigo de herramienta.

Como Despachar Consumibles

Los despachos se registran a traves de la pestana stg_despacho_consumibles. Cada fila representa un despacho de producto contra una OS activa.

1. Abrir la pestana stg_despacho_consumibles (o el formulario en AppSheet).
2. Llenar los campos:
   • stg_id: Identificador unico del despacho (se genera automaticamente en AppSheet).
   • os_id: Seleccionar la orden de servicio activa.
   • producto_id: Seleccionar el producto del catalogo (_productos).
   • cantidad: Numero de unidades a despachar.
   • mecanico_id: Seleccionar el mecanico que recibe el producto.
   • nota: (Opcional) Informacion adicional sobre el despacho.
3. El sistema valida que el stock disponible sea suficiente para la cantidad solicitada.
4. Si hay stock suficiente, el sistema:
   • Crea un registro en _movimientos_inventario con tipo_movimiento = salida.
   • Decrementa stock_actual del producto en _productos.
5. Verificar en la vista que el stock se actualizo correctamente.

Estados validos de OS para despacho: en_proceso, trabajo_terminado, refacciones_cargadas.

Como Gestionar Prestamos de Herramienta

Los prestamos y devoluciones se registran a traves de la pestana stg_prestamo_herramienta. Cada fila representa una accion de prestamo o devolucion.

Prestar herramienta

1. Abrir la pestana stg_prestamo_herramienta (o el formulario en AppSheet).
2. Llenar los campos:
   • stg_id: Identificador unico del prestamo (se genera automaticamente en AppSheet).
   • herramienta_id: Seleccionar la herramienta del catalogo (_herramientas).
   • mecanico_id: Seleccionar el mecanico que recibe la herramienta.
   • os_id: Seleccionar la orden de servicio asociada al trabajo.
   • accion: Seleccionar prestar.
   • nota: (Opcional) Informacion adicional.
3. El sistema valida que la herramienta este disponible (no prestada actualmente).
4. Si esta disponible, el sistema:
   • Crea un registro en _prestamos_herramienta con estado = prestada y fecha_prestamo = NOW().
   • Actualiza _herramientas.estado a prestada.

Devolver herramienta

1. Abrir la pestana stg_prestamo_herramienta.
2. Llenar los campos:
   • herramienta_id: Seleccionar la herramienta a devolver.
   • mecanico_id: Seleccionar el mecanico que devuelve.
   • os_id: Seleccionar la orden de servicio asociada.
   • accion: Seleccionar devolver.
   • nota: (Opcional) Informacion sobre el estado de la herramienta al devolverla.
3. El sistema valida que exista un prestamo activo para esa herramienta.
4. Si existe, el sistema:
   • Actualiza _prestamos_herramienta: estado = devuelta, fecha_devolucion = NOW().
   • Actualiza _herramientas.estado a disponible.

Semaforo de Nivel de Stock

El semaforo es el principal instrumento de decision del almacenista. Se calcula comparando stock_actual contra stock_minimo de cada producto:

Verde — Suficiente

• Condicion: stock_actual > stock_minimo * 1.5
• Accion requerida: Ninguna. El nivel de stock es saludable.
• Ejemplo: Si stock_minimo = 10 y stock_actual = 18, el indicador es verde (18 > 15).

Amarillo — Bajo

• Condicion: stock_actual > stock_minimo y stock_actual <= stock_minimo * 1.5
• Accion requerida: Planificar reorden proximo. Comunicar a Compras (INT-4) para que programe la adquisicion.
• Ejemplo: Si stock_minimo = 10 y stock_actual = 12, el indicador es amarillo (12 > 10 pero 12 <= 15).

Rojo — Critico

• Condicion: stock_actual <= stock_minimo
• Accion requerida: Reordenar de inmediato. Crear solicitud urgente a Compras (INT-4). Evaluar si hay OS en riesgo de paro por falta de material.
• Ejemplo: Si stock_minimo = 10 y stock_actual = 8, el indicador es rojo (8 <= 10).

Cuando Escalar

Las siguientes situaciones requieren accion adicional y no pueden resolverse directamente en el flujo normal:

Stock insuficiente para despacho

Si la cantidad solicitada excede el stock disponible:

1. Verificar si hay stock fisico no registrado (diferencia fisica vs sistema).
2. Si no hay stock fisico suficiente, coordinar con Compras (INT-4) para compra urgente.
3. Si hay autorizacion verbal para despachar con stock negativo, llenar campos de override (ver seccion de Excepciones).

Herramienta prestada mas de 7 dias

Si una herramienta lleva mas de 7 dias sin devolucion:

1. Contactar al mecanico directamente.
2. Si el mecanico no responde o no devuelve, escalar a Jefe de Taller.
3. Documentar en la nota del prestamo el seguimiento realizado.

Discrepancia de inventario

Si el conteo fisico no coincide con el sistema:

1. Registrar la diferencia como un ajuste de inventario (ver seccion de Excepciones).
2. Documentar la causa probable en la nota.
3. Si la diferencia es significativa (>10% del stock registrado), reportar al administrador.

Herramienta danada o extraviada

1. Reportar al Jefe de Taller.
2. Documentar en nota del prestamo si estaba prestada al momento del evento.
3. No intentar resolver la situacion desde esta interfaz.

Excepciones

Cuando una situacion requiere desviarse del flujo normal, se utilizan los campos de override en las pestanas de staging.

Campos de override

Campo	Proposito
override_reason_code	Codigo del motivo de la excepcion
override_nota	Descripcion libre del motivo
override_por	Nombre de quien autoriza la excepcion
override_fecha	Fecha de la autorizacion

Cuando usar override

• Stock insuficiente con autorizacion: Cuando se autoriza verbalmente un despacho que dejaria el stock en negativo.
• Despacho sin OS asociada: Cuando se necesita despachar material sin una OS activa (situacion excepcional).
• Ajuste de inventario: Cuando se detecta una diferencia entre el conteo fisico y el sistema.

Codigos de motivo (override_reason_code)

Los codigos deben describir la situacion. Codigos especificos del almacen:

• ajuste_inventario — diferencia detectada entre conteo fisico y sistema
• despacho_sin_os — despacho de material sin orden de servicio asociada
• stock_insuficiente_autorizado — despacho autorizado a pesar de stock insuficiente
• devolucion_danada — herramienta devuelta en mal estado
• prestamo_urgente — prestamo sin OS por situacion urgente

Reglas Importantes

1. Revisar la vista de almacen al inicio de cada jornada. Productos en rojo (critico) requieren accion inmediata.
2. Coordinar con Compras (INT-4) para todo producto en amarillo o rojo. No esperar a que el stock llegue a cero.
3. Para despachar consumible: seleccionar OS, producto, cantidad y mecanico. El sistema valida stock automaticamente.
4. Para prestar herramienta: verificar que la herramienta este disponible antes de llenar el formulario.
5. Para devolver herramienta: usar accion devolver. La fecha de devolucion se registra automaticamente.
6. Si la cantidad excede el stock disponible, el sistema rechaza el despacho. Solo proceder con override si hay autorizacion.
7. Dar seguimiento a herramientas en amarillo (>3 dias). No esperar a que lleguen a rojo (>7 dias).
8. No modificar tablas canonicas directamente. Todo cambio pasa por stg_despacho_consumibles o stg_prestamo_herramienta.
9. Para ajustes de inventario, registrar como despacho con override_reason_code = ajuste_inventario y nota explicativa.
10. Cada despacho debe tener OS y mecanico asociados. Solo usar despacho_sin_os como excepcion documentada.

Errores Comunes

Cuando una fila de staging se procesa incorrectamente, el sistema escribe el resultado en los campos de sistema:

Campo	Valor
status_procesamiento	ok (exito) o error (fallo)
error_code	Codigo del error (ej. VALIDATION_ERROR)
error_detail	Descripcion detallada del problema
procesado_at	Fecha y hora del procesamiento

Errores frecuentes y solucion

Error	Causa	Solucion
”os_id es obligatorio”	No se selecciono la OS	Verificar que el campo os_id tenga un valor valido
”OS con id=X no encontrada”	El os_id no existe en _ordenes_servicio	Verificar el ID correcto en la vista
”producto_id es obligatorio”	No se selecciono producto para despacho	Seleccionar un producto del catalogo _productos
”cantidad debe ser > 0”	Cantidad cero o negativa	Ingresar una cantidad mayor a cero
”Stock insuficiente”	La cantidad solicitada excede stock_actual	Reducir cantidad o llenar campos de override si hay autorizacion
”herramienta_id es obligatorio”	No se selecciono herramienta	Seleccionar herramienta del catalogo _herramientas
”Herramienta ya prestada”	Se intenta prestar una herramienta que ya esta en prestamo	Verificar que la herramienta este disponible; primero registrar devolucion
”No hay prestamo activo”	Se intenta devolver una herramienta que no tiene prestamo activo	Verificar el codigo de herramienta correcto
”accion debe ser: prestar o devolver”	Valor invalido en el campo accion	Usar unicamente prestar o devolver
”OS en estado X no acepta despacho”	La OS esta en un estado que no permite despacho	Solo se despacha a OS en en_proceso, trabajo_terminado o refacciones_cargadas

Que hacer si una fila tiene error

1. Revisar los campos error_code y error_detail en la fila de staging.
2. Corregir el dato incorrecto.
3. Limpiar el campo status_procesamiento (dejarlo vacio) para que el sistema vuelva a procesar la fila.
4. Esperar el siguiente ciclo de procesamiento o ejecutar manualmente.

Referencias

• Especificacion tecnica: docs/views/int-5_almacen.yaml
• Arquitectura de datos: docs/architecture/dec_001_modelo-de-datos-canonico.md
• Capas de datos: docs/architecture/dec_002_capa-canonica-y-vistas-operativas.md
• Vistas por rol: docs/architecture/dec_003_vistas-decision-support-por-rol.md
• Ruta de intervencion: docs/architecture/spec_ruta-de-intervencion.md