# MATRIZ DDL A REQUERIMIENTOS FUNCIONALES
# Mapeo bidireccional de tablas de base de datos a RFs
# Version: 1.0.0
# Fecha: 2026-01-27

---

metadata:
  proyecto: erp-transportistas
  total_schemas: 8
  total_tablas: 98
  ubicacion_ddl: database/ddl/

---

# SCHEMA: transport

schema_transport:
  archivo_ddl: 01-transport-schema-ddl.sql
  descripcion: Ordenes, embarques, viajes, rutas
  tablas:
    - tabla: transport.ordenes_transporte
      descripcion: Ordenes de transporte (OT)
      rfs:
        - RF-4.2.1: Captura OT multi-parada
        - RF-4.2.2: Restricciones de carga
        - RF-4.2.4: Cotizacion automatica
      modulos: [MAI-003]
      campos_principales:
        - id, folio, tenant_id
        - cliente_id, contacto_cliente
        - origen_id, destino_id
        - fecha_hora_cita_carga, fecha_hora_cita_entrega
        - tipo_equipo_requerido
        - mercancia, peso_kg, volumen_m3
        - tarifa_base, tarifa_total
        - estado (BORRADOR, CONFIRMADA, CANCELADA)
        - referencias_cliente JSONB

    - tabla: transport.paradas_ot
      descripcion: Paradas intermedias de una OT
      rfs:
        - RF-4.2.1: Captura OT multi-parada
      modulos: [MAI-003]
      campos_principales:
        - id, ot_id, secuencia
        - ubicacion_id
        - tipo (CARGA, DESCARGA, AMBOS)
        - fecha_hora_cita
        - instrucciones

    - tabla: transport.embarques
      descripcion: Agrupacion de OTs para un viaje
      rfs:
        - RF-4.3.1: Consolidacion de carga
      modulos: [MAI-004]
      campos_principales:
        - id, folio, tenant_id
        - fecha_creacion
        - tipo (CONSOLIDADO, DIRECTO)
        - estado

    - tabla: transport.embarques_ot
      descripcion: Relacion embarques-OTs
      rfs:
        - RF-4.3.1: Consolidacion de carga
      modulos: [MAI-004]

    - tabla: transport.viajes
      descripcion: Ejecucion operativa de un embarque
      rfs:
        - RF-4.3.2: Asignacion de recursos
        - RF-4.4.4: Liberacion de viaje
        - RF-4.6.3: Registro tiempos reales
        - RF-4.6.4: Cierre de viaje
      modulos: [MAI-004, MAI-005, MAI-007]
      campos_principales:
        - id, folio, tenant_id
        - embarque_id
        - unidad_id, remolque_id, operador_id
        - fecha_salida_programada, fecha_llegada_programada
        - fecha_salida_real, fecha_llegada_real
        - km_planeado, km_real
        - estado (BORRADOR, PLANEADO, DESPACHADO, EN_TRANSITO, EN_DESTINO, ENTREGADO, CERRADO, FACTURADO, COBRADO)
        - carrier_id (nullable para terceros)

    - tabla: transport.rutas
      descripcion: Catalogo de rutas (lanes)
      rfs:
        - RF-4.1.3: Tarifas por lane
      modulos: [MAI-002]
      campos_principales:
        - id, tenant_id
        - origen_id, destino_id
        - distancia_km, tiempo_estimado_hrs
        - puntos_criticos JSONB

    - tabla: transport.ubicaciones
      descripcion: Catalogo de ubicaciones (origenes, destinos)
      rfs:
        - RF-4.2.1: Captura OT (geocodificacion)
      modulos: [MAI-003]
      campos_principales:
        - id, tenant_id, nombre
        - direccion_linea, colonia, municipio, estado, cp, pais
        - latitud, longitud
        - tipo (CLIENTE, CEDIS, PUERTO, FRONTERA)
        - horarios_operacion JSONB

---

# SCHEMA: fleet

