TruckRoute — Sistema de ruteo logístico para Tres Reyes

1Control de Cambios

Registro de las modificaciones sobre la documentación y el alcance del proyecto. Cada validación con Roberto que derive en un cambio de requerimiento se anota como fila nueva.

2Diagnóstico: Árbol de Problemas y Soluciones

Diagnóstico original elaborado por el equipo a partir de la entrevista a Roberto García (Tres Reyes). A partir del problema central y sus causas se definieron las decisiones de diseño del sistema, y cada medio del árbol de soluciones dio origen a uno o más requerimientos funcionales (sección 5.1).

Problema central

Causas

Condiciones que producen el problema central. Cada una se relevó en la entrevista y se traduce después en un requerimiento concreto.

Efectos

Consecuencias que el problema central produce hoy en Tres Reyes. Sus valores actuales son la línea de base contra la que se mide el proyecto.

Árbol de soluciones

Cada medio del árbol de soluciones neutraliza una causa identificada más arriba, y se convierte después en uno o varios requerimientos del sistema.

Los fines son el espejo de los efectos: expresan a qué valor debería llegar cada uno con el sistema funcionando.

3Introducción

3.1. Propósito

El propósito del proyecto es reemplazar el método manual de planificación de repartos de Tres Reyes, que hoy se resuelve con Google Maps y coordinación por WhatsApp, por un sistema que calcule automáticamente la ruta óptima de cada camión, controle la carga por salida y le dé a Roberto García visibilidad real de la operación logística diaria.

TruckRoute busca resolver tres problemas medibles detectados en la entrevista (ver también el árbol de problemas, sección 2): el tiempo perdido armando rutas a mano, el combustible desperdiciado por rutas no optimizadas y las dobles pasadas por el mismo punto, y la falta de control de carga (kg) por camión y salida.

3.2. Alcance

El sistema incluye: importación y parseo automático de boletas en PDF, geocodificación de direcciones, agrupación de entregas por zona, cálculo de ruta óptima (Google Routes API con optimización del orden de paradas), generación de hoja de ruta digital, gestión del ciclo de vida del viaje (armar → confirmar → iniciar → finalizar), navegación GPS giro a giro para el repartidor, control de carga por camión, un panel de alertas y autenticación con roles diferenciados.

El sistema no incluye facturación ni gestión contable, gestión de stock o inventario, liquidación de sueldos, integración con sistemas de terceros ni soporte multiempresa en esta versión. El detalle completo está en las Limitaciones (dentro de 5.1) y se formaliza en el Contrato (sección 9).

3.3. Personal Involucrado

Roles del equipo de proyecto según el Gantt (6.1): PM/DUX (Varela), D01 (Traverso), D02 (Crupi), D03 (García), BD (Silva), más los encargados administrativos ADO01 (Gurschpon) y ADO02 (Rodríguez).

3.4. Definiciones, acrónimos y abreviaturas

3.5. Referencias

Formato APA 7ª edición.

• Pedaci, L. (2026). Evaluación de Proyectos - Módulo 01: El Proyecto y sus generalidades. Instituto Leonardo Murialdo.
• Pedaci, L. (2026). Evaluación de Proyectos - Módulo 02: Fases de un Proyecto. Instituto Leonardo Murialdo.
• Pedaci, L. (2026). Evaluación de Proyectos - Módulo de Documentación. Instituto Leonardo Murialdo.
• Universidad Tecnológica Nacional. (2012). Buenas Prácticas para Proyectos Informáticos. edUTecNe. ISBN 978-987-1896-01-1.
• Equipo N° 5. (2026). TruckRoute — MVP [Aplicación web]. tres-reyes-logistica.page.gd

3.6. Resumen Ejecutivo

