Skip to content

Datos Maestros

Datos que Ontime debe preparar y cargar antes de poner PROXIMITI en produccion. Se organizan en datos de referencia (catalogos), datos operativos (centros, usuarios, clientes), y datos transaccionales. El objetivo es que el sistema arranque con toda la informacion necesaria para operar desde el dia uno.

1. Vista General de Carga

CategoriaTablas principalesRegistros estimadosFuente en OntimePrioridad
Catalogos basetp_pprx_carrier, tp_pprx_cluster, td_tipo_establecimiento~50ALINA / OperacionesCritica
Red de centrostp_pprx_centro~100-500ALINA + proveedoresCritica
Usuariostp_pprx_usuario~50-200Azure AD + asignacionesCritica
Clientestp_pprx_cliente, tp_pprx_direccion_cliente~1000+ALINA / CRMAlta
Tarifas centrotp_pprx_tarifa, tp_pprx_tarifa_historico~100-500Departamento financieroAlta
Tarifas clientetp_pprx_tarifa_cliente~20-50Departamento comercialAlta
Contratostp_pprx_contrato, td_plantilla_contrato~100-500Legal / ComercialMedia
Terminos y condicionestd_terminos_condiciones~1LegalMedia
Proveedorestd_proveedor~5-10IT / Adaptador configMedia
Historicostp_pprx_envio, tp_pprx_envio_tracking, tp_pprx_pod0 (arranque limpio)ALINABaja

Convencion de nomenclatura de tablas:

  • tp_pprx_* -- tablas operativas (datos que cambian en tiempo real)
  • td_* -- tablas de catalogo/referencia (datos relativamente estaticos)

2. Catalogos Base

2.1 Carriers (tp_pprx_carrier)

Empresas de transporte que operan rutas hacia los centros PUDO.

ColumnaTipoRequeridoDescripcion
cod_carrierVARCHAR(50)SiCodigo unico del carrier (ej: ONTIME-CARRIER-001)
nom_carrierVARCHAR(200)SiNombre comercial
activoBOOLEANSiSi opera actualmente (default TRUE)

Fuente: Departamento de operaciones / ALINA. Listar todas las empresas de transporte que tendran rutas de entrega/recogida en centros PUDO.

Ejemplo seed:

sql
INSERT INTO tp_pprx_carrier (nom_carrier, cod_carrier, activo)
VALUES ('Ontime Express', 'ONTIME-EXP-001', TRUE)
ON CONFLICT (cod_carrier) DO NOTHING;

2.2 Clusters (tp_pprx_cluster)

Agrupaciones geograficas de centros PUDO. Cada cluster define una zona de servicio mediante un poligono GeoJSON y se asigna a un carrier responsable.

ColumnaTipoRequeridoDescripcion
nom_clusterVARCHAR(100)SiNombre de la zona (ej: Madrid Centro)
id_carrierBIGINT (FK)NoCarrier asignado a esta zona
poligono_geojsongeometry(Polygon, 4326)NoPoligono PostGIS que delimita la zona

Formato del poligono: GeoJSON con coordenadas [longitud, latitud] en EPSG:4326. El primer y ultimo punto deben coincidir para cerrar el poligono.

json
{
  "type": "Polygon",
  "coordinates": [[
    [-3.7038, 40.4168],
    [-3.7038, 40.4268],
    [-3.6938, 40.4268],
    [-3.6938, 40.4168],
    [-3.7038, 40.4168]
  ]]
}

Fuente: Departamento de operaciones/logistica. Definir zonas de reparto con poligonos reales que cubran las areas de servicio.

2.3 Tipos de Establecimiento (td_tipo_establecimiento)

Catalogo de tipos de centro PUDO. Viene pre-cargado con 8 tipos por defecto. Se pueden agregar tipos adicionales.

ColumnaTipoRequeridoDescripcion
cod_tipoVARCHAR(50)SiCodigo unico (ej: TIENDA)
des_tipoVARCHAR(200)SiDescripcion legible
cap_defectoINTEGERNoCapacidad por defecto al crear un centro de este tipo
horario_defectoJSONBNoHorario tipo por defecto (formato descrito en seccion 3.1)
activoBOOLEANSiActivo en el catalogo (default TRUE)