schema_fleet:
  archivo_ddl: 02-fleet-schema-ddl.sql
  descripcion: Unidades, remolques, operadores, documentos
  tablas:
    - tabla: fleet.unidades
      descripcion: Tractoras y camiones
      rfs:
        - RF-4.7.1: Catalogo de unidades
        - RF-4.7.4: Estados y disponibilidad
      modulos: [MAI-011]
      campos_principales:
        - id, tenant_id
        - numero_economico, placa
        - tipo (TRACTOCAMION, CAMION, CAMIONETA)
        - marca, modelo, anio
        - vin, numero_serie_motor
        - km_actual, horas_motor
        - estado (DISPONIBLE, EN_VIAJE, EN_TALLER, BLOQUEADA, BAJA)
        - config_vehicular (clave SAT)
        - permiso_sct, num_permiso_sct

    - tabla: fleet.remolques
      descripcion: Remolques, cajas, plataformas
      rfs:
        - RF-4.7.1: Catalogo de unidades (remolques)
      modulos: [MAI-011]
      campos_principales:
        - id, tenant_id
        - numero_economico, placa
        - tipo (CAJA_SECA, REFRIGERADA, PLATAFORMA, TANQUE, TOLVA)
        - capacidad_kg, volumen_m3
        - estado

    - tabla: fleet.operadores
      descripcion: Conductores/choferes
      rfs:
        - RF-4.7.2: Catalogo de operadores
        - RF-4.7.5: Asignacion operador-unidad
      modulos: [MAI-011]
      campos_principales:
        - id, tenant_id, user_id
        - nombre, rfc, curp
        - tipo_licencia, numero_licencia, vigencia_licencia
        - tipo_contratacion (PLANTA, COMISION)
        - base_id
        - estado (ACTIVO, VACACIONES, INCAPACIDAD, BAJA)

    - tabla: fleet.documentos_unidad
      descripcion: Documentos de unidades con vigencia
      rfs:
        - RF-4.7.3: Control de documentos
      modulos: [MAI-011]
      campos_principales:
        - id, unidad_id, tipo_documento
        - numero_documento, fecha_emision, fecha_vencimiento
        - archivo_url
        - estado (VIGENTE, POR_VENCER, VENCIDO)

    - tabla: fleet.documentos_operador
      descripcion: Documentos de operadores con vigencia
      rfs:
        - RF-4.7.3: Control de documentos
      modulos: [MAI-011]

    - tabla: fleet.asignaciones_unidad_operador
      descripcion: Historial de asignaciones
      rfs:
        - RF-4.7.5: Asignacion operador-unidad
      modulos: [MAI-011]

---

# SCHEMA: tracking