TruckRoute es un sistema de software pensado para Tres Reyes — Aceitunas y Encurtidos (San Miguel, Buenos Aires): una empresa de distribución con más de 20 años en el rubro, 7 empleados y flota propia. El sistema reemplaza el método actual (Google Maps + WhatsApp) por un flujo digital: se cargan las boletas del día en PDF, el sistema geocodifica los destinos, agrupa por zona y calcula la ruta óptima para cada camión, respetando su capacidad de carga. El repartidor recibe la hoja de ruta y navega con GPS giro a giro; el administrador ve el estado de todos los viajes y recibe alertas de cierre.

Resultados esperados: eliminar las dobles pasadas por el mismo punto, reducir la distancia total recorrida en al menos un 15%, bajar el armado de rutas de un proceso manual a menos de 2 minutos automáticos, y que los repartidores dejen de depender de WhatsApp para coordinar su jornada.

4Descripción General

4.1. Perspectiva del producto

TruckRoute es un sistema nuevo: hoy Tres Reyes no tiene ningún sistema digital de ruteo, todo se resuelve con Google Maps y WhatsApp. No reemplaza un software existente ni es parte de un sistema mayor, aunque sí se apoya en infraestructura ya disponible: las PCs y celulares del equipo de Tres Reyes (Roberto usa iPhone, Tomás un dispositivo Android simple) y en las APIs de Google Cloud (Geocoding, Routes y Maps JavaScript).

4.2. Funcionalidad del producto

• Importar boletas en PDF y extraer automáticamente nombre, dirección y peso de cada una.
• Convertir cada dirección en coordenadas y agruparlas por zona geográfica.
• Calcular el orden óptimo de paradas para minimizar la distancia recorrida (Google Routes API), agrupando en una sola parada las boletas del mismo cliente con la misma dirección.
• Generar la hoja de ruta digital de cada camión, sin armarla a mano.
• Mostrar el recorrido en un mapa, con navegación GPS en tiempo real para el repartidor.
• Al iniciar el viaje, tomar la ubicación actual del repartidor como punto de partida y abrir Google Maps directamente con la hoja de ruta completa cargada en el orden ya optimizado, lista para navegar.
• Registrar los kilos asignados a cada camión por salida.
• Avisar cuando un viaje se cierra, con el detalle de zona y camión de los últimos 7 días.

4.3. Características de los Usuarios Buenas Prácticas UTN p.56/57

4.4. Restricciones Buenas Prácticas UTN p.57

4.4.1. Políticas reguladoras

El sistema se desarrolla mayormente con software libre y de código abierto: PHP, MySQL/MariaDB, Vanilla JS, PDF.js. La excepción es la capa de mapas, geocodificación y ruteo, migrada a las APIs de Google Cloud (Geocoding API, Routes API y Maps JavaScript API) en el sprint 5: son servicios pagos con cuota gratuita mensual, que requieren una cuenta de Google Cloud con facturación habilitada (aunque el uso se mantenga dentro de la cuota gratuita). El hosting actual (InfinityFree) es un plan gratuito. El repositorio de las presentaciones está publicado en GitHub Pages.

4.4.2. Limitaciones de infraestructura

El backend corre sobre hosting compartido gratuito (InfinityFree, base de datos en sql113.infinityfree.com), sin servidor propio. No hay hardware dedicado: el sistema depende de los dispositivos que Tres Reyes ya tiene (PC administrativa, celular del repartidor).

4.4.3. Interfaces con otras aplicaciones

El sistema se integra con la Google Geocoding API para geocodificar direcciones, con la Google Routes API para optimizar el orden de las paradas, y con la Google Maps JavaScript API para los mapas del sistema (Viajes pendientes, Tracking y mapa del repartidor). La navegación giro a giro se delega a la app de Google Maps. Usa la Geolocation API del navegador para obtener la posición GPS real. Reemplaza a WhatsApp como canal de coordinación (RF07, pendiente de sprint).

4.4.4. Función de control

Autenticación con email y contraseña (bcrypt) y roles diferenciados: administrador y repartidor. El repartidor no puede modificar rutas ni ver datos de otros camiones (RNF04).

4.4.5. Requisitos del lenguaje

