From 87e5bcae5bc68c1bb1b5d2fd1b3aaef771a8b933 Mon Sep 17 00:00:00 2001
From: "Jan-Peter v. Hunnius" <jan@hunnius.net>
Date: Fri, 5 Jun 2026 21:28:27 +0200
Subject: [PATCH] feat: align frontend with rusty-telemetry v0.5.0 API changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update ShiftPointAnalysis types: gear_ranges → gear_curves (with
  acceleration data points), shift_events → crossover_points, add
  runs_analyzed field
- Add UseCaseInfo type for GET /api/use-cases (now returns objects
  with id, name, guidance instead of plain strings)
- Add guidance and recording_id fields to UseCaseSession
- Rewrite ShiftPointsView: scatter chart for gear acceleration curves,
  dual y-axis bar chart for crossover RPM/speed, 4-column summary
- Update SessionDetailView: show session guidance, crossover points
  and runs analyzed in analysis stats
- Extract shared type guard functions into src/utils/analysis.ts
- Type getAnalysis/reAnalyze as AnalysisResult instead of
  Record<string, unknown>
- Type getGames return as string[] to match backend
---
 src/api/client.ts               |  20 ++--
 src/stores/sessions.ts          |   4 +-
 src/types/index.ts              |  38 ++++++--
 src/utils/analysis.ts           |  24 +++++
 src/views/SessionDetailView.vue |  26 ++++--
 src/views/ShiftPointsView.vue   | 158 +++++++++++++++-----------------
 6 files changed, 156 insertions(+), 114 deletions(-)
 create mode 100644 src/utils/analysis.ts