Tipos pre-cargados (no requieren accion):

cod_tipoDescripcionCapacidad defecto
TIENDATienda30
ESTANCOEstanco15
GASOLINERAGasolinera20
HOTELHotel25
RESTAURANTERestaurante10
OFICINAOficina40
LOCKERLocker automatico50
OTROOtro tipo20

Accion requerida: Revisar si faltan tipos propios de Ontime. Si existen categorias adicionales (ej: CENTRO_COMERCIAL, FARMACIA), agregarlas antes de cargar centros.


3. Red de Centros PUDO (tp_pprx_centro)

Esta es la carga mas critica. Cada centro PUDO del que Ontime es propietario debe tener un registro completo. Los centros de proveedores externos (Kanguro, Hublocker) se sincronizan automaticamente via el servicio adaptador.

ColumnaTipoRequeridoDescripcion
cod_centroVARCHAR(50)SiCodigo unico (ej: PUDO-MAD-001)
nom_centroVARCHAR(200)SiNombre del establecimiento
num_capacidad_totalINTEGERSiHuecos totales para paquetes
num_espacios_libresINTEGERSiHuecos disponibles (= num_capacidad_total al inicio)
id_clusterBIGINT (FK)NoZona geografica asignada
direccionVARCHAR(500)NoDireccion completa
latitudDOUBLE PRECISIONSi*Coordenada latitud (WGS84)
longitudDOUBLE PRECISIONSi*Coordenada longitud (WGS84)
cod_proveedorVARCHAR(20)SiONTIME para centros propios (default)
estado_centroVARCHAR(30)SiEstado inicial (ver tabla abajo)
id_tipo_establecimientoBIGINT (FK)NoReferencia a td_tipo_establecimiento
email_contactoVARCHAR(200)NoEmail del responsable del centro
telefonoVARCHAR(50)NoTelefono de contacto
nif_cifVARCHAR(20)NoNIF/CIF del establecimiento
horarioJSONBNoHorario de apertura (ver formato en 3.1)
dias_retencionINTEGERNoDias maximos de retencion de paquetes
versionINTEGERSiControl de concurrencia optimista (iniciar en 1)
sync_statusVARCHAR(20)SiDISABLED para centros propios (default FRESH)

IMPORTANTE: latitud y longitud deben ser coordenadas reales obtenidas de Google Maps, HERE, o similar. Los datos seed de desarrollo usan valores sinteticos que NO sirven para produccion. El widget de seleccion PUDO usa estas coordenadas para busqueda por proximidad -- si son incorrectas, el selector no funcionara.

Estados de centro (estado_centro):

EstadoDescripcionUso en carga inicial
PENDIENTE_ACTIVACIONDado de alta, pendiente de revisionCentros nuevos por validar
ACTIVOOperativo, recibe enviosCentros listos desde el dia 1
SUSPENDIDOTemporalmente inactivoNo usar en carga inicial
BAJA_TEMPORALBaja temporal reversibleNo usar en carga inicial
BAJA_DEFINITIVADado de baja permanenteNo usar en carga inicial

3.1 Formato de Horario (JSONB)

El campo horario acepta un objeto JSON con los dias de la semana como claves. Cada dia contiene un array de rangos horarios para soportar jornada partida.

json
{
  "lunes":    [{"apertura": "09:00", "cierre": "14:00"}, {"apertura": "17:00", "cierre": "20:00"}],
  "martes":   [{"apertura": "09:00", "cierre": "14:00"}, {"apertura": "17:00", "cierre": "20:00"}],
  "miercoles":[{"apertura": "09:00", "cierre": "14:00"}, {"apertura": "17:00", "cierre": "20:00"}],
  "jueves":   [{"apertura": "09:00", "cierre": "14:00"}, {"apertura": "17:00", "cierre": "20:00"}],
  "viernes":  [{"apertura": "09:00", "cierre": "14:00"}, {"apertura": "17:00", "cierre": "20:00"}],
  "sabado":   [{"apertura": "10:00", "cierre": "14:00"}],
  "domingo":  []
}
  • Dias sin servicio: array vacio []
  • Jornada continua: un solo rango (ej: [{"apertura": "08:00", "cierre": "20:00"}])
  • Jornada partida: dos rangos (manana + tarde)
  • Formato hora: HH:MM en 24 horas

