refactor: replace fake_online_state integer with typed mcu2_online_ch… (#5245)

* refactor: replace fake_online_state integer with typed mcu2_online_check atom

The integer values 0/1/2/3 were undocumented magic numbers that required
reading multiple comments to understand. Replace with a self-documenting
atom enum:

  :idle            – no MCU2 check in progress (was: 0)
  :probing         – stream connected, awaiting first power reading (was: 1)
  :confirmed_fake  – stream reported power=nil, subsystem wakeup (was: 2)
  :confirmed_real  – stream reported numeric power, genuine wakeup (was: 3)

No behaviour changes.

Author: brianmay

lib/teslamate/vehicles/vehicle.ex

@@ -25,11 +25,18 @@ defmodule TeslaMate.Vehicles.Vehicle do
               task: nil,
               import?: false,
               stream_pid: nil,
-              # fake_online_state is introduced because older cars upgraded to MCU2 have a little wakeup every hour to check subsystems.
-              # They report online but if vehicle_data is requested they wake up completely (cars clicks) and is awake for
-              # 15 minutes instead of a 2-3 minutes. The only difference (known at this moment) is that stream reports power=nil
-              # in subsystem online and reports power as a number when it is a real online.
-              fake_online_state: 0
+              # pre_online_check tracks whether an apparent online event is a real wakeup or a brief
+              # subsystem check. Some vehicles (especially MCU2-upgraded cars) wake briefly (~2-3 min)
+              # each hour for subsystem checks and report online, but requesting vehicle_data causes a
+              # full wakeup (~15 min). The distinguishing signal is the streaming API: power=nil means
+              # a subsystem check (fake online), a numeric power value means a genuine wakeup (real online).
+              #
+              # Values:
+              #   :idle             – no pre-online check in progress (default)
+              #   :probing          – stream connected, waiting for first power reading
+              #   :confirmed_fake   – stream reported power=nil, treating as fake online
+              #   :confirmed_real   – stream reported numeric power, treating as real online
+              pre_online_check: :idle
   end
 
   @asleep_interval 30
@@ -355,30 +362,29 @@ defmodule TeslaMate.Vehicles.Vehicle do
 
                 {:ok, pid} = connect_stream(data)
 
-                {:keep_state, %Data{data | stream_pid: pid, fake_online_state: 1},
+                {:keep_state, %Data{data | stream_pid: pid, pre_online_check: :probing},
                  [broadcast_fetch(false), schedule_fetch(@asleep_interval, data)]}
 
               {%CarSettings{use_streaming_api: true}, state, %Data{stream_pid: pid}}
               when state in [:asleep, :offline] and is_pid(pid) ->
                 case data do
-                  %Data{fake_online_state: 1} ->
+                  %Data{pre_online_check: :probing} ->
                     # Under normal circumstances stream always give data within @asleep_interval (30s)
                     # otherwise detect it here and allow vehicle_data in next fetch
                     Logger.info("Stream connected, but nothing received, allow real online",
                       car_id: data.car.id
                     )
 
-                    # fetch now and go through regular :start -> :online by setting fake_online_state=3
-                    {:keep_state, %Data{data | fake_online_state: 3},
+                    {:keep_state, %Data{data | pre_online_check: :confirmed_real},
                      [broadcast_fetch(false), schedule_fetch(0, data)]}
 
-                  %Data{fake_online_state: 0} ->
+                  %Data{pre_online_check: :idle} ->
                     Logger.warning(
-                      "Stream connected, but fake_online_state is 0, shouldnt be possible, allow real online",
+                      "Stream connected, but pre_online_check is :idle, shouldn't be possible, allow real online",
                       car_id: data.car.id
                     )
 
-                    {:keep_state, %Data{data | fake_online_state: 3},
+                    {:keep_state, %Data{data | pre_online_check: :confirmed_real},
                      [broadcast_fetch(false), schedule_fetch(0, data)]}
 
                   %Data{} ->
@@ -393,7 +399,8 @@ defmodule TeslaMate.Vehicles.Vehicle do
                   car_id: data.car.id
                 )
 
-                data =
+                %Data{} =
+                  data =
                   with %Data{last_response: nil} <- data do
                     {last_response, geofence} = restore_last_known_values(vehicle, data)
                     %Data{data | last_response: last_response, geofence: geofence}
@@ -402,7 +409,7 @@ defmodule TeslaMate.Vehicles.Vehicle do
                 {:ok, pid} = connect_stream(data)
 
                 {:next_state, {:offline, @asleep_interval},
-                 %Data{data | stream_pid: pid, fake_online_state: 1},
+                 %Data{data | stream_pid: pid, pre_online_check: :probing},
                  [broadcast_fetch(false), schedule_fetch(@asleep_interval, data)]}
 
               {%CarSettings{use_streaming_api: true}, _state, %Data{}} ->
@@ -422,13 +429,14 @@ defmodule TeslaMate.Vehicles.Vehicle do
         # (in that case we won't go through Start / :offline or Start / :asleep)
         :ok = disconnect_stream(data)
 
-        data =
+        %Data{} =
+          data =
           with %Data{last_response: nil} <- data do
             {last_response, geofence} = restore_last_known_values(vehicle, data)
             %Data{data | last_response: last_response, geofence: geofence}
           end
 
-        {:keep_state, %Data{data | fake_online_state: 0, stream_pid: nil},
+        {:keep_state, %Data{data | pre_online_check: :idle, stream_pid: nil},
          [
            broadcast_fetch(false),
            {:next_event, :internal, {:update, {String.to_existing_atom(state), vehicle}}}
@@ -524,26 +532,30 @@ defmodule TeslaMate.Vehicles.Vehicle do
   #### sleep or offline
   # stream is started in def handle_event(:info, {ref, fetch_result}, state, %Data{task: %Task{ref: ref}} = data)
 
-  def handle_event(:info, {:stream, %Stream.Data{} = stream_data}, {state, _}, data)
+  def handle_event(:info, {:stream, %Stream.Data{} = stream_data}, {state, _}, %Data{} = data)
       when state in [:asleep, :offline] do
     case stream_data do
       %Stream.Data{power: nil} ->
         Logger.debug(inspect(stream_data), car_id: data.car.id)
 
-        # stay on stream, keep asking if online and see if a real one appears
-        # set to 2 to avoid triggering real online in fetch_result (fallback if stream doesn't work)
+        # Stay on stream and keep waiting to see if a real online appears.
+        # Transition to :confirmed_fake so the fetch fallback (if stream stalls) won't
+        # re-trigger a confirmed_real promotion.
         case data do
-          %Data{fake_online_state: 1} ->
-            Logger.info("Fake online: power is nil", car_id: data.car.id)
-            {:keep_state, %Data{data | fake_online_state: 2}}
+          %Data{pre_online_check: :probing} ->
+            Logger.info("Subsystem check detected: power is nil, treating as fake online",
+              car_id: data.car.id
+            )
 
-          %Data{fake_online_state: 0} ->
+            {:keep_state, %Data{data | pre_online_check: :confirmed_fake}}
+
+          %Data{pre_online_check: :idle} ->
             Logger.warning(
-              "Fake online: power is nil, but fake_online_state is 0, shouldnt be possible, allow real online",
+              "Subsystem check detected: power is nil, but pre_online_check is :idle, shouldn't be possible, treating as fake online",
               car_id: data.car.id
             )
 
-            {:keep_state, %Data{data | fake_online_state: 2}}
+            {:keep_state, %Data{data | pre_online_check: :confirmed_fake}}
 
           %Data{} ->
             :keep_state_and_data
@@ -553,22 +565,23 @@ defmodule TeslaMate.Vehicles.Vehicle do
         Logger.debug(inspect(stream_data), car_id: data.car.id)
 
         case data do
-          %Data{fake_online_state: fake_online_state}
-          when is_number(fake_online_state) and fake_online_state in [1, 2] ->
+          %Data{pre_online_check: check} when check in [:probing, :confirmed_fake] ->
             Logger.info("Real online detected: power is a number", car_id: data.car.id)
-            # fetch now and go through regular :start -> :online by setting fake_online_state=3
-            {:keep_state, %Data{data | fake_online_state: 3}, schedule_fetch(0, data)}
 
-          %Data{fake_online_state: 0} ->
+            {:keep_state, %Data{data | pre_online_check: :confirmed_real},
+             schedule_fetch(0, data)}
+
+          %Data{pre_online_check: :idle} ->
             Logger.warning(
-              "Real online detected: power is a number, but fake_online_state is 0, shouldnt be possible, allow real online",
+              "Real online detected: power is a number, but pre_online_check is :idle, shouldn't be possible, treating as real online",
               car_id: data.car.id
             )
 
-            {:keep_state, %Data{data | fake_online_state: 3}, schedule_fetch(0, data)}
+            {:keep_state, %Data{data | pre_online_check: :confirmed_real},
+             schedule_fetch(0, data)}
 
           %Data{} ->
-            # fake_online_state already set to 3, dont fetch again to avoid 'Fetch already in progress ...'
+            # pre_online_check already :confirmed_real — don't fetch again to avoid 'Fetch already in progress'
             :keep_state_and_data
         end
 
@@ -911,7 +924,7 @@ defmodule TeslaMate.Vehicles.Vehicle do
     :ok = disconnect_stream(data)
 
     {:next_state, {:asleep, asleep_interval()},
-     %{data | last_state_change: last_state_change, stream_pid: nil, fake_online_state: 0},
+     %{data | last_state_change: last_state_change, stream_pid: nil, pre_online_check: :idle},
      [broadcast_summary(), schedule_fetch(data)]}
   end
 
@@ -924,7 +937,7 @@ defmodule TeslaMate.Vehicles.Vehicle do
     :ok = disconnect_stream(data)
 
     {:next_state, {:offline, asleep_interval()},
-     %{data | last_state_change: last_state_change, stream_pid: nil, fake_online_state: 0},
+     %{data | last_state_change: last_state_change, stream_pid: nil, pre_online_check: :idle},
      [broadcast_summary(), schedule_fetch(data)]}
   end
 
@@ -1485,7 +1498,7 @@ defmodule TeslaMate.Vehicles.Vehicle do
 
             {state, _} when state in [:asleep, :offline] ->
               case data do
-                %Data{fake_online_state: 3} -> true
+                %Data{pre_online_check: :confirmed_real} -> true
                 %Data{} -> false
               end