1. Introducción al Diseño

Este documento describe el diseño técnico completo del sistema RutaCC, incluyendo la arquitectura general, los componentes principales, el modelo de datos, las APIs y las consideraciones de seguridad y despliegue.

El sistema ha sido diseñado siguiendo los principios de:

• Modularidad: Cada funcionalidad está encapsulada en módulos independientes
• Escalabilidad: Arquitectura preparada para crecer en usuarios y tenants
• Seguridad por diseño: Controles de seguridad integrados en cada capa
• Mantenibilidad: Código estructurado y documentado

2. Arquitectura del Sistema

2.1 Arquitectura General

2.2 Arquitectura Multi-Tenant

El sistema implementa un modelo multi-tenant de base de datos compartida, donde todos los tenants comparten la misma base de datos pero sus datos están aislados mediante el campo tenant_id.

2.3 Patrón de Diseño

El sistema sigue un patrón MVC simplificado:

• Modelo: Base de datos PostgreSQL + consultas preparadas (PDO)
• Vista: Archivos HTML + JavaScript + CSS
• Controlador: Archivos PHP que procesan peticiones

3. Stack Tecnológico

Capa	Tecnología	Versión	Justificación
Backend	PHP	8.2 (imagen php:8.2-apache)	Lenguaje maduro, amplio soporte, bajo costo de hosting
Base de Datos	PostgreSQL	16+ (con extensión pg_cron)	Open source, transaccional, integridad referencial estricta y soporte nativo de PL/pgSQL
Servidor Web	Apache	2.4+ (mod_headers habilitado)	Estándar de la industria, compatible con .htaccess; mod_headers entrega las cabeceras de seguridad
Contenerización	Docker + Docker Compose	-	Entorno reproducible: servicios web, db, proxy y adminer
Frontend	HTML5 + CSS3 + JS	-	Estándares web, sin framework de build (sin bundler ni transpilación)
Mapas	Leaflet.js + OSM	1.9+	Gratuito, sin API key, personalizable
Gráficos	Chart.js	4.4+	Librería ligera, responsive, fácil de usar
Rutas	OSRM	-	Open Source Routing Machine, gratuito
Tablas avanzadas	js/advanced_table.js (componente propio, vanilla JS)	-	Filtros, orden, paginación y export CSV/Excel/PDF en 18 listados del sistema (ver docs/GUIA_TABLAS_AVANZADAS.md). Tabulator se evaluó como alternativa (ver docs/Grilla Avanzada.docx y su demo) pero no es lo que quedó en producción.
Exportación	jsPDF + jspdf-autotable, SheetJS (xlsx)	-	Generación de PDF y Excel desde el navegador, sin backend adicional
Tiempo real	Socket.IO (cliente)	4.7+	Cargado para paneles de tracking en vivo
Iconografía	Font Awesome	6.4+	Íconos de interfaz vía CDN
Asistente IA	Google Gemini API	modelo configurable vía GEMINI_MODEL	Chatbot de ayuda (chat.php) y de apoyo comercial (chatv.php), llamado por HTTP desde el backend PHP
Tracking móvil	OwnTracks (Android/iOS) + GPSLogger	-	Apps de terceros que envían posición GPS del conductor al backend (ver docs/OWNTRACKS_*.md, docs/GPSLOGGER_*.md)

4. Diseño de Módulos

4.1 Estructura de Módulos

4.2 Detalle de Módulos

Módulo de Autenticación

Archivo	Función
login.php	Procesa credenciales y genera sesión
logout.php	Destruye sesión de forma segura
security.php	Funciones de seguridad centralizadas
auth_functions.php	Funciones auxiliares de autenticación

Módulo de Despachos

Archivo	Función
despachos_list.php	Lista despachos del tenant
despachos_activos.php	Lista despachos en curso
despachos_iniciar.php	Inicia despacho (km, hora salida)
despachos_finalizar.php	Finaliza despacho (km, hora llegada)
despachos_cancelar.php	Cancela despacho
despachos_entregar.php	Marca pedido como entregado
despachos_asignar_pedidos.php	Asigna pedidos a despacho
despachos_planificar_ruta.php	Planifica orden de ruta

Módulo de Tracking GPS

Ubica vehículos en tiempo real a partir de la posición que reporta el celular del conductor (vía la app OwnTracks o GPSLogger), sin hardware GPS dedicado en el vehículo.