3.2 Centros de Proveedores Externos

Los centros de Kanguro y Hublocker NO requieren carga manual. El servicio ws-pprx-adapter sincroniza automaticamente cada 5 minutos via las APIs de los proveedores. Estos centros se crean con cod_proveedor = 'KANGURO' o 'HUBLOCKER' y sync_status = 'FRESH'.

Solo los centros con cod_proveedor = 'ONTIME' necesitan carga manual.


4. Usuarios (tp_pprx_usuario)

ColumnaTipoRequeridoDescripcion
keycloak_subVARCHAR(255)SiUUID del proveedor de identidad (Azure AD sub claim)
nom_usuarioVARCHAR(200)SiNombre completo
emailVARCHAR(200)SiEmail unico
rolVARCHAR(50)SiRol del sistema (ver tabla abajo)
id_centro_pudoBIGINT (FK)CondicionalRequerido para USER_PUDO; NULL para el resto
url_fotoVARCHAR(1024)NoURL de foto de perfil en MinIO

Roles disponibles:

RolDescripcionRequiere centro
USER_PUDOOperador de centro PUDOSi -- id_centro_pudo obligatorio
USER_CARRIERConductor/transportistaNo
USER_ADMINAdministrador del sistemaNo
USER_CUSTOMERCliente final (consumidor)No
USER_BILLINGFacturacion/finanzasNo

Auto-provisioning: PROXIMITI crea automaticamente el registro de usuario en la primera autenticacion. Sin embargo, la asignacion de centro (id_centro_pudo) para operadores PUDO requiere que el atributo center_code este configurado en Azure AD como claim del usuario.

Lo que Ontime debe preparar:

  1. Operadores PUDO: Lista de personas con su email + codigo de centro asignado (cod_centro)
  2. Carriers: Lista de conductores con su email
  3. Administradores: Lista de usuarios admin con su email
  4. Billing: Lista de usuarios de facturacion con su email
  5. Configuracion Azure AD: Asegurar que el atributo center_code este mapeado como claim en el token JWT para operadores PUDO

5. Clientes (tp_pprx_cliente + tp_pprx_direccion_cliente)

5.1 Perfil de Cliente (tp_pprx_cliente)

ColumnaTipoRequeridoDescripcion
id_usuarioBIGINT (FK)SiReferencia a tp_pprx_usuario (rol USER_CUSTOMER)
nifVARCHAR(20)NoNIF/NIE/CIF del cliente
telefonoVARCHAR(30)NoTelefono de contacto
idioma_prefVARCHAR(10)SiIdioma preferido (default es)
notif_emailBOOLEANSiRecibir notificaciones por email (default TRUE)
notif_smsBOOLEANSiRecibir notificaciones por SMS (default FALSE)

5.2 Direcciones del Cliente (tp_pprx_direccion_cliente)

ColumnaTipoRequeridoDescripcion
id_clienteBIGINT (FK)SiReferencia al perfil de cliente
aliasVARCHAR(100)SiNombre corto (ej: Casa, Oficina)
nom_destinatarioVARCHAR(200)SiNombre del destinatario
nif_destinatarioVARCHAR(20)NoNIF/NIE del destinatario
linea_1VARCHAR(300)SiLinea de direccion principal
linea_2VARCHAR(300)NoLinea complementaria (piso, puerta, etc.)
ciudadVARCHAR(100)SiCiudad
provinciaVARCHAR(100)SiProvincia
codigo_postalVARCHAR(10)SiCodigo postal
paisVARCHAR(100)SiPais (default Espana)
telefonoVARCHAR(30)NoTelefono del destinatario
emailVARCHAR(200)NoEmail del destinatario
es_predeterminadaBOOLEANSiDireccion por defecto (default FALSE)

Fuente: CRM existente o base de datos de ALINA. Los clientes tambien pueden auto-registrarse via el portal de clientes, por lo que la carga inicial puede incluir solo clientes existentes con historico.


6. Tarifas

6.1 Tarifas de Centro (tp_pprx_tarifa)

