Proposito

Esta intervencion permite al encargado de compras (Omar) gestionar el ciclo completo de abastecimiento del taller: desde la captura de necesidades del taller, la busqueda de cotizaciones con proveedores, el envio para aprobacion de direccion, hasta el seguimiento del pago y la recepcion del material.

El flujo sigue el modelo de demanda de abastecimiento:

Demanda → Cotizaciones → Aprobacion → Pago → Recepcion

Cada etapa tiene su propia pestana de captura y su propia vista de seguimiento. Compras es el orquestador principal y coordina con almacen (stock-check, recepcion), direccion (aprobacion), y finanzas (pago).

Guias relacionadas por funcion

Funcion	Guia	Pestana de captura
Compras (captura de demanda y opciones)	Esta guia	`stg_demanda_abastecimiento`, `stg_opcion_abastecimiento`
Direccion (aprobacion)	Aprobaciones	`stg_decision_abastecimiento`
Finanzas (pagos)	Pagos a Proveedor	`stg_pago_proveedor`
Almacen (recepcion)	Recepciones Pendientes	`stg_recepcion_abastecimiento`

Flujo v2: Demanda de Abastecimiento (simsa-1hz)

El flujo principal de compras sigue el modelo de demanda de abastecimiento. Cada necesidad del taller se registra como una demanda, se cotiza con proveedores, se envia a direccion para aprobacion, se paga, y finalmente se recibe el material.

Paso 1: Capturar Demanda

Cuando el taller necesita material o servicio externo, compras registra la demanda en stg_demanda_abastecimiento:

Abrir stg_demanda_abastecimiento (o el formulario en AppSheet).
Llenar los campos:
- os_id: OS que requiere el material (obligatorio para demandas vinculadas a servicio).
- replenishment_reason_code: Razon de la demanda.
- requested_by_user_id: Quien solicita.
- requested_by_function: Funcion del solicitante (ej. compras, jefe_taller).
- item_kind: Tipo de articulo (product, service, external_repair, consumable, stock_replenishment).
- producto_id: (Opcional) Producto del catalogo. Dejar vacio para servicios o articulos no catalogados.
- descripcion_solicitada: Descripcion clara de lo que se necesita.
- cantidad_requerida: Cantidad necesaria.
- unidad_medida: Unidad (pza, lt, hr, etc.).
- urgency_code: normal, urgente, o paro_operativo.
El sistema crea la demanda en _demandas_abastecimiento en estado capturada.
Almacen puede verificar stock antes de que compras busque externamente.

Paso 2: Registrar Opciones de Cotizacion

Una vez que compras obtiene cotizaciones de proveedores:

Abrir stg_opcion_abastecimiento.
Llenar los campos por cada cotizacion:
- demanda_id: ID de la demanda.
- proveedor_id: Proveedor que cotizo.
- descripcion_oferta: Lo que ofrece el proveedor.
- cantidad_ofertada: Cantidad que puede surtir.
- precio_unitario: Precio por unidad.
- monto_total: Total de la cotizacion.
- lead_time_value y lead_time_unit: Plazo de entrega (ej. 3, dias).
- requires_prepayment: Si el proveedor pide pago anticipado (true/false).
- supplier_doc_refs_json: Referencias a la cotizacion (ej. ["cotizacion_001.pdf"]).
El sistema registra la opcion en _opciones_abastecimiento en estado vigente.
Registrar todas las opciones disponibles antes de enviar a aprobacion.
Cuando las opciones estan listas, la demanda se transiciona a en_revision_direccion.

Paso 3: Seguimiento de Aprobacion

Despues de registrar opciones, la demanda aparece en vista_aprobaciones para que direccion decida:

Aprobada: Compras puede proceder. La opcion seleccionada se marca como seleccionada, las demas como descartada.
Feedback requerido: Direccion necesita mas informacion. Compras debe buscar datos adicionales y responder.
Rechazada: La demanda se cancela. Buscar alternativas o informar al taller.

El seguimiento se hace desde vista_compras observando el estado_demanda.

Paso 4: Coordinar Pago y Recepcion

Una vez aprobada la demanda:

Pago: Finanzas (Fer/Lorena) registra el pago en stg_pago_proveedor. Ver Pagos a Proveedor.
Recepcion: Almacen (Beto) registra la recepcion en stg_recepcion_abastecimiento. Ver Recepciones Pendientes.
Compras monitorea el progreso desde vista_compras.

Codigos de urgencia

Codigo	Significado	Accion esperada
`normal`	Sin urgencia inmediata	Cotizar con al menos 2 proveedores
`urgente`	Plazo corto o impacto operativo	Cotizar rapidamente, puede usar 1 solo proveedor
`paro_operativo`	Unidad detenida	Accion inmediata, puede saltarse cotizacion multiple con excepcion