Archivo	Función
tracking_auth.php	Autentica el dispositivo móvil del conductor (email/password → token de dispositivo)
tracking_batch.php	Recibe lotes de posiciones GPS enviadas por la app móvil
tracking_ultima_posicion.php	Última posición conocida de cada vehículo (para el mapa en vivo)
tracking_despacho_activo.php	Despacho activo de un vehículo con sus pedidos y estado
tracking_ruta_vehiculo.php	Reconstruye el recorrido real de un despacho pasado a partir de las posiciones GPS
tracking_cambiar_estado_pedido.php / tracking_forzar_estado.php	Actualiza el estado de un pedido desde la app móvil o manualmente desde el panel
owntracks_recibir.php	Webhook que recibe los mensajes nativos de OwnTracks y los normaliza a las tablas de tracking

Módulo de Asistente Virtual (Chatbot con IA)

Dos widgets de chat flotantes, ambos sobre la API de Google Gemini, cada uno con su propia base de conocimiento y sus propios límites de uso:

Archivo	Función
chat.php	Chat de ayuda dentro de la app — requiere sesión iniciada, responde dudas de uso del sistema
chatv.php	Chat comercial en páginas públicas — sin sesión, orientado a apoyar la venta
gemini_helper.php	Llama a la API de Gemini vía cURL, sanea el historial de conversación y aplica el límite de mensajes por sesión
conocimiento_ayuda.php / conocimiento_venta.php	Base de conocimiento (texto de referencia) inyectada en el system prompt de cada chatbot, para que responda con hechos reales del producto en vez de improvisar
js/chat_widget.js + css/chat_widget.css	Motor de UI genérico del widget flotante, reutilizado por ambos chats

Módulo de Administración de Empresa (rol Administrador)

Funciones de autoservicio que un Administrador gestiona dentro de su propia empresa — parte del producto que usa el cliente:

Archivo	Función
admin_usuarios.html + usuarios_list.php / usuarios_create.php / usuarios_update.php	Gestión de usuarios y su rol dentro de un tenant
permisos.html + permisos_paginas	Matriz de permisos por rol y página dentro de un tenant

5. Diseño de Base de Datos

5.1 Modelo Relacional

La base de datos rutacc (schema rutacc en PostgreSQL) contiene 30 tablas organizadas en el siguiente modelo relacional:

5.2 Resto de las tablas

Las entidades anteriores son el núcleo operativo; el resto de las 30 tablas cubre seguridad, tracking GPS, administración multi-tenant e historial — no se detallan campo a campo acá, solo su propósito:

Grupo	Tablas	Propósito
Seguridad de sesión	login_attempts, remember_tokens, password_reset_tokens	Control de fuerza bruta, cookie "Recordarme" y recuperación de contraseña
Documentos	documentos_vehiculo, documentos_conductor	SOAP, revisión técnica, seguros y licencias, con fecha de vencimiento (alimentan las alertas)
Historial	historial_estados_vehiculos, historial_estados_conductores, historial_estados_pedido, historial_sueldos_conductores	Traza de cambios de estado y remuneración, para auditoría y reportes
Tracking GPS	dispositivos_moviles, telemetria_gps, ultima_posicion_vehiculo, owntracks_raw, owntracks_temporal	Registro de dispositivos autorizados, posiciones GPS crudas y procesadas de OwnTracks/GPSLogger
Administración multi-tenant	modulos, tenant_modulos, paginas, modulo_paginas, permisos_paginas	Qué módulos/páginas tiene habilitados cada tenant y qué puede hacer cada rol en cada una
Reportes	indicadores_ipc	Serie histórica de IPC usada para ajustar/comparar costos en el tiempo

5.3 Índices y Optimización

Tabla	Índice	Propósito
despachos	idx_tenant_estado	Consultas por tenant y estado
despachos	idx_numero_orden_tenant	Búsqueda de órdenes únicas
pedidos	idx_despacho_orden	Ordenar pedidos en despacho
documentos_vehiculo	idx_docvehiculo_vehiculo	Documentos por vehículo
otros_cobros	idx_estado_vencimiento	Alertas de cobros
permisos_paginas	uq_usuario_pagina	Permisos únicos

5.4 Integridad Referencial

Todas las relaciones están protegidas con foreign keys y reglas de cascada:

• ON DELETE CASCADE: Al eliminar un tenant, se eliminan todos sus datos
• ON DELETE SET NULL: Al eliminar una bodega, los despachos mantienen historial
• ON UPDATE CASCADE: Actualizaciones se propagan automáticamente

6. Diseño de APIs

6.1 Endpoints Principales

Autenticación

Vehículos

Despachos

Reportes

Tracking GPS

Asistente IA (Chatbot)

Administración de Empresa

6.2 Formato de Respuesta

Todas las APIs responden en formato JSON:

{
  "success": true,
  "data": { ... },
  "message": "Operación exitosa"
}

// En caso de error:
{
  "success": false,
  "message": "Descripción del error"
}

7. Arquitectura de Seguridad

7.1 Capas de Seguridad

7.2 Cumplimiento Normativo

RutaCC está diseñado siguiendo los principios de estos estándares — no cuenta con una certificación formal de terceros. El chatbot comercial (chatv.php) usa este mismo matiz al responder sobre cumplimiento, para no prometer más de lo que el sistema realmente tiene.

Estándar	Aplicación
OWASP Top 10	Prevención de inyección, XSS, CSRF, broken auth
ISO/IEC 27001:2022	Control de acceso, cifrado, segregación de datos (diseño alineado, no certificado)
Ley 21.710 (Chile)	Protección de datos personales
NIST Framework	Gestión de identidad, protección de datos

8. Diseño Frontend

8.1 Estructura de Páginas

Página	Archivo	Funcionalidad
Login	login.html	Formulario de acceso
Dashboard	dashboard.html	Panel principal con estadísticas
Vehículos	vehiculos.html	Gestión de flota
Conductores	conductores.html	Gestión de conductores
Bodegas	bodegas.html	Gestión de bodegas
Pedidos	pedidos.html	Gestión de pedidos
Despachos	despachos.html	Lista de despachos
Despacho Inicio	despachos_inicio.html	Iniciar despachos
Despacho Cierre	despachos_cierre.html	Finalizar despachos
Combustible	combustible.html	Registro de combustible
Mantención	mantenimiento.html	Gestión de mantenciones
Fallos	fallos.html	Registro de fallos
Cobros	cobros.html	Gestión de cobros
Reportes	reportes_costos.html	Reportes financieros
Configuración	configuracion.html	Configuración del sistema

8.2 Arquitectura Frontend

8.3 Módulos JavaScript

Archivo	Responsabilidad
api.js	Cliente HTTP centralizado (fetch + CSRF automático), autenticación/sesión, carga del menú lateral, reloj, e inyección del widget de chat de ayuda
theme.js	Alterna entre tema oscuro/claro/azul, persistido en localStorage
chat_widget.js	Motor genérico del widget de chat flotante (ayuda y venta)
advanced_table.js	Componente propio de tabla avanzada: filtros estilo Excel, orden, paginación y export CSV/Excel/PDF (SheetJS + jsPDF)
tracking_monitor.js / tracking_ruta.js	Mapa de posición en vivo y reconstrucción de rutas GPS (Leaflet)
reportes.js / reportes_costos.js	Generación de reportes y gráficos (Chart.js)
{módulo}.js / {módulo}_ficha.js	Un archivo por página, siguiendo el mismo patrón que su HTML (ver convención de nombres) — 64 archivos en total

9. Arquitectura de Despliegue

9.1 Entornos

Hoy el proyecto define un único entorno reproducible vía docker-compose.yml, parametrizado con variables de entorno (APP_ENV, credenciales de BD, API key de Gemini) para distinguir desarrollo de un eventual despliegue productivo — todavía no existen ambientes de staging/producción separados.

Servicio	Contenedor	Propósito
web	php:8.2-apache + mod_headers	Sirve todo el código de este repositorio (HTML, PHP, assets)
db	PostgreSQL (build propio) + pg_cron	Base de datos rutacc, con tareas programadas (limpieza de telemetría GPS)
proxy	YARP (.NET)	Reverse proxy de entrada
adminer	Adminer	Administración visual de la base de datos (solo desarrollo)

9.2 Requisitos de Servidor

Recurso	Mínimo (dev/demo)	Recomendado
CPU	2 cores	4 cores
RAM	2 GB	4 GB
Disco	20 GB SSD	50 GB SSD
PHP	8.2 (fijo por la imagen del Dockerfile)	8.2
PostgreSQL	16 (fijo por el build del servicio db)	16

9.3 Backups