Tarifa vigente por centro PUDO. Define el coste por hora de almacenamiento y por bulto.

ColumnaTipoRequeridoDescripcion
cod_centroVARCHAR(50) (FK)SiCodigo del centro
precio_horasNUMERIC(10,4)SiPrecio por hora de almacenamiento (EUR)
precio_bultoNUMERIC(10,4)NoPrecio por bulto
fec_vigenciaDATESiFecha desde la que aplica

6.2 Historico de Tarifas (tp_pprx_tarifa_historico)

Versionado de cambios de tarifa. Cada entrada tiene rango de vigencia.

ColumnaTipoRequeridoDescripcion
cod_centroVARCHAR(50) (FK)SiCodigo del centro
precio_horasNUMERIC(10,4)SiPrecio por hora
precio_bultoNUMERIC(10,4)NoPrecio por bulto
effective_fromDATESiInicio de vigencia
effective_toDATENoFin de vigencia (NULL = vigente)

6.3 Tarifas de Cliente (tp_pprx_tarifa_cliente)

Tarifas de envio por peso para clientes finales. Pre-cargadas con 4 tramos.

ColumnaTipoRequeridoDescripcion
codigoVARCHAR(50)SiCodigo unico (ej: S, M, L, XL)
nombreVARCHAR(200)SiNombre comercial
descripcionTEXTNoDescripcion para el cliente
peso_min_kgNUMERIC(8,2)SiPeso minimo del tramo (kg)
peso_max_kgNUMERIC(8,2)SiPeso maximo del tramo (kg)
precio_baseNUMERIC(10,2)SiPrecio base (EUR)
precio_por_kgNUMERIC(10,2)SiPrecio adicional por kg (EUR)
monedaVARCHAR(3)SiMoneda ISO 4217 (default EUR)

Tramos pre-cargados (revisar precios reales):

CodigoNombrePesoPrecio baseEUR/kg
SSmall0-2 kg3.500.00
MMedium2-5 kg5.000.50
LLarge5-15 kg8.000.40
XLExtra Large15-30 kg12.000.35

Accion requerida: El departamento comercial debe validar estos precios y ajustarlos a la politica de precios real antes de go-live.


7. Contratos (tp_pprx_contrato + td_plantilla_contrato)

7.1 Plantillas de Contrato (td_plantilla_contrato)

Catalogo de plantillas pre-cargadas. Definen valores financieros y SLA por defecto.

ColumnaTipoDescripcion
cod_plantillaVARCHAR(50)Codigo unico: STANDARD, PREMIUM, ENTERPRISE
des_plantillaVARCHAR(200)Nombre descriptivo
comision_recepcion_defectoDECIMAL(5,2)Comision por recepcion (EUR)
comision_entrega_defectoDECIMAL(5,2)Comision por entrega (EUR)
tarifa_fija_mensual_defectoDECIMAL(10,2)Cuota mensual fija (EUR)
seguro_incluido_defectoBOOLEANIncluye seguro
importe_seguro_defectoDECIMAL(10,2)Importe maximo asegurado (EUR)
dias_retencion_defectoINTEGERDias de retencion maxima
horas_recepcion_max_defectoINTEGERHoras maximas para recepcionar

Plantillas pre-cargadas:

PlantillaComision recep.Comision entregaCuota mensualSeguroRetencionRecepcion max
STANDARD2.003.0050.00No7 dias24 h
PREMIUM3.004.5080.00Si (500)10 dias12 h
ENTERPRISE4.006.00150.00Si (1000)14 dias6 h

7.2 Contratos por Centro (tp_pprx_contrato)

Cada centro PUDO activo debe tener un contrato. Formato del codigo: CTR-{YYYY}-{COD_CENTRO}.

