Reportes

Los reportes son el registro del trabajador de campo del trabajo completado. Cuando un trabajador termina una instalación, reparación o inspección, envía un reporte capturando qué se hizo, qué materiales se usaron, dónde se realizó el trabajo y cualquier foto o nota. Enviar un reporte crea automáticamente transacciones de consumo de inventario y alimenta los cálculos de pago — no se requiere papeleo adicional.

Estructura de Reporte

Página de reportes mostrando registros de ejecución de campo con consumo y estado

Campos Principales:

• Nombre - Título de reporte o resumen
• Descripción - Notas detalladas, observaciones, problemas encontrados
• Reportado Por - Usuario que envió el reporte
• Fecha de Reporte - Cuándo se realizó el trabajo
• Orden de trabajo - Enlace opcional a la asignación padre
• Geometría - Ubicación donde se realizó el trabajo (punto, línea, o polígono)

Documentación de Trabajo:

• Trabajo Completado - Array de recursos consumidos y tareas terminadas
• Consumido De - Qué artículos de stock fueron agotados (genera transacciones)

Medios:

• Fotos - Imágenes antes/después, problemas encontrados
• Adjuntos - Documentos, diagramas, certificaciones

Estructura de Trabajo Completado

Cada entrada en la lista de Trabajo Completado documenta un tipo de trabajo realizado:

Ejemplo: Un trabajador reporta la instalación de 45 m de Cable Cat6, 8 Cajas de Conexión y 3,5 horas de trabajo de electricista, todo contra la misma tarea.

Reportes Ad-Hoc (Sin Tarea Formal)

El campo Tarea en cada entrada de trabajo completado es opcional — esto soporta trabajo no planificado:

Casos de Uso:

• Reparaciones de emergencia (equipo roto, accidentes)
• Llamadas de servicio al cliente (visitas a sitio no planificadas)
• Mantenimiento descubierto durante otro trabajo
• Trabajo exploratorio (encuestas, evaluaciones)

Ejemplo:

Reporte: "Reparación de fibra de emergencia - daño por tormenta"
Trabajo Completado: [
  { resource: "Cable de Fibra", volume: 20, uom: "metros" }
  // Sin tarea vinculada - este fue trabajo de emergencia no planificado
]
Consumido De: [
  { stockItemId: truck_fiber_id, resource: "Cable de Fibra", volume: 20, uom: "metros" }
]

El sistema aún crea transacciones de consumo, rastrea costos de materiales, calcula el pago — incluso sin asignación formal de tarea.

Consumido De (Transacciones Automáticas)

La lista Consumido De genera la deducción automática de inventario cuando se envía el reporte:

Flujo de Trabajo:

1. El trabajador envía el reporte con entradas Consumido De
2. El sistema valida la disponibilidad de stock en cada artículo de stock
3. Las transacciones de consumo se crean automáticamente
4. Las transacciones se vinculan a este reporte
5. Los balances de los artículos de stock se reducen
6. Si stock insuficiente → reporte rechazado o trabajador solicitado para parcial

Ejemplo:

Consumido De: [
  { stockItemId: johns_truck_cable, resource: "Cable Cat6", volume: 45, uom: "metros" },
  { stockItemId: johns_truck_boxes, resource: "Cajas de Conexión", volume: 8, uom: "unidades" }
]

Resultado:
  - 2 transacciones de consumo creadas
  - Inventario del camión de Juan reducido en 45 m de cable y 8 cajas
  - Transacciones vinculadas a este reporte
  - El cálculo de pago tiene datos de consumo confiables

Beneficios:

• Stock siempre preciso (no se puede reportar trabajo sin registrar consumo)
• Registro de auditoría de transacciones automático
• Previene "consumo fantasma" (reporte sin cambio de stock)
• Pago basado en materiales reales usados

Validación de Reporte

Cuando el reporte es enviado, el sistema valida:

Disponibilidad de Stock:

• Se verifica cada entrada consumido-de
• Si un artículo de stock tiene volumen insuficiente → opciones:
  1. Rechazar el reporte completo (mensaje de error)
  2. Solicitar consumo parcial (reducir el volumen reportado)
  3. Permitir balance negativo (con advertencia - requiere transacción de ajuste después)

Coincidencia Trabajo-Consumo:

• Advertencia si los totales de consumo no se alinean con los volúmenes de trabajo completado
• Ejemplo: Se reportaron 50 m de trabajo con cable, pero solo 30 m consumidos del stock
• No bloquea el envío (el trabajador podría haber usado materiales personales)
• Marca para revisión de validación

Validación de Geometría:

• Los puntos deben tener coordenadas válidas
• Las líneas deben tener al menos 2 puntos
• Los polígonos deben cerrar (primer punto = último punto)
• La ubicación del trabajo debe estar dentro de una distancia razonable de la geometría de la tarea (configurable)

Creando Reportes

Acceso Requerido: derecho admin reportsCreate (o permiso de auto-reporte)

Flujo de Trabajo:

1. Navegar a Cumplimiento → Reportes
2. Hacer clic en "Agregar Reporte"
3. Llenar la información básica (nombre, descripción, fecha)
4. Vincular a la asignación (opcional - necesario para seguimiento de progreso)
5. Agregar entradas de trabajo completado:
   • Seleccionar recurso
   • Ingresar volumen completado
   • Vincular a tarea (opcional)
6. Agregar entradas consumido de:
   • Seleccionar artículo de stock (usualmente el sitio personal del trabajador)
   • Seleccionar recurso
   • Ingresar volumen consumido
7. Establecer geometría (dónde se realizó el trabajo)
8. Subir fotos/adjuntos
9. Enviar → transacciones creadas automáticamente

Reporte Rápido desde Orden de Trabajo: Formulario pre-completado desde la vista de detalle de la asignación:

• Orden de trabajo, asignado a, tareas disponibles auto-completadas
• Consumo sugerido basado en objetivos de recursos
• El trabajador ajusta los valores reales y envía

Creación de Reporte Móvil: Interfaz móvil simplificada:

• Integración de cámara para fotos
• Auto-captura GPS para geometría
• Voz a texto para descripciones
• Campos requeridos mínimos

Contribución de Progreso de Reporte

Los reportes actualizan el progreso de tareas y asignaciones:

Progreso de Tarea:

• Sumar todo el trabajo completado para esta tarea (de todos los reportes)
• Dividir por los requisitos de recursos de la tarea
• Máximo del 100% por recurso

Progreso de Orden de Trabajo:

• Sumar todo el trabajo completado para esta asignación (de todos los reportes)
• Dividir por los objetivos de recursos de la asignación
• Máximo del 100% por recurso
• Calcular el promedio a través de todos los objetivos

Sobre-Entrega: El trabajador puede reportar más de lo asignado:

• Contribuye al progreso de la tarea (ayuda a completar la tarea más rápido)
• El progreso de la orden de trabajo está limitado al 100% (el trabajador superó los objetivos)
• La validación revisa la sobre-entrega (verificar precisión)

Vista de Detalle de Reporte

Información Mostrada:

• Detalles básicos (nombre, descripción, fecha, reportado por)
• Enlace de orden de trabajo (si aplica)
• Lista de trabajo completado con referencias de tarea
• Lista consumido de con enlaces de artículo de stock
• Transacciones de consumo (auto-creadas)
• Fotos y adjuntos
• Geometría en mapa
• Resultados de validación (si se realizó QC)

Acciones Disponibles:

• Editar reporte (antes de la validación)
• Subir fotos adicionales
• Agregar comentarios/notas
• Solicitar validación
• Ver transacciones de consumo
• Imprimir reporte (exportar PDF)

Cálculo de Pago

Los reportes impulsan los flujos de trabajo de pago:

Pago de Labor:

Trabajo Completado:
  - Electricista: 3,5 horas
  
Pago = 3,5 horas × tarifa por hora

Costos de Materiales:

Consumido De:
  - Cable Cat6: 45 m × $2/m = $90
  - Cajas de Conexión: 8 unidades × $15/unidad = $120
  
