# Desembarques # control/grupo/listar - [index] (1,2) Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Retorna una lista paginada de **grupos de cargueros de desembarque**, filtrados por terminal, nombre y fecha. Cada grupo incluye sus placas asociadas y el nombre legible de la terminal. Realiza consultas en la base **empresarial**, transforma datos y enriquece la respuesta con nombres de terminales y placas de cargueros programados. --- # 🚀 **Endpoint**
`POST /cargueros-desembarque`
--- # 📥 **Request Body**
`{ "terminal": 3, "pagina": 1, "nombre": "TURNO A"}`
### Parámetros
CampoTipoObligatorioDescripción
terminalint✔️ SíID de la terminal.
paginaint✔️ SíNúmero de página (paginación de 15 registros).
nombrestring✖️ OpcionalFiltra por nombre del grupo (activa rango de fecha extendido).
--- # 🔐 **Seguridad** Requiere token o autenticación definida en middleware general (no se valida dentro del método). --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. Validaciones iniciales - Si no envían `terminal` → error obligatorio. - Se toma `pagina` para paginar. - Se define `limit = 15`. - Fecha mínima: - Por defecto: **ayer** - Si se envía `nombre`: se amplía rango **–10 días a +10 días** y se agrega filtro LIKE al nombre. ### 2. Construcción del filtro para la consulta Filtros aplicados: - terminal = enviado - status = 1 - fecha\_creacion > fechaDesde - si existe nombre → LIKE %nombre% y fecha\_creacion < fechaHasta ### 3. Consulta de grupos de desembarque Tabla: `emp_grupo_cargueros_desembarque` Campos retornados: - id - grupo (array JSON de cap\_id) - nombre - terminal - cerrar\_grupo - fecha\_creacion - placas = null (placeholder) Si no hay resultados → “No se encontraron grupos”. ### 4. Obtención del catálogo de terminales Consulta `emp_terminal` y crea un arreglo tipo diccionario:
`[ ter_id => ter_nombre ]`
### 5. Enriquecimiento de la data Para cada grupo: 1. Decodifica `grupo` (lista de cap\_id). 2. Consulta placas desde: - **emp\_cargprogramado (cap)** - **emp\_carguero\_new (carg)** Campos: - placa1 - codigo1 - placa2 3. Construye lista de placas: `"placa1 codigo1"` 4. Reemplaza el id de terminal por su nombre real. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "lista de grupos", "data": [ { "id": 15, "grupo": [123, 124], "nombre": "TURNO A", "terminal": "Terminal Callao", "cerrar": 0, "fecha": "2025-01-26 10:21:00", "placas": [ "B1234 C001", "B2288 C002" ] } ]}`
--- # ❗ **Posibles Errores** ### 1. Terminal obligatorio
`{ "success": false, "message": "Es obligatorio enviar una terminal"}`
### 2. Sin resultados
`{ "success": false, "message": "No se encontraron grupos"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "grupo": "json array of cap_id", "nombre": "string", "terminal": "number", "cerrar_grupo": "number", "fecha_creacion": "datetime"}`
### **emp\_cargprogramado + emp\_carguero\_new**
`{ "placa1": "string", "codigo1": "string", "placa2": "string"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string", "ter_abrebiatura": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !terminal -> errorfechaDesde = yesterdayif nombre: fechaDesde = -10 days fechaHasta = +10 days add filter nombre LIKE %nombre% add filter fecha_creacion < fechaHastaadd filter fecha_creacion > fechaDesdegrupos = SELECT from emp_grupo_cargueros_desembarque where filters, paginatedif empty -> errorterminales = SELECT all terminalesmap[ter_id] = ter_nombrefor each grupo: ids = decode(grupo.grupo) cargueros = SELECT placas info using ids grupo.placas = format placas grupo.terminal = terminales[grupo.terminal]return grupos`
# control/grupo/obtener - [show] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Este servicio obtiene la **información detallada de un grupo de cargueros de desembarque**, incluyendo: - Datos del grupo - Terminal asociada - Cargueros programados (placas/códigos) - Información estructurada lista para visualizar en pantalla El servicio consulta varias tablas del sistema empresarial para reconstruir toda la información relacionada al grupo. --- # 🚀 **Endpoint**
`POST /grupo-desembarque/show`
--- # 📥 **Request Body**
`{ "grp_id": 123}`
### Parámetros
CampoTipoObligatorioDescripción
grp\_idintegerSíID del grupo a consultar.
--- # 🔐 **Seguridad** Requiere autenticación estándar del sistema (middleware). La función no implementa validación de permisos directamente. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. **Validación del parámetro** - Si no se envía `grp_id`, retorna error. --- ### 2. **Obtiene información del grupo** Consulta:
`SELECT id, grupo, nombre, terminal, cerrar_grupo AS cerrar, fecha_creacion AS fecha, null AS placasFROM emp_grupo_cargueros_desembarqueWHERE id = `
- Si no se encuentra → error *"No se encontró el grupo"*. --- ### 3. **Reemplaza el ID de terminal por su nombre** Consulta:
`SELECT ter_id, ter_nombre, ter_abrebiaturaFROM emp_terminalWHERE ter_id = <grupo.terminal>`
Actualiza: `grupo.terminal = ` --- ### 4. **Convierte el campo grupo a JSON** `grupo.grupo` es un JSON que contiene una lista de `cap_id`. Ejemplo:
`[12, 15, 19]`
--- ### 5. **Obtiene información de cargueros programados** Consulta:
`SELECT cap.cap_cargueroid AS placa1, carg.car_codigo AS codigo1, cap.cap_carguero_id2 AS placa2FROM emp_cargprogramado capLEFT JOIN emp_carguero_new carg ON cap.cap_cargid = carg.idWHERE cap.cap_id IN () AND cap.eliminado = 0`
Luego construye una lista tipo: `["PLACA001 COD001", "PLACA002 COD009", ...]` Asignado a: `grupo.placas = [...]` --- ### 6. **Respuesta final** Retorna toda la estructura ensamblada. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Informacion de grupo", "data": { "id": 12, "grupo": [125, 126], "nombre": "GRUPO 1", "terminal": "Terminal Norte", "cerrar": 0, "fecha": "2025-01-10 10:20:00", "placas": [ "ABC123 COD001", "XYZ998 COD077" ] }}`
--- # ❗ **Posibles Errores** ### 1. Falta de parámetro obligatorio
`{ "success": false, "message": "Es obligatorio enviar grp_id"}`
### 2. Grupo no encontrado
`{ "success": false, "message": "No se encontró el grupo"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "grupo": "json-array", "nombre": "string", "terminal": "number", "cerrar": "number", "fecha": "datetime", "placas": "array"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string", "ter_abrebiatura": "string"}`
### **emp\_cargprogramado + emp\_carguero\_new**
`{ "placa1": "string", "codigo1": "string", "placa2": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> errorgrupo = SELECT ... FROM emp_grupo_cargueros_desembarque WHERE id=grp_idif !grupo -> errorterminal = SELECT ... FROM emp_terminal WHERE ter_id=grupo.terminalgrupo.terminal = terminal.nombreterminales = JSON decode(grupo.grupo)grupo.grupo = terminalesif terminales not empty: cargueros = SELECT cargueros programados WHERE cap_id IN terminales grupo.placas = ["placa1 codigo1", ...]return grupo`
# control/carguero/grupo - [listarPorGrupo] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Este servicio recibe un **ID de grupo de cargueros (`grp_id`)** y retorna la **lista de cargueros asociados al grupo**, incluyendo información enriquecida: - Datos del carguero (placas, choferes, ruta, origen/destino) - Estado de QR generado - Datos de desembarque (paquetes desembarcados y guías desembarcadas) - Escalas generadas dinámicamente según origen y destino El servicio consulta varias tablas del sistema Empresarial y CentOS y consolida la información en una sola respuesta. --- # 🚀 **Endpoint**
`POST /listar-por-grupo`
--- # 📥 **Request Body**
`{ "grp_id": "number"}`
### Parámetros
CampoTipoObligatorioDescripción
grp\_idnumberSíID del grupo registrado en la tabla `emp_grupo_cargueros_desembarque`.
--- # 🔐 **Seguridad** Protegido generalmente por autenticación de la API (token/middleware definido). El método no valida credenciales directamente. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación de entrada** - Verifica que `grp_id` exista; si no, retorna error. - Busca el grupo en `emp_grupo_cargueros_desembarque`. - Verifica que el grupo tenga cargueros registrados. 2. **Obtiene cargueros asociados** Consulta `emp_cargprogramado` para los `cap_id` del grupo:
`SELECT fecha, cap_id, chofer1, chofer2, ruta, origen, destino, placa1, placa2, cerradoFROM emp_cargprogramadoWHERE eliminado = 0 AND cap_id IN ()ORDER BY fecha DESC`
3. **Obtiene catálogo de terminales** - Lista nombres y abreviaturas de todas las terminales. - Se usa para convertir IDs de terminal en texto legible. 4. **Procesamiento por cada carguero** Para cada `cap_id`: - Decodifica JSON de `origen` y `destino`. - Traduce IDs a abreviaturas de terminal:
`ORIGEN → "LIM - CHI - ARE"DESTINO → "ARE - JUL"`
- Verifica si tiene QR generado (consulta en CentOS). - Obtiene información de desembarque por guía: - Paquetes desembarcados - Total de paquetes - Estado de guía (DESEMBARCADA, SIN GUIA, FALTA DESEMBARCAR GUIA) - Calcula: - Total de paquetes desembarcados - Total de guías desembarcadas - Construye lista de **escalas** combinando origen + destino. 5. **Devuelve lista final de cargueros procesados** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de cargueros", "data": [ { "fecha": "2025-01-10 08:00:00", "cap_id": 98765, "chofer1": 1122, "chofer2": 3344, "ruta": "RUTA-01", "origen": "LIM - ARE", "destino": "ARE - JUL", "placa1": "ABC-123", "placa2": "XYZ-789", "cerrado": 0, "qr_generado": true, "escalas": [ "1 Terminal Lima", "2 Terminal Arequipa", "3 Terminal Juliaca" ], "paquetes": 150, "guias": 12 } ]}`
--- # ❗ **Posibles Errores** ### 1. No se envió `grp_id`
`{ "success": false, "message": "Envie grp_id"}`
### 2. Grupo no existe
`{ "success": false, "message": "No se encontró grupo"}`
### 3. Grupo sin cargueros
`{ "success": false, "message": "Agregue cargueros al grupo"}`
### 4. No hay cargueros coincidentes
`{ "success": false, "message": "Agregue cargueros al grupo"}`
--- # 📚 **Schemas (estructuras utilizadas)** ### **emp\_grupo\_cargueros\_desembarque**
`{ "id": number, "grupo": "string (JSON array)"}`
### **emp\_cargprogramado**
`{ "cap_id": number, "cap_fhsalidaprogramada": datetime, "cap_chofer1id": number, "cap_chofer2id": number|null, "cap_rutacarguero": string, "cap_origen": "JSON array", "cap_destino": "JSON array", "cap_cargueroid": string, "cap_carguero_id2": string|null, "cap_cerrado": number}`
### **emp\_terminal**
`{ "ter_id": number, "ter_nombre": string, "ter_abrebiatura": string}`
### **emp\_desembarque\_historial + emp\_ordenservicio**
`{ "des_ose_id": number, "desembarcados": "comma separated string", "total": number, "estadoguia": "FALTA DESEMBARCAR GUIA | SIN GUIA | GUIA DESEMBARCADA"}`
--- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> errorgrupo = SELECT grupo WHERE id=grp_idif !grupo -> errorcap_ids = json_decode(grupo.grupo)if empty -> errorcargueros = SELECT cargueros WHERE cap_id IN cap_idsif empty -> errorterminales = SELECT ter_id, ter_nombre, abreviaturafor each carguero: origen_ids = json_decode(carguero.origen) destino_ids = json_decode(carguero.destino) traducir ids a abreviaturas verificar QR generado consultar historial de desembarque calcular paquetes desembarcados y guías desembarcadas generar escalas a partir de origen + destinoreturn cargueros procesados`
# control/grupo/guardar - [store] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Crea un nuevo registro en **emp\_grupo\_cargueros\_desembarque**, que representa un grupo de cargueros/desembarque asociado a un terminal. Si el usuario no envía un nombre, el sistema genera uno automáticamente usando el nombre del terminal y la fecha de creación. --- # 🚀 **Endpoint**
`POST /grupo-cargueros-desembarque`
--- # 📥 **Request Body**
`{ "nombre": "string (opcional)", "terminal": "number (requerido)", "usuario": "string (opcional)"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
terminalnumberSíID del terminal donde se creará el grupo.
nombrestringNoNombre personalizado del grupo. Si no se envía, el sistema genera uno.
usuariostringNoUsuario que realiza la operación (no se usa dentro de la función).
--- # 🔐 **Seguridad** El método no define validación propia, pero depende del middleware o autenticación general de la API. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Obtiene los parámetros**: nombre, terminal, usuario, fecha actual. 2. **Valida que terminal sea numérico**. Si no lo es → retorna:
`{ "success": false, "message": "Debe enviar el terminal" }`
3. **Busca datos del terminal** en `emp_terminal`:
`SELECT ter_id, ter_nombre AS nombreFROM emp_terminalWHERE ter_id = {terminal}`
4. **Genera nombre automáticamente** si no se envía: → ` ` 5. **Inserta un nuevo grupo** en `emp_grupo_cargueros_desembarque`:
`INSERT INTO emp_grupo_cargueros_desembarque(nombre, terminal, fecha_creacion)VALUES (...)`
6. **Retorna ID generado** mediante `insertGetId`. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Grupo creado correctamente", "data": 58}`
*(donde `58` es el ID del nuevo grupo)* --- # ❗ **Posibles Errores** ### 1. Terminal no válido
`{ "success": false, "message": "Debe enviar el terminal"}`
*(No existen más validaciones dentro del método.)* --- # 📚 **Schemas (estructuras usadas)** ### **emp\_terminal**
`{ "ter_id": "number", "nombre": "string"}`
### **emp\_grupo\_cargueros\_desembarque**
`{ "id": "number", "nombre": "string", "terminal": "number", "fecha_creacion": "datetime"}`
--- # 🗃 **Lógica en pseudo-código**
`nombre = request.nombreterminal = request.terminalusuario = request.usuariofecha = now()if terminal is not numeric: return errorterminal_data = SELECT nombre FROM emp_terminal WHERE ter_id = terminalif nombre is empty: nombre = terminal_data.nombre + " " + fechagrupo_new = INSERT INTO emp_grupo_cargueros_desembarque (nombre, terminal, fecha_creacion)return success with grupo_new id`
# control/grupo/carguero/agregar - [agregarCarguero] Path: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/GrupoController.php ## 🧾 **Descripción** Agrega un **carguero (cap\_id)** a un **grupo de cargueros de desembarque (grp\_id)**. El servicio valida que: - Exista el grupo. - El grupo tenga su lista de cargueros almacenados en formato JSON. - El carguero no esté ya incluido en el grupo. - Luego actualiza la tabla agregando el carguero al listado. Este servicio modifica directamente la tabla: **emp\_grupo\_cargueros\_desembarque** --- # 🚀 **Endpoint**
`POST /agregar-carguero`
--- # 📥 **Request Body**
`{ "grp_id": "number", "cap_id": "number"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
grp\_idnumberSíID del grupo de cargueros de desembarque.
cap\_idnumberSíID del carguero a agregar.
--- # 🔐 **Seguridad** Protegido por autenticación del sistema (middleware). El servicio no valida permisos dentro de la función. --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación inicial de parámetros** - Si falta `grp_id` → retorna error. - Si falta `cap_id` → retorna error. 2. **Obtiene información del grupo**
`SELECT grupoFROM emp_grupo_cargueros_desembarqueWHERE id = grp_id`
- Si no existe → error “Grupo no encontrado”. 3. **Decodifica el campo `grupo`** - Si el campo `grupo` tiene JSON → se convierte en array. - Si está vacío → se crea array vacío. 4. **Verifica si el carguero ya está en el grupo** - Si `cap_id` ya existe → error “El carguero ya se encuentra en el grupo”. 5. **Agrega el nuevo carguero al grupo** - Inserta `cap_id` dentro del array. - Convierte el array nuevamente a JSON. 6. **Actualiza la BD**
`UPDATE emp_grupo_cargueros_desembarqueSET grupo = json_encode(arreglo_actualizado)WHERE id = grp_id`
7. **Retorna éxito**
`"Carguero agregado al grupo"`
--- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Carguero agregado al grupo"}`
--- # ❗ **Posibles Errores** ### 1. Falta `grp_id`
`{ "success": false, "message": "Falta cap_id"}`
*(El mensaje es incorrecto en el código, pero lo dejamos tal cual está implementado.)* --- ### 2. Falta `cap_id`
`{ "success": false, "message": "Falta cap_id"}`
--- ### 3. Grupo no existe
`{ "success": false, "message": "Grupo no encontrado"}`
--- ### 4. Carguero repetido
`{ "success": false, "message": "El carguero ya se encuentra en el grupo"}`
--- # 📚 **Schemas (estructuras usadas)** ### Tabla: `emp_grupo_cargueros_desembarque`
`{ "id": "number", "grupo": "string(JSON array of cap_id)"}`
Ejemplo del campo `grupo`: `["123", "245", "300"]` --- # 🗃 **Lógica en pseudo-código**
`if !grp_id -> error("Falta cap_id")if !cap_id -> error("Falta cap_id")grupo = SELECT grupo FROM tabla WHERE id = grp_idif !grupo -> error("Grupo no encontrado")grupos = decode(grupo.grupo) OR []if cap_id in grupos: error("El carguero ya se encuentra en el grupo")grupos.append(cap_id)UPDATE tabla SET grupo = encode(grupos) WHERE id = grp_idsuccess("Carguero agregado al grupo")`
# control/carguero/obtener - [show] PATH: /var/www/html/qaservicesapp/app/Http/Controllers/ShalomControl/CargueroController.php ## 🧾 **Descripción** Este servicio devuelve **toda la información detallada** de un carguero programado (`cap_id`), incluyendo: - Datos generales del carguero (choferes, placas, ruta, fechas). - Orígenes y destinos estructurados con su nombre de terminal. - Escalas calculadas (orígenes + destinos). - Cantidad de órdenes de servicio asociadas al carguero. - Suma de los montos finales de dichas OS. Lee información combinada de `emp_cargprogramado`, `emp_terminal` y `emp_ordenservicio`. --- # 🚀 **Endpoint**
`POST /carguero/show`
--- # 📥 **Request Body**
`{ "cap_id": "number", "terminal": "string (opcional)", "usuario": "string (opcional)"}`
### Parámetros requeridos
CampoTipoObligatorioDescripción
cap\_idnumberSíID del carguero programado.
usuariostringNoUsuario que ejecuta el proceso.
terminalstringNoTerminal de operación.
--- # 🔐 **Seguridad** Requiere sesión o token según la configuración del middleware (no validado en la función). --- # 🧠 **Flujo del Servicio (resumen real)** 1. **Validación inicial** - Si no se envía `cap_id`, retorna error. 2. **Obtiene datos del carguero**
`SELECT fecha, cap_id, chofer1, chofer2, ruta, placa1, placa2, cerrado, origen, destinoFROM emp_cargprogramadoWHERE cap_id = :cap_id`
3. **Obtiene datos de terminales**
`SELECT ter_id, ter_nombre FROM emp_terminal`
Construye un diccionario:
`listaTerminal[id] = nombre`
4. **Procesa orígenes y destinos** - Decodifica JSON almacenado en BD. - Convierte cada id de terminal a:
`"<id> <nombre>"`
5. **Calcula escalas**
`escalas = origenes ∪ destinos`
6. **Busca órdenes de servicio asociadas al carguero**
`SELECT ose_montofinal, ose_idFROM emp_ordenservicioWHERE ose_ultimo_carprog_embarque = :cap_idORDER BY ose_ultima_fecha_embarque DESC`
7. **Calcula:** - `cantidad` = total de OS encontradas - `suma` = sumatoria de `ose_montofinal` 8. **Retorna el carguero con estructura final.** --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de cargueros", "data": { "fecha": "2025-01-21 14:00:00", "cap_id": 441, "chofer1": "CH00123", "chofer2": "CH00452", "ruta": "NORTE 01", "placa1": "ABC-123", "placa2": "XYZ-987", "cerrado": 0, "cantidad": 12, "suma": 1560.50, "escalas": [ "01 LIMA", "05 CHIMBOTE", "07 TRUJILLO" ], "origenes": [ "01 LIMA", "05 CHIMBOTE" ], "destinos": [ "07 TRUJILLO" ] }}`
--- # ❗ **Posibles Errores** ### 1. cap\_id no enviado
`{ "success": false, "message": "Es obligatorio enviar un id"}`
### 2. No se encuentra carguero (si cap\_id no existe) *(Laravel devolverá null y puede lanzar errores posteriores, según tu implementación)* Puedes documentarlo así:
`{ "success": false, "message": "Carguero no encontrado"}`
*(**Sugerencia:** en tu función no validas esto, pero debería considerarse.)* --- # 📚 **Schemas (estructuras usadas)** ### **emp\_cargprogramado**
`{ "cap_id": "number", "cap_fhsalidaprogramada": "datetime", "cap_chofer1id": "string", "cap_chofer2id": "string", "cap_rutacarguero": "string", "cap_cargueroid": "string", "cap_carguero_id2": "string", "cap_origen": "json[]", "cap_destino": "json[]", "cap_cerrado": "number"}`
### **emp\_terminal**
`{ "ter_id": "number", "ter_nombre": "string"}`
### **emp\_ordenservicio**
`{ "ose_id": "number", "ose_montofinal": "float", "ose_ultimo_carprog_embarque": "number", "ose_ultima_fecha_embarque": "datetime"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cap_id -> errorcarguero = SELECT carguero WHERE cap_idterminales = SELECT id, nombre FROM terminalmapaTerminal = map(id => nombre)carguero.origenes = decodeJSON(carguero.origen)carguero.destinos = decodeJSON(carguero.destino)escalas = unique(origenes + destinos)convertir ids a " " usando mapaTerminalordenes = SELECT OS WHERE os.ose_ultimo_carprog_embarque = cap_idcarguero.cantidad = count(ordenes)carguero.suma = sum(ordenes.montofinal)return carguero`
# query/validar_crear_ruta - [funct_validar_crear_ruta_module] Path: /var/www/html/moradex-qa/app/Models/GeneralesApp.php ## 🧾 **Descripción** Servicio que valida si un usuario o un terminal tienen permiso para acceder a un módulo específico. Actualmente, debido a un `return` colocado antes de la validación, **el servicio siempre devuelve acceso permitido**, pero la lógica diseñada incluye listas de usuarios y terminales autorizados. --- # 🚀 **Endpoint**
`POST /validar-crear-ruta-module`
--- # 📥 **Request Body**
`{ "username": "string", "terminalId": "string"}`
### Parámetros
CampoTipoObligatorioDescripción
usernamestringSíDNI o identificador del usuario.
terminalIdstringSíID del terminal desde el cual accede.
--- # 🔐 **Seguridad** Sin validación interna adicional. Generalmente depende del middleware aplicado al endpoint. --- # 🧠 **Flujo del Servicio (resumen real)** > **IMPORTANTE:** El servicio retorna inmediatamente acceso permitido debido al primer `return`. ### Flujo implementado (real): 1. Obtiene: - `username` (usuario) - `terminalId` (terminal) 2. Retorna:
`{ valor: true, msn: "Puede acceder al modulo" }`
Esto interrumpe el método, haciendo que la lógica posterior nunca se ejecute. --- ### Flujo diseñado (pero actualmente inactivo por el return anticipado) 1. Verificar si el usuario está en la lista de usuarios permitidos:
`if (in_array($user, $usuarios_permitidas)) acceso permitido`
2. Verificar si el terminal está en la lista de terminales permitidas:
`if (in_array($terminal, $terminales_permitidas)) acceso permitido`
3. Si no coincide con ninguna lista → acceso denegado (pero el código está incompleto y termina con `retur`). --- # 📤 **Response – Ejemplo (actual)** ### ✔️ Acceso permitido (siempre)
`{ "valor": true, "msn": "Puede acceder al modulo"}`
--- # ❗ **Posibles Errores (según la lógica esperada)** > *Actualmente NO se producen porque la función retorna antes de validar.* ### 1. Usuario NO autorizado
`{ "valor": false, "msn": "Usuario no autorizado"}`
### 2. Terminal NO autorizada
`{ "valor": false, "msn": "Terminal no autorizada"}`
### 3. Petición incompleta
`{ "valor": false, "msn": "Datos insuficientes (username o terminalId faltantes)"}`
--- # 📚 **Schemas (estructuras usadas)** ### Request
`{ "username": "string", "terminalId": "string"}`
### Response
`{ "valor": "boolean", "msn": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`user = POST.usernameterminal = POST.terminalIdreturn { valor: true, msn: "Puede acceder al modulo" } // retorna siempreusuarios_permitidos = [...]terminales_permitidas = [...]if user in usuarios_permitidos: return acceso permitidoif terminal in terminales_permitidas: return acceso permitidoreturn acceso denegado`
# control/desembarque/pendientes - [pendientes] ## 🧾 **Descripción** Este servicio retorna la lista de **órdenes de servicio (OSE)** que **aún tienen paquetes pendientes por desembarcar** en una unidad específica (`cap_id`). Combina información de embarques, desembarques, órdenes de servicio, detalles de OS, atributos, terminales y datos de personas. Permite aplicar **filtro por número de guía** y soporta **paginación**. Es un servicio crítico para la vista de **desembarques pendientes**. --- # 🚀 **Endpoint**
`POST /pendientes`
--- # 📥 **Request Body**
`{ "cap_id": "number", "pagina": "number", "guia": "string (opcional)"}`
### Parámetros
CampoTipoObligatorioDescripción
cap\_idnumber✔ SíID de la unidad de carga programada.
paginanumber✔ SíNúmero de página a listar.
guiastring✘ NoFiltra por número de guía del cliente.
--- # 🔐 **Seguridad** Requiere autenticación estándar usada en los endpoints del backend (middleware Laravel). No se valida explícitamente dentro del método. --- # 🧠 **Flujo del Servicio (resumen real)** ### 1. Validación inicial - `cap_id` es obligatorio. - Define paginación con `limit = 15`. --- ### 2. Obtener embarques asociados al `cap_id` Consulta tabla `emp_embarque_historial`: - Se filtra por: - estado activo (`status = 1`) - paquete habilitado (`emb_estado_paquete = 1`) - carg\_id igual al cap\_id Si no hay embarques: **“Aún no se ha embarcado nada en esta unidad.”** Se arma: - Lista de OSE (`ose_ids`) - Información del embarque por OSE: - estado de guía - cantidad de paquetes embarcados - cantidad total de paquetes --- ### 3. Obtener desembarques del mismo `cap_id` Consulta tabla `emp_desembarque_historial` similares filtros: Se arma: - Lista de desembarques por OSE: - estado de guía - paquetes desembarcados - total de paquetes --- ### 4. Obtener órdenes de servicio relacionadas Consulta:
`SELECT (varios campos)FROM emp_ordenservicioWHERE ose_id IN (ose_ids)AND (opcional) ose_nroguiacliente = guiaOFFSET (pagina - 1) * 15LIMIT 15`
Si no encuentra OS → **“No ha embarcado nada aun”** --- ### 5. Obtener terminales (origen y destino) Convierte IDs a: - nombre - alias (para construir la ruta) --- ### 6. Obtener detalle de OS Consulta `emp_os_detalle`: Agrupa por: - OSE - Tipo Construye por OSE: - contenido: `"cantidad tipo"` - cantidad total sumada --- ### 7. Obtener atributos de tipo de pago Convierte `tipo_pago` → abreviatura usando tabla `emp_atributos`. --- ### 8. Integrar datos (núcleo del servicio) Por cada OS: - Si existe desembarque: - Calcula paquetes pendientes = total – desembarcados - Marca guía como `"GUIA EMBARCADA"` o `"SIN GUIA"` - Si no existe desembarque: - Paquetes pendientes = total del detalle - Si cantidad pendiente es `0` → se omite del resultado final. - Se construye: - contenido - cantidad total - cantidad pendiente - ruta origen → destino - nombre de terminales Si después de filtrar no hay OS pendientes: → **“No hay desembarques pendientes”** --- ### 9. Obtener nombres de remitentes Consulta `emp_persona` usando los DNIs encontrados: Reemplaza el DNI por nombre completo. --- ### ✔ 10. Respuesta Final Devuelve toda la data procesada. --- # 📤 **Response 200 – Ejemplo**
`{ "success": true, "message": "Lista de ordenes", "data": [ { "ose_id": 202525, "fecha": "2025-02-15 10:30:00", "monto": 45.50, "guia": "GUIA-882233", "remitente": "Carlos Gómez", "destinatario": "Empresa ABC", "tipo_pago": "CR", "origen": "LIMA", "destino": "AREQUIPA", "ruta": "LIM - AQP", "cap_id": 33112, "contenido": "10 CAJA, 2 SOBRE", "cant_paq": 5, "cant_total": 12, "desembarque_guia": "SIN GUIA", "usuario": "jperez" } ]}`
--- # ❗ **Posibles Errores** ### 1. No envía `cap_id`
`{ "success": false, "message": "Es obligatorio enviar un cap_id"}`
### 2. No hay embarques
`{ "success": false, "message": "Aun nó se ha embarcado nada en esta unidad."}`
### 3. No hay órdenes
`{ "success": false, "message": "No ha embarcado nada aun"}`
### 4. No hay desembarques pendientes
`{ "success": false, "message": "No hay desembarques pendientes"}`
--- # 📚 **Schemas (estructuras usadas)** ### **emp\_embarque\_historial**
`{ "emb_ose_id": "number", "emb_estado_guia": "string", "emb_cant_paquetes_embarcados": "string", "emb_cant_paquetes_total": "number"}`
### **emp\_desembarque\_historial**
`{ "des_ose_id": "number", "des_estado_guia": "string", "des_cant_paquetes_desembarcados": "string", "des_cant_paquetes_total": "number"}`
### **emp\_ordenservicio** Campos usados:
`{ "ose_id": "number", "ose_fhpreferenciapartida": "datetime", "ose_nroguiacliente": "string", "ose_remiteempresa": "string", "ose_destinaempresa": "string", "ose_servpagotipo": "string", "ose_termorigenatencion": "number", "ose_termdestinoentrega": "number", "ose_estadoPago": "number"}`
### **emp\_os\_detalle**
`{ "osd_osid": "number", "osd_tipopreciomanual": "string", "cantidad": "number"}`
### **emp\_atributos**
`{ "valor": "string", "abreviatura": "string"}`
### **emp\_persona**
`{ "documento": "string", "nombre": "string"}`
--- # 🗃 **Lógica en pseudo-código**
`if !cap_id -> errorembarques = SELECT embarques WHERE cap_id = inputif empty -> errordesembarques = SELECT desembarques WHERE cap_id = inputose_ids = embarques.ose_idordenes = SELECT OS WHERE ose_id in ose_ids FILTER guia IF EXISTS PAGINACIONif empty -> errordetalles = SELECT SUM(cantidad), tipo FROM emp_os_detalle WHERE ose_id in ose_ids GROUP BY ose_id,tipoatributos = SELECT mapa tipo_pago -> abreviaturaterminales = SELECT terminal_id -> nombre, aliasbuild lista: para cada OS: calcular paquetes pendientes si 0 → excluir traducir tipo_pago generar ruta origen/destino agregar contenido y totalesif lista vacía -> “No hay desembarques pendientes”buscar nombres remitente en emp_personareturn lista final`