Proposito

Esta intervencion permite a la administradora definir costos de mano de obra (MO), facturar ordenes de servicio y registrar cobros. Las tres acciones se ejecutan desde una sola pestana de captura (stg_cierre_os), usando el campo accion para seleccionar la operacion deseada.

El objetivo es que cada OS avance desde trabajo terminado hasta cobrada o en credito, asegurando que los montos de factura y cobro queden registrados en las tablas canonicas.

Vista: Facturacion

La pestana vista_facturacion es una vista de solo lectura (Capa 3a) que muestra las OS que estan pendientes de facturacion, junto con los totales de refacciones y mano de obra. Se actualiza automaticamente cada vez que se procesan cambios.

Columnas de la vista

Columna	Descripcion
Folio OS	Identificador unico de la orden de servicio
Cliente	Nombre del cliente asociado
Placas	Placas de la unidad
Estado	Estado actual de la OS
Fecha Ingreso	Fecha en que ingreso la unidad
Mecanico	Mecanico asignado
Tipo Servicio	Tipo de servicio de la OS
Total Refacciones	Suma de subtotales de lineas tipo refaccion y consumible
Total MO	Suma de subtotales de lineas tipo mano de obra
Total OS	Suma de todos los subtotales de la OS
Facturabilidad	Semaforo que indica si la OS esta lista para facturar (ver abajo)

Semaforo de facturabilidad

El semaforo indica si la OS tiene los componentes necesarios para ser facturada:

Color	Etiqueta	Significado
Verde	Lista para facturar	La OS tiene mano de obra definida y refacciones/consumibles cargados (o es un servicio de solo MO). Puede facturarse directamente.
Amarillo	Faltan refacciones	La OS tiene mano de obra pero no tiene refacciones ni consumibles, y el tipo de servicio no es de solo MO. Verificar con el capturista.
Rojo	Falta MO	La OS no tiene mano de obra definida. Usar la accion `definir_mo` antes de facturar.

Importante: Solo las OS con semaforo en verde (Lista para facturar) pueden facturarse sin override. Si el semaforo no esta en verde y se necesita facturar, se deben llenar los campos de override (ver seccion de Excepciones).

Filtros

Solo aparecen OS en los siguientes estados:

trabajo_terminado — el mecanico termino, pendiente de definir MO
refacciones_cargadas — tiene refacciones pero falta definir MO
mo_definida — tiene MO definida, pendiente de facturar
facturable — lista para facturar

Las OS en otros estados (registrada, en_proceso, facturada, cobrada, etc.) no aparecen en esta vista.

Ordenamiento

Las OS se muestran ordenadas por fecha de ingreso de mas antigua a mas reciente, para priorizar las que llevan mas tiempo en el taller.

Como Operar

Las tres acciones se ejecutan a traves de la pestana de captura stg_cierre_os. Cada fila representa una operacion sobre una OS. El campo accion determina que operacion se realiza y que campos son obligatorios.

Definir Mano de Obra

Abrir la pestana stg_cierre_os (o el formulario en AppSheet).
Llenar los campos:
- stg_id: Identificador unico de esta captura (se genera automaticamente en AppSheet).
- os_id: Seleccionar la OS por su ID (consultable en la vista).
- accion: Seleccionar definir_mo.
- descripcion_mo: Descripcion del trabajo realizado (ej. “Diagnostico electrico”, “Afinacion mayor”).
- horas_mo: Numero de horas de trabajo.
- precio_hora: Precio por hora de mano de obra.
El sistema crea una linea en _lineas_os con tipo_linea=mano_obra y transiciona la OS a estado mo_definida.
Verificar en la vista que el semaforo cambie a verde (si ya tiene refacciones) o a amarillo (si faltan refacciones).

Nota: Esta accion solo es valida para OS en estado trabajo_terminado o refacciones_cargadas.

Facturar OS

Abrir la pestana stg_cierre_os.
Verificar en la vista que el semaforo de facturabilidad este en verde.
Llenar los campos:
- os_id: Seleccionar la OS.
- accion: Seleccionar facturar.
- numero_factura: Numero de la factura emitida.
- monto_factura: Monto total de la factura.
- fecha_factura: Fecha de emision de la factura.
El sistema registra los datos de factura en _ordenes_servicio y transiciona la OS a estado facturada.

