REPORTE SOLICITUD DE MATERIALES

Fuente:  /var/www/html/qareportes/app/Http/Controllers/Cloud/RecursosHumanosController.php

1) Nombre del reporte

• Nombre: Reporte de Solicitud de Materiales

• Código / Alias: report_solicitud_materiales

• Responsable:  Equipo de Reportes Cloud

• Propósito (1 línea):

2) Alcance temporal

• Campo(s) de fecha utilizados:

• fecha_inicio

• fecha_fin

• Tipo de rango (diario / mensual / personalizado): Mensual

• Inclusión de horas (sí/no). Si sí: [00:00:00 – 23:59:59]

• Zona horaria: La del servidor

3) Origen de datos (tablas/APIs)

• Conexión / Base: ERP CAPACITACION

• Tabla / Recurso: tabMaterial Request

• Alias (si aplica): mtr

• Campos utilizados (clave → descripción):

• material_request_type →Tipo de Proposito

• propósito_de_transferencia → Tipo de Propósito de Transferencia

• fecha_y_hora_de_transferencia →  Fecha y hora de transferencia

• status → Estado de Transferencia 

• fecha_y_hora_de_transaccion_erp → Fecha de la Transacción

• confirmar_transferencia → Confirmación de transferencia 

• numero_orden → Número de Guia asociada 

• aprobador_por_ → Usuario que aprobó la transferencia 

• aprobado_nombre_completo → Nombre completo del usuario que aprobó la transferencia

• aprobacion_de_solicitud → Tipo de Aprobación

• cancelado_por → Usuario que cancelo la solicitud

• cancelado_nombre_completo → Nombre completo del usuario que cancelo la solicitud

• detalle_cancelacion→  Detalle de la cancelación 

• id_sucursal → ID de la terminal que envía el producto (Origen)

• zona_nacional → Zona nacional a la que pertenece la terminal de Origen

• sucursal → Nombre de la terminal Origen

• division → Indica si la terminal Origen pertenece a Lima o Provincia 

• departamento → Departamento(Area) de shalom

• per_ordered → Indica un porcentaje

• ultima_actualizacion_el → Fecha y hora en que se actualizó el registro por última vez

• ultima_actualizacion_por →Usuario que actualizó el registro por última vez

• owner→ Usuario que creó el registro

• creation → Fecha de Creacion del registro

• item_code → Código del producto

• item_name → Nombre del producto

• stock_uom → Unidad de medida utilizada en el almacén

• qty → Cantidad 

• puesto → Puesto del Empleado

• sexo → Sexo del Empleado

• nombre_completo_empleado →Nombre completo Empleado

• stock_qty → Cantidad existente

• actual_qty → Cantidad actual

• no_guia as estado_de_orden → Estado de la Guia

• Condiciones (WHERE) aplicadas:

• Filtra el registro, si la fecha de creación están entre los parámetros  $fecha_inicio y $fecha_fin
  
  

• Tipo de unión con otras fuentes (JOIN y llave): Une la tabla tabMaterial Request y tabMaterial Request Item
  
  

• Observaciones (ej. particiones, índices): no se encontraron el valor exacto de actual_qty, stock_qty y per_ordered

4) Filtros globales del reporte

• Inclusiones (must-have): 

• Depende de lo que reciba dateUnlimited y el rango de fecha (first_day y last_day)

• Exclusiones (reglas de descarte): 

• Si numero_orden es null, se descarta del reporte

• Si la API de estados devuelve un error o está vacía, el flujo corta y retorna vacío o la data sin procesar.

• Reglas por estado / habilitado: 

• mtr.status: Permite clasificar los registros en función de su estado.

• obtain_estados: Sí retorna la api de NEWWEBSERVICES validado, se sobrescribe, si no queda vacío.

• Parámetros externos (si el usuario puede filtrarlo): Sí, el usuario puede incluir la fecha inicio y fecha fin en el rango de búsqueda.

5) Transformaciones y Reglas de negocio

• Derivaciones de campos (cómo se calculan):

• usuario_creatransferencia se deriva de $userTransfers y $userGroups:Si existe el usuario dueño de la transferencia, se asigna su full_name, si no, queda vacío.

•  estado_de_orden Se deriva a partir de la consulta externa a otro servicio (buscar-estados-guia).

• Mapeos de estado:

• mtr.status as estado Se mapea directamente desde la tabla tabMaterial Request.

• estado_de_orden Se mapea desde el servicio externo (buscar-estados-guia)

• En la función baseReport, si la tabla es nueva se agrega un índice sobre status, reforzando que este campo es clave para consultas.

• Reglas de validación (p.ej., sólo registros validados):

• Si no se ingresa un rango de fecha se retorna el siguiente mensaje: "Los campos fecha inicio y fecha fin son obligatorios"

• Si la tabla destino no se creo correctamente se inserta un registro en error_reports

• Reglas condicionales (si X entonces Y):

• Si no hay numero_orden, se salta ese registro

• Si $dateUnlimited == "TODOS", "12", "8" o cualquier otro valor → se construyen los rangos de fechas de forma distinta:

• "TODOS" → desde el 2021 hasta el año actual.

• "12" → desde un pivote hasta la fecha actual mes a mes.

• "8" → últimos 8 meses.

• Otro → mes actual y, en caso de enero/febrero, incluye diciembre del año anterior.

• Si la tabla es nueva, se aplica ALTER TABLE para agregar índice sobre status.

• Si ocurre algún error en la transacción se elimina la inserción de la tabla y se retorna un mensaje.

6) Estructura de salida

• Tabla/archivo destino: report_solicitud_materiales