Toda la interfaz está en español, con tipografía de al menos 18px por la dificultad visual de Roberto (RNF02), y un flujo de uso autoevidente pensado para un nivel tecnológico medio (RNF05: aprendizaje en menos de 20 minutos).

4.4.6. Protocolos señalados

Comunicación frontend–backend por HTTP/REST (JSON). Geocodificación y mapas vía las APIs de Google Cloud, ambos por HTTPS con API Key. CORS habilitado en el backend.

4.4.7. Requisitos de fiabilidad

El algoritmo de ruteo debe responder en menos de 5 segundos para hasta 50 destinos por salida (RNF01). El repartidor puede consultar su hoja de ruta sin conexión una vez descargada (RNF03, offline parcial).

4.4.8. Credibilidad de la aplicación

El panel muestra en tiempo real las boletas cargadas, el peso total y la cantidad de direcciones geolocalizadas apenas se sube el PDF del día. Así el administrador ve al instante si alguna boleta no se pudo leer o geolocalizar.

4.4.9. Consideraciones de seguridad

Las contraseñas se almacenan con bcrypt (password_hash), nunca en texto plano. Hay pendientes críticos identificados por el propio equipo (ver 4.6): mover la contraseña de la base de datos a un archivo .env, reemplazar el sessionStorage por JWT o sesión segura, auditar el 100% de las consultas SQL con bind_param, y forzar HTTPS antes de producción real.

La recuperación de contraseña está limitada a la cuenta de administrador: el enlace se envía por correo (SMTP propio, mailer.php + recuperar.php) a una casilla fija del admin, sin exponer un campo de email a los demás usuarios.

4.5. Suposiciones y dependencias

• Se asume que el consumo de las APIs de Google (Geocoding, Routes y Maps JavaScript) se mantiene dentro de la cuota gratuita mensual; si el volumen de boletas crece, esto pasa a ser un costo real a presupuestar (ver Oferta Económica, sección 7).
• El proyecto depende de que InfinityFree mantenga activo el hosting gratuito de backend y base de datos.
• Se asume que los repartidores cuentan con datos móviles para usar la navegación GPS en tiempo real.
• Roberto García mostró intención de seguir usando el sistema al ver el prototipo funcional (KR3 del Objetivo 5), lo que sostiene la viabilidad comercial del proyecto.

4.6. Evolución previsible del sistema

Próximos pasos del equipo, agrupados por urgencia.

Crítico, antes de producción:

• Mover la contraseña de la base de datos (DB_PASS) a un archivo .env, nunca en el código fuente.
• Reemplazar sessionStorage por autenticación JWT o sesión real con tokens HTTP-only.
• Auditar y preparar el 100% de las consultas SQL con bind_param.
• Forzar HTTPS en .htaccess antes de producción.

Importante, próximo sprint:

• RF07 — Notificación al repartidor (reemplazo de WhatsApp) por push o SMS.
• Caché de geocodificación, para no repetir direcciones ya resueltas.
• RF10 — Completar el reporte de eficiencia: comparar tiempo real vs. estimado y km reales recorridos (la pantalla Reportes ya muestra km estimados, combustible estimado y duración del viaje).

Mejoras para iteraciones futuras:

• App nativa (PWA o React Native) con soporte offline para el repartidor.
• Dashboard de OKRs con métricas automáticas de adopción y ahorro.

Objetivos y Resultados Clave (OKRs)

5Requisitos Específicos

5.1. Requerimientos funcionales Buenas Prácticas UTN p.59/60

Requerimientos no funcionales (RNF)

Limitaciones del alcance

Definen qué no hace el sistema en esta entrega. Se revisaron con Roberto antes de la firma del contrato (sección 9).

5.2. Interfaces de usuario Buenas Prácticas UTN p.58

El único punto de contacto de Roberto, Facundo y Tomás con el sistema es el dashboard web: una SPA en negro con acentos verdes, coherente con la identidad visual del sistema. Es responsive y usa fuente grande (mín. 18px, RNF02) por la dificultad visual de Roberto. El equipo pasó de la especificación de requerimientos a un MVP funcional en producción, y la interfaz se fue ajustando directamente sobre ese panel.