Codigos de excepcion (exception_reason_code)

Codigo	Significado
`sin_factura`	El proveedor no emite factura
`pago_en_efectivo`	Pago en efectivo requerido
`liquidacion_inmediata`	Pago antes de entrega
`proveedor_alterno_urgente`	Proveedor no habitual por urgencia
`stock_no_confiable`	El inventario registrado no coincide con existencia real
`replenishment_sin_os`	Reposicion de stock no vinculada a OS
`compatibilidad_por_muestra`	Verificacion de compatibilidad requiere muestra fisica
`sobreprecio_autorizado`	Precio mayor al habitual, autorizado
`recepcion_con_discrepancia`	Material recibido difiere de lo pedido
`backorder_proveedor`	Proveedor confirma faltante que llegara despues

Flujo v1: Ordenes de Compra (legado)

Nota: El flujo v1 basado en stg_compra y _ordenes_compra sigue funcionando para OC creadas antes de la migracion a demandas. Para nuevas compras, usar el flujo v2 de demanda de abastecimiento documentado arriba.

Vista: Compras

La pestana vista_compras es una vista de solo lectura (Capa 3a) que muestra las ordenes de compra activas junto con indicadores de autorizacion y urgencia. Se actualiza automaticamente cada vez que se procesan cambios.

Columnas de la vista

Columna	Descripcion
Folio OC	Identificador unico de la orden de compra
Proveedor	Nombre del proveedor asociado
OS Vinculada	Folio de la orden de servicio vinculada (vacio para compras directas)
Estado	Estado actual de la OC (`pendiente`, `autorizada`, `en_transito`)
Fecha Solicitud	Fecha en que se creo la OC
Fecha Entrega	Fecha esperada de entrega del proveedor
Total	Monto total de la OC
Solicitado Por	Persona que solicito la compra
# Lineas	Numero total de lineas en la OC
Autorizacion	Semaforo de autorizacion (ver abajo)
Urgencia	Semaforo de urgencia (ver abajo)

Semaforo de autorizacion

El semaforo indica si la OC esta dentro del umbral de autorizacion del rol:

Color	Etiqueta	Significado
Verde	Dentro de umbral	El total de la OC esta dentro del limite de autorizacion del rol. Se puede proceder sin autorizacion adicional.
Amarillo	Cerca del limite	El total de la OC esta entre el umbral y el doble del umbral. Revisar si se puede dividir en OC menores.
Rojo	Excede umbral	El total de la OC excede el doble del umbral. Requiere autorizacion de direccion antes de proceder.

Semaforo de urgencia

El semaforo indica el estado de la fecha de entrega respecto al plazo critico:

Color	Etiqueta	Significado
Verde	En tiempo	Faltan mas de 3 dias para la fecha de entrega. Sin accion inmediata requerida.
Amarillo	Urgente	Faltan entre 1 y 3 dias para la fecha de entrega. Confirmar con proveedor que la entrega va en tiempo.
Rojo	Vencida	La fecha de entrega ya paso o es hoy. Priorizar seguimiento inmediato con el proveedor.

Importante: Las OC con semaforo de urgencia en rojo (Vencida) deben atenderse antes que cualquier otra tarea de compras.

Filtros

Solo aparecen OC en los siguientes estados:

pendiente — la OC fue creada y esta en espera de autorizacion
autorizada — la OC fue aprobada y esta lista para enviarse al proveedor
en_transito — la OC fue enviada al proveedor y se espera recepcion

Las OC en otros estados (recibida, cerrada) no aparecen en esta vista.

Ordenamiento

Las OC se muestran ordenadas por:

Urgencia — las OC con semaforo rojo (vencidas) aparecen primero.
Fecha de solicitud — de mas antigua a mas reciente, para priorizar las que llevan mas tiempo pendientes.

Como Crear una Orden de Compra

Las ordenes de compra se crean a traves de la pestana de captura stg_compra. Cada fila representa una linea de OC que se desea registrar.

Abrir la pestana stg_compra (o el formulario en AppSheet).
Llenar los campos:
- stg_id: Identificador unico de esta captura (se genera automaticamente en AppSheet).
- proveedor_id: Seleccionar el proveedor del catalogo (_proveedores).
- producto_id: Seleccionar el producto del catalogo (_productos).
- cantidad: Numero de unidades a comprar.
- precio_unitario: Precio por unidad. Se toma del catalogo. Si el precio real difiere, ver seccion de Excepciones.
- os_id: (Opcional) Seleccionar la OS vinculada. Dejar vacio para compras directas sin OS.
- fecha_entrega_esperada: (Opcional) Fecha en que se espera recibir el producto del proveedor.
- nota: (Opcional) Informacion adicional relevante para la compra.
El sistema procesa la fila automaticamente y la promueve a _ordenes_compra / _lineas_oc.
El subtotal se calcula como cantidad x precio_unitario.
Verificar en la vista que la OC aparece reflejada con el semaforo de autorizacion correspondiente.