Costo Total de Materiales = $210

Costo Total del Trabajo:

Labor + Materiales = Pago al trabajador + Costo de materiales = Total

El registro de auditoría de transacciones proporciona costos de materiales confiables (no se puede inflar el consumo - atado al agotamiento real de stock).

Insignias de Validación en la Lista de Reportes

Las validaciones ahora se muestran directamente en la página de reportes como insignias de semáforo — ya no es necesario navegar a una página separada /fulfillment/validations para verlas o crearlas. Cada fila de reporte tiene:

• Una insignia de validación agregada en su propia columna, que muestra el estado más grave con un conteo (p. ej. FAILED · 3). Pasa el cursor para ver el desglose por estado.
• Una fila de insignias agrupadas por estado dentro del reporte expandido, con una insignia por validación.

Al hacer clic en cualquier insignia se abre el ValidationEditModal — un overlay completo para ver, editar o crear una validación sin salir del reporte. El botón Enviar en el modal confirma las ediciones del reporte y la validación juntas de forma atómica.

Consulta Validaciones para el recorrido completo.

Filtrado de Reportes

Filtros Pre-Construidos:

• Reportado por mí - Tus reportes enviados
• Necesita validación - Reportes sin ninguna validación (insignia gris)
• Reciente - Últimos 7 días

Filtro de Estado de Validación: La lista de reportes acepta un filtro de estado de validación con estas opciones:

• all - todos los reportes (por defecto)
• none - reportes sin ninguna validación
• any - reportes con al menos una validación
• failed - reportes con al menos una validación fallida
• revision - reportes con al menos una validación needs-revision
• passed - reportes donde todas las validaciones aprueban

Filtros Personalizados:

• Rango de fecha
• Reportado por usuario específico
• Asignación
• Referencia de tarea

Mejores Prácticas

Reporte de Consumo Preciso:

• Reportar materiales reales usados (no estimados)
• Usar artículos de stock de tu sitio personal (demuestra que tenías los materiales)
• Documentar sobre-consumo (explicar por qué se necesitaron más materiales)

Envío Oportuno:

• Enviar reportes el mismo día en que se realizó el trabajo
• GPS y marcas de tiempo proporcionan responsabilidad
• Memoria fresca = detalles más precisos

Documentación Fotográfica:

• Fotos antes (condición del sitio)
• Fotos durante (trabajo en progreso)
• Fotos después (instalación completada)
• Fotos de problemas (daños, obstáculos, condiciones no estándar)

Descripciones Detalladas:

• Notar cualquier desviación de los requisitos de la tarea
• Documentar razones para sobre/bajo-consumo
• Registrar problemas para referencia futura (puertas bloqueadas, permisos faltantes, clima)

Vincular a Tareas Cuando Sea Posible:

• Ayuda a rastrear el progreso de la tarea
• Habilita el análisis espacial (dónde se concentra el trabajo)
• Mejora la estimación futura de tareas

Responder a los Hallazgos de Validación:

• Revisar los resultados de validación con prontitud
• Proporcionar aclaraciones si se cuestionan
• Corregir errores en reportes futuros
• Aprender de la retroalimentación de calidad

Inmutabilidad de Reportes

Soft Deletes: Los reportes pueden marcarse como eliminados pero permanecen en la base de datos:

• Preserva el historial de transacciones (las transacciones de consumo permanecen)
• Mantiene el registro de auditoría de pagos
• Período de retención configurable (configuraciones de la app)
• Derecho admin viewDeleted para ver reportes eliminados

Restricciones de Edición: Después de la validación realizada:

• Los reportes se vuelven de solo lectura
• Las correcciones requieren un nuevo reporte con notas
• Preserva la integridad del QC
• El historial de versiones rastrea todos los cambios antes de la validación

Registro de Auditoría:

• Cada edición de reporte registrada (quién, cuándo, qué cambió)
• Las transacciones de consumo nunca se editan (inmutables)
• Los cálculos de pago son trazables a los datos del reporte original