ColumnaTipoRequeridoDescripcion
cod_contratoVARCHAR(50)SiCodigo unico (ej: CTR-2026-PUDO-MAD-001)
id_centroBIGINT (FK)SiCentro asociado
id_plantillaBIGINT (FK)NoPlantilla base (puede sobreescribir valores)
estado_contratoVARCHAR(30)SiEstado del contrato
comision_recepcionDECIMAL(5,2)NoSobreescribe valor de plantilla
comision_entregaDECIMAL(5,2)NoSobreescribe valor de plantilla
tarifa_fija_mensualDECIMAL(10,2)NoSobreescribe valor de plantilla
fec_inicioDATESiFecha de inicio del contrato
fec_finDATENoFecha de fin (NULL = indefinido)
monedaVARCHAR(3)SiMoneda (default EUR)
dias_retencion_contratoINTEGERNoDias de retencion (default 7)
horas_recepcion_maxINTEGERNoHoras para recepcionar (default 24)
firmado_porVARCHAR(255)NoNombre del firmante
fec_firmaTIMESTAMPTZNoFecha de firma

Ciclo de vida del contrato:

EstadoDescripcion
BORRADOREn preparacion
PENDIENTE_FIRMAEnviado al centro para firma
ACTIVOVigente y operativo
SUSPENDIDOTemporalmente suspendido
VENCIDOHa expirado su fecha fin
RESCINDIDORescindido anticipadamente

Restriccion: Solo puede haber un contrato ACTIVO por centro (enforced por indice parcial unico en DB).


8. Terminos y Condiciones (td_terminos_condiciones)

Versionado de T&C que los centros PUDO deben aceptar. Solo una version puede estar vigente.

ColumnaTipoRequeridoDescripcion
num_versionVARCHAR(20)SiVersion unica (ej: v1.0)
tituloVARCHAR(200)SiTitulo del documento
resumenTEXTNoResumen ejecutivo
contenido_urlVARCHAR(1024)NoURL al documento completo en MinIO
vigenteBOOLEANSiSolo una version puede ser TRUE
fec_publicacionDATENoFecha de publicacion

Accion requerida: El departamento legal debe preparar el documento de T&C definitivo, subirlo a MinIO, y activar la version antes de go-live.


9. Proveedores Externos (td_proveedor)

Catalogo de proveedores de puntos PUDO (lockers, redes de terceros).

ColumnaTipoRequeridoDescripcion
cod_proveedorVARCHAR(20)SiCodigo unico (PK)
nombreVARCHAR(100)SiNombre del proveedor
activoBOOLEANSiActivo en el sistema (default TRUE)

Pre-cargados:

CodigoNombreDescripcion
ONTIMEOntime (Internal)Centros propios de Ontime
KANGUROKanguroRed de puntos PUDO Kanguro
HUBLOCKERHublockerRed de lockers Hublocker

Accion requerida: Si Ontime integra proveedores adicionales, agregar entradas aqui y configurar las credenciales API en el servicio adaptador (ws-pprx-adapter).


10. Formato de Carga

10.1 SQL Directo (recomendado para catalogos)

Scripts INSERT idempotentes siguiendo el patron de 02_seed.sql. Usar ON CONFLICT DO NOTHING para permitir re-ejecucion.

Orden obligatorio de insercion (dependencias FK):

  1. td_proveedor -- sin dependencias
  2. td_tipo_establecimiento -- sin dependencias
  3. tp_pprx_carrier -- sin dependencias
  4. tp_pprx_cluster -- depende de tp_pprx_carrier
  5. tp_pprx_centro -- depende de tp_pprx_cluster, td_tipo_establecimiento
  6. td_plantilla_contrato -- sin dependencias
  7. tp_pprx_contrato -- depende de tp_pprx_centro, td_plantilla_contrato
  8. tp_pprx_usuario -- depende de tp_pprx_centro
  9. tp_pprx_cliente -- depende de tp_pprx_usuario
  10. tp_pprx_direccion_cliente -- depende de tp_pprx_cliente
  11. tp_pprx_tarifa / tp_pprx_tarifa_historico -- depende de tp_pprx_centro
  12. tp_pprx_tarifa_cliente -- sin dependencias
  13. td_terminos_condiciones -- sin dependencias

10.2 CSV Import (recomendado para volumenes grandes)

Para centros y clientes con cientos o miles de registros, usar COPY de PostgreSQL o herramientas como pgAdmin.