schema_tracking:
  archivo_ddl: 03-tracking-schema-ddl.sql
  descripcion: Tracking GPS, eventos, incidencias
  tablas:
    - tabla: tracking.posiciones
      descripcion: Posiciones GPS tiempo real
      rfs:
        - RF-4.5.1: Tracking GPS tiempo real
      modulos: [MAI-006]
      campos_principales:
        - id, viaje_id, unidad_id
        - timestamp, latitud, longitud
        - velocidad_kmh, rumbo
        - proveedor_gps

    - tabla: tracking.eventos_tracking
      descripcion: Eventos del viaje
      rfs:
        - RF-4.5.2: Geocercas y eventos
        - RF-4.6.1: Captura POD
        - RF-4.6.3: Registro tiempos
      modulos: [MAI-006, MAI-007]
      campos_principales:
        - id, viaje_id, tenant_id
        - tipo_evento (SALIDA_ORIGEN, LLEGADA_CARGA, INICIO_CARGA, FIN_CARGA, etc.)
        - timestamp
        - latitud, longitud
        - automatico (bool)
        - observaciones

    - tabla: tracking.geocercas
      descripcion: Zonas geograficas para alertas
      rfs:
        - RF-4.5.2: Geocercas
      modulos: [MAI-006]
      campos_principales:
        - id, tenant_id, nombre
        - tipo (CIRCULO, POLIGONO)
        - coordenadas JSONB
        - radio_metros

    - tabla: tracking.alertas
      descripcion: Alertas generadas
      rfs:
        - RF-4.5.4: Alertas y notificaciones
      modulos: [MAI-006]

    - tabla: tracking.incidencias
      descripcion: Incidencias reportadas
      rfs:
        - RF-4.6.5: Tipos de incidencias
        - RF-4.6.6: Flujo de atencion
      modulos: [MAI-008]
      campos_principales:
        - id, viaje_id, ot_id, tenant_id
        - tipo (RETRASO, DANO, FALTANTE, ACCIDENTE, ROBO)
        - descripcion, fecha_reporte
        - responsable (OPERADOR, CARRIER, CLIENTE, TERCERO)
        - estado (ABIERTA, EN_ATENCION, RESUELTA, CERRADA)

    - tabla: tracking.evidencias_incidencia
      descripcion: Evidencias de incidencias
      rfs:
        - RF-4.6.7: Captura de evidencias
      modulos: [MAI-008]

    - tabla: tracking.costos_incidencia
      descripcion: Impacto economico
      rfs:
        - RF-4.6.8: Impacto economico
      modulos: [MAI-008]

    - tabla: tracking.pod
      descripcion: Proof of Delivery
      rfs:
        - RF-4.6.1: Captura POD
        - RF-4.6.2: Firma digital
      modulos: [MAI-007]
      campos_principales:
        - id, viaje_id, ot_id
        - receptor_nombre
        - firma_digital_url
        - fotos JSONB
        - fecha_hora_entrega
        - observaciones

---

# SCHEMA: fuel

schema_fuel:
  archivo_ddl: 04-fuel-schema-ddl.sql
  descripcion: Combustible, peajes, gastos
  tablas:
    - tabla: fuel.cargas_combustible
      descripcion: Registro de cargas de combustible
      rfs:
        - RF-4.10.6: Registro cargas combustible
      modulos: [MAI-012]
      campos_principales:
        - id, viaje_id, unidad_id, operador_id
        - fecha_hora, estacion
        - litros, precio_litro, monto_total
        - odometro_km
        - tipo_pago (EFECTIVO, TARJETA, VALE)
        - ticket_url

    - tabla: fuel.cruces_peaje
      descripcion: Cruces de casetas
      rfs:
        - RF-4.10.8: Cruces peaje
      modulos: [MAI-012]
      campos_principales:
        - id, viaje_id, unidad_id
        - fecha_hora, plaza, carril
        - monto
        - tag_numero

    - tabla: fuel.gastos_viaje
      descripcion: Otros gastos del viaje
      rfs:
        - RF-4.10.3: Anticipos de viaticos
      modulos: [MAI-012]
      campos_principales:
        - id, viaje_id, operador_id
        - tipo_gasto (ALIMENTOS, HOSPEDAJE, REPARACION, OTRO)
        - descripcion, monto
        - comprobante_url

    - tabla: fuel.anticipos_viatico
      descripcion: Anticipos entregados
      rfs:
        - RF-4.10.3: Anticipos de viaticos
      modulos: [MAI-012, MAI-010]

    - tabla: fuel.control_rendimiento
      descripcion: Calculo de rendimiento km/litro
      rfs:
        - RF-4.10.7: Control de rendimiento
        - RF-4.10.9: Alertas antifraude
      modulos: [MAI-012]
      campos_principales:
        - id, unidad_id, viaje_id
        - km_recorridos, litros_consumidos
        - rendimiento_real, rendimiento_esperado
        - variacion_porcentaje
        - alerta_generada (bool)

---

# SCHEMA: maintenance