• Particionado / sufijo: report_solicitud_materiales_YYYY_MM

• Clave(s) primaria(s) o únicas: name de la tabla “tabMaterial Request”

• Columnas del reporte (nombre → tipo → descripción):

• id → INT AUTO_INCREMENT → Identificador único de la fila (PK interna)

• name → VARCHAR(50) → ID del documento Material Request en ERPNext

• material_request_type → VARCHAR(100) → Tipo de solicitud de material

• propósito_de_transferencia → VARCHAR(255) → Propósito de la transferencia

• fecha_y_hora_de_transferencia → VARCHAR(100) → Fecha/hora de la transferencia

• estado → VARCHAR(50) → Estado de la solicitud (ej. Draft, Submitted, Cancelled)

• fecha_y_hora_de_transaccion_erp → VARCHAR(100) → Fecha/hora de creación en ERP

• confirmar_transferencia → VARCHAR(50) → Indicador de confirmación

• numero_orden → VARCHAR(100) → Número de orden asociado

• aprobador_por_ → VARCHAR(100) → Usuario que aprobó

• aprobado_nombre_completo → VARCHAR(255) → Nombre completo del aprobador

• aprobacion_de_solicitud → VARCHAR(50) → Estado de la aprobación

• cancelado_por → VARCHAR(100) → Usuario que canceló

• cancelado_nombre_completo → VARCHAR(255) → Nombre completo del que canceló

• detalle_cancelacion → VARCHAR(500) → Motivo o detalle de cancelación

• id_sucursal → VARCHAR(20) → Código de la sucursal

• zona_nacional → VARCHAR(50) → Zona geográfica

• sucursal → VARCHAR(50) → Nombre de sucursal

• division → VARCHAR(50) → División interna

• departamento → VARCHAR(50) → Departamento

• per_ordered → INT → Cantidad pedida

• owner → VARCHAR(100) → Usuario creador del documento

• creation → VARCHAR(255) → Fecha de creación del documento

• item_code → VARCHAR(100) → Código del ítem

• item_name → VARCHAR(100) → Nombre del ítem

• stock_uom → VARCHAR(100) → Unidad de medida

• cantidad → INT → Cantidad solicitada

• puesto → VARCHAR(100) → Puesto del empleado asociado

• sexo → VARCHAR(50) → Sexo del empleado

• nombre_completo_empleado → VARCHAR(255) → Nombre completo del empleado

• stock_qty → INT → Cantidad en stock

• actual_qty → INT → Cantidad actual en almacén

• ultima_actualizacion_el → VARCHAR(255) → Fecha de última actualización

• ultima_actualizacion_por → VARCHAR(255) → Usuario que realizó la última actualización

• estado_de_orden → VARCHAR(255) → Estado de la orden (devuelto de API externa `buscar-estados-guia`)

• usuario_creatransferencia → VARCHAR(255) → Nombre completo del usuario que creó la transferencia

• created_date → DATETIME → Fecha de inserción en el datawarehouse

• status → tinyint(4) → Estado de la carga (1 = OK, 0 = error)

• Ordenamiento por defecto: No se especifica

7) Frecuencia y operación

• Frecuencia de actualización: Probablemente mensual( Por Cron)

• Ventana que recalcula (días/meses):  Calcula en un rango de 8 meses consecutivos tomando el 1mer y ultimo dia de cada mes.

• Tamaño de lote / paginado (chunking): Los inserts se hacen en lotes de 900 registros máximo.

• Tolerancia a fallos / reintentos: try catch para la inserción de datos.

• Tiempos de ejecución esperados: Dependerá de la cantidad de datos.

8) Calidad y controles

• Validaciones previas/post: 

• Previas:

• Se valida que $fecha_inicio y $fecha_fin existan, de lo contrario retorna un mensaje de error

• Se controla la existencia de la tabla con verifyExistTable() antes de insertar los datos

• Se encapsula la inserción de datos en transacciones con beginTransaction(), commit(), rollBack()

• Post:

• Si hay error en la consulta HTTP ($guzzle->request), se atrapa con catch (\Exception $e) y se retorna un mensaje claro.

• En caso de error de base de datos (catch (\PDOException $e)), se registra en la tabla emp_reportes_validation y se hace rollBack() para no dejar datos inconsistentes

• Controles de duplicados: Indirecta

• Creación de Tablas por sufijo

• Se usa CREATE TABLE {$db_name} LIKE report_nota_entrega; → las tablas nuevas se generan limpias
  
  

• Métricas de completitud (qué se monitorea):

• error_reports → cuando falla la creación de tablas.

• emp_reportes_validation → cuando ocurre un error de inserción en la carga de datos.

• Cada registro de ejecución guarda report, first_date, second_date, created_date, y status, lo cual permite monitorear

9) Dependencias externas

ERPNext – CAPACITACION

• APIs / servicios y endpoints: method/send-query-database

• Autenticación / headers: Se envían headers básicos: 

• $options = [

•    'headers' => [

•        "Accept" => "application/json",

•        "Content-Type" => "application/json"

•    ]

• ];

• No aparece un Authorization: Bearer <token> ni otra forma de autenticación explícita.
  
  

• Mapeos y contratos de datos:

• Entrada: filtros por fecha_ini, fecha_fin.

• Transformación: mapeo SQL → PHP arrays.

• Persistencia: creación de tablas dinámicas en MySQL con tipos definidos.

• Salida: array estructurado con campos enriquecidos (usuario_creatransferencia, estado_de_orden).

10) Historial de cambios

2025-09-22 13:58 - Elian Franco Arroyo Rodas - Documentación inicial