diff --git a/src/api/client.ts b/src/api/client.ts
index 5509c86..c46563c 100644
--- a/src/api/client.ts
+++ b/src/api/client.ts
@@ -7,8 +7,8 @@ import type {
   CreateSessionRequest,
   StartRunRequest,
   SessionRun,
-  UseCase,
-  Game,
+  UseCaseInfo,
+  AnalysisResult,
 } from '@/types'
 
 const api = axios.create({
@@ -93,25 +93,25 @@ export async function completeSession(id: string): Promise<UseCaseSession> {
   return res.data
 }
 
-export async function getAnalysis(id: string): Promise<Record<string, unknown>> {
-  const res = await api.get<Record<string, unknown>>(`/sessions/${id}/analysis`)
+export async function getAnalysis(id: string): Promise<AnalysisResult> {
+  const res = await api.get<AnalysisResult>(`/sessions/${id}/analysis`)
   return res.data
 }
 
-export async function reAnalyze(id: string): Promise<Record<string, unknown>> {
-  const res = await api.post<Record<string, unknown>>(`/sessions/${id}/analyze`)
+export async function reAnalyze(id: string): Promise<AnalysisResult> {
+  const res = await api.post<AnalysisResult>(`/sessions/${id}/analyze`)
   return res.data
 }
 
 // ── Metadata ──
 
-export async function getUseCases(): Promise<UseCase[]> {
-  const res = await api.get<UseCase[]>('/use-cases')
+export async function getUseCases(): Promise<UseCaseInfo[]> {
+  const res = await api.get<UseCaseInfo[]>('/use-cases')
   return res.data
 }
 
-export async function getGames(): Promise<Game[]> {
-  const res = await api.get<Game[]>('/games')
+export async function getGames(): Promise<string[]> {
+  const res = await api.get<string[]>('/games')
   return res.data
 }
 
diff --git a/src/stores/sessions.ts b/src/stores/sessions.ts
index 271ef77..606a40f 100644
--- a/src/stores/sessions.ts
+++ b/src/stores/sessions.ts
@@ -1,6 +1,6 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
-import type { UseCaseSession, CreateSessionRequest, StartRunRequest, SessionRun } from '@/types'
+import type { UseCaseSession, CreateSessionRequest, StartRunRequest, SessionRun, AnalysisResult } from '@/types'
 import * as api from '@/api/client'
 
 export const useSessionsStore = defineStore('sessions', () => {
@@ -110,7 +110,7 @@ export const useSessionsStore = defineStore('sessions', () => {
     }
   }
 
-  async function reAnalyze(id: string): Promise<Record<string, unknown> | null> {
+  async function reAnalyze(id: string): Promise<AnalysisResult | null> {
     try {
       return await api.reAnalyze(id)
     } catch (e: unknown) {
diff --git a/src/types/index.ts b/src/types/index.ts
index 1441e4c..e1d4b56 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -100,6 +100,8 @@ export interface UseCaseSession {
   completed_at: string | null
   runs: SessionRun[]
   analysis: AnalysisResult | null
+  guidance: string | null
+  recording_id: string | null
 }
 
 export interface CreateSessionRequest {
@@ -112,31 +114,49 @@ export interface StartRunRequest {
   label?: string | null
 }
 
+// ── Use Cases ──
+
+export interface UseCaseInfo {
+  id: string
+  name: string
+  guidance: string
+}
+
 // ── Analysis Results ──
 
 // Shift Point Analysis (use_case = "shift_points")
-export interface GearRpmRange {
+export interface GearDataPoint {
+  speed_kmh: number
+  rpm: number
+  acceleration_g: number
+}
+
+export interface GearCurve {
   gear: number
   gear_display: string
+  run_label: string
+  data_points: GearDataPoint[]
   min_rpm: number
   max_rpm: number
-  avg_rpm: number
+  min_speed_kmh: number
+  max_speed_kmh: number
   sample_count: number
 }
 
-export interface ShiftEvent {
+export interface CrossoverPoint {
   from_gear: number
   to_gear: number
-  rpm_before_shift: number
-  rpm_after_shift: number
-  rpm_drop: number
-  speed_kmh: number
+  from_gear_display: string
+  to_gear_display: string
+  crossover_speed_kmh: number
+  crossover_rpm: number
 }
 
 export interface ShiftPointAnalysis {
-  gear_ranges: GearRpmRange[]
-  shift_events: ShiftEvent[]
+  gear_curves: GearCurve[]
+  crossover_points: CrossoverPoint[]
   recommended_shift_rpm: number | null
+  runs_analyzed: number
   total_frames_analyzed: number
 }
 
diff --git a/src/utils/analysis.ts b/src/utils/analysis.ts
new file mode 100644
index 0000000..370f80f
--- /dev/null
+++ b/src/utils/analysis.ts
@@ -0,0 +1,24 @@
+import type { ShiftPointAnalysis, TrackMapAnalysis } from '@/types'
+
+/**
+ * Runtime type guard: checks if an unknown value is a ShiftPointAnalysis.
+ * Uses the 'gear_curves' discriminator field that the backend includes.
+ */
+export function isShiftPointAnalysis(data: unknown): data is ShiftPointAnalysis {
+  return typeof data === 'object' && data !== null && 'gear_curves' in data
+}
+
+/**
+ * Runtime type guard: checks if an unknown value is a TrackMapAnalysis.
+ * Uses the 'boundaries' discriminator field that the backend includes.
+ */
+export function isTrackMapAnalysis(data: unknown): data is TrackMapAnalysis {
+  return typeof data === 'object' && data !== null && 'boundaries' in data
+}
+
+/**
+ * Runtime type guard: checks if an unknown value is a NotImplementedResponse.
+ */
+export function isNotImplemented(data: unknown): data is { status: 'not_implemented'; use_case: string } {
+  return typeof data === 'object' && data !== null && 'status' in data && (data as { status: string }).status === 'not_implemented'
+}
diff --git a/src/views/SessionDetailView.vue b/src/views/SessionDetailView.vue
index abcba7b..c121443 100644
--- a/src/views/SessionDetailView.vue
+++ b/src/views/SessionDetailView.vue
@@ -3,6 +3,7 @@ import { ref, onMounted, computed } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useSessionsStore } from '@/stores/sessions'
 import type { ShiftPointAnalysis, TrackMapAnalysis } from '@/types'
+import { isShiftPointAnalysis, isTrackMapAnalysis } from '@/utils/analysis'
 
 const props = defineProps<{
   id: string
@@ -34,19 +35,16 @@ const analysisData = computed(() => {
 
 const shiftAnalysis = computed((): ShiftPointAnalysis | null => {
   if (!analysisData.value) return null
-  // The analysis field is the full analysis object
-  const data = analysisData.value
-  if (data && typeof data === 'object' && 'gear_ranges' in data) {
-    return data as unknown as ShiftPointAnalysis
+  if (isShiftPointAnalysis(analysisData.value)) {
+    return analysisData.value
   }
   return null
 })
 
 const trackAnalysis = computed((): TrackMapAnalysis | null => {
   if (!analysisData.value) return null
-  const data = analysisData.value
-  if (data && typeof data === 'object' && 'boundaries' in data) {
-    return data as unknown as TrackMapAnalysis
+  if (isTrackMapAnalysis(analysisData.value)) {
+    return analysisData.value
   }
   return null
 })
@@ -147,6 +145,10 @@ async function handleDelete() {
             <span class="info-label">Completed</span>
             <span>{{ formatTime(session.completed_at) }}</span>
           </div>
+          <div v-if="session.guidance" class="info-item" style="grid-column: 1 / -1">
+            <span class="info-label">Guidance</span>
+            <span class="text-secondary" style="font-size: 0.85rem">{{ session.guidance }}</span>
+          </div>
         </div>
       </section>
 
@@ -243,14 +245,18 @@ async function handleDelete() {
           </div>
 
           <!-- Quick stats for shift points -->
-          <div v-if="shiftAnalysis" class="analysis-stats grid grid-2 mb-2">
+          <div v-if="shiftAnalysis" class="analysis-stats grid grid-3 mb-2">
             <div class="stat-card">
               <span class="stat-label">Recommended Shift RPM</span>
               <span class="stat-value mono">{{ Math.round(shiftAnalysis.recommended_shift_rpm ?? 0) }}</span>
             </div>
             <div class="stat-card">
-              <span class="stat-label">Shift Events Detected</span>
-              <span class="stat-value mono">{{ shiftAnalysis.shift_events.length }}</span>
+              <span class="stat-label">Crossover Points</span>
+              <span class="stat-value mono">{{ shiftAnalysis.crossover_points.length }}</span>
+            </div>
+            <div class="stat-card">
+              <span class="stat-label">Runs Analyzed</span>
+              <span class="stat-value mono">{{ shiftAnalysis.runs_analyzed }}</span>
             </div>
           </div>
 
diff --git a/src/views/ShiftPointsView.vue b/src/views/ShiftPointsView.vue
index 4255ec9..06f76ed 100644
--- a/src/views/ShiftPointsView.vue
+++ b/src/views/ShiftPointsView.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref, onMounted, computed } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { Bar, Line } from 'vue-chartjs'
+import { Bar, Scatter } from 'vue-chartjs'
 import {
   Chart as ChartJS,
   CategoryScale,
@@ -15,6 +15,7 @@ import {
   Filler,
 } from 'chart.js'
 import type { ShiftPointAnalysis } from '@/types'
+import { isShiftPointAnalysis } from '@/utils/analysis'
 import * as api from '@/api/client'
 
 ChartJS.register(CategoryScale, LinearScale, BarElement, LineElement, PointElement, Title, Tooltip, Legend, Filler)
@@ -30,8 +31,8 @@ const error = ref<string | null>(null)
 onMounted(async () => {
   try {
     const data = await api.getAnalysis(sessionId.value)
-    if (data && 'gear_ranges' in data) {
-      analysis.value = data as unknown as ShiftPointAnalysis
+    if (isShiftPointAnalysis(data)) {
+      analysis.value = data
     } else {
       error.value = 'Analysis data not available or wrong type'
     }
@@ -42,96 +43,87 @@ onMounted(async () => {
   }
 })
 
-// Gear RPM range chart data
-const gearRangeChartData = computed(() => {
+const gearCurvesChartData = computed(() => {
   if (!analysis.value) return null
-  const ranges = analysis.value.gear_ranges.filter((g) => g.gear >= 1)
+  const curves = analysis.value.gear_curves.filter((g) => g.gear >= 2)
+  const colors = ['#4f8ff7', '#34d399', '#fbbf24', '#f87171', '#a78bfa', '#60a5fa', '#f472b6']
   return {
-    labels: ranges.map((g) => g.gear_display),
-    datasets: [
-      {
-        label: 'Min RPM',
-        data: ranges.map((g) => g.min_rpm),
-        backgroundColor: 'rgba(79, 143, 247, 0.3)',
-        borderColor: 'rgba(79, 143, 247, 0.8)',
-        borderWidth: 1,
-      },
-      {
-        label: 'Avg RPM',
-        data: ranges.map((g) => g.avg_rpm),
-        backgroundColor: 'rgba(52, 211, 153, 0.3)',
-        borderColor: 'rgba(52, 211, 153, 0.8)',
-        borderWidth: 1,
-      },
-      {
-        label: 'Max RPM',
-        data: ranges.map((g) => g.max_rpm),
-        backgroundColor: 'rgba(248, 113, 113, 0.3)',
-        borderColor: 'rgba(248, 113, 113, 0.8)',
-        borderWidth: 1,
-      },
-    ],
+    datasets: curves.map((curve, i) => ({
+      label: `${curve.gear_display} (${curve.run_label})`,
+      data: curve.data_points.map((p) => ({ x: p.speed_kmh, y: p.acceleration_g })),
+      borderColor: colors[i % colors.length],
+      backgroundColor: colors[i % colors.length] + '20',
+      showLine: true,
+      fill: false,
+      tension: 0.3,
+      pointRadius: 0,
+      borderWidth: 2,
+    })),
   }
 })
 
-const gearRangeOptions = {
+const gearCurvesOptions = {
   responsive: true,
   plugins: {
     legend: { labels: { color: '#8b8fa3' } },
-    title: { display: true, text: 'Gear RPM Ranges', color: '#e2e4ea' },
+    title: { display: true, text: 'Gear Acceleration Curves', color: '#e2e4ea' },
   },
   scales: {
-    x: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' } },
-    y: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' }, title: { display: true, text: 'RPM', color: '#8b8fa3' } },
+    x: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' }, title: { display: true, text: 'Speed (km/h)', color: '#8b8fa3' } },
+    y: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' }, title: { display: true, text: 'Acceleration (g)', color: '#8b8fa3' } },
   },
 }
 
-// Shift events timeline data
-const shiftEventsChartData = computed(() => {
-  if (!analysis.value || analysis.value.shift_events.length === 0) return null
-  const events = analysis.value.shift_events
+const crossoverChartData = computed(() => {
+  if (!analysis.value || analysis.value.crossover_points.length === 0) return null
+  const points = analysis.value.crossover_points
   return {
-    labels: events.map((_, i) => `#${i + 1}`),
+    labels: points.map((p) => `${p.from_gear_display} → ${p.to_gear_display}`),
     datasets: [
       {
-        label: 'RPM Before Shift',
-        data: events.map((e) => e.rpm_before_shift),
-        borderColor: 'rgba(248, 113, 113, 1)',
-        backgroundColor: 'rgba(248, 113, 113, 0.1)',
-        fill: false,
-        tension: 0.2,
-        pointRadius: 4,
+        label: 'Crossover RPM',
+        data: points.map((p) => p.crossover_rpm),
+        backgroundColor: 'rgba(79, 143, 247, 0.5)',
+        borderColor: 'rgba(79, 143, 247, 1)',
+        borderWidth: 1,
+        yAxisID: 'y',
       },
       {
-        label: 'RPM After Shift',
-        data: events.map((e) => e.rpm_after_shift),
+        label: 'Crossover Speed (km/h)',
+        data: points.map((p) => p.crossover_speed_kmh),
+        backgroundColor: 'rgba(52, 211, 153, 0.5)',
         borderColor: 'rgba(52, 211, 153, 1)',
-        backgroundColor: 'rgba(52, 211, 153, 0.1)',
-        fill: false,
-        tension: 0.2,
-        pointRadius: 4,
+        borderWidth: 1,
+        yAxisID: 'y1',
       },
     ],
   }
 })
 
-const shiftEventsOptions = {
+const crossoverChartOptions = {
   responsive: true,
   plugins: {
     legend: { labels: { color: '#8b8fa3' } },
-    title: { display: true, text: 'Shift Events — RPM Before/After', color: '#e2e4ea' },
+    title: { display: true, text: 'Crossover Points', color: '#e2e4ea' },
   },
   scales: {
     x: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' } },
-    y: { ticks: { color: '#8b8fa3' }, grid: { color: '#2a2e3f' }, title: { display: true, text: 'RPM', color: '#8b8fa3' } },
+    y: {
+      type: 'linear' as const,
+      position: 'left' as const,
+      ticks: { color: '#4f8ff7' },
+      grid: { color: '#2a2e3f' },
+      title: { display: true, text: 'RPM', color: '#4f8ff7' },
+    },
+    y1: {
+      type: 'linear' as const,
+      position: 'right' as const,
+      ticks: { color: '#34d399' },
+      grid: { drawOnChartArea: false },
+      title: { display: true, text: 'Speed (km/h)', color: '#34d399' },
+    },
   },
 }
-
-function gearLabel(gear: number): string {
-  if (gear === -1) return 'R'
-  if (gear === 0) return 'N'
-  return gear.toString()
-}
 </script>
 
 <template>
@@ -146,14 +138,18 @@ function gearLabel(gear: number): string {
 
     <template v-else-if="analysis">
       <!-- Summary Stats -->
-      <div class="grid grid-3 mb-3">
+      <div class="grid grid-4 mb-3">
         <div class="card stat-card">
           <span class="stat-label">Recommended Shift RPM</span>
           <span class="stat-value mono">{{ Math.round(analysis.recommended_shift_rpm ?? 0) }}</span>
         </div>
         <div class="card stat-card">
-          <span class="stat-label">Shift Events</span>
-          <span class="stat-value mono">{{ analysis.shift_events.length }}</span>
+          <span class="stat-label">Crossover Points</span>
+          <span class="stat-value mono">{{ analysis.crossover_points.length }}</span>
+        </div>
+        <div class="card stat-card">
+          <span class="stat-label">Runs Analyzed</span>
+          <span class="stat-value mono">{{ analysis.runs_analyzed }}</span>
         </div>
         <div class="card stat-card">
           <span class="stat-label">Frames Analyzed</span>
@@ -161,20 +157,20 @@ function gearLabel(gear: number): string {
         </div>
       </div>
 
-      <!-- Gear RPM Ranges Chart -->
-      <div v-if="gearRangeChartData" class="card mb-3">
-        <Bar :data="gearRangeChartData" :options="gearRangeOptions" />
+      <!-- Gear Acceleration Curves Chart -->
+      <div v-if="gearCurvesChartData" class="card mb-3">
+        <Scatter :data="gearCurvesChartData" :options="gearCurvesOptions" />
       </div>
 
-      <!-- Shift Events Chart -->
-      <div v-if="shiftEventsChartData" class="card mb-3">
-        <Line :data="shiftEventsChartData" :options="shiftEventsOptions" />
+      <!-- Crossover Points Chart -->
+      <div v-if="crossoverChartData" class="card mb-3">
+        <Bar :data="crossoverChartData" :options="crossoverChartOptions" />
       </div>
 
-      <!-- Shift Events Table -->
-      <div v-if="analysis.shift_events.length > 0" class="card">
+      <!-- Crossover Points Table -->
+      <div v-if="analysis.crossover_points.length > 0" class="card">
         <div class="card-header">
-          <h2>Shift Events Detail</h2>
+          <h2>Crossover Points</h2>
         </div>
         <div class="table-wrap">
           <table>
@@ -182,20 +178,16 @@ function gearLabel(gear: number): string {
               <tr>
                 <th>#</th>
                 <th>From → To</th>
-                <th>RPM Before</th>
-                <th>RPM After</th>
-                <th>RPM Drop</th>
-                <th>Speed (km/h)</th>
+                <th>Crossover RPM</th>
+                <th>Crossover Speed (km/h)</th>
               </tr>
             </thead>
             <tbody>
-              <tr v-for="(event, i) in analysis.shift_events" :key="i">
+              <tr v-for="(point, i) in analysis.crossover_points" :key="i">
                 <td class="mono">{{ i + 1 }}</td>
-                <td>{{ gearLabel(event.from_gear) }} → {{ gearLabel(event.to_gear) }}</td>
-                <td class="mono">{{ Math.round(event.rpm_before_shift) }}</td>
-                <td class="mono">{{ Math.round(event.rpm_after_shift) }}</td>
-                <td class="mono">{{ Math.round(event.rpm_drop) }}</td>
-                <td class="mono">{{ Math.round(event.speed_kmh) }}</td>
+                <td>{{ point.from_gear_display }} → {{ point.to_gear_display }}</td>
+                <td class="mono">{{ Math.round(point.crossover_rpm) }}</td>
+                <td class="mono">{{ point.crossover_speed_kmh.toFixed(1) }}</td>
               </tr>
             </tbody>
           </table>