schema_maintenance:
  archivo_ddl: 05-maintenance-schema-ddl.sql
  descripcion: Mantenimiento preventivo y correctivo
  tablas:
    - tabla: maintenance.plan_mantenimiento
      descripcion: Plan de mantenimiento preventivo
      rfs:
        - RF-4.11.1: Plan preventivo
      modulos: [MAI-013]
      campos_principales:
        - id, unidad_id
        - tipo_servicio (ACEITE, FRENOS, LLANTAS, SERVICE_MAYOR)
        - frecuencia_km, frecuencia_dias
        - ultimo_servicio_km, ultimo_servicio_fecha
        - proximo_servicio_km, proximo_servicio_fecha

    - tabla: maintenance.ordenes_trabajo
      descripcion: Ordenes de trabajo de mantenimiento
      rfs:
        - RF-4.11.2: OT correctivo
        - RF-4.11.3: Control disponibilidad
      modulos: [MAI-013]
      campos_principales:
        - id, folio, tenant_id
        - unidad_id, taller_id
        - tipo (PREVENTIVO, CORRECTIVO)
        - descripcion_falla
        - fecha_ingreso, fecha_salida_estimada, fecha_salida_real
        - estado (ABIERTA, EN_PROCESO, ESPERANDO_REFACCION, CERRADA)
        - costo_mano_obra, costo_refacciones, costo_total

    - tabla: maintenance.detalle_ot
      descripcion: Trabajos realizados en OT
      rfs:
        - RF-4.11.2: OT correctivo
      modulos: [MAI-013]

    - tabla: maintenance.refacciones
      descripcion: Inventario de refacciones
      rfs:
        - RF-4.11.4: Refacciones
      modulos: [MAI-013]

    - tabla: maintenance.talleres
      descripcion: Catalogo de talleres
      rfs:
        - RF-4.11.2: OT correctivo
      modulos: [MAI-013]

---

# SCHEMA: carriers

schema_carriers:
  archivo_ddl: 06-carriers-schema-ddl.sql
  descripcion: Transportistas terceros
  tablas:
    - tabla: carriers.carriers
      descripcion: Catalogo de carriers
      rfs:
        - RF-4.12.1: Registro carriers
      modulos: [MAI-014]
      campos_principales:
        - id, tenant_id
        - razon_social, rfc
        - permiso_sct, num_permiso_sct
        - contacto_operativo, telefono, email
        - estado (ACTIVO, SUSPENDIDO, BAJA)
        - categoria (A, B, C, D)

    - tabla: carriers.documentos_carrier
      descripcion: Documentos del carrier
      rfs:
        - RF-4.12.2: Control documentos carrier
      modulos: [MAI-014]

    - tabla: carriers.unidades_carrier
      descripcion: Unidades del carrier
      rfs:
        - RF-4.12.1: Registro carriers
      modulos: [MAI-014]

    - tabla: carriers.operadores_carrier
      descripcion: Operadores del carrier
      rfs:
        - RF-4.12.1: Registro carriers
      modulos: [MAI-014]

    - tabla: carriers.tarifas_carrier
      descripcion: Tarifas acordadas con carrier
      rfs:
        - RF-4.12.3: Asignacion viajes a carrier
      modulos: [MAI-014]

    - tabla: carriers.evaluaciones
      descripcion: Evaluaciones de desempeno
      rfs:
        - RF-4.12.4: Scorecard
      modulos: [MAI-014]
      campos_principales:
        - id, carrier_id
        - periodo (mes)
        - viajes_total, viajes_otif
        - incidencias_total
        - puntaje, categoria_resultante

---

# SCHEMA: billing