Cuando Escalar

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

OC excede umbral de autorizacion

Si el semaforo de autorizacion esta en rojo (el total excede el doble del umbral del rol):

No proceder con la compra hasta obtener autorizacion de direccion.
Comunicar al director el monto y la justificacion de la compra.
Una vez autorizada, registrar la autorizacion en los campos de override.

Proveedor no existe en catalogo

Si el proveedor al que se desea comprar no aparece en el catalogo (_proveedores):

No intentar crear la OC sin proveedor_id.
Solicitar el alta del proveedor en _proveedores antes de crear la OC.
Una vez dado de alta, regresar a stg_compra y crear la OC con el nuevo proveedor_id.

Precio difiere mas del 20% del catalogo

Si el precio unitario real difiere mas del 20% del precio registrado en catalogo para ese producto:

Agregar la linea con el precio real (no el de catalogo).
Llenar los campos de override (ver seccion de Excepciones).
El motivo debe justificar la diferencia (ej. “Precio de proveedor alterno”, “Compra urgente con sobreprecio”).

Excepciones

Cuando una situacion requiere desviarse del flujo normal, se utilizan los campos de override en stg_compra:

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

OC excede umbral de autorizacion: Cuando el monto total requiere aprobacion de direccion.
Precio diferente al catalogo: Cuando el precio unitario ingresado no coincide con el precio del catalogo del producto (diferencia > 20%).
Compra urgente fuera de proveedor habitual: Cuando se compra a un proveedor que no es el habitual por razones de urgencia.

Codigos de motivo (override_reason_code)

Los codigos deben describir la situacion. Ejemplos comunes:

precio_proveedor_alterno — el precio difiere porque se compro a otro proveedor
compra_urgente — sobreprecio o proveedor no habitual por urgencia de entrega
descuento_volumen — se aplico descuento por volumen
autorizacion_direccion — monto excede umbral, autorizado por direccion

Reglas Importantes

Revisar la vista de compras. Solo aparecen OC en estado pendiente, autorizada o en_transito.
Las OC con semaforo de urgencia en rojo estan vencidas — priorizar seguimiento con proveedor.
Si el semaforo de urgencia esta en amarillo, la fecha de entrega esta dentro del plazo critico. Confirmar con proveedor.
Si el semaforo de autorizacion esta en rojo, la OC excede el doble del umbral y requiere autorizacion de direccion antes de proceder.
Si el semaforo de autorizacion esta en amarillo, la OC esta cerca del limite. Revisar si se puede dividir en OC menores.
Para crear una OC: llenar proveedor_id, producto_id, cantidad y precio_unitario en stg_compra. El campo os_id es opcional para compras directas.
Si el proveedor no aparece en catalogo, solicitar alta antes de crear la OC.
Si el precio unitario difiere mas del 20% del precio en catalogo, llenar los campos de override con el motivo.
Las compras urgentes fuera de proveedor habitual requieren nota justificando la excepcion.

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
”proveedor_id es obligatorio”	No se selecciono el proveedor	Verificar que el campo proveedor_id tenga un valor valido del catalogo
”Proveedor con id=X no encontrado”	El proveedor_id no existe en `_proveedores`	Verificar el ID correcto o solicitar alta del proveedor
”producto_id es obligatorio”	No se selecciono el producto	Verificar que el campo producto_id tenga un valor valido del catalogo
”Producto con id=X no encontrado”	El producto_id no existe en `_productos`	Verificar el ID correcto en el catalogo de productos
”cantidad debe ser > 0”	Cantidad cero o negativa	Ingresar una cantidad mayor a cero
”precio_unitario debe ser > 0”	Precio cero o negativo	Ingresar un precio mayor a cero
”OC excede umbral de autorizacion”	El total de la OC supera el limite permitido	Solicitar autorizacion de direccion y llenar campos de override
”Precio difiere > 20% del catalogo sin override”	El precio unitario difiere significativamente del catalogo y no se lleno override	Llenar override_reason_code y override_nota justificando la diferencia

Que hacer si una fila tiene error

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

Referencias

Especificacion tecnica: docs/views/int-4_compras.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

Procedimiento: Compras y Abastecimiento