Skip to main content

Modelos de Datos

Esta sección explica en detalle la estructura de datos del sistema Paso Rápido, incluyendo las entidades principales, sus relaciones y propósitos específicos.

Arquitectura de Datos

Principios Fundamentales

Multi-Tenancia

Aislamiento por OrganizaciónCada organización tiene sus datos completamente separados mediante el campo org_id en todas las tablas principales.
  • Seguridad garantizada entre organizaciones
  • Escalabilidad horizontal
  • Gestión independiente de datos

Trazabilidad

Auditoría CompletaTodos los cambios importantes se registran con timestamps y usuarios responsables.
  • Campos created_at y updated_at
  • Historial de validaciones
  • Registro de acciones de usuarios

Entidades Principales

1. Organizaciones

  • Estructura
  • Campos Detallados
  • Relaciones
organizations {
  id: UUID (Primary Key)
  name: TEXT
  avatar_url: TEXT
  created_at: TIMESTAMP
  updated_at: TIMESTAMP
  karma_api_url: TEXT
  karma_username: TEXT
  karma_password_encrypted: TEXT
}
Propósito: Entidad raíz que representa cada empresa cliente del sistema.

2. Usuarios y Membresías

Configuración de organización y usuarios
  • Estructura
  • Roles Disponibles
org_members {
  org_id: UUID (FK → organizations.id)
  user_id: UUID (FK → auth.users.id)
  role: TEXT (OrgAdmin|Dispatcher|Analyst|Driver|ReadOnly)
  created_at: TIMESTAMP
  updated_at: TIMESTAMP
  PRIMARY KEY (org_id, user_id)
}
Propósito: Define qué usuarios pertenecen a cada organización y con qué nivel de acceso.

3. Vehículos

Panel detallado de información del vehículo
  • Estructura
  • Campos Detallados
  • Categorías de Vehículos
cars {
  car_id: BIGINT (Primary Key)
  device_id: BIGINT
  project_id: BIGINT (FK → projects.project_id)
  time_zone: TEXT
  car_number: TEXT
  license_plate: TEXT
  car_title: TEXT
  car_type: TEXT
  sub_type: TEXT
  car_year: TEXT
  car_color: TEXT
  sim_imsi: TEXT
  sim_phone: TEXT
  karma_video_data: TEXT
  fetch_timestamp: TIMESTAMP
  org_id: UUID (FK → organizations.id)
}
Propósito: Representa cada vehículo de la flota con su información técnica y administrativa.

4. Asignaciones de Tags

  • Estructura
  • Gestión de Asignaciones
  • Estados y Tipos
tag_assignments {
  id: BIGINT (Primary Key)
  date: DATE
  tag_number: INTEGER
  car_id: BIGINT (FK → cars.car_id)
  category: INTEGER (1-5)
  type: TEXT (corporativo|prepago)
  issued_at: DATE
  expires_at: DATE
  status: TEXT (Valido|Inhabilitado)
  created_at: TIMESTAMP
  updated_at: TIMESTAMP
  org_id: UUID (FK → organizations.id)
}
Propósito: Define qué tag está asignado a cada vehículo en un período específico.

5. Estaciones de Peaje

  • Estructura
  • Información Geográfica
  • Tarifas y Validación
tolls {
  id: BIGINT (Primary Key)
  name: TEXT
  latitude: DECIMAL(10,8)
  longitude: DECIMAL(11,8)
  category_1: BIGINT
  category_2: BIGINT
  category_3: BIGINT
  category_4: BIGINT
  category_5: BIGINT
  image: TEXT
  org_id: UUID (FK → organizations.id)
}
Propósito: Catálogo de estaciones de peaje con ubicación exacta y tarifas oficiales por categoría.

6. Cargos de Peaje

  • Estructura
  • Campos de Validación
  • Estados de Cargo
