services/api/src/modules/match/geo-distance.js

Overview

Este archivo expone la base geométrica mínima que usa Match para medir distancias en kilómetros. Es un puerto backend, de solo lectura, de la fórmula Haversine que ya existe en el frontend, y el propio código aclara que no importa nada desde apps/backoffice-web.

Su papel dentro del dominio de Match es muy concreto: ofrecer una función pura para calcular distancia de gran círculo y una constante compartida de radio terrestre. Esa fórmula la consume services/api/src/modules/match/comparison-contract.js cuando compara Requirement.searchZones[] contra Offer.location. fileciteturn0file9turn0file6

[!NOTE] Este módulo no valida latitud ni longitud. Esa validación defensiva vive en comparison-contract.js, que decide cuándo vale la pena invocar esta fórmula.

How it works

flowchart TD
  CC[comparison contract] --> HD[haversineDistanceKm]
  HD --> TR[toRadians]
  HD --> ER[EARTH_RADIUS_KM 6371]
  HD --> KM[Distance in kilometers]

La ejecución es directa. haversineDistanceKm convierte diferencias de grados a radianes, aplica la fórmula Haversine y multiplica el resultado por EARTH_RADIUS_KM. El helper interno toRadians solo existe para esa conversión. El resultado es siempre una distancia en kilómetros y nunca depende de I/O, Mongo ni tiempo del sistema.

Key components

{
    "title": "haversineDistanceKm",
    "content": "Calcula la distancia de gran c\u00edrculo entre dos puntos geogr\u00e1ficos en kil\u00f3metros. Usa una implementaci\u00f3n pura basada en Haversine y devuelve un n\u00famero no negativo.",
    "type": "function",
    "filePath": "services/api/src/modules/match/geo-distance.js",
    "badges": [
        "public"
    ]
}

Data & fields

[
    {
        "name": "EARTH_RADIUS_KM",
        "type": "number",
        "required": true,
        "description": "Radio terrestre usado por la fórmula Haversine. El valor exportado es 6371."
    }
]

La constante se exporta para que otros módulos usen exactamente el mismo valor que la fórmula. La suite de pruebas de Match verifica explícitamente que el valor exportado es 6371.

Behaviors

  • toRadians(degrees) — convierte grados a radianes para alimentar la fórmula de distancia.
  • haversineDistanceKm(lat1, lng1, lat2, lng2) — calcula la distancia de gran círculo en kilómetros entre dos coordenadas y retorna un number.
  • haversineDistanceKm(...) — preserva la simetría matemática de la distancia y produce siempre un valor finito para entradas numéricas válidas. fileciteturn0file1turn0file15

Parámetros de haversineDistanceKm

[
    {
        "name": "lat1",
        "type": "number",
        "required": true,
        "description": "Latitud del primer punto, en grados."
    },
    {
        "name": "lng1",
        "type": "number",
        "required": true,
        "description": "Longitud del primer punto, en grados."
    },
    {
        "name": "lat2",
        "type": "number",
        "required": true,
        "description": "Latitud del segundo punto, en grados."
    },
    {
        "name": "lng2",
        "type": "number",
        "required": true,
        "description": "Longitud del segundo punto, en grados."
    }
]

La función resta las coordenadas, convierte esas diferencias a radianes y calcula el arco central con Math.atan2. Después multiplica por EARTH_RADIUS_KM. El archivo documenta que el retorno es una distancia en kilómetros y que siempre es >= 0.

Gotchas & edge cases

[!WARNING] Este módulo no protege contra coordenadas fuera de rango. La validación de rangos no ocurre aquí, así que este archivo debe recibir datos ya filtrados por la capa que lo llama. fileciteturn0file1turn0file9

[!NOTE] El punto (0, 0) es un valor válido. La suite de pruebas confirma que no se interpreta como “ausente”, sino como una coordenada calculable.

[!TIP] El archivo está diseñado como una utilidad pura. No consulta Mongo, no muta argumentos y no depende de Date.now() ni de otros efectos externos.

services/api/src/modules/match/comparison-contract.js importa haversineDistanceKm desde este módulo para resolver la geografía de radio de Match. Ese contrato usa la distancia para comparar zonas declaradas del Requirement contra la ubicación del Offer. fileciteturn0file9turn0file6

services/api/test/match-m2.2-geography.test.js cubre este archivo con verificaciones de distancia cero, simetría, el valor de EARTH_RADIUS_KM y un caso representativo de distancia sobre el ecuador. fileciteturn0file2turn0file15

Updated