Skip to content

Route Optimization Runs

Status: ✅ Shipped — route_optimization_runs telemetry (WO-SB-RO2) is fully wired: two player-facing producer endpoints, a player-facing read-your-own-history endpoint, and an admin NH18 dashboard consumer. Previously undocumented beyond a bare migrations.md table row.

Append-only run-log of successful route-optimizer calls. It exists purely to give the admin dashboard a real feed and let players inspect their own optimization history — nothing in the game reads this table transactionally, and a failed insert never fails the player's actual request.

Schema

RouteOptimizationRun (table route_optimization_runs):

Field Type Notes
id UUID PK
player_id UUID FK → players.id CASCADE on delete, indexed
objective string(32) shortest | profit | risk | balanced | ai_trading
start_sector string(64)
end_sector string(64), nullable
sectors JSONB ordered list of sector ids the route passes through
total_profit float
total_distance int
total_time_hours float
cargo_efficiency float
route_confidence float
status string(16), default completed
created_at timestamptz, indexed

Source: services/gameserver/src/models/route_optimization_run.py.

Producers (two endpoints, both best-effort)

  • POST /routes/optimize (route_optimizer.py) — the player-facing graph route optimizer; objective ∈ shortest/profit/risk/balanced. On a successful response, _record_optimization_run inserts a row.
  • POST /ai/optimize-route (ai.py) — AI-driven optimizer; recorded with objective="ai_trading".

Both wrap the insert in try/except: a logging failure logs the error and rolls back the telemetry write only — it never propagates into the player's actual optimize response. This is deliberate (see the model's own docstring) — the table is pure telemetry, not part of the request's success contract.

Consumers

  • Player self-history — GET /routes/... (route_optimizer.py) returns the current player's own rows only, newest first, capped at 50 (_HISTORY_LIMIT_MAX), limit query param (default 10). Strictly scoped to current_player.id — never another player's rows regardless of the limit value passed.
  • Admin NH18 dashboard — GET /admin/ai/route-optimization (admin_comprehensive.py) — total run count, recent runs, average cargo efficiency / profit, and an active-window count (runs since a cutoff). Backs the admin RouteOptimizationDisplay UI panel.

What this is not

Not a queue, not a cache, not consulted by the route optimizer itself when computing a route — purely an append-only record of past successful calls, read by the two consumers above and nothing else.

Source map

Concern Path
Model services/gameserver/src/models/route_optimization_run.py
Migration cdea102d345b_add_route_optimization_runs.py
Player producer + self-history services/gameserver/src/api/routes/route_optimizer.py
AI producer services/gameserver/src/api/routes/ai.py
Admin NH18 consumer services/gameserver/src/api/routes/admin_comprehensive.py