Arquitectura Técnica
| Servicio | Responsabilidad | Comandos (write) | Consultas (read) |
|---|---|---|---|
| fth-tracks | Ingesta, parseo, ownership e idempotencia de tracks. | POST /v1/tracks, PATCH /status, DELETE |
GET /v1/tracks/{id}, GET /original |
| fth-analyzer | Segmentación hike/fly/rest, métricas y catálogo derivado. | POST /v1/analyze, moderación y feedback |
GET /v1/analysis/{track_id}, GET /v1/activities... |
| fth-competitions | Rulesets, enrollments, scoring y leaderboards. | POST /v1/competitions, POST /score-activity, enroll/zones |
GET /v1/competitions..., GET /v1/leaderboards... |
| fth-orchestrator | Sagas/jobs asíncronos y coordinación entre servicios. | POST /v1/sagas/process-track, jobs/retry/recovery |
GET /v1/jobs..., GET /v1/sagas... |
Contratos entre Servicios
-
Header de identidad:
X-User-Idse usa como identidad operativa para ownership y consultas. -
Contrato Tracks → Analyzer:
analyzer consume
GET /v1/tracks/{track_id}?response_mode=full. - Contrato Analyzer → Competitions: competitions consulta actividad/segmentos y aplica scoring por actividad.
-
Contrato Orchestrator → Competitions:
scoring real por comando
POST /v1/competitions/{id}/score-activity. - IDs públicos: analyzer y competitions usan ULID en entidades API públicas (actividad, competición, sitios/rutas).
Ranking y Reglas Técnicas
El ranking se define por ruleset versionado por categoría. Categorías soportadas en competiciones:
Hike, Fly,
HikeFly, Combo,
Club y General.
Flujo de scoring: validar competición + período, resolver enrollment/auto_enroll, aplicar reglas por categoría, persistir scores por actividad y recalcular leaderboards de participante/club.
En configuración típica global: General agrega top resultados de HikeFly + Combo (por ejemplo top15 HikeFly y top4 combo) según parámetros del ruleset cargado.
Analyzer: Parámetros que Separan y Puntúan Segmentos
| Parámetro | Default | Uso |
|---|---|---|
fly_min_mps |
6.0 | Umbral principal de velocidad horizontal para activar vuelo. |
takeoff_confirm_sec |
8.0 | Tiempo mínimo para confirmar transición ground → sustain. |
sustain_confirm_sec |
60.0 | Tiempo sostenido para confirmar sustain → flight. |
landing_speed_max |
3.0 | Velocidad máxima para detectar aterrizaje. |
landing_confirm_sec |
10.0 | Persistencia requerida para confirmar flight → ground. |
ma_period_sec |
10.0 | Ventana de medias móviles (hma/vma) usada por la máquina de estados. |
takeoff_vma_activate |
0.9 | Vario mínimo para activar candidato de despegue. |
takeoff_vma_sustain |
0.05 | Vario mínimo para mantener fase de sustain. |
sustain_hspeed_mps |
1.5 | Velocidad horizontal mínima durante sustain. |
gap_tolerance_sec |
5.0 | Tolerancia para fusionar subtramos de vuelo separados por gaps cortos. |
scoring_ruleset |
XContest | Ruleset para fly_metrics (FFVL/XContest/FAI/XCLeague). |
Validez funcional de segmentos:
hike.valid = elev_gain_m >= 200
fly.valid = max(elev_gain_m, elev_loss_m) >= 200
Además, para crear enlaces a sitios desde fly se exige
FLY_SITE_CONFIDENCE_MIN (default 0.85).
Notas de Implementación
- El catálogo de rutas hike se nutre de segmentos hike válidos y matching por Fréchet + ratio de longitud.
- La puntuación de vuelo evalúa modos (free 3TP, triángulos, O&R) y selecciona mejor modo por reglas del ruleset.
- Los leaderboards son proyecciones recalculables: separación explícita comando (scoring) vs consulta (ranking).
- La frontera de seguridad asume red interna para llamadas de servicio a servicio; si se expone públicamente, hay que reforzar validación de propietario.