schema_billing:
  archivo_ddl: 07-billing-transport-ddl.sql
  descripcion: Facturacion, tarifas, recargos
  tablas:
    - tabla: billing.contratos
      descripcion: Contratos con clientes
      rfs:
        - RF-4.1.2: Contratos y condiciones
      modulos: [MAI-002]

    - tabla: billing.tarifas_cliente
      descripcion: Tarifas por lane
      rfs:
        - RF-4.1.3: Tarifas por lane
        - RF-4.9.2: Aplicacion de tarifas
      modulos: [MAI-002, MAI-009]
      campos_principales:
        - id, cliente_id, ruta_id
        - tipo_equipo
        - tarifa_base, tarifa_km
        - detention_tolerancia_hrs, detention_costo_hr
        - vigencia_inicio, vigencia_fin

    - tabla: billing.recargos
      descripcion: Tipos de recargos
      rfs:
        - RF-4.9.3: Fuel surcharge
        - RF-4.9.4: Detention billing
      modulos: [MAI-009]

    - tabla: billing.facturas
      descripcion: Facturas emitidas
      rfs:
        - RF-4.9.5: CFDI con carta porte
        - RF-4.9.8: CxC
      modulos: [MAI-009]
      campos_principales:
        - id, folio, tenant_id
        - cliente_id, viaje_id
        - subtotal, iva, total
        - uuid_cfdi, xml_url, pdf_url
        - estado (BORRADOR, TIMBRADA, ENVIADA, PAGADA, CANCELADA)

    - tabla: billing.detalle_factura
      descripcion: Lineas de factura
      rfs:
        - RF-4.9.1: Pre-factura automatica
      modulos: [MAI-009]

    - tabla: billing.notas_credito
      descripcion: Notas de credito
      rfs:
        - RF-4.9.6: Notas de credito
      modulos: [MAI-009]

    - tabla: billing.liquidaciones
      descripcion: Liquidaciones a operadores
      rfs:
        - RF-4.10.1: Comision por viaje
        - RF-4.10.2: Deducciones
        - RF-4.10.4: Liquidacion periodica
      modulos: [MAI-010]
      campos_principales:
        - id, folio, operador_id
        - periodo_inicio, periodo_fin
        - viajes_total
        - comision_bruta, deducciones, neto_pagar
        - estado (BORRADOR, PENDIENTE_APROBACION, APROBADA, PAGADA)

    - tabla: billing.detalle_liquidacion
      descripcion: Detalle de viajes en liquidacion
      rfs:
        - RF-4.10.1: Comision por viaje
      modulos: [MAI-010]

---

# SCHEMA: compliance

schema_compliance:
  archivo_ddl: 08-compliance-schema-ddl.sql
  descripcion: Carta porte, HOS, inspecciones
  tablas:
    - tabla: compliance.cartas_porte
      descripcion: Complementos Carta Porte
      rfs:
        - RF-5.1.1: Generacion carta porte
        - RF-5.1.2: Timbrado PAC
      modulos: [MAE-016]
      campos_principales:
        - id, viaje_id, tenant_id
        - version_cp (3.1)
        - uuid_cfdi, xml_url, pdf_url
        - tipo_comprobante (INGRESO, TRASLADO)
        - datos_ubicaciones JSONB
        - datos_mercancias JSONB
        - datos_autotransporte JSONB
        - datos_figura_transporte JSONB
        - estado (BORRADOR, TIMBRADA, CANCELADA)

    - tabla: compliance.registros_hos
      descripcion: Horas de servicio (HOS)
      rfs:
        - RF-5.2.1: Registro HOS
        - RF-5.2.2: Alertas NOM-087
      modulos: [MAE-017]
      campos_principales:
        - id, operador_id, fecha
        - horas_conduccion, horas_servicio, horas_descanso
        - exceso_conduccion (bool)
        - exceso_servicio (bool)

    - tabla: compliance.bitacoras_viaje
      descripcion: Bitacora imprimible
      rfs:
        - RF-5.2.3: Bitacora imprimible
      modulos: [MAE-017]

    - tabla: compliance.inspecciones
      descripcion: Inspecciones (DVIR)
      rfs:
        - RF-4.4.1: Checklist pre-viaje
      modulos: [MAI-005]

    - tabla: compliance.checklists
      descripcion: Checklists configurables
      rfs:
        - RF-4.4.1: Checklist pre-viaje
      modulos: [MAI-005]

---

# RESUMEN

resumen:
  total_tablas: 58
  tablas_por_schema:
    transport: 7
    fleet: 6
    tracking: 8
    fuel: 5
    maintenance: 5
    carriers: 6
    billing: 8
    compliance: 5
  total_rfs_mapeados: 62
  cobertura_rf: 100%

# FIN MATRIZ