bash
# Ejemplo: carga masiva de centros desde CSV
psql -h localhost -U proximiti -d proximiti_db \
  -c "\COPY tp_pprx_centro(cod_centro, nom_centro, num_capacidad_total, num_espacios_libres, direccion, latitud, longitud, cod_proveedor, estado_centro, telefono, email_contacto) FROM 'centros_produccion.csv' WITH (FORMAT csv, HEADER true)"

Plantillas CSV a preparar: Se deben generar plantillas CSV con las columnas exactas para cada tabla, incluyendo cabeceras y datos de ejemplo.

10.3 API REST (para actualizaciones incrementales)

Los endpoints de administracion del BFF (/api/v1/centers, /api/v1/shipments, etc.) permiten CRUD post-lanzamiento. Requiere autenticacion con rol USER_ADMIN.

10.4 Sincronizacion Automatica

MecanismoDatosFrecuencia
Adapter syncCentros Kanguro y HublockerCada 5 minutos
Auto-provisioningUsuarios al primer loginTiempo real
Portal de clientesRegistro de clientes + direccionesAutoservicio

11. Datos que NO se Migran (Arranque Limpio)

Las siguientes tablas se generan operativamente y no requieren carga inicial:

TablaRazon
tp_pprx_envioLos envios se crean en tiempo real
tp_pprx_envio_trackingEventos de tracking generados automaticamente (particionado por anio)
tp_pprx_podPruebas de entrega capturadas en el momento de la entrega
tp_pprx_notificacionNotificaciones de envio generadas por eventos
tp_pprx_notificacion_usuarioNotificaciones del centro, generadas por eventos
tp_pprx_incidenciaIncidencias creadas segun necesidad
tp_pprx_issues / tp_pprx_issue_auditIssues y auditoria del servicio de soporte
tp_pprx_alina_outbox / tp_pprx_expiry_dlqColas transaccionales operativas
tp_pprx_log_alinaLog de auditoria ALINA
qr_session / tp_pprx_qr_sessionSesiones QR de handshake (efimeras)
tp_pprx_candidatoPipeline de onboarding (se crea via UI)
tp_pprx_documentoDocumentos de centros (se suben via UI)
tp_pprx_forecastForecasts de capacidad (generados por el sistema)
tp_pprx_centro_historial_estadoAuditoria de cambios de estado de centros
tp_pprx_contrato_historialAuditoria de cambios de estado de contratos
tp_pprx_aceptacion_tcRegistro de aceptaciones de T&C

12. Checklist de Datos Maestros

DatoResponsableFormatoVolumen estimadoEstado
Carriers (empresas de transporte)OperacionesSQL~10-20Pendiente
Clusters (zonas geograficas)OperacionesSQL + GeoJSON~10-30Pendiente
Poligonos de zonas (GeoJSON)Operaciones / GISGeoJSON~10-30Pendiente
Tipos de establecimiento adicionalesOperacionesSQL~0-5Pendiente
Centros PUDO propiosOperacionesCSV~100-500Pendiente
Coordenadas reales lat/lngOperaciones / GISCSV~100-500Pendiente
Horarios de centrosOperacionesJSON (en CSV)~100-500Pendiente
Datos de contacto de centrosOperacionesCSV~100-500Pendiente
Plantillas de contrato (ajuste precios)Comercial / LegalSQL3 (pre-cargadas)Pendiente
Contratos por centroLegal / ComercialSQL/CSV~100-500Pendiente
Terminos y condiciones (documento)LegalPDF + SQL1 versionPendiente
Operadores PUDO (lista email + centro)RRHH + OperacionesLista~50-200Pendiente
Conductores carrier (lista email)RRHH + OperacionesLista~20-50Pendiente
Administradores (lista email)ITLista~5-10Pendiente
Config Azure AD (claim center_code)IT / IdentidadConfigN/APendiente
Clientes existentesComercial / CRMCSV~1000+Pendiente
Direcciones de clientesComercial / CRMCSV~2000+Pendiente
Tarifas de centro (precio/hora, precio/bulto)FinancieroCSV~100-500Pendiente
Tarifas de cliente (tramos peso/precio)ComercialSQL~4-10Pendiente
Proveedores externos adicionalesITSQL~0-5Pendiente
Credenciales API proveedoresITConfig (env vars)~2-5Pendiente

Ecosistema PUDO de PROXIMITI — documentacion interna