5.2.1. Mockup inicial (pre-MVP)

Antes de arrancar con la base de datos real, el equipo construyó una primera versión básica de la interfaz para validar el flujo conceptual con el cliente. Era una maqueta funcional muy simple, sin base de datos ni autenticación, solo para confirmar que el flujo boletas → rutas → zonas era entendible para Roberto. A partir de la validación del 20/05/2026, la interfaz se iteró directamente sobre el MVP en producción (sin Figma), llegando al panel actual documentado en 5.2 y en la Guía de Inicio Rápido.

5.3. Interfaz de hardware

No aplica. TruckRoute es un proyecto 100% software: no incluye sensores, placas ni dispositivos propios. Se apoya en hardware que Tres Reyes ya posee (PC de escritorio, celulares de Roberto y del repartidor), sin requerir instalación física alguna.

5.4. Interfaces de software Buenas Prácticas UTN p.59

5.5. Interfaces de comunicación Buenas Prácticas UTN p.59

5.6. Modelo Entidad-Relación de la base de datos

Modelo reconstruido a partir de las 8 tablas existentes en la base de datos (if0_42217493_base_datos, InfinityFree): usuarios, repartidores, camiones, boletas, viajes, posiciones, alertas_sistema y puntos_finalizacion.

Relaciones

Esquema relacional (MySQL / MariaDB)

Esquema alineado con el diagrama de arriba: tablas base más las columnas agregadas por las migraciones. Las tablas posiciones, alertas_sistema y puntos_finalizacion se transcriben tal cual de sus migraciones; en ellas las relaciones con viajes son lógicas (índices, sin restricción FK).

