Objetivo del producto
HF Earth transforma tracks GPX/IGC en actividades Hike & Fly, detecta tramos válidos de hike/fly, calcula métricas y publica puntuación en competiciones. El objetivo es tener resultados consistentes para usuario final (catálogo de actividades) y para ranking (leaderboards por categorías).
Modelo de Dominio
Archivo y Track
El usuario sube un archivo (GPX/IGC). El sistema genera un track_id
por hash SHA-256 del contenido normalizado.
Actividad
Contenedor funcional de un día/jornada o secuencia continua. Tiene public_id
ULID y un resumen agregado (distancia, duración, desnivel, fases).
Segmento
Tramo homogéneo detectado por el analyzer: hike,
fly o rest.
Cada segmento incluye geometría, métricas y validez.
Sitios y Rutas
De segmentos válidos se derivan sitios (takeoff/landing) y
rutas de hike recurrentes (hike_routes).
Competición y Enrollment
Una competición define período + ruleset versionado. El enrollment asocia usuario (y opcionalmente club) a la competición para scoring.
Score y Leaderboard
El servicio de competiciones persiste score por actividad/categoría y mantiene proyecciones de ranking de participantes y clubs.
Decisiones Clave
-
Idempotencia de track:
el mismo archivo genera el mismo
track_id. Si ya existe y pertenece al mismo usuario se devuelve recurso existente; si pertenece a otro, conflicto. - Continuidad de actividad: se evalúa distancia/tiempo entre actividad previa y nueva para decidir continuidad o nueva actividad.
- Validez por desnivel: hike válido si gana desnivel mínimo; fly válido si cambio vertical (ganancia o pérdida) supera umbral.
- Confianza para catálogo: los segmentos fly con baja confianza no crean enlaces a sitios para reducir falsos positivos.
- Moderación: segmentos, rutas y sitios son moderables; los segmentos excluidos no participan por defecto en consultas y scoring.
- Scoring por ruleset: cálculo de vuelo configurable por reglas (XContest por defecto) y puntuación de competición separada por categorías.
Flujo Funcional
-
1. Usuario sube track a
fth-tracksy se encola la saga de procesado. -
2. Orchestrator valida track, lanza análisis en
fth-analyzery actualiza estado del track. - 3. Analyzer segmenta hike/fly/rest, calcula métricas, persiste actividad/segmentos/eventos y enlaza sitios/rutas cuando aplica.
-
4. Orchestrator solicita scoring en
fth-competitionspara global anual y competiciones activas del usuario. - 5. Competitions guarda puntos por categoría y actualiza leaderboards de participantes/clubs.
- 6. Se notifica resultado y el backoffice permite revisión, moderación y reanálisis cuando sea necesario.
Estados y Resultado Operativo
| Entidad | Estados / Resultado |
|---|---|
| Track | uploaded, analysis_queued, analysis_running, analyzed, approved, analysis_failed, archived |
| Segmento | kind (hike/fly/rest) + valid + moderación (excluido/activo) |
| Actividad | Resumen agregable, fecha de actividad, continuidad con historial de usuario |
| Competición | draft, active, archived + ruleset versionado por categorías |