Gate: Si el semaforo no esta en verde, el sistema rechaza la operacion. Para proceder de todas formas, llenar los campos de override (ver seccion de Excepciones).

Nota: Esta accion solo es valida para OS en estado mo_definida o facturable.

Registrar Cobro

Abrir la pestana stg_cierre_os.
Llenar los campos:
- os_id: Seleccionar la OS.
- accion: Seleccionar registrar_cobro.
- monto_cobro: Monto cobrado.
- fecha_cobro: Fecha del cobro.
- tipo_cobro: Seleccionar contado o credito.
El sistema registra el cobro y transiciona la OS:
- Si tipo_cobro=contado -> estado cobrada.
- Si tipo_cobro=credito -> estado en_credito.

Nota: Esta accion solo es valida para OS en estado facturada.

Cuando Escalar

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

Facturacion sin semaforo verde

Si se necesita facturar una OS cuyo semaforo no esta en verde (falta MO o refacciones):

Verificar si realmente es correcto facturar en ese estado.
Si es correcto (ej. servicio especial que no requiere refacciones), llenar los campos de override con el motivo.
Si no es correcto, coordinar con el capturista (INT-2) para completar la carga.

Monto de cobro difiere del monto de factura

Si el monto cobrado no coincide con el monto facturado:

No registrar el cobro directamente.
Escalar al supervisor antes de proceder.
Documentar la diferencia y el motivo.

Asignacion de credito

Cuando se registra un cobro con tipo_cobro=credito:

Registrar la justificacion en los campos de override.
La OS queda en estado en_credito y aparecera en la vista de cobranza para seguimiento.
Consultar la vista de cobranza (vista_cobranza) para dar seguimiento a facturas en credito.

Excepciones

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

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

Facturacion sin semaforo verde: Cuando se factura una OS que no tiene el semaforo de facturabilidad en verde (falta MO o refacciones).
Monto de factura ajustado: Cuando el monto de factura difiere del total calculado de la OS.

Codigos de motivo (override_reason_code)

Los codigos deben describir la situacion. Ejemplos comunes:

solo_mo_no_catalogado — servicio de solo MO cuyo tipo de servicio no tiene la bandera solo_mo
refacciones_pendientes — se factura antes de que el capturista termine la carga
ajuste_monto — el monto de factura difiere del total calculado por acuerdo con cliente
autorizacion_gerencia — excepcion autorizada por gerencia

Reglas Importantes

Revisar la vista de facturacion. Solo aparecen OS en estado trabajo_terminado, refacciones_cargadas, mo_definida o facturable.
Si el semaforo de facturabilidad esta en rojo, primero definir mano de obra usando la accion definir_mo.
Si el semaforo esta en amarillo, verificar si la OS requiere refacciones. Si es un servicio de solo MO, el semaforo debe estar en verde.
Para facturar: seleccionar accion facturar, ingresar numero de factura, monto y fecha. Solo procede si el semaforo esta en verde o se llena override.
Para registrar cobro: seleccionar accion registrar_cobro, ingresar monto, fecha y tipo de cobro (contado o credito).
Si el monto de cobro no coincide con el monto de factura, escalar al supervisor antes de proceder.
Revisar la vista de cobranza para dar seguimiento a facturas pendientes. Las que tienen mas de 30 dias aparecen en rojo.

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
”accion es obligatoria”	No se selecciono la accion	Seleccionar una de las tres acciones: `definir_mo`, `facturar`, `registrar_cobro`
”OS en estado X no acepta accion Y”	La OS esta en un estado que no permite la accion solicitada	Verificar el estado actual de la OS y la accion valida para ese estado
”horas_mo debe ser > 0”	Horas de MO cero o negativas	Ingresar un valor mayor a cero
”precio_hora debe ser > 0”	Precio por hora cero o negativo	Ingresar un valor mayor a cero
”numero_factura es obligatorio”	Se intento facturar sin numero de factura	Ingresar el numero de factura
”monto_factura debe ser > 0”	Monto de factura cero o negativo	Ingresar el monto correcto
”facturabilidad no es verde”	Se intento facturar sin semaforo verde y sin override	Definir MO o cargar refacciones, o bien llenar los campos de override
”tipo_cobro debe ser contado o credito”	Tipo de cobro invalido	Seleccionar `contado` o `credito`

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-3_facturacion.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

Procedimiento: Facturacion y Cobranza