CREATE TABLE usuarios (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  nombre         VARCHAR(80)  NOT NULL,
  usuario        VARCHAR(50)  NOT NULL UNIQUE,
  email          VARCHAR(120),              -- se usa para el login
  password_hash  VARCHAR(255) NOT NULL,
  rol            ENUM('admin','repartidor') NOT NULL DEFAULT 'repartidor'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE camiones (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  patente        VARCHAR(10)  NOT NULL UNIQUE,
  capacidad_kg   DECIMAL(8,2) NOT NULL,
  marca          VARCHAR(50),
  modelo         VARCHAR(50),
  estado         ENUM('disponible','en_viaje','mantenimiento') NOT NULL DEFAULT 'disponible'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE repartidores (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  usuario_id     INT UNIQUE,
  camion_id      INT NULL,
  FOREIGN KEY (usuario_id) REFERENCES usuarios(id),
  FOREIGN KEY (camion_id)  REFERENCES camiones(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- migracion_destinos.sql
CREATE TABLE IF NOT EXISTS puntos_finalizacion (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  nombre         VARCHAR(100) NOT NULL,
  calle          VARCHAR(150) NOT NULL,
  altura         VARCHAR(20)  NOT NULL,
  localidad      VARCHAR(100) NOT NULL,
  provincia      VARCHAR(100) NOT NULL,
  cp             VARCHAR(15)  NULL,
  lat            DECIMAL(10,7) NULL,
  lon            DECIMAL(10,7) NULL,
  created_at     DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE viajes (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  camion_id      INT NULL,                  -- nullable desde migracion_zonas.sql
  repartidor_id  INT,
  destino_id     INT NULL,                  -- migracion_destinos.sql
  zona           VARCHAR(60),
  estado         VARCHAR(20) NOT NULL DEFAULT 'armado',  -- armado / confirmado / en_curso / finalizado
  fecha          DATE NOT NULL,
  peso_total     DECIMAL(8,2),
  orden_paradas  JSON,
  dia_salida     DATE,                      -- migracion_dia_hora.sql
  started_at     DATETIME,
  finished_at    DATETIME,
  FOREIGN KEY (camion_id)     REFERENCES camiones(id),
  FOREIGN KEY (repartidor_id) REFERENCES repartidores(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE boletas (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  viaje_id       INT NULL,
  cliente        VARCHAR(120),
  direccion      VARCHAR(160) NOT NULL,
  lat            DECIMAL(10,7),
  lon            DECIMAL(10,7),
  cp             VARCHAR(15),               -- migracion_cp.sql
  barrio         VARCHAR(80),
  zona           VARCHAR(60),               -- migracion_zonas.sql
  peso_kg        DECIMAL(8,2) NOT NULL,
  geo_aproximada TINYINT(1) DEFAULT 0,      -- migracion_geo_aproximada.sql
  estado         VARCHAR(20) NOT NULL DEFAULT 'pendiente',  -- pendiente / asignada / entregada / pospuesta
  fecha_carga    DATETIME DEFAULT CURRENT_TIMESTAMP,
  entregada_at   DATETIME,                  -- migracion_dia_hora.sql
  FOREIGN KEY (viaje_id) REFERENCES viajes(id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- migracion_tracking.sql (22/09/2026)
CREATE TABLE IF NOT EXISTS posiciones (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  viaje_id       INT NOT NULL,
  repartidor_id  INT NOT NULL,
  lat            DECIMAL(10,7) NOT NULL,
  lon            DECIMAL(10,7) NOT NULL,
  accuracy       FLOAT DEFAULT 0,
  timestamp      DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_viaje_id  (viaje_id),
  INDEX idx_timestamp (timestamp)
);

CREATE TABLE IF NOT EXISTS alertas_sistema (
  id             INT AUTO_INCREMENT PRIMARY KEY,
  tipo           VARCHAR(30)  NOT NULL,     -- desvio / finalizacion / sobrecarga / subutilizacion
  viaje_id       INT          NULL,
  repartidor_id  INT          NULL,
  mensaje        VARCHAR(500) NOT NULL,
  leida          TINYINT(1)   NOT NULL DEFAULT 0,
  timestamp      DATETIME     DEFAULT CURRENT_TIMESTAMP,
  INDEX idx_viaje_id  (viaje_id),
  INDEX idx_leida     (leida),
  INDEX idx_timestamp (timestamp)
);

5.7. Diagrama de flujo del proceso principal

Flujo de extremo a extremo del sistema: desde que Roberto carga las boletas del día hasta que el repartidor finaliza su turno y los datos quedan asentados.

6Oferta de Gestión

6.1. GANTT

Cronograma real de tareas, responsables y duración, organizado en 6 etapas. Inicio del proyecto: 01/04/2026 · Fin previsto: 17/10/2026 (148 días). Roles: PM/DUX (Varela), D01 (Traverso), D02 (Crupi), D03 (García), BD (Silva).

6.2. Equipo de proyecto Buenas Prácticas UTN p.62

Joaquín Varela

PM / Diseñador UX·UI

Gestión temporal y de alcance, relación con el cliente, diseño de interfaz.

Mateo Silva

Administrador de Base de Datos (BD)

Modelo de datos, migraciones y consultas SQL en MySQL/MariaDB.

Traverso

Desarrollador 01 — Backend

Servidor PHP, endpoints de la API e integración del servidor con las APIs de Google Cloud.

Crupi

Desarrollador 02 — Frontend/Backend

Módulos del panel, integraciones externas y optimización de rutas.

García

Desarrollador 03 — Frontend

Dashboard SPA, mapas interactivos con Google Maps y validación de interfaz con el usuario.

Gurschpon

Encargado Administrativo 01

Documentación técnica, control de cambios y entregables del proyecto.

Rodríguez

Encargado Administrativo 02

Gestión operativa y coordinación de entregas del equipo.

Herramientas de gestión

7Oferta Económica

La oferta económica toma como base la columna "Cantidad de trabajo en horas" del Gantt (6.1), que permite calcular las horas-hombre por rol una vez fijado el costo por hora. El stack propio (PHP, MySQL, Vanilla JS y PDF.js) es open-source, así que no hay costos de licencia, y el hosting en InfinityFree es gratuito. Los costos a considerar son las APIs de Google (Geocoding, Routes y Maps JavaScript), que hoy se usan dentro de la cuota gratuita mensual pero requieren facturación habilitada y pasan a tener costo si crece el volumen (ver 4.4.1), y un eventual servicio de SMS o push para RF07.

8Estimación Económica

Hoja de estimación de costos extraída directamente del Gantt del proyecto (6.1). Detalla rubros de horas-hombre por rol, herramientas y servicios externos.

9Contrato

Documento que explicita el acuerdo entre el equipo desarrollador y el cliente, Roberto García (Tres Reyes — Aceitunas y Encurtidos, San Miguel).

9.1. Objetivo del proyecto

Desarrollar y mantener TruckRoute, un sistema de ruteo logístico que calcula rutas óptimas, controla la carga por camión y hace seguimiento de los repartos de Tres Reyes, para eliminar el uso manual de Google Maps y WhatsApp.

9.2. Partes involucradas

Equipo desarrollador (integrantes y roles según 3.3) y cliente: Roberto García, dueño de Tres Reyes — Aceitunas y Encurtidos, San Miguel, Buenos Aires.

9.3. Alcance

Se entrega lo definido en 3.2 y 5 (RF01 a RF10, según prioridad). Queda fuera lo listado en las Limitaciones (5.1): facturación, stock, liquidación de sueldos, integración con terceros, CRM avanzado y soporte multiempresa.

9.4. Plazos

Fechas clave según el cronograma (6.1): inicio del proyecto el 01/04/2026; cierre de E01 y primera presentación el 04/05/2026; cierre de E02 y segunda presentación el 06/07/2026; cierre de E03 el 31/07/2026; tercera presentación el 25/09/2026; fin previsto del proyecto el 17/10/2026 (148 días).

9.5. Responsabilidades

El equipo: desarrollo, endurecimiento de seguridad, puesta en marcha y documentación. El cliente: validar requerimientos y prototipo, y proveer acceso a las boletas y a la operación diaria para las pruebas.

9.6. Criterios de aceptación

Se apoyan en los OKRs del proyecto (4.6): 0 rutas con doble pasada en los primeros 30 días, reducción de distancia recorrida ≥15%, armado de ruta automático en menos de 2 minutos, y que el repartidor complete su jornada usando solo la app.

9.7. Condiciones de modificación

Todo cambio de alcance solicitado durante el desarrollo se registra en el control de cambios (sección 1) y se evalúa su impacto en el GANTT antes de aceptarse.

9.8. Firmas

Firma del equipo desarrollador y de Roberto García (simbólica, en la validación del prototipo).

10Bitácora del Proyecto

Documento de trabajo del equipo. Registra la investigación de campo (entrevistas y minutas) y el seguimiento de la iteración (cambios sobre la interfaz y avances técnicos por etapa). Se actualiza a medida que avanza el proyecto.

10.1. Registro de Entrevistas

Instancias de relevamiento con el cliente y con los usuarios de Tres Reyes. Cada entrevista alimenta un apartado concreto de esta carpeta, por eso se registra el objetivo junto a la fecha.

10.2. Minutas de Reunión

Acta breve de cada reunión con el cliente o del equipo. Se completa una minuta por reunión, siempre con los mismos seis campos, para que cualquier participante pueda reconstruir qué se decidió y quién quedó a cargo de qué.

Plantilla de minuta

Minuta 01 · Validación del MVP con Roberto García

Minuta 02 · Tercera entrevista: devoluciones del cliente sobre el MVP con BD

10.3. Registro de Cambios del Mockup

A diferencia de un proyecto que parte de un mockup en Figma, el equipo diseñó la interfaz iterando directamente sobre el MVP ya en producción (ver 5.2). Por eso este apartado registra los cambios reales de interfaz que surgieron de cada validación con el usuario.

10.4. Bitácora de Avances Técnicos

Hitos técnicos cerrados, en orden cronológico, siguiendo las etapas del cronograma (6.1). Registrar la fecha real de cierre permite comparar el avance efectivo contra el GANTT planificado.