toll_charges {
  id: BIGINT (Primary Key)
  date: TIMESTAMP
  amount: DOUBLE PRECISION
  tag: BIGINT
  station: TEXT
  type: TEXT
  matched_message_id: BIGINT
  is_duplicate: BOOLEAN
  duplicate_resolution: TEXT
  category_error: BOOLEAN
  expected_amount: DOUBLE PRECISION
  amount_difference: DOUBLE PRECISION
  tag_status_at_time: TEXT
  tag_status_error: BOOLEAN
  fraud_type: TEXT
  fraud_reasons: TEXT
  is_fraudulent: BOOLEAN
  fleet: TEXT
  validation_status: TEXT
  validation_details: TEXT
  matched_car_id: BIGINT (FK → cars.car_id)
  matched_license_plate: TEXT
  assignment_date_used: DATE
  distance_meters: DOUBLE PRECISION
  time_diff_minutes: DOUBLE PRECISION
  manual_revision_status: TEXT
  manual_revision_comment: TEXT
  created_at: TIMESTAMP
  updated_at: TIMESTAMP
  org_id: UUID (FK → organizations.id)
}
Propósito: Registro central de todos los cargos de peaje con sus validaciones y estados.

7. Datos de Telemetría GPS

  • Estructura
  • Sincronización con ERM Karma
  • Uso en Validaciones
edata_telemetry {
  car_id: BIGINT (FK → cars.car_id)
  device_id: BIGINT
  car_number: TEXT
  message_id: BIGINT
  edt: TIMESTAMP
  edt_tz: TEXT
  pdt: TEXT
  speed_kph: DOUBLE PRECISION
  odometer_km: DOUBLE PRECISION
  latitude: DOUBLE PRECISION
  longitude: DOUBLE PRECISION
  fetch_timestamp: TIMESTAMP
  batch_number: BIGINT
  org_id: UUID (FK → organizations.id)
}
Propósito: Almacena datos de telemetría GPS obtenidos desde ERM Karma para validaciones de ubicación.

Relaciones Entre Entidades

Diagrama de Relaciones

Flujo de Datos Principal

Gestión de proyectos en el sistema
1

Configuración Inicial

Entidades: Organizations, Users, Cars, Projects
  • Se crea la organización y usuarios
  • Se importan vehículos y proyectos desde ERM Karma
  • Se configura la integración API
Base de datos preparada para operación.
2

Gestión de Tags

Entidades: tag_assignments, cars
  • Se asignan tags a vehículos específicos
  • Se define categoría y período de vigencia
  • Se mantiene historial de cambios
Las asignaciones correctas son críticas para validaciones precisas.
3

Importación de Cargos

Entidades: toll_charges, tolls
  • Se importan cargos desde archivos CSV
  • Se asocian con estaciones conocidas
  • Se inicia proceso de validación
Cargos de estaciones desconocidas requieren configuración adicional.
4

Validación Automática

Entidades: edata_telemetry, toll_chargesIntegración con ERM Karma API
  • Se obtienen datos GPS relevantes
  • Se ejecutan algoritmos de validación
  • Se actualizan estados y resultados
El proceso es automático pero puede monitorearse en tiempo real.
5

Revisión y Reportes

Entidades: toll_charges (estados finales)
  • Se revisan casos sospechosos manualmente
  • Se generan reportes ejecutivos
  • Se documentan decisiones para auditoría
Los reportes pueden exportarse a Excel para análisis adicional.

Integridad y Consistencia

Restricciones de Negocio

Regla: Un tag solo puede estar asignado a un vehículo a la vezImplementación:
  • Constraint único en (tag_number, org_id)
  • Validación de fechas de asignación sin solapamiento
  • Proceso de reasignación controlado
Excepción: Tags inhabilitados pueden reasignarse después de reemplazo físico
Regla: Los cargos solo pueden validarse con datos GPS contemporáneosImplementación:
  • Ventana de tiempo configurable para matching
  • Validación de timestamps coherentes
  • Manejo de zonas horarias
Consideración: Diferencias de reloj entre sistemas pueden requerir ajustes
Regla: Los datos de una organización nunca deben ser visibles para otraImplementación:
  • Row Level Security (RLS) en todas las tablas
  • Filtrado automático por org_id
  • Validación de permisos en cada consulta
Garantía: Seguridad certificada a nivel de base de datos

Políticas de Retención

  • Datos Operativos
  • Logs de Sistema
  • Reportes Generados
Período: 2 años mínimo
  • Cargos de peaje y validaciones
  • Datos GPS de telemetría
  • Asignaciones de tags
Justificación: Auditoría, análisis histórico, disputas legales

Próximos Pasos