From 990666f38e1095ed8b971ec57ea1fa9897da6c73 Mon Sep 17 00:00:00 2001 From: AvianJay Date: Thu, 19 Nov 2026 07:45:26 +0800 Subject: [PATCH 1/5] feat: improve smart route recommendations and Android reminders Learn route habits from dated visits and share a reminder plan with Android. Look up arrivals at the actual stop, keep full-width stop IDs in notification launches, and cover the plan, database and launch contract with regression tests. --- .../taiwanbus/flutter/MainActivity.kt | 9 + .../SmartRouteNotificationScheduler.kt | 64 +- .../flutter/SmartRouteNotificationWorker.kt | 884 ++++------ .../flutter/SmartRouteReminderRules.kt | 528 ++++++ .../taiwanbus/flutter/AppLaunchStopIdTest.kt | 92 +- .../taiwanbus/flutter/LastBusMessageTest.kt | 42 - .../SmartRouteNotificationDatabaseTest.kt | 210 +++ .../flutter/SmartRouteReminderRulesTest.kt | 819 +++++++++ .../flutter/SmartRouteReminderStoreTest.kt | 109 ++ lib/core/android_home_integration.dart | 29 + lib/core/app_controller.dart | 175 +- lib/core/bus_repository.dart | 24 + lib/core/models.dart | 155 +- lib/core/smart_route_habit.dart | 417 +++++ lib/core/smart_route_plan.dart | 391 +++++ lib/core/smart_route_service.dart | 637 ++++--- lib/core/storage_service.dart | 14 + lib/l10n/app_en.arb | 6 +- lib/l10n/app_localizations.dart | 6 +- lib/l10n/app_localizations_en.dart | 6 +- lib/l10n/app_localizations_zh.dart | 12 +- lib/l10n/app_zh.arb | 6 +- lib/l10n/app_zh_TW.arb | 6 +- lib/screens/route_detail_screen.dart | 34 + test/fixtures/smart_route_plan_v1.json | 102 ++ .../fixtures/smart_route_reminder_log_v1.json | 16 + test/smart_route_habit_test.dart | 444 +++++ test/smart_route_plan_controller_test.dart | 409 +++++ test/smart_route_plan_test.dart | 501 ++++++ test/smart_route_service_test.dart | 1470 +++++++++++------ test/support/route_usage_fixtures.dart | 50 + 31 files changed, 6231 insertions(+), 1436 deletions(-) create mode 100644 android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt create mode 100644 android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationDatabaseTest.kt create mode 100644 android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt create mode 100644 android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt create mode 100644 lib/core/smart_route_habit.dart create mode 100644 lib/core/smart_route_plan.dart create mode 100644 test/fixtures/smart_route_plan_v1.json create mode 100644 test/fixtures/smart_route_reminder_log_v1.json create mode 100644 test/smart_route_habit_test.dart create mode 100644 test/smart_route_plan_controller_test.dart create mode 100644 test/smart_route_plan_test.dart create mode 100644 test/support/route_usage_fixtures.dart diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/MainActivity.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/MainActivity.kt index b91cb620..67378d95 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/MainActivity.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/MainActivity.kt @@ -94,6 +94,15 @@ class MainActivity : FlutterActivity() { result.success(null) } + "getSmartRouteReminderLog" -> { + result.success(SmartRouteNotificationSupport.loadReminderLog(this)) + } + + "forgetSmartRouteReminders" -> { + SmartRouteNotificationSupport.forgetReminders(this) + result.success(null) + } + "setApplicationInForeground" -> { val appInForeground = call.argument("appInForeground") ?: false AppRuntimeStateStore.setAppInForeground(this, appInForeground) diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt index a6ab3fa6..a13e18f3 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt @@ -7,23 +7,20 @@ import androidx.work.NetworkType import androidx.work.PeriodicWorkRequestBuilder import androidx.work.WorkManager import java.util.concurrent.TimeUnit -import org.json.JSONArray -import org.json.JSONObject object SmartRouteNotificationScheduler { private const val WORK_NAME = "smart_route_notification_refresh" - private const val MIN_TOTAL_OPENS_FOR_RECOMMENDATION = 3 - private const val FLUTTER_PREFERENCES_NAME = "FlutterSharedPreferences" - private const val SETTINGS_KEY = "flutter.app_settings" - private const val SETTINGS_FALLBACK_KEY = "app_settings" - private const val ROUTE_USAGE_KEY = "flutter.route_usage_profiles" - private const val ROUTE_USAGE_FALLBACK_KEY = "route_usage_profiles" - private const val SETTINGS_NOTIFICATIONS_ENABLED_KEY = "enableSmartRouteNotifications" + /** + * Runs the background check only while there is something for it to do: + * the setting is on and the plan still holds a habit that has not lapsed. + */ fun sync(context: Context, enabled: Boolean) { - val workManager = WorkManager.getInstance(context) - if (!enabled || !hasLearnedRoutes(context)) { - workManager.cancelUniqueWork(WORK_NAME) + val plan = if (enabled) SmartRouteNotificationSupport.loadPlan(context) else null + if (plan == null || + !SmartRouteReminderRules.hasLiveSlots(plan, System.currentTimeMillis()) + ) { + cancel(context) return } @@ -36,51 +33,14 @@ object SmartRouteNotificationScheduler { .build(), ).build() - workManager.enqueueUniquePeriodicWork( + WorkManager.getInstance(context).enqueueUniquePeriodicWork( WORK_NAME, ExistingPeriodicWorkPolicy.UPDATE, request, ) } - fun syncFromPreferences(context: Context) { - sync(context, loadEnabledFromPreferences(context)) - } - - private fun loadEnabledFromPreferences(context: Context): Boolean { - val preferences = context.getSharedPreferences( - FLUTTER_PREFERENCES_NAME, - Context.MODE_PRIVATE, - ) - val raw = preferences.getString(SETTINGS_KEY, null) - ?: preferences.getString(SETTINGS_FALLBACK_KEY, null) - ?: return false - return try { - JSONObject(raw).optBoolean(SETTINGS_NOTIFICATIONS_ENABLED_KEY, false) - } catch (_: Exception) { - false - } - } - - private fun hasLearnedRoutes(context: Context): Boolean { - val preferences = context.getSharedPreferences( - FLUTTER_PREFERENCES_NAME, - Context.MODE_PRIVATE, - ) - val raw = preferences.getString(ROUTE_USAGE_KEY, null) - ?: preferences.getString(ROUTE_USAGE_FALLBACK_KEY, null) - ?: return false - return try { - val profiles = JSONArray(raw) - for (index in 0 until profiles.length()) { - val item = profiles.optJSONObject(index) ?: continue - if (item.optInt("totalOpens", 0) >= MIN_TOTAL_OPENS_FOR_RECOMMENDATION) { - return true - } - } - false - } catch (_: Exception) { - false - } + fun cancel(context: Context) { + WorkManager.getInstance(context).cancelUniqueWork(WORK_NAME) } } diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt index f9bf43ce..5aa82400 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt @@ -10,6 +10,7 @@ import android.content.pm.PackageManager import android.database.sqlite.SQLiteDatabase import android.location.Location import android.os.Build +import android.os.SystemClock import androidx.core.app.NotificationCompat import androidx.core.app.NotificationManagerCompat import androidx.core.content.ContextCompat @@ -24,7 +25,6 @@ import java.net.HttpURLConnection import java.net.URLEncoder import java.net.URL import java.util.concurrent.TimeUnit -import org.json.JSONArray import org.json.JSONObject class SmartRouteNotificationWorker( @@ -47,85 +47,126 @@ class SmartRouteNotificationWorker( return Result.success() } - val profiles = SmartRouteNotificationSupport - .loadProfiles(applicationContext) - .filter { it.provider == settings.provider } + // When to remind, and about what, was worked out by the app the + // last time it was used. This only has to follow it. + val plan = SmartRouteNotificationSupport.loadPlan(applicationContext) + ?: return Result.success() val now = System.currentTimeMillis() - val candidates = SmartRouteNotificationSupport.chooseProfilesForNow( - profiles = profiles, - nowMs = now, - ) - if (candidates.isEmpty()) return Result.success() + if (!SmartRouteReminderRules.hasLiveSlots(plan, now)) { + // Every habit in the plan has lapsed. Nothing can fire until + // the app is opened and writes a new one, which reschedules. + SmartRouteNotificationScheduler.cancel(applicationContext) + return Result.success() + } + val dueSlots = SmartRouteReminderRules.dueSlots(plan, settings.provider, now) + if (dueSlots.isEmpty()) { + return Result.success() + } - val currentLocation = SmartRouteNotificationSupport.loadCurrentLocation( - applicationContext, - ) ?: return Result.success() + val clock = SmartRouteReminderRules.serviceClock(now, plan.dayStartHour) + val history = SmartRouteNotificationSupport.loadHistory(applicationContext) + if (!SmartRouteReminderRules.mayRemind(history, now, clock.day)) { + return Result.success() + } - for (candidate in candidates) { - if (SmartRouteNotificationSupport.wasRecentlyInteracted(candidate, now)) continue + // Asked for at most once, and only once a slot has got this far: + // a fix costs battery, and most runs end before needing one. + val currentLocation by lazy { + SmartRouteNotificationSupport.loadCurrentLocation(applicationContext) + } + for (slot in dueSlots) { + if (SmartRouteReminderRules.wasSeenForWindow(slot, now, clock.minute)) continue + val lastForRoute = SmartRouteNotificationSupport.loadLastReminderForRoute( + applicationContext, + slot, + ) + if (!SmartRouteReminderRules.mayRemindRoute(lastForRoute, now)) continue val routeData = SmartRouteNotificationSupport.loadRouteData( - context = applicationContext, - provider = candidate.provider, - routeKey = candidate.routeKey, - fallbackRouteName = candidate.routeName, + applicationContext, + slot, ) ?: continue - val nearestStop = SmartRouteNotificationSupport.findNearestStop( - location = currentLocation, + val choice = SmartRouteNotificationSupport.chooseStop( + slot = slot, routeData = routeData, - pathId = candidate.pathId, + location = currentLocation, ) ?: continue val liveStop = SmartRouteNotificationSupport.fetchLiveStop( - routeId = routeData.routeId, - preferredPathId = nearestStop.pathId, - stopId = nearestStop.stopId, + routeId = slot.routeId, + pathId = slot.pathId, + rawStopId = choice.stop.rawStopId, + nowMs = now, ) ?: continue - if (!SmartRouteNotificationSupport.shouldNotify(liveStop)) continue - if (!SmartRouteNotificationSupport.shouldDeliverNotification( - context = applicationContext, - provider = candidate.provider, - routeKey = candidate.routeKey, - pathId = nearestStop.pathId, - stopId = nearestStop.stopId, - nowMs = now, - ) - ) continue + val decision = SmartRouteReminderRules.decide(liveStop, choice.distanceMeters) + ?: continue SmartRouteNotificationSupport.showNotification( context = applicationContext, - profile = candidate, - routeData = routeData, - nearestStop = nearestStop, - liveStop = liveStop, - distanceMeters = nearestStop.distanceMeters, + slot = slot, + stop = choice.stop, + text = SmartRouteReminderRules.buildText( + routeName = slot.routeName, + pathName = routeData.pathName, + stopName = choice.stop.stopName, + decision = decision, + distanceMeters = choice.distanceMeters, + slot = slot, + dayStartHour = plan.dayStartHour, + nowMs = now, + ), + timeoutMs = SmartRouteReminderRules.timeoutMs(decision), + ) + SmartRouteNotificationSupport.saveReminder( + context = applicationContext, + slot = slot, + history = SmartRouteReminderRules.afterReminder(history, now, clock.day), nowMs = now, ) break } Result.success() } catch (_: Exception) { - Result.retry() + // Everything that can fail for a passing reason — the network, a + // database mid-download — is already handled where it happens, so + // what reaches here would fail the same way on a retry. The next + // period runs regardless. + Result.failure() } } } internal object SmartRouteNotificationSupport { - private const val MIN_TOTAL_OPENS_FOR_RECOMMENDATION = 3 - private const val MIN_RELEVANT_INTERACTIONS_FOR_RECOMMENDATION = 2 private const val FLUTTER_PREFERENCES_NAME = "FlutterSharedPreferences" private const val SETTINGS_KEY = "flutter.app_settings" private const val SETTINGS_FALLBACK_KEY = "app_settings" - private const val ROUTE_USAGE_KEY = "flutter.route_usage_profiles" - private const val ROUTE_USAGE_FALLBACK_KEY = "route_usage_profiles" + + // Written by StorageService.saveSmartRoutePlan on the Flutter side. + private const val PLAN_KEY = "flutter.smart_route_plan" private const val NOTIFICATION_PREFERENCES_NAME = "smart_route_notifications" - private const val LAST_NOTIFIED_KEY_PREFIX = "last_notified_" + private const val LAST_REMINDER_KEY = "last_reminder_ms" + private const val REMINDER_DAY_KEY = "reminder_day" + private const val REMINDER_COUNT_KEY = "reminder_count" + private const val LAST_ROUTE_REMINDER_KEY_PREFIX = "last_route_reminder_" + private const val REMINDER_LOG_KEY = "reminder_log" private const val CHANNEL_ID = "smart_route_recommendation" private const val CHANNEL_NAME = "智慧推薦提醒" private const val CHANNEL_DESCRIPTION = - "在你常查看某條路線的時間點附近,依最近站牌到站時間主動提醒。" + "在你常查看某條路線的時間點附近,依常用或最近站牌的到站時間主動提醒。" + private const val NOTIFICATION_ID_BASE = 710_000 private const val ROUTE_REQUEST_TIMEOUT_MS = 10_000 private const val API_BASE_URL = "https://bus.avianjay.sbs" - private const val NOTIFICATION_COOLDOWN_MS = 75 * 60 * 1000L - private const val RECENT_INTERACTION_SUPPRESSION_MS = 30 * 60 * 1000L + + // BusRepository keeps its databases in this directory, under the path + // sqflite's getDatabasesPath() returns: stops per provider in one file, + // route and direction names for every provider in another. + private const val DATABASE_DIRECTORY = ".yabus_backend" + private val METADATA_DATABASE_NAMES = listOf( + "routes_metadata_v1.sqlite", + "routes_metadata_v2.sqlite", + ) + + // A fix older than this may be from wherever the phone last had a map + // open, which is no guide to which stop its owner is near now. + private const val MAX_LOCATION_AGE_MS = 10 * 60 * 1000L fun ensureChannel(context: Context) { if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) { @@ -147,115 +188,84 @@ internal object SmartRouteNotificationSupport { } fun loadSettings(context: Context): SmartRouteSettings? { - val root = loadFlutterJsonObject( - context = context, - primaryKey = SETTINGS_KEY, - fallbackKey = SETTINGS_FALLBACK_KEY, - ) ?: return null + val preferences = flutterPreferences(context) + val raw = preferences.getString(SETTINGS_KEY, null) + ?: preferences.getString(SETTINGS_FALLBACK_KEY, null) + ?: return null + val root = try { + JSONObject(raw) + } catch (_: Exception) { + return null + } return SmartRouteSettings( provider = root.optString("provider", "twn"), enableNotifications = root.optBoolean("enableSmartRouteNotifications", false), ) } - fun loadProfiles(context: Context): List { - val preferences = context.getSharedPreferences( - FLUTTER_PREFERENCES_NAME, - Context.MODE_PRIVATE, + fun loadPlan(context: Context): SmartRoutePlan? = + SmartRouteReminderRules.parsePlan( + flutterPreferences(context).getString(PLAN_KEY, null), ) - val raw = preferences.getString(ROUTE_USAGE_KEY, null) - ?: preferences.getString(ROUTE_USAGE_FALLBACK_KEY, null) - ?: return emptyList() - val array = try { - JSONArray(raw) - } catch (_: Exception) { - return emptyList() - } - val result = mutableListOf() - for (index in 0 until array.length()) { - val item = array.optJSONObject(index) ?: continue - val routeKey = item.optInt("routeKey", 0) - val pathId = if (item.has("pathId")) item.optInt("pathId") else null - if (routeKey <= 0 || pathId == null) { - continue - } - val hourlyOpens = mutableMapOf() - val hourlyObject = item.optJSONObject("hourlyOpens") - hourlyObject?.keys()?.forEach { key -> - val hour = key.toIntOrNull() ?: return@forEach - if (hour !in 0..23) { - return@forEach - } - val count = hourlyObject.optInt(key, 0) - if (count > 0) { - hourlyOpens[hour] = count - } - } - val hourlySelections = mutableMapOf() - val selectionObject = item.optJSONObject("hourlySelections") - selectionObject?.keys()?.forEach { key -> - val hour = key.toIntOrNull() ?: return@forEach - if (hour !in 0..23) { - return@forEach - } - val count = selectionObject.optInt(key, 0) - if (count > 0) { - hourlySelections[hour] = count - } - } - result += SmartRouteProfile( - provider = item.optString("provider", "twn"), - routeKey = routeKey, - pathId = pathId, - routeName = item.optString("routeName", "").trim(), - totalOpens = item.optInt("totalOpens", 0), - lastOpenedAtMs = item.optLong("lastOpenedAtMs", 0L), - totalSelections = item.optInt("totalSelections", 0), - lastSelectedAtMs = item.optLong("lastSelectedAtMs", 0L), - hourlyOpens = hourlyOpens, - hourlySelections = hourlySelections, - ) - } - return result + fun loadHistory(context: Context): SmartReminderHistory { + val preferences = notificationPreferences(context) + return SmartReminderHistory( + lastAnyMs = preferences.getLong(LAST_REMINDER_KEY, 0L), + countDay = preferences.getLong(REMINDER_DAY_KEY, 0L), + countThatDay = preferences.getInt(REMINDER_COUNT_KEY, 0), + ) } - fun chooseProfilesForNow( - profiles: List, + fun loadLastReminderForRoute(context: Context, slot: SmartPlanSlot): Long = + notificationPreferences(context).getLong(routeReminderKey(slot), 0L) + + fun saveReminder( + context: Context, + slot: SmartPlanSlot, + history: SmartReminderHistory, nowMs: Long, - ): List { - val now = java.util.Calendar.getInstance().apply { - timeInMillis = nowMs - } - val currentHour = now.get(java.util.Calendar.HOUR_OF_DAY) - val previousHour = (currentHour + 23) % 24 - val nextHour = (currentHour + 1) % 24 - - return profiles - .filter { - hasEnoughHistoryForRecommendation( - profile = it, - currentHour = currentHour, - previousHour = previousHour, - nextHour = nextHour, - ) - } - .sortedByDescending { profile -> - scoreProfile(profile, currentHour, previousHour, nextHour, nowMs) - } - .distinctBy { profile -> - listOf(profile.provider, profile.routeKey, profile.pathId) - } + ) { + val preferences = notificationPreferences(context) + preferences + .edit() + .putLong(LAST_REMINDER_KEY, history.lastAnyMs) + .putLong(REMINDER_DAY_KEY, history.countDay) + .putInt(REMINDER_COUNT_KEY, history.countThatDay) + .putLong(routeReminderKey(slot), nowMs) + .putString( + REMINDER_LOG_KEY, + SmartRouteReminderRules.appendToReminderLog( + preferences.getString(REMINDER_LOG_KEY, null), + slot, + nowMs, + ), + ) + .apply() } - fun wasRecentlyInteracted(profile: SmartRouteProfile, nowMs: Long): Boolean { - val lastInteractionAt = profile.latestInteractionAtMs - if (lastInteractionAt <= 0L) { - return false - } - return nowMs - lastInteractionAt < RECENT_INTERACTION_SUPPRESSION_MS + /** The reminders shown so far, as JSON, for the Flutter side to read. */ + fun loadReminderLog(context: Context): String = + notificationPreferences(context).getString(REMINDER_LOG_KEY, null) ?: "[]" + + /** + * Drops every trace of reminders already shown: the log, and what holds + * the next one back. For when the rider clears what the app has learned + * about them, which this is part of. + */ + fun forgetReminders(context: Context) { + notificationPreferences(context).edit().clear().apply() } + private fun routeReminderKey(slot: SmartPlanSlot): String = + LAST_ROUTE_REMINDER_KEY_PREFIX + + listOf(slot.provider, slot.routeKey, slot.pathId).joinToString("_") + + /** + * The device's location, or null when it may not be read in the + * background or no recent fix can be had. A reminder can still go out + * without one, as long as the plan names the rider's usual stop. + */ fun loadCurrentLocation(context: Context): Location? { if (!hasLocationPermission(context)) { return null @@ -268,7 +278,7 @@ internal object SmartRouteNotificationSupport { } catch (_: Exception) { null } - if (lastKnown != null) { + if (lastKnown != null && isRecent(lastKnown)) { return lastKnown } @@ -286,106 +296,175 @@ internal object SmartRouteNotificationSupport { } } - fun loadRouteData( - context: Context, - provider: String, - routeKey: Int, - fallbackRouteName: String, - ): SmartRouteData? { - val databaseFile = resolveDatabaseFile(context, provider) ?: return null - if (!databaseFile.exists()) { + private fun isRecent(location: Location): Boolean { + val ageMs = + (SystemClock.elapsedRealtimeNanos() - location.elapsedRealtimeNanos) / 1_000_000 + return ageMs <= MAX_LOCATION_AGE_MS + } + + /** + * The stops of the slot's direction, and that direction's name. + * + * Null when the stops cannot be read — the provider's database is not + * downloaded, or is being replaced — which is not an error: there is + * simply nothing to remind about until it is back. + */ + fun loadRouteData(context: Context, slot: SmartPlanSlot): SmartRouteData? { + val stops = queryDatabase(context, listOf("bus_${slot.provider}_v2.sqlite")) { database -> + loadStops(database, slot.routeId, slot.pathId) + } + if (stops.isNullOrEmpty()) { return null } - - val database = SQLiteDatabase.openDatabase( - databaseFile.path, - null, - SQLiteDatabase.OPEN_READONLY, + return SmartRouteData( + // The name only labels the reminder, so doing without is fine. + pathName = queryDatabase(context, METADATA_DATABASE_NAMES) { database -> + loadPathName(database, slot.routeId, slot.pathId) + }, + stops = stops, ) - return try { - var routeId: String? = null - val routeName = database.rawQuery( - "SELECT route_id, route_name FROM routes WHERE route_key = ? LIMIT 1", - arrayOf(routeKey.toString()), - ).use { cursor -> - if (cursor.moveToFirst()) { - routeId = cursor.getString(0) - ?.trim() - ?.takeIf { it.isNotEmpty() } - cursor.getString(1).orEmpty() - } else { - fallbackRouteName - } - } + } - val pathNames = linkedMapOf() - database.rawQuery( - "SELECT path_id, path_name FROM paths WHERE route_key = ? ORDER BY path_id ASC", - arrayOf(routeKey.toString()), - ).use { cursor -> - while (cursor.moveToNext()) { - pathNames[cursor.getInt(0)] = cursor.getString(1).orEmpty() + internal fun loadStops( + database: SQLiteDatabase, + routeId: String, + pathId: Int, + ): List { + val result = mutableListOf() + database.rawQuery( + """ + SELECT stopid, name, seq, lon, lat + FROM stops + WHERE routeid = ? AND pathid = ? + ORDER BY seq ASC + """.trimIndent(), + arrayOf(routeId, pathId.toString()), + ).use { cursor -> + while (cursor.moveToNext()) { + val rawStopId = cursor.getString(0)?.trim().orEmpty() + if (rawStopId.isEmpty()) { + continue } + result += SmartRouteStop( + pathId = pathId, + rawStopId = rawStopId, + stopName = cursor.getString(1).orEmpty(), + sequence = cursor.getInt(2), + lon = cursor.getDouble(3), + lat = cursor.getDouble(4), + ) } + } + return result + } - val stops = loadStopsFromDatabase(database, routeKey) - if (stops.isEmpty() || routeId.isNullOrEmpty()) { - null + internal fun loadPathName(database: SQLiteDatabase, routeId: String, pathId: Int): String? = + database.rawQuery( + "SELECT name FROM paths WHERE routeid = ? AND pathid = ? LIMIT 1", + arrayOf(routeId, pathId.toString()), + ).use { cursor -> + if (cursor.moveToFirst()) { + cursor.getString(0)?.trim()?.takeIf { it.isNotEmpty() } } else { - SmartRouteData( - provider = provider, - routeKey = routeKey, - routeId = routeId!!, - routeName = routeName.ifBlank { fallbackRouteName }, - pathNames = pathNames, - stops = stops.sortedWith(compareBy({ it.pathId }, { it.sequence })), - ) + null } + } + + /** + * Runs [query] against the first of [fileNames] that exists, read-only. + * Null if none does or the query cannot be answered. + */ + private fun queryDatabase( + context: Context, + fileNames: List, + query: (SQLiteDatabase) -> T?, + ): T? { + val file = databaseDirectories(context) + .flatMap { directory -> fileNames.map { File(directory, it) } } + .firstOrNull { it.exists() } + ?: return null + val database = try { + SQLiteDatabase.openDatabase(file.path, null, SQLiteDatabase.OPEN_READONLY) + } catch (_: Exception) { + return null + } + return try { + query(database) + } catch (_: Exception) { + // A schema this build does not know, or a file caught halfway + // through being replaced by a database update. + null } finally { - database.close() + runCatching { database.close() } } } - fun findNearestStop( - location: Location, + private fun databaseDirectories(context: Context): List = listOfNotNull( + // Where the app keeps them now. + context.getDatabasePath("_").parentFile?.let { File(it, DATABASE_DIRECTORY) }, + // Where it kept them before it moved them there. + context.filesDir.parentFile?.let { File(it, "app_flutter/$DATABASE_DIRECTORY") }, + File(context.filesDir, DATABASE_DIRECTORY), + ) + + /** Measures what can be measured and leaves the choice to the rules. */ + fun chooseStop( + slot: SmartPlanSlot, routeData: SmartRouteData, - pathId: Int, - ): SmartNearestStop? { - var bestStop: SmartNearestStop? = null - for (stop in routeData.stops) { - if (stop.pathId != pathId || stop.lat == 0.0 || stop.lon == 0.0) { - continue - } - val results = FloatArray(1) - Location.distanceBetween( - location.latitude, - location.longitude, - stop.lat, - stop.lon, - results, - ) - val distance = results[0].toDouble() - if (bestStop == null || distance < bestStop.distanceMeters) { - bestStop = SmartNearestStop( - pathId = stop.pathId, - stopId = stop.stopId, - launchStopId = stop.launchStopId, - stopName = stop.stopName, - distanceMeters = distance, - ) + location: Location?, + ): SmartStopChoice? { + val usualStop = SmartRouteReminderRules.findUsualStop(slot, routeData.stops) + var nearestStop: SmartRouteStop? = null + var nearestDistance: Double? = null + if (location != null) { + for (stop in routeData.stops) { + val distance = distanceMeters(location, stop) ?: continue + if (nearestDistance == null || distance < nearestDistance) { + nearestDistance = distance + nearestStop = stop + } } } - return bestStop + return SmartRouteReminderRules.chooseStop( + usualStop = usualStop, + usualDistanceMeters = if (usualStop != null && location != null) { + distanceMeters(location, usualStop) + } else { + null + }, + nearestStop = nearestStop, + nearestDistanceMeters = nearestDistance, + ) + } + + private fun distanceMeters(location: Location, stop: SmartRouteStop): Double? { + if (stop.lat == 0.0 || stop.lon == 0.0) { + return null + } + val results = FloatArray(1) + Location.distanceBetween( + location.latitude, + location.longitude, + stop.lat, + stop.lon, + results, + ) + return results[0].toDouble() } fun fetchLiveStop( routeId: String, - preferredPathId: Int, - stopId: Int, + pathId: Int, + rawStopId: String, + nowMs: Long, ): SmartLiveStop? { val encodedRouteId = URLEncoder.encode(routeId, Charsets.UTF_8.name()) - val connection = URL("$API_BASE_URL/api/v1/routes/$encodedRouteId/realtime") - .openConnection() as HttpURLConnection + val connection = try { + URL("$API_BASE_URL/api/v1/routes/$encodedRouteId/realtime") + .openConnection() as HttpURLConnection + } catch (_: Exception) { + return null + } connection.connectTimeout = ROUTE_REQUEST_TIMEOUT_MS connection.readTimeout = ROUTE_REQUEST_TIMEOUT_MS connection.requestMethod = "GET" @@ -401,7 +480,7 @@ internal object SmartRouteNotificationSupport { val jsonText = connection.inputStream.bufferedReader(Charsets.UTF_8).use { reader -> reader.readText() } - parseLiveStopMap(jsonText, preferredPathId)[stopId] + SmartRouteReminderRules.parseLiveStop(jsonText, pathId, rawStopId, nowMs) } } catch (_: Exception) { null @@ -410,103 +489,47 @@ internal object SmartRouteNotificationSupport { } } - fun shouldNotify(liveStop: SmartLiveStop): Boolean { - val message = liveStop.msg?.trim().orEmpty() - if (isLastBusMessage(message)) { - return false - } - if (message.isNotEmpty()) { - return true - } - val seconds = liveStop.sec ?: return false - return seconds <= 20 * 60 - } - - fun shouldDeliverNotification( - context: Context, - provider: String, - routeKey: Int, - pathId: Int, - stopId: Int, - nowMs: Long, - ): Boolean { - val preferences = notificationPreferences(context) - val key = LAST_NOTIFIED_KEY_PREFIX + listOf(provider, routeKey, pathId, stopId).joinToString("_") - val lastNotified = preferences.getLong(key, 0L) - return nowMs - lastNotified >= NOTIFICATION_COOLDOWN_MS - } - fun showNotification( context: Context, - profile: SmartRouteProfile, - routeData: SmartRouteData, - nearestStop: SmartNearestStop, - liveStop: SmartLiveStop, - distanceMeters: Double, - nowMs: Long, + slot: SmartPlanSlot, + stop: SmartRouteStop, + text: SmartReminderText, + timeoutMs: Long, ) { val contentIntent = PendingIntent.getActivity( context, - profile.routeKey * 173 + nearestStop.stopId, + slot.routeKey * 31 + slot.pathId, AppLaunchConstants.createRouteDetailIntent( context = context, - provider = profile.provider, - routeKey = profile.routeKey, - pathId = nearestStop.pathId, - // Full-width: Flutter matches this against its own stop ids, and - // the folded key would select nothing there. - stopId = nearestStop.launchStopId, + provider = slot.provider, + routeKey = slot.routeKey, + routeId = slot.routeId, + pathId = slot.pathId, + // Use the selected stop, not the plan's usual stop: location + // can pick a different one. Flutter needs the full-width id. + stopId = launchStopId(stop.rawStopId).takeIf { it > 0L }, ), PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE, ) - val title = "智慧推薦:${routeData.routeName.ifBlank { profile.routeName.ifBlank { "路線" } }}" - val etaText = formatEtaText(liveStop) - val contentText = "最近站牌 ${nearestStop.stopName},預估 $etaText" - val hourLabel = profile.preferredHour.toString().padStart(2, '0') - val pathName = routeData.pathNames[nearestStop.pathId] - val bigText = buildString { - append("你通常會在 ") - append(hourLabel) - append(":00 左右查看這條路線。") - if (!pathName.isNullOrBlank()) { - append("方向:") - append(pathName) - append("。") - } - append("最近站牌:") - append(nearestStop.stopName) - append("(距離你約 ") - append(formatDistance(distanceMeters)) - append(")。預估到站 ") - append(etaText) - append('。') - } - val notification = NotificationCompat.Builder(context, CHANNEL_ID) .setSmallIcon(R.drawable.ic_notification_bus) - .setContentTitle(title) - .setContentText(contentText) - .setStyle(NotificationCompat.BigTextStyle().bigText(bigText)) + .setContentTitle(text.title) + .setContentText(text.text) + .setStyle(NotificationCompat.BigTextStyle().bigText(text.bigText)) .setPriority(NotificationCompat.PRIORITY_HIGH) .setAutoCancel(true) .setContentIntent(contentIntent) .setCategory(NotificationCompat.CATEGORY_RECOMMENDATION) + // Once the bus has gone the reminder is wrong, and a wrong arrival + // time is worse than none: it takes itself down. + .setTimeoutAfter(timeoutMs) .build() NotificationManagerCompat.from(context).notify( - 710000 + profile.routeKey, + NOTIFICATION_ID_BASE + slot.routeKey % 100_000, notification, ) - - notificationPreferences(context) - .edit() - .putLong( - LAST_NOTIFIED_KEY_PREFIX + - listOf(profile.provider, profile.routeKey, nearestStop.pathId, nearestStop.stopId) - .joinToString("_"), - nowMs, - ).apply() } fun canPostNotifications(context: Context): Boolean { @@ -522,57 +545,6 @@ internal object SmartRouteNotificationSupport { ) == PackageManager.PERMISSION_GRANTED } - private fun scoreProfile( - profile: SmartRouteProfile, - currentHour: Int, - previousHour: Int, - nextHour: Int, - nowMs: Long, - ): Double { - val currentOpenCount = profile.countAtHour(currentHour) - val currentSelectionCount = profile.selectionCountAtHour(currentHour) - val adjacentOpenCount = - profile.countAtHour(previousHour) + profile.countAtHour(nextHour) - val adjacentSelectionCount = - profile.selectionCountAtHour(previousHour) + - profile.selectionCountAtHour(nextHour) - val preferredCount = profile.combinedCountAtHour(profile.preferredHour) - val recencyDays = if (profile.latestInteractionAtMs <= 0L) { - 365.0 - } else { - (nowMs - profile.latestInteractionAtMs).toDouble() / (24 * 60 * 60 * 1000) - } - val recencyBonus = when { - recencyDays <= 2 -> 1.5 - recencyDays <= 7 -> 0.75 - else -> 0.0 - } - return (currentOpenCount * 5) + - (currentSelectionCount * 3.5) + - (adjacentOpenCount * 2.5) + - (adjacentSelectionCount * 1.5) + - (preferredCount * 0.5) + - (profile.totalOpens * 0.15) + - (profile.totalSelections * 0.1) + - recencyBonus - } - - private fun hasEnoughHistoryForRecommendation( - profile: SmartRouteProfile, - currentHour: Int, - previousHour: Int, - nextHour: Int, - ): Boolean { - if (profile.totalOpens < MIN_TOTAL_OPENS_FOR_RECOMMENDATION) { - return false - } - val relevantInteractions = - profile.combinedCountAtHour(currentHour) + - profile.combinedCountAtHour(previousHour) + - profile.combinedCountAtHour(nextHour) - return relevantInteractions >= MIN_RELEVANT_INTERACTIONS_FOR_RECOMMENDATION - } - private fun hasLocationPermission(context: Context): Boolean { val hasFine = ContextCompat.checkSelfPermission( context, @@ -597,153 +569,11 @@ internal object SmartRouteNotificationSupport { return true } - private fun resolveDatabaseFile(context: Context, provider: String): File? { - val filesParent = context.filesDir.parentFile ?: return null - val candidates = listOf( - File(filesParent, "app_flutter/.yabus_backend/bus_${provider}_v2.sqlite"), - File(context.filesDir, ".yabus_backend/bus_${provider}_v2.sqlite"), - File(filesParent, "app_flutter/.taiwanbus/bus_${provider}.sqlite"), - File(context.filesDir, ".taiwanbus/bus_${provider}.sqlite"), - ) - return candidates.firstOrNull { it.exists() } ?: candidates.first() - } + private fun flutterPreferences(context: Context): SharedPreferences = + context.getSharedPreferences(FLUTTER_PREFERENCES_NAME, Context.MODE_PRIVATE) - private fun loadStopsFromDatabase( - database: SQLiteDatabase, - routeKey: Int, - ): List { - val result = mutableListOf() - database.rawQuery( - """ - SELECT path_id, stop_id, stop_name, sequence, lon, lat - FROM stops - WHERE route_key = ? - ORDER BY path_id ASC, sequence ASC - """.trimIndent(), - arrayOf(routeKey.toString()), - ).use { cursor -> - while (cursor.moveToNext()) { - // stop_id is a TEXT column and 高雄 ids exceed Int. It is needed - // twice, as two different numbers: folded, to key the live - // feed; and at full width, for the notification tap that goes - // back into Flutter, whose stop models hold the unfolded id. - val storedStopId = cursor.getString(1) - result += SmartRouteStop( - pathId = cursor.getInt(0), - stopId = foldStopId(storedStopId), - launchStopId = launchStopId(storedStopId), - stopName = cursor.getString(2).orEmpty(), - sequence = cursor.getInt(3), - lon = cursor.getDouble(4), - lat = cursor.getDouble(5), - ) - } - } - return result - } - - private fun parseLiveStopMap( - jsonText: String, - preferredPathId: Int, - ): Map { - val root = JSONObject(jsonText) - val paths = root.optJSONArray("paths") ?: return emptyMap() - val result = mutableMapOf() - - fun appendPath(pathObject: JSONObject) { - val stops = pathObject.optJSONArray("stops") ?: return - for (index in 0 until stops.length()) { - val stop = stops.optJSONObject(index) ?: continue - val stopId = parseStopId(stop.opt("stopid")) - if (stopId <= 0) { - continue - } - result[stopId] = SmartLiveStop( - sec = toIntOrNull(stop.opt("eta")), - msg = stop.opt("message") - ?.toString() - ?.trim() - ?.takeIf { it.isNotEmpty() && !it.equals("null", ignoreCase = true) }, - ) - } - } - - var matchedPath = false - for (index in 0 until paths.length()) { - val pathObject = paths.optJSONObject(index) ?: continue - if (toIntOrNull(pathObject.opt("pathid")) == preferredPathId) { - matchedPath = true - appendPath(pathObject) - } - } - - if (!matchedPath) { - for (index in 0 until paths.length()) { - val pathObject = paths.optJSONObject(index) ?: continue - appendPath(pathObject) - } - } - - return result - } - - private fun parseStopId(raw: Any?): Int = foldStopId(raw) - - private fun toIntOrNull(raw: Any?): Int? { - return when (raw) { - is Number -> raw.toInt() - else -> raw?.toString()?.trim()?.toIntOrNull() - } - } - - private fun formatEtaText(liveStop: SmartLiveStop): String { - val message = liveStop.msg?.trim().orEmpty() - if (message.isNotEmpty()) { - return message - } - val seconds = liveStop.sec ?: return "--" - if (seconds <= 0) { - return "進站中" - } - if (seconds < 60) { - return "1 分內" - } - return "${seconds / 60} 分" - } - - private fun formatDistance(distanceMeters: Double): String { - if (distanceMeters < 1000) { - return "${distanceMeters.toInt()}m" - } - val kilometers = distanceMeters / 1000.0 - return String.format("%.1fkm", kilometers) - } - - private fun loadFlutterJsonObject( - context: Context, - primaryKey: String, - fallbackKey: String, - ): JSONObject? { - val preferences = context.getSharedPreferences( - FLUTTER_PREFERENCES_NAME, - Context.MODE_PRIVATE, - ) - val raw = preferences.getString(primaryKey, null) - ?: preferences.getString(fallbackKey, null) - ?: return null - return try { - JSONObject(raw) - } catch (_: Exception) { - null - } - } - - private fun notificationPreferences(context: Context): SharedPreferences { - return context.getSharedPreferences( - NOTIFICATION_PREFERENCES_NAME, - Context.MODE_PRIVATE, - ) - } + private fun notificationPreferences(context: Context): SharedPreferences = + context.getSharedPreferences(NOTIFICATION_PREFERENCES_NAME, Context.MODE_PRIVATE) } internal data class SmartRouteSettings( @@ -751,70 +581,8 @@ internal data class SmartRouteSettings( val enableNotifications: Boolean, ) -internal data class SmartRouteProfile( - val provider: String, - val routeKey: Int, - val pathId: Int, - val routeName: String, - val totalOpens: Int, - val lastOpenedAtMs: Long, - val totalSelections: Int, - val lastSelectedAtMs: Long, - val hourlyOpens: Map, - val hourlySelections: Map, -) { - fun countAtHour(hour: Int): Int = hourlyOpens[hour] ?: 0 - fun selectionCountAtHour(hour: Int): Int = hourlySelections[hour] ?: 0 - fun combinedCountAtHour(hour: Int): Int = countAtHour(hour) + selectionCountAtHour(hour) - - val latestInteractionAtMs: Long - get() = maxOf(lastOpenedAtMs, lastSelectedAtMs) - - val preferredHour: Int - get() { - var bestHour = 0 - var bestCount = -1 - for (hour in 0..23) { - val count = combinedCountAtHour(hour) - if (count > bestCount) { - bestHour = hour - bestCount = count - } - } - return bestHour - } -} - internal data class SmartRouteData( - val provider: String, - val routeKey: Int, - val routeId: String, - val routeName: String, - val pathNames: Map, + val pathName: String?, + /** The stops of one direction, in running order. */ val stops: List, ) - -internal data class SmartRouteStop( - val pathId: Int, - /** Folded, as the live feeds are: only usable for looking up ETAs. */ - val stopId: Int, - /** Full-width, as Flutter holds it: what a notification tap may carry. */ - val launchStopId: Long, - val stopName: String, - val sequence: Int, - val lon: Double, - val lat: Double, -) - -internal data class SmartNearestStop( - val pathId: Int, - val stopId: Int, - val launchStopId: Long, - val stopName: String, - val distanceMeters: Double, -) - -internal data class SmartLiveStop( - val sec: Int?, - val msg: String?, -) diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt new file mode 100644 index 00000000..39233b3a --- /dev/null +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt @@ -0,0 +1,528 @@ +package tw.avianjay.taiwanbus.flutter + +import java.util.Calendar +import java.util.Locale +import java.util.TimeZone +import kotlin.math.max +import kotlin.math.roundToInt +import kotlinx.serialization.Serializable +import kotlinx.serialization.encodeToString +import kotlinx.serialization.json.Json +import kotlinx.serialization.json.JsonArray +import kotlinx.serialization.json.JsonElement +import kotlinx.serialization.json.JsonNull +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.JsonPrimitive +import kotlinx.serialization.json.decodeFromJsonElement + +/** + * One stretch of one weekday in which a route is worth a reminder. + * + * Written by the Flutter side (`SmartRoutePlanner`), which is where the habit + * is learned. Nothing here scores a habit: this side only follows the plan, + * so the two can never disagree about what the rider's routine is. + */ +@Serializable +internal data class SmartPlanSlot( + val provider: String, + val routeKey: Int, + /** What the stop database and the realtime API know the route by. */ + val routeId: String, + val pathId: Int, + val routeName: String = "", + /** 1 = Monday .. 7 = Sunday, of the service day. */ + val weekday: Int, + /** Minutes since the service day began, both ends inclusive. */ + val startMinute: Int, + val endMinute: Int, + /** When within the window the route is most often opened. */ + val peakMinute: Int, + val confidence: Double = 0.0, + val supportDays: Int = 0, + /** The habit has gone unconfirmed for too long once this has passed. */ + val validUntilMs: Long, + /** When the rider last opened or chose this route in the app. */ + val lastActivityAtMs: Long = 0L, + /** The stop to watch, as Flutter holds stop ids. Null when none is known. */ + val stopId: Long? = null, +) + +@Serializable +internal data class SmartRoutePlan( + val version: Int, + val generatedAtMs: Long = 0L, + /** The hour at which a service day begins; slot minutes count from it. */ + val dayStartHour: Int = 4, + val slots: List = emptyList(), +) + +/** Where a moment falls on the plan's service-day grid. */ +internal data class SmartServiceClock( + /** The same all service day and different the next; nothing more. */ + val day: Long, + val weekday: Int, + val minute: Int, +) + +internal data class SmartRouteStop( + val pathId: Int, + /** As the stop database and the live feed both spell it. */ + val rawStopId: String, + val stopName: String, + val sequence: Int, + val lon: Double, + val lat: Double, +) + +/** The stop a reminder will be about. */ +internal data class SmartStopChoice( + val stop: SmartRouteStop, + /** Straight-line distance from the device, when its location is known. */ + val distanceMeters: Double?, +) + +internal data class SmartLiveStop( + val sec: Int?, + val msg: String?, + /** Every timed arrival the feed lists for the stop, in seconds. */ + val arrivals: List = emptyList(), +) + +/** A bus worth telling the rider about. */ +internal data class SmartEtaDecision( + val etaSeconds: Int, + /** The one after it, so a reminder that is read late is still of use. */ + val followingEtaSeconds: Int?, +) + +/** What has already been sent, so the next reminder can be held back. */ +internal data class SmartReminderHistory( + val lastAnyMs: Long = 0L, + val countDay: Long = 0L, + val countThatDay: Int = 0, +) + +internal data class SmartReminderText( + val title: String, + val text: String, + val bigText: String, +) + +/** + * A reminder that was actually shown. + * + * Kept for the Flutter side, which learns the rider's habits from when they + * open a route. A reminder changes that: one that did its job takes away the + * reason to open the route at all, and one that is tapped has it opened at + * the reminder's time instead of the rider's own. Read without this, the + * first would look like a day the rider stayed home and the second like a + * routine that had moved earlier. + */ +@Serializable +internal data class SmartReminderLogEntry( + val provider: String, + val routeKey: Int, + val pathId: Int, + val atMs: Long, + /** The [SmartPlanSlot.peakMinute] of the slot the reminder was for. */ + val peakMinute: Int? = null, +) + +internal object SmartRouteReminderRules { + /** Plans of any other version are ignored rather than half-understood. */ + const val SUPPORTED_PLAN_VERSION = 1 + + /** + * How long before the rider's usual time a reminder may go out. One + * period of the background check, so that a check lands in it; any + * earlier and the bus reported is one they would not have taken. + */ + const val LEAD_MINUTES = 15 + + /** + * Opening the route this long before its window, or any time since, means + * the rider has already looked: a reminder would only repeat the screen + * they just closed. + */ + const val SEEN_BEFORE_WINDOW_MS = 30 * 60 * 1000L + + /** One reminder per route per window; windows are hours apart. */ + const val ROUTE_COOLDOWN_MS = 3 * 60 * 60 * 1000L + + /** Two routes due at once do not get to arrive as a burst. */ + const val MIN_GAP_MS = 20 * 60 * 1000L + const val MAX_PER_DAY = 6 + + /** Farther than this from the usual stop, the rider is somewhere else today. */ + const val USUAL_STOP_REACH_METERS = 1000.0 + + /** Without a usual stop, only one this close is taken to be theirs. */ + const val NEAREST_STOP_REACH_METERS = 800.0 + + /** + * Straight-line metres covered per second on foot. Slower than anyone + * walks, because the straight line is shorter than the pavement. + */ + const val WALK_METERS_PER_SECOND = 1.0 + const val WALK_BUFFER_SECONDS = 60 + + /** A bus closer than this cannot be caught by someone not yet at the stop. */ + const val MIN_ETA_SECONDS = 3 * 60 + + /** A bus farther off than this is not news yet; the next check will see it. */ + const val MAX_ETA_SECONDS = 25 * 60 + + /** A stop whose estimate is older than this is not a basis for a reminder. */ + const val MAX_FEED_AGE_MS = 5 * 60 * 1000L + + /** As far back as the habit model looks; older entries can change nothing. */ + const val REMINDER_LOG_RETENTION_MS = 56L * 24 * 60 * 60 * 1000 + const val REMINDER_LOG_MAX_ENTRIES = 400 + + /** + * How long before a slot lapses its reminders start saying that it will. + * A rider the reminders work for has no cause to open the app, and would + * otherwise learn that the habit needs confirming only when they stop. + */ + const val LAPSE_NOTICE_MS = 3L * 24 * 60 * 60 * 1000 + + private const val POST_ARRIVAL_LINGER_SECONDS = 3 * 60 + + private val json = Json { ignoreUnknownKeys = true } + + fun parsePlan(raw: String?): SmartRoutePlan? { + if (raw.isNullOrBlank()) { + return null + } + val plan = try { + json.decodeFromString(raw) + } catch (_: Exception) { + return null + } + return plan.takeIf { + it.version == SUPPORTED_PLAN_VERSION && it.dayStartHour in 0..23 + } + } + + fun serviceClock( + nowMs: Long, + dayStartHour: Int, + zone: TimeZone = TimeZone.getDefault(), + ): SmartServiceClock { + val calendar = Calendar.getInstance(zone).apply { + timeInMillis = nowMs - dayStartHour * 60 * 60 * 1000L + } + return SmartServiceClock( + day = calendar.get(Calendar.YEAR) * 1000L + calendar.get(Calendar.DAY_OF_YEAR), + // Calendar counts from Sunday = 1; the plan from Monday = 1. + weekday = (calendar.get(Calendar.DAY_OF_WEEK) + 5) % 7 + 1, + minute = calendar.get(Calendar.HOUR_OF_DAY) * 60 + calendar.get(Calendar.MINUTE), + ) + } + + /** + * Slots a reminder may go out for right now, the most certain first, one + * per route and direction. + */ + fun dueSlots( + plan: SmartRoutePlan, + provider: String, + nowMs: Long, + zone: TimeZone = TimeZone.getDefault(), + ): List { + val clock = serviceClock(nowMs, plan.dayStartHour, zone) + return plan.slots + .filter { slot -> + slot.provider == provider && + slot.weekday == clock.weekday && + clock.minute >= max(slot.startMinute, slot.peakMinute - LEAD_MINUTES) && + clock.minute <= slot.endMinute && + nowMs < slot.validUntilMs + } + .sortedByDescending { it.confidence } + .distinctBy { it.routeKey to it.pathId } + } + + /** Whether any slot at all could still fire, now or on a later day. */ + fun hasLiveSlots(plan: SmartRoutePlan, nowMs: Long): Boolean = + plan.slots.any { nowMs < it.validUntilMs } + + /** Whether [slot] will lapse soon enough that its reminder should say so. */ + fun isAboutToLapse(slot: SmartPlanSlot, nowMs: Long): Boolean = + slot.validUntilMs - nowMs <= LAPSE_NOTICE_MS + + /** Whether the rider has had the route open since shortly before [slot] began. */ + fun wasSeenForWindow(slot: SmartPlanSlot, nowMs: Long, nowMinute: Int): Boolean { + val windowStartMs = nowMs - (nowMinute - slot.startMinute) * 60_000L + return slot.lastActivityAtMs >= windowStartMs - SEEN_BEFORE_WINDOW_MS + } + + fun mayRemind(history: SmartReminderHistory, nowMs: Long, today: Long): Boolean { + if (nowMs - history.lastAnyMs < MIN_GAP_MS) { + return false + } + return history.countDay != today || history.countThatDay < MAX_PER_DAY + } + + fun mayRemindRoute(lastForRouteMs: Long, nowMs: Long): Boolean = + nowMs - lastForRouteMs >= ROUTE_COOLDOWN_MS + + fun afterReminder(history: SmartReminderHistory, nowMs: Long, today: Long) = + SmartReminderHistory( + lastAnyMs = nowMs, + countDay = today, + countThatDay = if (history.countDay == today) history.countThatDay + 1 else 1, + ) + + /** Entries that cannot be read are passed over; the rest are still good. */ + fun parseReminderLog(log: String?): List { + if (log.isNullOrBlank()) { + return emptyList() + } + val entries = try { + json.parseToJsonElement(log) as? JsonArray + } catch (_: Exception) { + null + } ?: return emptyList() + return entries.mapNotNull { entry -> + try { + json.decodeFromJsonElement(entry) + } catch (_: Exception) { + null + } + } + } + + /** + * [log] with a reminder shown at [nowMs] for [slot] added, and whatever + * is too old to matter dropped. + */ + fun appendToReminderLog(log: String?, slot: SmartPlanSlot, nowMs: Long): String { + val kept = parseReminderLog(log).filter { nowMs - it.atMs < REMINDER_LOG_RETENTION_MS } + + SmartReminderLogEntry( + provider = slot.provider, + routeKey = slot.routeKey, + pathId = slot.pathId, + atMs = nowMs, + peakMinute = slot.peakMinute, + ) + return json.encodeToString(kept.takeLast(REMINDER_LOG_MAX_ENTRIES)) + } + + /** The plan's usual stop among [stops], matched by the id Flutter holds. */ + fun findUsualStop(slot: SmartPlanSlot, stops: List): SmartRouteStop? { + val usualStopId = slot.stopId?.takeIf { it > 0L } ?: return null + return stops.firstOrNull { stop -> + stop.pathId == slot.pathId && launchStopId(stop.rawStopId) == usualStopId + } + } + + /** + * Picks the stop to watch. + * + * The stop the rider usually uses comes first, and needs no location at + * all. Location, when there is one, can only overrule it: far from the + * usual stop, the nearest one stands in if the rider is close to the + * route, and otherwise there is nothing to remind them of. + * + * A distance is null when it could not be measured — no location, or a + * stop without coordinates. + */ + fun chooseStop( + usualStop: SmartRouteStop?, + usualDistanceMeters: Double?, + nearestStop: SmartRouteStop?, + nearestDistanceMeters: Double?, + ): SmartStopChoice? { + if (usualStop != null) { + if (usualDistanceMeters == null) { + return SmartStopChoice(usualStop, distanceMeters = null) + } + if (usualDistanceMeters <= USUAL_STOP_REACH_METERS) { + return SmartStopChoice(usualStop, usualDistanceMeters) + } + } + if (nearestStop != null && + nearestDistanceMeters != null && + nearestDistanceMeters <= NEAREST_STOP_REACH_METERS + ) { + return SmartStopChoice(nearestStop, nearestDistanceMeters) + } + return null + } + + /** + * Reads one stop out of a `/routes/{id}/realtime` response. + * + * Only [pathId] is searched. The same stop id can sit on both directions + * of a route, and the other direction's bus is the one going the wrong + * way. + */ + fun parseLiveStop( + jsonText: String, + pathId: Int, + rawStopId: String, + nowMs: Long, + ): SmartLiveStop? { + val root = try { + json.parseToJsonElement(jsonText) as? JsonObject + } catch (_: Exception) { + null + } ?: return null + val wanted = rawStopId.trim() + for (pathElement in root["paths"] as? JsonArray ?: return null) { + val path = pathElement as? JsonObject ?: continue + if (path["pathid"].asInt() != pathId) { + continue + } + for (stopElement in path["stops"] as? JsonArray ?: continue) { + val stop = stopElement as? JsonObject ?: continue + if (stop["stopid"].asText() != wanted) { + continue + } + if (isOutdated(stop["updated_at"].asLong(), nowMs)) { + return null + } + return SmartLiveStop( + sec = stop["eta"].asInt(), + msg = stop["message"].asText(), + arrivals = (stop["etas"] as? JsonArray).orEmpty().mapNotNull { eta -> + // An arrival that comes with a message is a status, + // not a time: "未發車" may still carry a timetable guess. + (eta as? JsonObject) + ?.takeIf { it["message"].asText() == null } + ?.get("eta") + .asInt() + }, + ) + } + } + return null + } + + fun walkingSeconds(distanceMeters: Double): Int = + (distanceMeters / WALK_METERS_PER_SECOND).roundToInt() + WALK_BUFFER_SECONDS + + /** + * The first bus the rider could still catch, if it is close enough to be + * worth saying so. + * + * A stop that carries a message instead of a time is in some state — not + * yet departed, not served today, last bus gone — and none of those is a + * reason to tell anyone to leave the house. Only a timed arrival counts. + */ + fun decide(liveStop: SmartLiveStop, distanceMeters: Double?): SmartEtaDecision? { + val message = liveStop.msg?.trim().orEmpty() + if (isLastBusMessage(message)) { + return null + } + val arrivals = buildList { + if (message.isEmpty()) { + liveStop.sec?.let { add(it) } + } + addAll(liveStop.arrivals) + }.filter { it >= 0 }.distinct().sorted() + val soonestCatchable = max( + MIN_ETA_SECONDS, + distanceMeters?.let(::walkingSeconds) ?: 0, + ) + val index = arrivals.indexOfFirst { it >= soonestCatchable } + if (index < 0 || arrivals[index] > MAX_ETA_SECONDS) { + return null + } + return SmartEtaDecision( + etaSeconds = arrivals[index], + followingEtaSeconds = arrivals.getOrNull(index + 1), + ) + } + + fun buildText( + routeName: String, + pathName: String?, + stopName: String, + decision: SmartEtaDecision, + distanceMeters: Double?, + slot: SmartPlanSlot, + dayStartHour: Int, + nowMs: Long, + zone: TimeZone = TimeZone.getDefault(), + ): SmartReminderText { + val route = routeName.ifBlank { "路線" } + // The clock time as well as the countdown: a reminder read ten + // minutes late still says when the bus was due. + val arrivalClock = formatClock(nowMs + decision.etaSeconds * 1000L, zone) + val following = decision.followingEtaSeconds + ?.let { ",下一班約 ${etaMinutes(it)} 分後" } + .orEmpty() + val direction = pathName?.trim() + ?.takeIf { it.isNotEmpty() } + ?.let { "方向:$it。" } + .orEmpty() + val distance = distanceMeters + ?.let { "距離你約 ${formatDistance(it)}。" } + .orEmpty() + val usualClock = formatMinuteOfDay( + ((slot.peakMinute / 5.0).roundToInt() * 5 + dayStartHour * 60) % (24 * 60), + ) + // Said while opening the route can still prevent it, rather than + // leaving the reminders to stop one morning without a word. + val lapseNotice = if (isAboutToLapse(slot, nowMs)) { + "\n已有一段時間沒有開啟這條路線,提醒即將暫停;點這則通知查看路線即可繼續收到。" + } else { + "" + } + return SmartReminderText( + title = "$route 約 ${etaMinutes(decision.etaSeconds)} 分後到站", + text = "$stopName · 預計 $arrivalClock 到站", + bigText = "$stopName 預計 $arrivalClock 到站$following。$direction$distance" + + "你常在 $usualClock 左右查看這條路線。$lapseNotice", + ) + } + + /** How long after posting a reminder stops being true, and should clear itself. */ + fun timeoutMs(decision: SmartEtaDecision): Long = + (decision.etaSeconds + POST_ARRIVAL_LINGER_SECONDS) * 1000L + + fun formatDistance(distanceMeters: Double): String { + if (distanceMeters < 1000) { + return "${distanceMeters.toInt()}m" + } + return String.format(Locale.US, "%.1fkm", distanceMeters / 1000.0) + } + + private fun isOutdated(updatedAt: Long?, nowMs: Long): Boolean { + val updatedAtMs = when { + updatedAt == null -> return false + updatedAt > 1_000_000_000_000L -> updatedAt + updatedAt > 1_000_000_000L -> updatedAt * 1000 + else -> return false + } + return nowMs - updatedAtMs > MAX_FEED_AGE_MS + } + + private fun etaMinutes(seconds: Int): Int = max(1, (seconds / 60.0).roundToInt()) + + private fun formatClock(timeMs: Long, zone: TimeZone): String { + val calendar = Calendar.getInstance(zone).apply { timeInMillis = timeMs } + return formatMinuteOfDay( + calendar.get(Calendar.HOUR_OF_DAY) * 60 + calendar.get(Calendar.MINUTE), + ) + } + + private fun formatMinuteOfDay(minute: Int): String = + "${(minute / 60).toString().padStart(2, '0')}:${(minute % 60).toString().padStart(2, '0')}" + + private fun JsonElement?.asText(): String? { + val primitive = this as? JsonPrimitive ?: return null + if (primitive is JsonNull) { + return null + } + return primitive.content.trim() + .takeIf { it.isNotEmpty() && !it.equals("null", ignoreCase = true) } + } + + private fun JsonElement?.asLong(): Long? = + asText()?.let { it.toLongOrNull() ?: it.toDoubleOrNull()?.toLong() } + + private fun JsonElement?.asInt(): Int? = asLong()?.toInt() +} diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/AppLaunchStopIdTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/AppLaunchStopIdTest.kt index d87f3a2e..78b0323f 100644 --- a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/AppLaunchStopIdTest.kt +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/AppLaunchStopIdTest.kt @@ -4,7 +4,6 @@ import android.app.Application import android.app.NotificationManager import android.content.Intent import android.database.sqlite.SQLiteDatabase -import android.location.Location import java.io.File import org.json.JSONArray import org.json.JSONObject @@ -144,69 +143,78 @@ class AppLaunchStopIdTest { @Test fun tappingASmartRouteNotificationLaunchesWithTheFullWidthId() { - // The stop comes out of the route database Flutter syncs, where the id - // is stored as text. + val slot = SmartPlanSlot( + provider = "khh", + routeKey = 100, + routeId = "KHH100", + pathId = 1, + routeName = "100", + weekday = 1, + startMinute = 190, + endMinute = 250, + peakMinute = 220, + validUntilMs = Long.MAX_VALUE, + stopId = RAW_STOP_ID, + ) val databaseFile = File( - application.filesDir.parentFile, - "app_flutter/.yabus_backend/bus_khh_v2.sqlite", + application.getDatabasePath("_").parentFile, + ".yabus_backend/bus_khh_v2.sqlite", ) databaseFile.parentFile!!.mkdirs() SQLiteDatabase.openOrCreateDatabase(databaseFile, null).use { database -> - database.execSQL("CREATE TABLE routes (route_key INTEGER, route_id TEXT, route_name TEXT)") - database.execSQL("CREATE TABLE paths (route_key INTEGER, path_id INTEGER, path_name TEXT)") database.execSQL( - "CREATE TABLE stops (route_key INTEGER, path_id INTEGER, stop_id TEXT, " + - "stop_name TEXT, sequence INTEGER, lon REAL, lat REAL)", + "CREATE TABLE stops (routeid TEXT, pathid INTEGER, seq INTEGER, stopid TEXT, " + + "name TEXT, name_en TEXT, lat REAL, lon REAL, PRIMARY KEY (routeid, pathid, seq))", ) - database.execSQL("INSERT INTO routes VALUES (100, 'KHH100', '100')") - database.execSQL("INSERT INTO paths VALUES (100, 0, '去程')") database.execSQL( - "INSERT INTO stops VALUES (100, 0, '$RAW_STOP_ID', '測試站', 1, 120.338401, 22.60612)", + "INSERT INTO stops VALUES ('KHH100', 1, 1, ?, '測試站', NULL, 22.60612, 120.338401)", + arrayOf(RAW_STOP_ID.toString()), ) } - val routeData = requireNotNull( - SmartRouteNotificationSupport.loadRouteData(application, "khh", 100, "100"), - ) - val here = Location("test").apply { - latitude = 22.60612 - longitude = 120.338401 - } - val nearestStop = requireNotNull( - SmartRouteNotificationSupport.findNearestStop(here, routeData, pathId = 0), + val routeData = requireNotNull(SmartRouteNotificationSupport.loadRouteData(application, slot)) + val choice = requireNotNull( + SmartRouteNotificationSupport.chooseStop(slot, routeData, location = null), ) - - assertEquals( - "the live feed is still looked up by the folded key", - foldStopId(RAW_STOP_ID), - nearestStop.stopId, + assertEquals(RAW_STOP_ID.toString(), choice.stop.rawStopId) + + // The feed is joined by the stored string, not the native folded key. + val feed = """ + {"paths": [{"pathid": 1, "stops": [ + {"stopid": "${foldStopId(RAW_STOP_ID)}", "eta": 300}, + {"stopid": "$RAW_STOP_ID", "eta": 480} + ]}]} + """.trimIndent() + val now = 1775604360000L + val live = requireNotNull( + SmartRouteReminderRules.parseLiveStop(feed, slot.pathId, choice.stop.rawStopId, now), ) + val decision = requireNotNull(SmartRouteReminderRules.decide(live, choice.distanceMeters)) + assertEquals(480, decision.etaSeconds) SmartRouteNotificationSupport.ensureChannel(application) SmartRouteNotificationSupport.showNotification( context = application, - profile = SmartRouteProfile( - provider = "khh", - routeKey = 100, - pathId = 0, - routeName = "100", - totalOpens = 5, - lastOpenedAtMs = 0L, - totalSelections = 0, - lastSelectedAtMs = 0L, - hourlyOpens = mapOf(8 to 5), - hourlySelections = emptyMap(), + slot = slot, + stop = choice.stop, + text = SmartRouteReminderRules.buildText( + routeName = slot.routeName, + pathName = routeData.pathName, + stopName = choice.stop.stopName, + decision = decision, + distanceMeters = choice.distanceMeters, + slot = slot, + dayStartHour = 4, + nowMs = now, ), - routeData = routeData, - nearestStop = nearestStop, - liveStop = SmartLiveStop(sec = 120, msg = null), - distanceMeters = nearestStop.distanceMeters, - nowMs = 1L, + timeoutMs = SmartRouteReminderRules.timeoutMs(decision), ) val posted = shadowOf(application.getSystemService(NotificationManager::class.java)) .allNotifications .single() val payload = launchPayloadOf(shadowOf(posted.contentIntent).savedIntent) + assertEquals("KHH100", payload["routeId"]) + assertEquals(1, payload["pathId"]) assertEquals(RAW_STOP_ID, payload.stopId("stopId")) } diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/LastBusMessageTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/LastBusMessageTest.kt index 5632f05d..58b89445 100644 --- a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/LastBusMessageTest.kt +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/LastBusMessageTest.kt @@ -1,7 +1,5 @@ package tw.avianjay.taiwanbus.flutter -import java.util.Calendar -import org.junit.Assert.assertEquals import org.junit.Assert.assertFalse import org.junit.Assert.assertTrue import org.junit.Test @@ -24,44 +22,4 @@ class LastBusMessageTest { listOf(null, "", "末班車 23:00", "末班車尚未駛離", "末班車即將進站", "一般班次已過站") .forEach { message -> assertFalse(message, isLastBusMessage(message)) } } - - @Test - fun finalBusLiveStopIsIneligibleForNotification() { - assertFalse( - SmartRouteNotificationSupport.shouldNotify( - SmartLiveStop(sec = 60, msg = "末班車:已過。"), - ), - ) - } - - @Test - fun rankingRetainsLowerCandidatesForEligibilityFallback() { - val now = Calendar.getInstance() - val currentHour = now.get(Calendar.HOUR_OF_DAY) - val profiles = listOf( - profile(routeKey = 1, hour = currentHour, count = 5), - profile(routeKey = 1, hour = currentHour, count = 4), - profile(routeKey = 2, hour = currentHour, count = 3), - ) - - val ranked = SmartRouteNotificationSupport.chooseProfilesForNow( - profiles = profiles, - nowMs = now.timeInMillis, - ) - - assertEquals(listOf(1, 2), ranked.map { it.routeKey }) - } - - private fun profile(routeKey: Int, hour: Int, count: Int) = SmartRouteProfile( - provider = "nwt", - routeKey = routeKey, - pathId = 0, - routeName = routeKey.toString(), - totalOpens = count, - lastOpenedAtMs = System.currentTimeMillis(), - totalSelections = 0, - lastSelectedAtMs = 0, - hourlyOpens = mapOf(hour to count), - hourlySelections = emptyMap(), - ) } diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationDatabaseTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationDatabaseTest.kt new file mode 100644 index 00000000..cfb2d2bf --- /dev/null +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationDatabaseTest.kt @@ -0,0 +1,210 @@ +package tw.avianjay.taiwanbus.flutter + +import android.app.Application +import android.content.Context +import android.database.sqlite.SQLiteDatabase +import java.io.File +import org.junit.Assert.assertEquals +import org.junit.Assert.assertNull +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.annotation.Config + +/** + * The reminder reads the same database files the Flutter side keeps, so these + * build them with the statements those files are actually created by. + */ +@RunWith(RobolectricTestRunner::class) +@Config(sdk = [34], application = Application::class) +class SmartRouteNotificationDatabaseTest { + private lateinit var context: Context + private lateinit var databaseDirectory: File + + private val slot = SmartPlanSlot( + provider = "khh", + routeKey = 101, + routeId = "KHH100", + pathId = 1, + routeName = "100", + weekday = 3, + startMinute = 190, + endMinute = 250, + peakMinute = 220, + validUntilMs = Long.MAX_VALUE, + stopId = 100100128221, + ) + + @Before + fun setUp() { + context = RuntimeEnvironment.getApplication() + // BusRepository._databaseDirectory(): getDatabasesPath()/.yabus_backend + databaseDirectory = File(context.getDatabasePath("_").parentFile, ".yabus_backend") + databaseDirectory.deleteRecursively() + databaseDirectory.mkdirs() + } + + private fun createStops(fileName: String = "bus_khh_v2.sqlite") { + SQLiteDatabase.openOrCreateDatabase(File(databaseDirectory, fileName), null).use { database -> + database.execSQL( + """ + CREATE TABLE stops ( + routeid TEXT NOT NULL, + pathid INTEGER NOT NULL, + seq INTEGER NOT NULL, + stopid TEXT NOT NULL, + name TEXT NOT NULL, + name_en TEXT, + lat REAL NOT NULL, + lon REAL NOT NULL, + PRIMARY KEY (routeid, pathid, seq) + ) + """.trimIndent(), + ) + fun insert(routeId: String, pathId: Int, seq: Int, stopId: String, name: String) = + database.execSQL( + "INSERT INTO stops VALUES (?, ?, ?, ?, ?, NULL, ?, ?)", + arrayOf(routeId, pathId, seq, stopId, name, 22.6 + seq / 1000.0, 120.3), + ) + // Out of order, to show the reader sorts by running order. + insert("KHH100", 1, 2, "100100128221", "第二站") + insert("KHH100", 1, 1, "100100128219", "第一站") + insert("KHH100", 1, 3, "101-11009", "第三站") + insert("KHH100", 0, 1, "100100128221", "對向") + insert("KHH200", 1, 1, "999", "別條路線") + } + } + + private fun createMetadata(fileName: String = "routes_metadata_v1.sqlite") { + SQLiteDatabase.openOrCreateDatabase(File(databaseDirectory, fileName), null).use { database -> + database.execSQL( + """ + CREATE TABLE routes ( + routeid TEXT PRIMARY KEY, + name TEXT NOT NULL, + name_en TEXT, + city_code TEXT NOT NULL, + path_name TEXT, + path_name_en TEXT, + operator_names TEXT + ) + """.trimIndent(), + ) + database.execSQL( + """ + CREATE TABLE paths ( + routeid TEXT NOT NULL, + pathid INTEGER NOT NULL, + name TEXT NOT NULL, + name_en TEXT, + PRIMARY KEY (routeid, pathid), + FOREIGN KEY (routeid) REFERENCES routes(routeid) ON DELETE CASCADE + ) + """.trimIndent(), + ) + database.execSQL("INSERT INTO routes VALUES ('KHH100', '100', NULL, 'KHH', NULL, NULL, NULL)") + database.execSQL("INSERT INTO paths VALUES ('KHH100', 0, '往甲', NULL)") + database.execSQL("INSERT INTO paths VALUES ('KHH100', 1, '往乙', NULL)") + } + } + + @Test + fun readsTheStopsOfOneDirectionFromTheDatabaseTheAppKeeps() { + createStops() + createMetadata() + + val data = SmartRouteNotificationSupport.loadRouteData(context, slot) + + assertEquals("往乙", data?.pathName) + assertEquals( + listOf("100100128219" to "第一站", "100100128221" to "第二站", "101-11009" to "第三站"), + data?.stops?.map { it.rawStopId to it.stopName }, + ) + assertEquals(listOf(1, 1, 1), data?.stops?.map { it.pathId }) + assertEquals(22.602, data!!.stops[1].lat, 1e-9) + assertEquals(120.3, data.stops[1].lon, 1e-9) + // And the plan's stop is found among them by its full-width id. + assertEquals( + "第二站", + SmartRouteReminderRules.findUsualStop(slot, data.stops)?.stopName, + ) + } + + @Test + fun doesWithoutADirectionNameWhenTheMetadataIsMissing() { + createStops() + + val data = SmartRouteNotificationSupport.loadRouteData(context, slot) + + assertNull(data?.pathName) + assertEquals(3, data?.stops?.size) + } + + @Test + fun readsTheMetadataFileUnderItsOlderName() { + createStops() + createMetadata("routes_metadata_v2.sqlite") + + assertEquals( + "往乙", + SmartRouteNotificationSupport.loadRouteData(context, slot)?.pathName, + ) + } + + @Test + fun hasNothingToOfferWithoutTheProvidersDatabase() { + createMetadata() + + assertNull(SmartRouteNotificationSupport.loadRouteData(context, slot)) + } + + @Test + fun hasNothingToOfferForARouteOrDirectionTheDatabaseDoesNotList() { + createStops() + + assertNull( + SmartRouteNotificationSupport.loadRouteData(context, slot.copy(routeId = "KHH999")), + ) + assertNull(SmartRouteNotificationSupport.loadRouteData(context, slot.copy(pathId = 7))) + } + + @Test + fun aDatabaseOfAnotherShapeIsNotAnError() { + // The layout this worker used to query, which the app stopped + // writing in 2026-04. Reading it must come back empty, not throw. + SQLiteDatabase.openOrCreateDatabase( + File(databaseDirectory, "bus_khh_v2.sqlite"), + null, + ).use { database -> + database.execSQL( + "CREATE TABLE stops (route_key INTEGER, path_id INTEGER, stop_id INTEGER, " + + "stop_name TEXT, sequence INTEGER, lon REAL, lat REAL)", + ) + } + + assertNull(SmartRouteNotificationSupport.loadRouteData(context, slot)) + } + + @Test + fun aFileThatIsNotADatabaseIsNotAnError() { + File(databaseDirectory, "bus_khh_v2.sqlite").writeText("half a download") + + assertNull(SmartRouteNotificationSupport.loadRouteData(context, slot)) + } + + @Test + fun stillFindsADatabaseLeftWhereTheAppUsedToKeepThem() { + databaseDirectory.deleteRecursively() + databaseDirectory = File(context.filesDir.parentFile, "app_flutter/.yabus_backend") + databaseDirectory.deleteRecursively() + databaseDirectory.mkdirs() + createStops() + + assertEquals( + 3, + SmartRouteNotificationSupport.loadRouteData(context, slot)?.stops?.size, + ) + } +} diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt new file mode 100644 index 00000000..951b4b20 --- /dev/null +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt @@ -0,0 +1,819 @@ +package tw.avianjay.taiwanbus.flutter + +import java.io.File +import java.util.Calendar +import java.util.TimeZone +import kotlinx.serialization.json.Json +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNotNull +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test + +class SmartRouteReminderRulesTest { + private val taipei = TimeZone.getTimeZone("Asia/Taipei") + + /** A moment on the wall clock in Taipei. 2026-04-08 is a Wednesday. */ + private fun at(day: Int, hour: Int, minute: Int): Long = + Calendar.getInstance(taipei).apply { + clear() + set(2026, Calendar.APRIL, day, hour, minute) + }.timeInMillis + + private fun slot( + weekday: Int = 3, + routeKey: Int = 101, + pathId: Int = 0, + provider: String = "khh", + startMinute: Int = 190, + endMinute: Int = 250, + peakMinute: Int = 220, + confidence: Double = 0.9, + validUntilMs: Long = at(22, 4, 0), + lastActivityAtMs: Long = at(7, 7, 40), + stopId: Long? = 100100128221, + ) = SmartPlanSlot( + provider = provider, + routeKey = routeKey, + routeId = "KHH$routeKey", + pathId = pathId, + routeName = "307", + weekday = weekday, + startMinute = startMinute, + endMinute = endMinute, + peakMinute = peakMinute, + confidence = confidence, + supportDays = 15, + validUntilMs = validUntilMs, + lastActivityAtMs = lastActivityAtMs, + stopId = stopId, + ) + + private fun plan(vararg slots: SmartPlanSlot) = + SmartRoutePlan(version = 1, dayStartHour = 4, slots = slots.toList()) + + private fun stop(rawStopId: String, pathId: Int = 0, name: String = "站") = + SmartRouteStop( + pathId = pathId, + rawStopId = rawStopId, + stopName = name, + sequence = 1, + lon = 120.3, + lat = 22.6, + ) + + // --- the plan ----------------------------------------------------------- + + @Test + fun readsThePlanTheFlutterSideWrites() { + // The same file SmartRoutePlanner's own test compares its output to. + val plan = SmartRouteReminderRules.parsePlan(sharedFixture().readText()) + + assertNotNull(plan) + assertEquals(4, plan!!.dayStartHour) + assertEquals(6, plan.slots.size) + val monday = plan.slots.first() + assertEquals("khh", monday.provider) + assertEquals(101, monday.routeKey) + assertEquals("KHH101", monday.routeId) + assertEquals(0, monday.pathId) + assertEquals("307", monday.routeName) + assertEquals(1, monday.weekday) + assertEquals(190, monday.startMinute) + assertEquals(250, monday.endMinute) + assertEquals(220, monday.peakMinute) + assertEquals(0.918, monday.confidence, 1e-9) + assertEquals(15, monday.supportDays) + assertEquals(1776801600000L, monday.validUntilMs) + assertEquals(1775518800000L, monday.lastActivityAtMs) + // Too wide for an Int: the reason this field is a Long. + assertEquals(100100128221L, monday.stopId) + val saturday = plan.slots.last() + assertEquals(6, saturday.weekday) + assertEquals("紅12", saturday.routeName) + assertNull(saturday.stopId) + } + + @Test + fun ignoresAPlanItCannotTrust() { + val valid = sharedFixture().readText() + + assertNull(SmartRouteReminderRules.parsePlan(null)) + assertNull(SmartRouteReminderRules.parsePlan(" ")) + assertNull(SmartRouteReminderRules.parsePlan("{not json")) + assertNull(SmartRouteReminderRules.parsePlan("""{"slots": []}""")) + assertNull( + SmartRouteReminderRules.parsePlan(valid.replace("\"version\": 1", "\"version\": 2")), + ) + assertNull( + SmartRouteReminderRules.parsePlan( + valid.replace("\"dayStartHour\": 4", "\"dayStartHour\": 24"), + ), + ) + // A field added by a later writer is not a reason to stop reading. + assertNotNull( + SmartRouteReminderRules.parsePlan( + valid.replace("\"version\": 1", "\"version\": 1, \"note\": \"x\""), + ), + ) + } + + // --- the clock ---------------------------------------------------------- + + @Test + fun aServiceDayRunsFromFourToFour() { + val morning = SmartRouteReminderRules.serviceClock(at(8, 7, 40), 4, taipei) + val justBeforeFour = SmartRouteReminderRules.serviceClock(at(8, 3, 59), 4, taipei) + val atFour = SmartRouteReminderRules.serviceClock(at(8, 4, 0), 4, taipei) + + assertEquals(3, morning.weekday) + assertEquals(220, morning.minute) + // 03:59 on Wednesday still belongs to Tuesday. + assertEquals(2, justBeforeFour.weekday) + assertEquals(23 * 60 + 59, justBeforeFour.minute) + assertEquals(3, atFour.weekday) + assertEquals(0, atFour.minute) + assertEquals(morning.day, atFour.day) + assertTrue(justBeforeFour.day != atFour.day) + } + + @Test + fun weekdaysCountFromMonday() { + // 2026-04-06 is a Monday, 2026-04-12 a Sunday. + assertEquals( + listOf(1, 2, 3, 4, 5, 6, 7), + (6..12).map { SmartRouteReminderRules.serviceClock(at(it, 12, 0), 4, taipei).weekday }, + ) + } + + // --- when a slot is due ------------------------------------------------- + + @Test + fun aSlotIsDueFromALittleBeforeTheUsualTimeUntilItsWindowEnds() { + val plan = plan(slot()) + fun dueAt(hour: Int, minute: Int) = + SmartRouteReminderRules.dueSlots(plan, "khh", at(8, hour, minute), taipei).size + + // Usual time 07:40, window 07:10 to 08:10, lead fifteen minutes. + assertEquals(0, dueAt(7, 10)) + assertEquals(0, dueAt(7, 24)) + assertEquals(1, dueAt(7, 25)) + assertEquals(1, dueAt(7, 40)) + assertEquals(1, dueAt(8, 10)) + assertEquals(0, dueAt(8, 11)) + } + + @Test + fun aNarrowWindowIsNotOpenedEarlyByTheLead() { + val plan = plan(slot(startMinute = 215, endMinute = 225)) + + assertEquals( + 0, + SmartRouteReminderRules.dueSlots(plan, "khh", at(8, 7, 34), taipei).size, + ) + assertEquals( + 1, + SmartRouteReminderRules.dueSlots(plan, "khh", at(8, 7, 35), taipei).size, + ) + } + + @Test + fun aSlotIsOnlyDueOnItsWeekdayForItsProviderAndWhileValid() { + val now = at(8, 7, 40) + fun due(slot: SmartPlanSlot, provider: String = "khh") = + SmartRouteReminderRules.dueSlots(plan(slot), provider, now, taipei).size + + assertEquals(1, due(slot())) + assertEquals(0, due(slot(weekday = 2))) + assertEquals(0, due(slot(), provider = "tpe")) + assertEquals(0, due(slot(validUntilMs = now))) + assertEquals(1, due(slot(validUntilMs = now + 1))) + } + + @Test + fun dueSlotsComeMostCertainFirstOncePerRouteAndDirection() { + val due = SmartRouteReminderRules.dueSlots( + plan( + slot(routeKey = 1, confidence = 0.6), + slot(routeKey = 2, confidence = 0.9), + slot(routeKey = 2, confidence = 0.7), + slot(routeKey = 2, pathId = 1, confidence = 0.8), + ), + "khh", + at(8, 7, 40), + taipei, + ) + + assertEquals( + listOf(2 to 0, 2 to 1, 1 to 0), + due.map { it.routeKey to it.pathId }, + ) + assertEquals(0.9, due.first().confidence, 1e-9) + } + + @Test + fun aPlanWithNothingLeftToFireIsNotLive() { + val now = at(8, 7, 40) + + assertTrue(SmartRouteReminderRules.hasLiveSlots(plan(slot()), now)) + assertFalse(SmartRouteReminderRules.hasLiveSlots(plan(slot(validUntilMs = now)), now)) + assertFalse(SmartRouteReminderRules.hasLiveSlots(plan(), now)) + } + + // --- holding a reminder back -------------------------------------------- + + @Test + fun aRouteAlreadyLookedAtForThisWindowIsNotRemindedAbout() { + // Window opens 07:10; anything from 06:40 on counts as having looked. + val now = at(8, 7, 40) + fun seen(lastActivityAtMs: Long) = SmartRouteReminderRules.wasSeenForWindow( + slot(lastActivityAtMs = lastActivityAtMs), + now, + nowMinute = 220, + ) + + assertFalse(seen(at(7, 7, 40))) + assertFalse(seen(at(8, 6, 39))) + assertTrue(seen(at(8, 6, 40))) + assertTrue(seen(at(8, 7, 30))) + } + + @Test + fun remindersKeepApartAndStopAfterSixInADay() { + val now = at(8, 7, 40) + val today = 2026098L + val twentyMinutes = 20 * 60 * 1000L + + assertTrue(SmartRouteReminderRules.mayRemind(SmartReminderHistory(), now, today)) + assertFalse( + SmartRouteReminderRules.mayRemind( + SmartReminderHistory(lastAnyMs = now - twentyMinutes + 1), + now, + today, + ), + ) + assertTrue( + SmartRouteReminderRules.mayRemind( + SmartReminderHistory(lastAnyMs = now - twentyMinutes), + now, + today, + ), + ) + assertFalse( + SmartRouteReminderRules.mayRemind( + SmartReminderHistory(countDay = today, countThatDay = 6), + now, + today, + ), + ) + assertTrue( + SmartRouteReminderRules.mayRemind( + SmartReminderHistory(countDay = today, countThatDay = 5), + now, + today, + ), + ) + // Yesterday's count does not carry over. + assertTrue( + SmartRouteReminderRules.mayRemind( + SmartReminderHistory(countDay = today - 1, countThatDay = 6), + now, + today, + ), + ) + } + + @Test + fun aReminderIsCountedAgainstItsDay() { + val now = at(8, 7, 40) + + assertEquals( + SmartReminderHistory(lastAnyMs = now, countDay = 7L, countThatDay = 3), + SmartRouteReminderRules.afterReminder( + SmartReminderHistory(lastAnyMs = 1L, countDay = 7L, countThatDay = 2), + now, + today = 7L, + ), + ) + assertEquals( + SmartReminderHistory(lastAnyMs = now, countDay = 8L, countThatDay = 1), + SmartRouteReminderRules.afterReminder( + SmartReminderHistory(lastAnyMs = 1L, countDay = 7L, countThatDay = 6), + now, + today = 8L, + ), + ) + } + + @Test + fun aRouteIsRemindedAboutOncePerWindow() { + val now = at(8, 7, 40) + val threeHours = 3 * 60 * 60 * 1000L + + assertTrue(SmartRouteReminderRules.mayRemindRoute(0L, now)) + assertFalse(SmartRouteReminderRules.mayRemindRoute(now - threeHours + 1, now)) + assertTrue(SmartRouteReminderRules.mayRemindRoute(now - threeHours, now)) + } + + // --- the log of what was shown ------------------------------------------ + + @Test + fun writesTheLogTheFlutterSideReads() { + // The same file SmartRoutePlanner's test reads reminders from. + val slots = SmartRouteReminderRules.parsePlan(sharedFixture().readText())!!.slots + val firstShown = 1775604360000L + val secondShown = 1775901000000L + + val log = SmartRouteReminderRules.appendToReminderLog( + SmartRouteReminderRules.appendToReminderLog(null, slots.first(), firstShown), + slots.last(), + secondShown, + ) + + assertEquals( + Json.parseToJsonElement(sharedFixture("smart_route_reminder_log_v1.json").readText()), + Json.parseToJsonElement(log), + ) + assertEquals( + listOf( + SmartReminderLogEntry("khh", 101, 0, firstShown, peakMinute = 220), + SmartReminderLogEntry("khh", 202, 1, secondShown, peakMinute = 840), + ), + SmartRouteReminderRules.parseReminderLog(log), + ) + } + + @Test + fun theLogForgetsWhatTheHabitModelNoLongerLooksAt() { + val now = at(8, 7, 40) + val eightWeeks = 56L * 24 * 60 * 60 * 1000 + fun shownAt(vararg times: Long) = times.fold(null as String?) { log, time -> + SmartRouteReminderRules.appendToReminderLog(log, slot(), time) + } + + val log = SmartRouteReminderRules.appendToReminderLog( + shownAt(now - eightWeeks, now - eightWeeks + 1, now - 1), + slot(routeKey = 7), + now, + ) + + assertEquals( + listOf(now - eightWeeks + 1 to 101, now - 1 to 101, now to 7), + SmartRouteReminderRules.parseReminderLog(log).map { it.atMs to it.routeKey }, + ) + } + + @Test + fun theLogKeepsOnlyItsNewestEntries() { + val now = at(8, 7, 40) + var log: String? = null + repeat(SmartRouteReminderRules.REMINDER_LOG_MAX_ENTRIES + 3) { index -> + log = SmartRouteReminderRules.appendToReminderLog(log, slot(), now + index) + } + + val entries = SmartRouteReminderRules.parseReminderLog(log) + assertEquals(SmartRouteReminderRules.REMINDER_LOG_MAX_ENTRIES, entries.size) + assertEquals(now + 3, entries.first().atMs) + assertEquals( + now + SmartRouteReminderRules.REMINDER_LOG_MAX_ENTRIES + 2, + entries.last().atMs, + ) + } + + @Test + fun aLogThatCannotBeReadIsStartedAgainNotFailedOn() { + val now = at(8, 7, 40) + + assertTrue(SmartRouteReminderRules.parseReminderLog(null).isEmpty()) + assertTrue(SmartRouteReminderRules.parseReminderLog(" ").isEmpty()) + assertTrue(SmartRouteReminderRules.parseReminderLog("[{").isEmpty()) + assertTrue(SmartRouteReminderRules.parseReminderLog("""{"atMs": 1}""").isEmpty()) + assertEquals( + listOf(now), + SmartRouteReminderRules.parseReminderLog( + SmartRouteReminderRules.appendToReminderLog("[{", slot(), now), + ).map { it.atMs }, + ) + } + + @Test + fun oneUnreadableEntryDoesNotCostTheLogItsOthers() { + val now = at(8, 7, 40) + val log = """ + [ + {"provider": "khh", "routeKey": 101, "pathId": 0, "atMs": ${now - 2}}, + {"provider": "khh", "routeKey": "one hundred", "pathId": 0, "atMs": ${now - 1}}, + "not an entry", + {"provider": "khh", "routeKey": 101, "pathId": 0, "atMs": $now, "peakMinute": 220, "later": true} + ] + """.trimIndent() + + assertEquals( + listOf( + // Written before the log said what a reminder was for. + SmartReminderLogEntry("khh", 101, 0, now - 2, peakMinute = null), + SmartReminderLogEntry("khh", 101, 0, now, peakMinute = 220), + ), + SmartRouteReminderRules.parseReminderLog(log), + ) + } + + // --- which stop --------------------------------------------------------- + + @Test + fun theUsualStopCanHaveANonNumericProviderId() { + val alphanumeric = stop("101-11009") + // Flutter stores the hash for a non-numeric id; the feed uses the text. + assertEquals( + alphanumeric, + SmartRouteReminderRules.findUsualStop(slot(stopId = 64427917L), listOf(alphanumeric)), + ) + assertNull(SmartRouteReminderRules.findUsualStop(slot(stopId = 0L), listOf(stop("")))) + } + + @Test + fun theUsualStopIsFoundByItsFullWidthIdOnTheSlotsDirection() { + val stops = listOf( + stop("18464"), + stop("100100128221", name = "常用站"), + stop("100100128221", pathId = 1, name = "對向"), + ) + + assertEquals( + "常用站", + SmartRouteReminderRules.findUsualStop(slot(), stops)?.stopName, + ) + assertNull(SmartRouteReminderRules.findUsualStop(slot(stopId = null), stops)) + assertNull(SmartRouteReminderRules.findUsualStop(slot(stopId = 999L), stops)) + // 100100128221 and 1315880413 share their low 32 bits; they are not + // the same stop. + assertNull(SmartRouteReminderRules.findUsualStop(slot(stopId = 1315880413L), stops)) + } + + @Test + fun theUsualStopIsWatchedWithoutAnyLocation() { + val usual = stop("1", name = "常用站") + + val choice = SmartRouteReminderRules.chooseStop( + usualStop = usual, + usualDistanceMeters = null, + nearestStop = null, + nearestDistanceMeters = null, + ) + + assertEquals(usual, choice?.stop) + assertNull(choice?.distanceMeters) + } + + @Test + fun theUsualStopIsKeptWhileItIsInReach() { + val usual = stop("1", name = "常用站") + val nearer = stop("2", name = "較近") + + val choice = SmartRouteReminderRules.chooseStop( + usualStop = usual, + usualDistanceMeters = 1000.0, + nearestStop = nearer, + nearestDistanceMeters = 50.0, + ) + + assertEquals(usual, choice?.stop) + assertEquals(1000.0, choice!!.distanceMeters!!, 1e-9) + } + + @Test + fun farFromTheUsualStopTheNearestStandsInIfItIsClose() { + val usual = stop("1", name = "常用站") + val nearest = stop("2", name = "最近") + + val close = SmartRouteReminderRules.chooseStop(usual, 1000.1, nearest, 800.0) + val tooFar = SmartRouteReminderRules.chooseStop(usual, 5000.0, nearest, 800.1) + + assertEquals(nearest, close?.stop) + assertEquals(800.0, close!!.distanceMeters!!, 1e-9) + assertNull(tooFar) + } + + @Test + fun withNoUsualStopOnlyANearbyOneWillDo() { + val nearest = stop("2", name = "最近") + + assertEquals( + nearest, + SmartRouteReminderRules.chooseStop(null, null, nearest, 300.0)?.stop, + ) + assertNull(SmartRouteReminderRules.chooseStop(null, null, nearest, 900.0)) + assertNull(SmartRouteReminderRules.chooseStop(null, null, null, null)) + } + + // --- the live feed ------------------------------------------------------ + + private val feedTime = at(8, 7, 30) + + private fun feed(updatedAtSeconds: Long = feedTime / 1000 - 15) = """ + {"routeid": "KHH101", "updated_at": $updatedAtSeconds, "stale": false, "paths": [ + {"pathid": 0, "name": "往甲", "stops": [ + {"stopid": "18464", "eta": null, "message": "未發車", "updated_at": $updatedAtSeconds, + "buses": [], "etas": []}, + {"stopid": "100100128221", "eta": 480, "message": null, + "updated_at": $updatedAtSeconds, "buses": [], + "etas": [{"eta": 480, "plate": "KKA-0001"}, + {"eta": 900, "message": "未發車"}, + {"eta": 1260, "plate": "KKA-0002", "message": ""}, + {"eta": null, "message": "末班駛離"}]}, + {"stopid": 18470, "eta": 95, "message": "即將進站", "updated_at": $updatedAtSeconds, + "buses": [], "etas": [{"eta": 95}]} + ]}, + {"pathid": 1, "name": "往乙", "stops": [ + {"stopid": "100100128221", "eta": 60, "message": null, + "updated_at": $updatedAtSeconds, "buses": [], "etas": []}, + {"stopid": "20001", "eta": 300, "message": null, "updated_at": $updatedAtSeconds} + ]} + ]} + """.trimIndent() + + @Test + fun readsAStopsArrivalsFromTheFeed() { + val stop = SmartRouteReminderRules.parseLiveStop(feed(), 0, "100100128221", feedTime) + + assertEquals(480, stop?.sec) + assertNull(stop?.msg) + // The entries that carry a status instead of a time are left out. + assertEquals(listOf(480, 1260), stop?.arrivals) + } + + @Test + fun readsAStopOnlyFromItsOwnDirection() { + // The same id is on both directions; the bus a minute away is the + // one going the other way. + assertEquals( + 60, + SmartRouteReminderRules.parseLiveStop(feed(), 1, "100100128221", feedTime)?.sec, + ) + assertNull(SmartRouteReminderRules.parseLiveStop(feed(), 0, "20001", feedTime)) + assertNull(SmartRouteReminderRules.parseLiveStop(feed(), 2, "100100128221", feedTime)) + } + + @Test + fun readsStatusMessagesAndNumericStopIds() { + val notDeparted = SmartRouteReminderRules.parseLiveStop(feed(), 0, "18464", feedTime) + val arriving = SmartRouteReminderRules.parseLiveStop(feed(), 0, "18470", feedTime) + + assertNull(notDeparted?.sec) + assertEquals("未發車", notDeparted?.msg) + assertEquals(emptyList(), notDeparted?.arrivals) + assertEquals(95, arriving?.sec) + assertEquals("即將進站", arriving?.msg) + } + + @Test + fun anEstimateTooOldToActOnIsNoEstimate() { + val fiveMinutes = 5 * 60L + fun read(updatedAtSeconds: Long) = SmartRouteReminderRules.parseLiveStop( + feed(updatedAtSeconds), + 0, + "100100128221", + feedTime, + ) + + assertNotNull(read(feedTime / 1000 - fiveMinutes)) + assertNull(read(feedTime / 1000 - fiveMinutes - 1)) + // A device clock a little behind the server's is not a stale feed. + assertNotNull(read(feedTime / 1000 + 120)) + } + + @Test + fun aResponseThatIsNotAFeedYieldsNothing() { + assertNull(SmartRouteReminderRules.parseLiveStop("", 0, "1", feedTime)) + assertNull(SmartRouteReminderRules.parseLiveStop("[]", 0, "1", feedTime)) + assertNull(SmartRouteReminderRules.parseLiveStop("{}", 0, "1", feedTime)) + assertNull(SmartRouteReminderRules.parseLiveStop("""{"paths": 3}""", 0, "1", feedTime)) + } + + // --- whether there is a bus worth mentioning ---------------------------- + + @Test + fun remindsAboutABusThatCanStillBeCaught() { + val decision = SmartRouteReminderRules.decide( + SmartLiveStop(sec = 480, msg = null, arrivals = listOf(480, 1260)), + distanceMeters = null, + ) + + assertEquals(SmartEtaDecision(etaSeconds = 480, followingEtaSeconds = 1260), decision) + } + + @Test + fun aBusTooCloseToCatchGivesWayToTheOneBehindIt() { + val live = SmartLiveStop(sec = 179, msg = null, arrivals = listOf(179, 900)) + + assertEquals( + SmartEtaDecision(etaSeconds = 900, followingEtaSeconds = null), + SmartRouteReminderRules.decide(live, distanceMeters = null), + ) + assertEquals( + 180, + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 180, msg = null), + distanceMeters = null, + )?.etaSeconds, + ) + } + + @Test + fun theWalkToTheStopDecidesWhichBusIsCatchable() { + // 600 m at a metre a second, plus a minute to spare: eleven minutes. + val live = SmartLiveStop(sec = 480, msg = null, arrivals = listOf(480, 659, 660, 1400)) + + assertEquals(660, SmartRouteReminderRules.walkingSeconds(600.0)) + assertEquals( + SmartEtaDecision(etaSeconds = 660, followingEtaSeconds = 1400), + SmartRouteReminderRules.decide(live, distanceMeters = 600.0), + ) + assertEquals(480, SmartRouteReminderRules.decide(live, distanceMeters = 100.0)?.etaSeconds) + } + + @Test + fun aBusStillFarOffIsLeftForALaterCheck() { + assertEquals( + 1500, + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 1500, msg = null), + distanceMeters = null, + )?.etaSeconds, + ) + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 1501, msg = null), + distanceMeters = null, + ), + ) + // Nor is a far bus mentioned just because a near one cannot be caught. + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 60, msg = null, arrivals = listOf(60, 1800)), + distanceMeters = null, + ), + ) + } + + @Test + fun aStopReportingAStatusIsNotAnArrival() { + // The old rule sent a reminder for any message at all, 未發車 included. + listOf("未發車", "交管不停靠", "今日未營運", "末班駛離").forEach { message -> + assertNull( + message, + SmartRouteReminderRules.decide( + SmartLiveStop(sec = null, msg = message), + distanceMeters = null, + ), + ) + } + // The top-level time is not trusted when a status comes with it, but + // a timed bus listed behind it still counts. + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 600, msg = "未發車"), + distanceMeters = null, + ), + ) + assertEquals( + 600, + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 30, msg = "進站中", arrivals = listOf(30, 600)), + distanceMeters = null, + )?.etaSeconds, + ) + } + + @Test + fun theLastBusHavingGoneEndsIt() { + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = 600, msg = "末班車:已過。", arrivals = listOf(600)), + distanceMeters = null, + ), + ) + } + + @Test + fun withNoTimedArrivalThereIsNothingToSay() { + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = null, msg = null), + distanceMeters = null, + ), + ) + assertNull( + SmartRouteReminderRules.decide( + SmartLiveStop(sec = -1, msg = null, arrivals = listOf(-5)), + distanceMeters = null, + ), + ) + } + + // --- what the reminder says --------------------------------------------- + + @Test + fun theReminderGivesTheArrivalAsAClockTime() { + val text = SmartRouteReminderRules.buildText( + routeName = "307", + pathName = "往市政府", + stopName = "捷運國父紀念館站", + decision = SmartEtaDecision(etaSeconds = 480, followingEtaSeconds = 1260), + distanceMeters = 350.0, + slot = slot(peakMinute = 218), + dayStartHour = 4, + nowMs = at(8, 7, 30), + zone = taipei, + ) + + assertEquals("307 約 8 分後到站", text.title) + assertEquals("捷運國父紀念館站 · 預計 07:38 到站", text.text) + assertEquals( + "捷運國父紀念館站 預計 07:38 到站,下一班約 21 分後。" + + "方向:往市政府。距離你約 350m。你常在 07:40 左右查看這條路線。", + text.bigText, + ) + } + + @Test + fun theReminderLeavesOutWhatItDoesNotKnow() { + val text = SmartRouteReminderRules.buildText( + routeName = " ", + pathName = null, + stopName = "常用站", + decision = SmartEtaDecision(etaSeconds = 200, followingEtaSeconds = null), + distanceMeters = null, + // 00:20, twenty hours and twenty minutes into the service day. + slot = slot(peakMinute = 1220), + dayStartHour = 4, + nowMs = at(8, 23, 58), + zone = taipei, + ) + + assertEquals("路線 約 3 分後到站", text.title) + assertEquals("常用站 · 預計 00:01 到站", text.text) + assertEquals("常用站 預計 00:01 到站。你常在 00:20 左右查看這條路線。", text.bigText) + } + + @Test + fun aReminderSaysSoWhenItsHabitIsAboutToLapse() { + val now = at(8, 7, 30) + val threeDays = 3L * 24 * 60 * 60 * 1000 + fun bigText(validUntilMs: Long) = SmartRouteReminderRules.buildText( + routeName = "307", + pathName = null, + stopName = "常用站", + decision = SmartEtaDecision(etaSeconds = 480, followingEtaSeconds = null), + distanceMeters = null, + slot = slot(validUntilMs = validUntilMs), + dayStartHour = 4, + nowMs = now, + zone = taipei, + ).bigText + val usual = "常用站 預計 07:38 到站。你常在 07:40 左右查看這條路線。" + val notice = "\n已有一段時間沒有開啟這條路線,提醒即將暫停;點這則通知查看路線即可繼續收到。" + + // Three days is when it starts being said, and not a moment sooner. + assertEquals(usual, bigText(now + threeDays + 1)) + assertEquals(usual + notice, bigText(now + threeDays)) + assertEquals(usual + notice, bigText(now + 1)) + assertFalse(SmartRouteReminderRules.isAboutToLapse(slot(), now)) + assertTrue( + SmartRouteReminderRules.isAboutToLapse(slot(validUntilMs = now + threeDays), now), + ) + } + + @Test + fun distancesReadTheSameInEveryLocale() { + assertEquals("999m", SmartRouteReminderRules.formatDistance(999.9)) + assertEquals("1.0km", SmartRouteReminderRules.formatDistance(1000.0)) + assertEquals("2.5km", SmartRouteReminderRules.formatDistance(2540.0)) + } + + @Test + fun aReminderOutlivesItsBusByThreeMinutes() { + assertEquals( + (480 + 180) * 1000L, + SmartRouteReminderRules.timeoutMs(SmartEtaDecision(480, null)), + ) + } + + /** + * A file under `test/fixtures` at the repository root, shared with the + * Dart tests so that a change to what one side writes cannot pass without + * the other side reading it. + */ + private fun sharedFixture(name: String = "smart_route_plan_v1.json"): File { + var directory: File? = File("").absoluteFile + while (directory != null) { + val candidate = File(directory, "test/fixtures/$name") + if (candidate.isFile) { + return candidate + } + directory = directory.parentFile + } + error("test/fixtures/$name not found above ${File("").absolutePath}") + } +} diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt new file mode 100644 index 00000000..53797515 --- /dev/null +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt @@ -0,0 +1,109 @@ +package tw.avianjay.taiwanbus.flutter + +import android.app.Application +import android.content.Context +import org.junit.Assert.assertEquals +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.annotation.Config + +/** What the worker keeps about the reminders it has shown, and for whom. */ +@RunWith(RobolectricTestRunner::class) +@Config(sdk = [34], application = Application::class) +class SmartRouteReminderStoreTest { + private lateinit var context: Context + + private val slot = SmartPlanSlot( + provider = "khh", + routeKey = 101, + routeId = "KHH101", + pathId = 0, + routeName = "307", + weekday = 3, + startMinute = 190, + endMinute = 250, + peakMinute = 220, + validUntilMs = Long.MAX_VALUE, + ) + private val shownAt = 1775604360000L + private val history = SmartReminderHistory( + lastAnyMs = shownAt, + countDay = 2026098L, + countThatDay = 1, + ) + + @Before + fun setUp() { + context = RuntimeEnvironment.getApplication() + } + + private fun loggedReminders() = SmartRouteReminderRules.parseReminderLog( + SmartRouteNotificationSupport.loadReminderLog(context), + ) + + @Test + fun nothingHasBeenShownToBeginWith() { + assertEquals("[]", SmartRouteNotificationSupport.loadReminderLog(context)) + assertEquals(SmartReminderHistory(), SmartRouteNotificationSupport.loadHistory(context)) + assertEquals(0L, SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot)) + } + + @Test + fun aReminderIsRememberedForTheNextCheckAndForTheFlutterSide() { + SmartRouteNotificationSupport.saveReminder(context, slot, history, shownAt) + + // For the next check: what holds a reminder back. + assertEquals(history, SmartRouteNotificationSupport.loadHistory(context)) + assertEquals( + shownAt, + SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot), + ) + // The other direction of the same route is another habit. + assertEquals( + 0L, + SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot.copy(pathId = 1)), + ) + // For the Flutter side: that it was shown, and what time it was for. + assertEquals( + listOf(SmartReminderLogEntry("khh", 101, 0, shownAt, peakMinute = 220)), + loggedReminders(), + ) + } + + @Test + fun eachReminderIsAddedToTheLog() { + val evening = slot.copy(routeKey = 202, pathId = 1, peakMinute = 840) + val later = shownAt + 10 * 60 * 60 * 1000L + + SmartRouteNotificationSupport.saveReminder(context, slot, history, shownAt) + SmartRouteNotificationSupport.saveReminder( + context, + evening, + history.copy(lastAnyMs = later, countThatDay = 2), + later, + ) + + assertEquals( + listOf( + SmartReminderLogEntry("khh", 101, 0, shownAt, peakMinute = 220), + SmartReminderLogEntry("khh", 202, 1, later, peakMinute = 840), + ), + loggedReminders(), + ) + assertEquals(2, SmartRouteNotificationSupport.loadHistory(context).countThatDay) + } + + @Test + fun forgettingLeavesNothingBehind() { + SmartRouteNotificationSupport.saveReminder(context, slot, history, shownAt) + + SmartRouteNotificationSupport.forgetReminders(context) + + assertEquals("[]", SmartRouteNotificationSupport.loadReminderLog(context)) + assertEquals(SmartReminderHistory(), SmartRouteNotificationSupport.loadHistory(context)) + assertEquals(0L, SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot)) + } +} diff --git a/lib/core/android_home_integration.dart b/lib/core/android_home_integration.dart index bf16164b..cbe5fb63 100644 --- a/lib/core/android_home_integration.dart +++ b/lib/core/android_home_integration.dart @@ -48,6 +48,10 @@ class AndroidHomeIntegration { }); } + /// Whether this platform has a background check that reads the reminder + /// plan. Elsewhere there is nobody to read one, so none is written. + static bool get supportsSmartRouteNotifications => _isAndroid; + static Future syncSmartRouteNotifications(bool enabled) async { if (!_isAndroid) { return; @@ -57,6 +61,31 @@ class AndroidHomeIntegration { }); } + /// The reminders the background check has shown, as the JSON it logs + /// them in, or null where there is no such check or it cannot be asked. + static Future loadSmartRouteReminderLog() async { + if (!_isAndroid) { + return null; + } + try { + return await _channel.invokeMethod('getSmartRouteReminderLog'); + } on MissingPluginException { + return null; + } on PlatformException { + return null; + } + } + + /// Has the background check forget which reminders it has shown. That + /// record is part of what the app has learned about the rider, so it goes + /// when the rest of it does. + static Future forgetSmartRouteReminders() async { + if (!_isAndroid) { + return; + } + await _channel.invokeMethod('forgetSmartRouteReminders'); + } + static Future setApplicationInForeground(bool value) async { if (!_isAndroid) { return; diff --git a/lib/core/app_controller.dart b/lib/core/app_controller.dart index 9a811c16..897c3e60 100644 --- a/lib/core/app_controller.dart +++ b/lib/core/app_controller.dart @@ -30,6 +30,7 @@ import 'haptic_feedback_service.dart'; import 'ios_widget_integration.dart'; import 'live_activity_service.dart'; import 'models.dart'; +import 'smart_route_plan.dart'; import 'smart_route_service.dart'; import 'storage_service.dart'; import 'wear_os_integration.dart'; @@ -155,6 +156,10 @@ class AppController extends ChangeNotifier { bool _pendingChangeDrivenAccountSync = false; int _recommendationRevision = 0; String? _cachedSmartRouteSignature; + + /// Route ids already looked up for the reminder plan, by provider and + /// route key. They do not change, so one lookup per route is enough. + final Map _smartRouteIds = {}; Object? _lastRecommendationRoutes; Object? _lastRecommendationFavorites; Object? _lastRecommendationUsage; @@ -506,11 +511,7 @@ class AppController extends ChangeNotifier { () => _syncWearOsSnapshot(requestRefresh: false), ); _attachWearOsEventStream(); - await _runNonCriticalStartupTask( - () => AndroidHomeIntegration.syncSmartRouteNotifications( - _settings.enableSmartRouteNotifications, - ), - ); + await _runNonCriticalStartupTask(_syncSmartRouteNotifications); await _runNonCriticalStartupTask( () => desktopDiscordPresenceService.refresh(settings: _settings), ); @@ -1290,9 +1291,7 @@ class AppController extends ChangeNotifier { await AndroidHomeIntegration.updateFavoriteWidgetAutoRefreshMinutes( _settings.favoriteWidgetAutoRefreshMinutes, ); - await AndroidHomeIntegration.syncSmartRouteNotifications( - _settings.enableSmartRouteNotifications, - ); + await _syncSmartRouteNotifications(); await desktopDiscordPresenceService.refresh(settings: _settings); await _syncWearOsSnapshot(requestRefresh: false); } @@ -2224,10 +2223,75 @@ class AppController extends ChangeNotifier { Future updateEnableSmartRouteNotifications(bool value) async { _settings = _settings.copyWith(enableSmartRouteNotifications: value); await _persistSettings(); - await AndroidHomeIntegration.syncSmartRouteNotifications(value); + await _syncSmartRouteNotifications(); notifyListeners(); } + /// Works out when a reminder is worth sending and hands that to the + /// platform, which only has to follow it. + /// + /// The plan is written before the scheduler is told anything, because the + /// scheduler decides whether to run at all by looking for one. + Future _syncSmartRouteNotifications() async { + final enabled = _settings.enableSmartRouteNotifications; + if (AndroidHomeIntegration.supportsSmartRouteNotifications) { + if (enabled) { + await ensureRecommendationDataReady(); + final now = DateTime.now(); + await _resolveSmartRouteIds(now); + await storage.saveSmartRoutePlan( + SmartRoutePlanner.build( + profiles: _routeUsageProfiles, + routeIdOf: (profile) => _smartRouteIds[_smartRouteIdKey(profile)], + reminders: SmartRouteReminder.parseLog( + await AndroidHomeIntegration.loadSmartRouteReminderLog(), + ), + favoriteProfiles: _favoriteUsageProfiles, + favorites: _favoriteGroups.values + .expand((group) => group) + .whereType(), + now: now, + ).toJson(), + ); + } else { + await storage.clearSmartRoutePlan(); + } + } + await AndroidHomeIntegration.syncSmartRouteNotifications(enabled); + } + + static String _smartRouteIdKey(RouteUsageProfile profile) => + '${profile.provider.name}:${profile.routeKey}'; + + /// Looks up the route ids the plan will need. Only the route key is kept + /// with the usage history, and the background worker cannot reverse it. + /// + /// A route that cannot be found is asked about again next time rather than + /// remembered as missing: its database may simply not be downloaded yet. + Future _resolveSmartRouteIds(DateTime now) async { + final wanted = >{}; + for (final profile in _routeUsageProfiles) { + if (!_smartRouteIds.containsKey(_smartRouteIdKey(profile)) && + SmartRoutePlanner.isCandidate(profile, now)) { + (wanted[profile.provider] ??= {}).add(profile.routeKey); + } + } + for (final entry in wanted.entries) { + try { + final routeIds = await repository.routeIdsForRouteKeys( + entry.key, + entry.value, + ); + routeIds.forEach((routeKey, routeId) { + _smartRouteIds['${entry.key.name}:$routeKey'] = routeId; + }); + } catch (_) { + // No database for that provider right now; its routes are left out + // of this plan and tried again with the next one. + } + } + } + Future updateKeepScreenAwakeOnRouteDetail(bool value) async { _settings = _settings.copyWith(keepScreenAwakeOnRouteDetail: value); await _persistSettings(); @@ -3062,6 +3126,8 @@ class AppController extends ChangeNotifier { profiles: const [], destinationChoices: const [], ); + // Which routes a reminder went out for, and when, was learned too. + await AndroidHomeIntegration.forgetSmartRouteReminders(); } Future clearRouteSelectionHistory() async { @@ -3254,11 +3320,17 @@ class AppController extends ChangeNotifier { ); } + /// Records that a route page was open long enough to count as a use. + /// + /// [stopId] is the stop the rider was looking at, if the page knew one. It + /// is what lets a reminder watch the right stop without the device's + /// location. Future recordRouteVisit( RouteSummary route, { required BusProvider provider, DateTime? openedAt, int? pathId, + int? stopId, }) async { final timestamp = openedAt ?? DateTime.now(); await ensureRouteHistoryReady(); @@ -3267,16 +3339,18 @@ class AppController extends ChangeNotifier { provider: provider, routeKey: route.routeKey, pathId: pathId, - record: (profile) => - profile.recordOpen(timestamp, routeName: route.routeName), - create: () => RouteUsageProfile( + record: (profile) => profile.recordOpen( + timestamp, + routeName: route.routeName, + stopId: stopId, + ), + create: () => _newlyOpenedRouteProfile( provider: provider, routeKey: route.routeKey, pathId: pathId, routeName: route.routeName, - totalOpens: 1, - lastOpenedAtMs: timestamp.millisecondsSinceEpoch, - hourlyOpens: {timestamp.hour: 1}, + timestamp: timestamp, + stopId: stopId, ), ); await _persistSmartRouteProfiles( @@ -3290,10 +3364,29 @@ class AppController extends ChangeNotifier { timestamp: timestamp, selection: false, pathId: pathId, + stopId: stopId, ); await analytics.logRouteVisit(provider: provider, routeKey: route.routeKey); } + RouteUsageProfile _newlyOpenedRouteProfile({ + required BusProvider provider, + required int routeKey, + required int? pathId, + required String routeName, + required DateTime timestamp, + required int? stopId, + }) { + return RouteUsageProfile( + provider: provider, + routeKey: routeKey, + pathId: pathId, + routeName: routeName, + totalOpens: 0, + lastOpenedAtMs: 0, + ).recordOpen(timestamp, stopId: stopId); + } + List _buildUpdatedRouteUsageProfiles({ required BusProvider provider, required int routeKey, @@ -3402,9 +3495,7 @@ class AppController extends ChangeNotifier { if (stopVisitsChanged) { await storage.saveStopVisitProfiles(_stopVisitProfiles); } - await AndroidHomeIntegration.syncSmartRouteNotifications( - _settings.enableSmartRouteNotifications, - ); + await _syncSmartRouteNotifications(); unawaited(_pushSmartSuggestionToWearOsIfNeeded()); notifyListeners(); } @@ -4029,6 +4120,7 @@ class AppController extends ChangeNotifier { required DateTime timestamp, required bool selection, required int? pathId, + int? stopId, }) async { if (!_tracksDeviceRouteHistory) return; final current = _profilesFromRouteHistoryDevice( @@ -4040,19 +4132,25 @@ class AppController extends ChangeNotifier { pathId: pathId, record: (profile) => selection ? profile.recordSelection(timestamp, routeName: routeName) - : profile.recordOpen(timestamp, routeName: routeName), - create: () => RouteUsageProfile( - provider: provider, - routeKey: routeKey, - pathId: pathId, - routeName: routeName.trim(), - totalOpens: selection ? 0 : 1, - lastOpenedAtMs: selection ? 0 : timestamp.millisecondsSinceEpoch, - hourlyOpens: selection ? const {} : {timestamp.hour: 1}, - selectionTimestampsMs: selection - ? [timestamp.millisecondsSinceEpoch] - : const [], - ), + : profile.recordOpen(timestamp, routeName: routeName, stopId: stopId), + create: () => selection + ? RouteUsageProfile( + provider: provider, + routeKey: routeKey, + pathId: pathId, + routeName: routeName.trim(), + totalOpens: 0, + lastOpenedAtMs: 0, + selectionTimestampsMs: [timestamp.millisecondsSinceEpoch], + ) + : _newlyOpenedRouteProfile( + provider: provider, + routeKey: routeKey, + pathId: pathId, + routeName: routeName.trim(), + timestamp: timestamp, + stopId: stopId, + ), source: current, ); await _updateRouteHistoryDevicePayload(profiles: next); @@ -4222,6 +4320,8 @@ class AppController extends ChangeNotifier { var lastOpenedAtMs = 0; final hourlyOpens = {}; final selections = []; + final visits = []; + int? legacyAsOfMs; for (final profile in profiles) { totalOpens += profile.totalOpens; if (profile.lastOpenedAtMs >= lastOpenedAtMs) { @@ -4232,6 +4332,14 @@ class AppController extends ChangeNotifier { hourlyOpens[hour] = (hourlyOpens[hour] ?? 0) + count; }); selections.addAll(profile.selectionTimestampsWithin()); + visits.addAll(profile.visits); + // The counters are summed, so they are as recent as the most recent + // device that still relies on them. + final profileLegacyAsOfMs = profile.legacyAsOfMs; + if (profileLegacyAsOfMs != null && + (legacyAsOfMs == null || profileLegacyAsOfMs > legacyAsOfMs)) { + legacyAsOfMs = profileLegacyAsOfMs; + } } selections.sort(); return RouteUsageProfile( @@ -4243,6 +4351,11 @@ class AppController extends ChangeNotifier { lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, selectionTimestampsMs: selections, + visits: RouteUsageProfile.normalizeVisits( + visits, + nowMs: DateTime.now().millisecondsSinceEpoch, + ), + legacyAsOfMs: legacyAsOfMs, ); } diff --git a/lib/core/bus_repository.dart b/lib/core/bus_repository.dart index 7b2fef80..6b24dc64 100644 --- a/lib/core/bus_repository.dart +++ b/lib/core/bus_repository.dart @@ -4928,6 +4928,30 @@ class BusRepository { return null; } + /// The routeids behind [routeKeys], for those of them the local database + /// lists. The reverse of [routeKeyForRouteId], done for many keys in the + /// one pass over the provider's routes that a single key would take. + Future> routeIdsForRouteKeys( + BusProvider provider, + Set routeKeys, + ) async { + if (routeKeys.isEmpty) { + return const {}; + } + final rows = await _loadMetadataPathRows(provider: provider); + final routeIds = {}; + for (final row in rows) { + if (row.routeId.isEmpty) { + continue; + } + final routeKey = _routeKeyForRouteId(row.routeId); + if (routeKeys.contains(routeKey)) { + routeIds.putIfAbsent(routeKey, () => row.routeId); + } + } + return routeIds; + } + /// The stable client-side key for a routeid. /// /// Route detail is addressed by [routeKey], but anything that arrives from diff --git a/lib/core/models.dart b/lib/core/models.dart index d663b2cf..74ae305c 100644 --- a/lib/core/models.dart +++ b/lib/core/models.dart @@ -1355,9 +1355,49 @@ class FavoriteUsageProfile { } } +/// One visit to a route page, kept with its time so a habit can be told apart +/// from a burst: the hourly counters on [RouteUsageProfile] cannot say which +/// day, or which weekday, an open happened on. +class RouteVisit { + const RouteVisit({required this.atMs, this.stopId}); + + final int atMs; + + /// The stop the rider was looking at, when the screen knew one. Lets the + /// usual boarding stop be learned without asking for the device's location. + final int? stopId; + + static RouteVisit? fromJson(Object? raw) { + if (raw is! Map) { + return null; + } + final atMs = (raw['t'] as num?)?.toInt() ?? 0; + if (atMs <= 0) { + return null; + } + final stopId = (raw['s'] as num?)?.toInt(); + return RouteVisit( + atMs: atMs, + stopId: stopId != null && stopId > 0 ? stopId : null, + ); + } + + Map toJson() => {'t': atMs, if (stopId != null) 's': stopId}; +} + class RouteUsageProfile { static const Duration selectionHistoryRetention = Duration(days: 7); + /// How far back visits are remembered. Long enough to hold eight samples of + /// a once-a-week trip, short enough that last semester's timetable is gone. + static const Duration visitHistoryRetention = Duration(days: 56); + + /// Opens closer together than this are one visit: reopening a page while + /// waiting for a late bus is not several trips. + static const Duration visitMergeWindow = Duration(minutes: 20); + + static const int maxVisits = 240; + const RouteUsageProfile({ required this.provider, required this.routeKey, @@ -1370,6 +1410,8 @@ class RouteUsageProfile { this.hourlyOpens = const {}, Map hourlySelections = const {}, this.selectionTimestampsMs = const [], + this.visits = const [], + this.legacyAsOfMs, }) : _legacyTotalSelections = totalSelections, _legacyLastSelectedAtMs = lastSelectedAtMs, _legacyHourlySelections = hourlySelections; @@ -1391,17 +1433,43 @@ class RouteUsageProfile { }); } + final lastOpenedAtMs = (json['lastOpenedAtMs'] as num?)?.toInt() ?? 0; + final rawVisits = json['visits']; + final nowMs = DateTime.now().millisecondsSinceEpoch; + final List visits; + int? legacyAsOfMs; + if (rawVisits is List) { + visits = normalizeVisits( + rawVisits.map(RouteVisit.fromJson).whereType(), + nowMs: nowMs, + ); + final storedLegacyAsOfMs = (json['legacyAsOfMs'] as num?)?.toInt() ?? 0; + legacyAsOfMs = storedLegacyAsOfMs > 0 ? storedLegacyAsOfMs : null; + } else { + // Written before visits were kept. The last open is the one visit whose + // time is known, and it also dates the hourly counters: everything in + // them happened no later than that. + visits = normalizeVisits([ + if (lastOpenedAtMs > 0) RouteVisit(atMs: lastOpenedAtMs), + ], nowMs: nowMs); + legacyAsOfMs = lastOpenedAtMs > 0 && hourlyOpens.isNotEmpty + ? lastOpenedAtMs + : null; + } + return RouteUsageProfile( provider: busProviderFromString(json['provider'] as String? ?? 'tpe'), routeKey: (json['routeKey'] as num?)?.toInt() ?? 0, pathId: (json['pathId'] as num?)?.toInt(), routeName: json['routeName'] as String? ?? '', totalOpens: (json['totalOpens'] as num?)?.toInt() ?? 0, - lastOpenedAtMs: (json['lastOpenedAtMs'] as num?)?.toInt() ?? 0, + lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, selectionTimestampsMs: _decodeRecentSelectionTimestamps( json['selectionTimestampsMs'], ), + visits: visits, + legacyAsOfMs: legacyAsOfMs, ); } @@ -1413,6 +1481,15 @@ class RouteUsageProfile { final int lastOpenedAtMs; final Map hourlyOpens; final List selectionTimestampsMs; + + /// Recent visits, oldest first, one per [visitMergeWindow]. + final List visits; + + /// Set only on profiles that predate [visits]: the moment up to which + /// [hourlyOpens] is the sole record of when the route was used. Null means + /// every open this profile has seen is also in [visits], so the undated + /// counters add nothing. + final int? legacyAsOfMs; final int _legacyTotalSelections; final int _legacyLastSelectedAtMs; final Map _legacyHourlySelections; @@ -1441,9 +1518,54 @@ class RouteUsageProfile { (key, value) => MapEntry(key.toString(), value), ), 'selectionTimestampsMs': prunedSelectionTimestamps, + // Always written, even when empty: its presence is what tells a reader + // this profile no longer needs seeding from the legacy counters. + 'visits': visitsWithin().map((visit) => visit.toJson()).toList(), + if (legacyAsOfMs != null) 'legacyAsOfMs': legacyAsOfMs, }; } + List visitsWithin({DateTime? now}) { + if (visits.isEmpty) { + return const []; + } + return normalizeVisits( + visits, + nowMs: (now ?? DateTime.now()).millisecondsSinceEpoch, + ); + } + + /// Drops visits older than [visitHistoryRetention], orders the rest, and + /// folds any that fall inside one [visitMergeWindow] into the first of them. + static List normalizeVisits( + Iterable visits, { + required int nowMs, + }) { + final cutoffMs = nowMs - visitHistoryRetention.inMilliseconds; + final sorted = visits.where((visit) => visit.atMs >= cutoffMs).toList() + ..sort((left, right) => left.atMs.compareTo(right.atMs)); + final merged = []; + for (final visit in sorted) { + if (merged.isNotEmpty && + visit.atMs - merged.last.atMs < visitMergeWindow.inMilliseconds) { + // Same visit. Keep its first moment, but take the stop from whichever + // open knew it: a list tap names the stop before the page has loaded. + if (merged.last.stopId == null && visit.stopId != null) { + merged[merged.length - 1] = RouteVisit( + atMs: merged.last.atMs, + stopId: visit.stopId, + ); + } + continue; + } + merged.add(visit); + } + if (merged.length > maxVisits) { + merged.removeRange(0, merged.length - maxVisits); + } + return merged; + } + int countAtHour(int hour) => hourlyOpens[hour] ?? 0; int selectionCountAtHour(int hour, {DateTime? now}) => hourlySelectionsAt(now: now)[hour] ?? 0; @@ -1511,7 +1633,11 @@ class RouteUsageProfile { int get preferredHour => preferredHourAt(); - RouteUsageProfile recordOpen(DateTime openedAt, {String? routeName}) { + RouteUsageProfile recordOpen( + DateTime openedAt, { + String? routeName, + int? stopId, + }) { final hour = openedAt.hour; final nextHourlyOpens = {...hourlyOpens}; nextHourlyOpens[hour] = (nextHourlyOpens[hour] ?? 0) + 1; @@ -1526,6 +1652,14 @@ class RouteUsageProfile { lastOpenedAtMs: openedAt.millisecondsSinceEpoch, hourlyOpens: nextHourlyOpens, selectionTimestampsMs: selectionTimestampsMs, + visits: normalizeVisits([ + ...visits, + RouteVisit( + atMs: openedAt.millisecondsSinceEpoch, + stopId: stopId != null && stopId > 0 ? stopId : null, + ), + ], nowMs: openedAt.millisecondsSinceEpoch), + legacyAsOfMs: legacyAsOfMs, ); } @@ -1545,6 +1679,8 @@ class RouteUsageProfile { lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, selectionTimestampsMs: nextSelectionTimestamps, + visits: visits, + legacyAsOfMs: legacyAsOfMs, ); } @@ -1557,6 +1693,8 @@ class RouteUsageProfile { totalOpens: totalOpens, lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, + visits: visits, + legacyAsOfMs: legacyAsOfMs, ); } @@ -1570,6 +1708,8 @@ class RouteUsageProfile { lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, selectionTimestampsMs: selectionTimestampsWithin(now: now), + visits: visits, + legacyAsOfMs: legacyAsOfMs, ); } @@ -1603,6 +1743,7 @@ class SmartRouteSuggestion { this.favorite, this.favoriteStop, this.favoritePath, + this.learnedStop, }); final RouteUsageProfile profile; @@ -1611,12 +1752,20 @@ class SmartRouteSuggestion { final RouteDetailData? detail; final StopInfo? nearestStop; final PathInfo? nearestPath; + + /// Distance to the stop that is shown when it is not a favorite: the + /// [learnedStop] if there is one, otherwise the [nearestStop]. final double? distanceMeters; final FavoriteStop? favorite; final StopInfo? favoriteStop; final PathInfo? favoritePath; - StopInfo? get recommendedStop => favoriteStop ?? nearestStop; + /// The stop this route is usually opened at around this time. Only set when + /// it should be shown ahead of [nearestStop] — that is, when the rider is + /// not already standing at some other stop of the route. + final StopInfo? learnedStop; + + StopInfo? get recommendedStop => favoriteStop ?? learnedStop ?? nearestStop; PathInfo? get recommendedPath => favoritePath ?? nearestPath; } diff --git a/lib/core/smart_route_habit.dart b/lib/core/smart_route_habit.dart new file mode 100644 index 00000000..e3b07b51 --- /dev/null +++ b/lib/core/smart_route_habit.dart @@ -0,0 +1,417 @@ +import 'dart:math' as math; + +import 'models.dart'; + +/// A moment placed on the service-day grid the habit model works on. +/// +/// A service day runs from [RouteHabitModel.serviceDayStartHour] to the same +/// hour the next morning, the way a bus timetable does. A ride home at 00:20 +/// on Saturday therefore belongs to Friday, and no time-of-day comparison ever +/// has to wrap around midnight. +class ServiceTime { + const ServiceTime({required this.day, required this.minute}); + + factory ServiceTime.fromDateTime(DateTime time) { + final shifted = time.toLocal().subtract( + const Duration(hours: RouteHabitModel.serviceDayStartHour), + ); + return ServiceTime( + day: + DateTime.utc( + shifted.year, + shifted.month, + shifted.day, + ).millisecondsSinceEpoch ~/ + Duration.millisecondsPerDay, + minute: shifted.hour * 60 + shifted.minute, + ); + } + + factory ServiceTime.fromMs(int ms) => + ServiceTime.fromDateTime(DateTime.fromMillisecondsSinceEpoch(ms)); + + /// Whole service days since the epoch, counted on the local calendar. + final int day; + + /// Minutes since the service day began, 0..1439. + final int minute; + + int get weekday => weekdayOfDay(day); + + /// [DateTime.monday]..[DateTime.sunday] for a service-day index. Day 0 is + /// 1970-01-01, a Thursday. + static int weekdayOfDay(int day) => ((day + 3) % 7 + 7) % 7 + 1; + + static bool isWeekend(int weekday) => + weekday == DateTime.saturday || weekday == DateTime.sunday; + + /// The local instant at which service day [day] begins. + static DateTime startOfDay(int day) { + final date = DateTime.fromMillisecondsSinceEpoch( + day * Duration.millisecondsPerDay, + isUtc: true, + ); + return DateTime( + date.year, + date.month, + date.day, + RouteHabitModel.serviceDayStartHour, + ); + } + + /// [minute] as a wall-clock minute of the day, 0..1439. + static int clockMinute(int minute) => + (minute + RouteHabitModel.serviceDayStartHour * 60) % (24 * 60); +} + +/// How likely a route is to be wanted at one time on one kind of day. +class RouteHabitEstimate { + const RouteHabitEstimate({ + required this.probability, + required this.supportDays, + this.lastSupportDay, + this.typicalMinute, + }); + + static const none = RouteHabitEstimate(probability: 0, supportDays: 0); + + /// Estimated chance, 0..1, that the route is used around the asked time on + /// a day like the asked one. + final double probability; + + /// Distinct past days on which the route was used around that time, on any + /// day of the week. A sample size, not a rate. + final int supportDays; + + /// The most recent of those days, as a service-day index. + final int? lastSupportDay; + + /// Where those uses centre, in service minutes. + final int? typicalMinute; +} + +/// A reminder that was shown for a route: when, and the service minute it was +/// sent for — the peak of its window — where that is known. +typedef RouteReminderShown = ({int atMs, int? forMinute}); + +/// The times a route was used, arranged for [RouteHabitModel]. +class RouteHabitEvidence { + RouteHabitEvidence._( + this._minutesByDay, + this._usedTodayAt, + this._remindersByDay, + this.today, + this._nowMinute, + this.nowMs, + ); + + /// [reminders] are the ones shown for this route. A reminder changes what + /// the rider does next, so the days it was shown on cannot be read the way + /// other days are; see [estimate] and [_minuteSpokenFor]. + factory RouteHabitEvidence.of( + RouteUsageProfile profile, + DateTime now, { + Iterable reminders = const [], + }) { + final nowMs = now.millisecondsSinceEpoch; + final nowTime = ServiceTime.fromDateTime(now); + final today = nowTime.day; + final minutesByDay = >{}; + final usedTodayAt = []; + final remindersByDay = >{}; + for (final reminder in reminders) { + final time = ServiceTime.fromMs(reminder.atMs); + (remindersByDay[time.day] ??= <_DayReminder>[]).add(( + minute: time.minute, + forMinute: reminder.forMinute, + )); + } + final timestamps = [ + for (final visit in profile.visitsWithin(now: now)) visit.atMs, + // A tap that never became a ten-second open is still a use. These are + // only kept for a week, so they sharpen the recent picture rather than + // carry it. + ...profile.selectionTimestampsWithin(now: now), + ]; + for (final timestamp in timestamps) { + if (timestamp > nowMs) { + continue; + } + final time = ServiceTime.fromMs(timestamp); + if (today - time.day > RouteHabitModel.lookbackDays) { + continue; + } + (minutesByDay[time.day] ??= []).add( + _minuteSpokenFor(time.minute, remindersByDay[time.day]), + ); + if (time.day == today) { + usedTodayAt.add(time.minute); + } + } + return RouteHabitEvidence._( + minutesByDay, + usedTodayAt, + remindersByDay, + today, + nowTime.minute, + nowMs, + ); + } + + /// The time of day a use at [minute] is evidence for. + /// + /// A reminder goes out ahead of the time the route is usually opened, and + /// tapping it opens the route there and then. Taken at face value, every + /// such tap would say the routine is a little earlier than believed; the + /// next reminder would go out earlier still, and be tapped earlier still. + /// So a use between a reminder and the time it was sent for agrees with + /// that time rather than moving it. + /// + /// Nothing else is moved. A use before the reminder was the rider's own + /// doing. One after the time it was for may well have been prompted by a + /// reminder that came late, but that only happens when no bus was due any + /// sooner, and then later is when looking was of use. + static int _minuteSpokenFor(int minute, List<_DayReminder>? reminders) { + var spokenFor = minute; + for (final reminder in reminders ?? const <_DayReminder>[]) { + final forMinute = reminder.forMinute; + if (forMinute != null && + reminder.minute <= minute && + forMinute > spokenFor) { + spokenFor = forMinute; + } + } + return spokenFor; + } + + /// The minutes each day's uses are evidence for; see [_minuteSpokenFor]. + final Map> _minutesByDay; + + /// When the route was actually used today, whatever that is evidence for. + final List _usedTodayAt; + final Map> _remindersByDay; + + /// The service day [RouteHabitEvidence.of] was asked on. + final int today; + final int _nowMinute; + final int nowMs; + + /// Distinct service days with any use at all. + int get dayCount => _minutesByDay.length; + + bool get isEmpty => _minutesByDay.isEmpty; + + /// Every minute at which the route was used, for callers that need to know + /// which parts of the day are worth asking about. + Iterable get minutes => _minutesByDay.values.expand((day) => day); + + /// How closely the use on [day] matches [minute]: 1 for a use at exactly + /// that minute, falling to 0 past [RouteHabitModel.timeCutoffMinutes]. + double matchOn(int day, int minute) => _bestMatch(day, minute).$1; + + (double, int?) _bestMatch(int day, int minute) { + final minutes = _minutesByDay[day]; + if (minutes == null) { + return (0, null); + } + var best = 0.0; + int? bestMinute; + for (final used in minutes) { + final match = RouteHabitModel.timeMatch((used - minute).abs()); + if (match > best) { + best = match; + bestMinute = used; + } + } + return (best, bestMinute); + } + + /// Whether [day], on which the route was not used around [minute], was a + /// chance to use it that was passed up. + /// + /// Two kinds of day cannot say. One is a day a reminder was shown around + /// that time: it gave the rider what they would have opened the route for, + /// so not opening it is no sign they stayed home — and counting it as one + /// would have every reminder that worked argue for sending fewer. The + /// other is today, for as long as there is still time: the plan for the + /// week is usually drawn up in the morning, and this evening has not been + /// missed yet. + bool _wasPassedUp(int day, int minute) { + final withinReach = RouteHabitModel.timeCutoffMinutes; + if (day == today && _nowMinute <= minute + withinReach) { + return false; + } + final reminders = _remindersByDay[day]; + return reminders == null || + reminders.every( + (reminder) => (reminder.minute - minute).abs() > withinReach, + ); + } + + /// Minutes since the most recent use today, or null when there was none. + int? minutesSinceLastUseToday(DateTime now) { + final nowMinute = ServiceTime.fromDateTime(now).minute; + int? best; + for (final used in _usedTodayAt) { + final age = nowMinute - used; + if (age >= 0 && (best == null || age < best)) { + best = age; + } + } + return best; + } + + /// The chance the route is used around [minute] on service day [targetDay]. + /// + /// Only days before [targetDay] count, and never days after [today]: asking + /// about today leaves today out, so a use this morning cannot vouch for + /// itself, while asking about tomorrow counts it. + /// + /// A day without a use counts against the habit only if it was a chance + /// that was passed up; see [_wasPassedUp]. + RouteHabitEstimate estimate({required int targetDay, required int minute}) { + final lastDay = math.min(targetDay - 1, today); + final firstDay = targetDay - RouteHabitModel.lookbackDays; + final matches = {}; + var supportDays = 0; + int? lastSupportDay; + int? firstUseDay; + var typicalWeight = 0.0; + var typicalSum = 0.0; + for (final day in _minutesByDay.keys) { + if (day < firstDay || day > lastDay) { + continue; + } + final (match, usedMinute) = _bestMatch(day, minute); + if (match <= 0) { + continue; + } + matches[day] = match; + if (match < RouteHabitModel.supportMatchThreshold) { + continue; + } + supportDays += 1; + if (lastSupportDay == null || day > lastSupportDay) { + lastSupportDay = day; + } + if (firstUseDay == null || day < firstUseDay) { + firstUseDay = day; + } + final weight = RouteHabitModel.decay(targetDay - day) * match; + typicalWeight += weight; + typicalSum += weight * usedMinute!; + } + if (firstUseDay == null) { + return RouteHabitEstimate.none; + } + + // Every day since the habit was first seen was a chance to repeat it, so + // a day without a use counts against it. Days before that do not: nobody + // can skip a routine they had not started. + final targetWeekday = ServiceTime.weekdayOfDay(targetDay); + final targetIsWeekend = ServiceTime.isWeekend(targetWeekday); + var usedSameWeekday = 0.0; + var chancesSameWeekday = 0.0; + var usedSameKind = 0.0; + var chancesSameKind = 0.0; + for (var day = firstUseDay; day <= lastDay; day++) { + final weekday = ServiceTime.weekdayOfDay(day); + if (ServiceTime.isWeekend(weekday) != targetIsWeekend) { + continue; + } + final match = matches[day]; + if (match == null && !_wasPassedUp(day, minute)) { + continue; + } + final weight = RouteHabitModel.decay(targetDay - day); + final used = weight * (match ?? 0); + usedSameKind += used; + chancesSameKind += weight; + if (weekday == targetWeekday) { + usedSameWeekday += used; + chancesSameWeekday += weight; + } + } + + // Two levels, each pulled toward the one above while it has little to go + // on: a Tuesday leans on weekdays in general until enough Tuesdays have + // been seen, and weekdays lean on a low base rate until enough of those + // have. This is what lets a Tuesday/Thursday class stand apart from a + // daily commute without waiting eight weeks to recommend either. + final sameKindRate = + (usedSameKind + + RouteHabitModel.kindPriorDays * RouteHabitModel.baseRate) / + (chancesSameKind + RouteHabitModel.kindPriorDays); + final probability = + (usedSameWeekday + RouteHabitModel.weekdayPriorDays * sameKindRate) / + (chancesSameWeekday + RouteHabitModel.weekdayPriorDays); + + return RouteHabitEstimate( + probability: probability.clamp(0.0, 1.0), + supportDays: supportDays, + lastSupportDay: lastSupportDay, + typicalMinute: typicalWeight > 0 + ? (typicalSum / typicalWeight).round() + : null, + ); + } + + /// [estimate] for the moment [now] itself. + RouteHabitEstimate estimateNow(DateTime now) { + final time = ServiceTime.fromDateTime(now); + return estimate(targetDay: time.day, minute: time.minute); + } +} + +typedef _DayReminder = ({int minute, int? forMinute}); + +/// The constants and curves the habit model is built from. +class RouteHabitModel { + const RouteHabitModel._(); + + /// 04:00. Late enough that the last night buses are still "yesterday", + /// early enough that the first morning ones are "today". + static const int serviceDayStartHour = 4; + + /// Matches [RouteUsageProfile.visitHistoryRetention]. + static const int lookbackDays = 56; + + /// A use two weeks ago counts half as much as one today. + static const double halfLifeDays = 14; + + /// Spread of the time-of-day match. Half an hour either way still counts + /// for most of a use; an hour away counts for little. + static const double timeSigmaMinutes = 30; + + /// Beyond this a use says nothing about the asked time. + static const int timeCutoffMinutes = 75; + + /// How close a use must be to count as a day the route was used "around + /// this time". 0.1 is a little over an hour away. + static const double supportMatchThreshold = 0.1; + + /// How often an arbitrary route is wanted at an arbitrary time, absent any + /// evidence. + static const double baseRate = 0.05; + + /// How many days of the base rate a weekday/weekend estimate starts with. + static const double kindPriorDays = 2; + + /// How many days of the weekday/weekend rate a single weekday starts with. + static const double weekdayPriorDays = 1; + + static double decay(num ageDays) { + if (ageDays <= 0) { + return 1; + } + return math.pow(0.5, ageDays / halfLifeDays).toDouble(); + } + + static double timeMatch(int minutesApart) { + if (minutesApart > timeCutoffMinutes) { + return 0; + } + final scaled = minutesApart / timeSigmaMinutes; + return math.exp(-0.5 * scaled * scaled); + } +} diff --git a/lib/core/smart_route_plan.dart b/lib/core/smart_route_plan.dart new file mode 100644 index 00000000..3263a071 --- /dev/null +++ b/lib/core/smart_route_plan.dart @@ -0,0 +1,391 @@ +import 'dart:convert'; +import 'dart:math' as math; + +import 'models.dart'; +import 'smart_route_habit.dart'; +import 'smart_route_service.dart'; + +/// One stretch of one weekday during which a route is worth a reminder. +class SmartRoutePlanSlot { + const SmartRoutePlanSlot({ + required this.provider, + required this.routeKey, + required this.routeId, + required this.pathId, + required this.routeName, + required this.weekday, + required this.startMinute, + required this.endMinute, + required this.peakMinute, + required this.confidence, + required this.supportDays, + required this.validUntilMs, + required this.lastActivityAtMs, + this.stopId, + }); + + final BusProvider provider; + final int routeKey; + + /// What the realtime API and the stop database know the route by. The + /// reader has no way to turn a [routeKey] back into one. + final String routeId; + final int pathId; + final String routeName; + + /// [DateTime.monday]..[DateTime.sunday], of the service day. + final int weekday; + + /// Service minutes, both inclusive. See [ServiceTime]. + final int startMinute; + final int endMinute; + + /// When within the window the route is most often opened. + final int peakMinute; + final double confidence; + final int supportDays; + + /// After this the habit has gone unconfirmed for too long to act on. + final int validUntilMs; + + /// The last time the rider opened or chose this route, so a reminder is + /// not sent for something they have just looked at. + final int lastActivityAtMs; + + /// The stop to watch when the device's location is unknown. + final int? stopId; + + Map toJson() => { + 'provider': provider.name, + 'routeKey': routeKey, + 'routeId': routeId, + 'pathId': pathId, + 'routeName': routeName, + 'weekday': weekday, + 'startMinute': startMinute, + 'endMinute': endMinute, + 'peakMinute': peakMinute, + 'confidence': double.parse(confidence.toStringAsFixed(3)), + 'supportDays': supportDays, + 'validUntilMs': validUntilMs, + 'lastActivityAtMs': lastActivityAtMs, + if (stopId != null) 'stopId': stopId, + }; +} + +/// A reminder the background check actually showed, as it logs them. +class SmartRouteReminder { + const SmartRouteReminder({ + required this.provider, + required this.routeKey, + required this.pathId, + required this.atMs, + this.peakMinute, + }); + + final BusProvider provider; + final int routeKey; + final int pathId; + final int atMs; + + /// The [SmartRoutePlanSlot.peakMinute] of the slot it was shown for. + final int? peakMinute; + + bool isFor(RouteUsageProfile profile) => + provider == profile.provider && + routeKey == profile.routeKey && + pathId == profile.pathId; + + /// Reads the log the platform side keeps. Anything unreadable is skipped: + /// a lost entry only makes the model a little more cautious. + static List parseLog(String? raw) { + if (raw == null || raw.trim().isEmpty) { + return const []; + } + final Object? decoded; + try { + decoded = jsonDecode(raw); + } catch (_) { + return const []; + } + if (decoded is! List) { + return const []; + } + final providers = BusProvider.values.asNameMap(); + final reminders = []; + for (final entry in decoded) { + if (entry is! Map) { + continue; + } + // The name the plan gave the worker, and nothing looser: a reminder + // that cannot be placed must not be pinned on some other city's route. + final provider = providers[entry['provider']]; + final routeKey = entry['routeKey']; + final pathId = entry['pathId']; + final atMs = entry['atMs']; + final peakMinute = entry['peakMinute']; + if (provider == null || + routeKey is! int || + pathId is! int || + atMs is! int || + atMs <= 0) { + continue; + } + reminders.add( + SmartRouteReminder( + provider: provider, + routeKey: routeKey, + pathId: pathId, + atMs: atMs, + peakMinute: + peakMinute is int && peakMinute >= 0 && peakMinute < 24 * 60 + ? peakMinute + : null, + ), + ); + } + return reminders; + } +} + +/// Everything the background reminder needs to know, worked out ahead of +/// time so the platform side never has to score a habit itself. +class SmartRoutePlan { + const SmartRoutePlan({required this.generatedAtMs, required this.slots}); + + /// Bumped when a reader of an older shape could misread a newer one. + static const int version = 1; + + final int generatedAtMs; + final List slots; + + Map toJson() => { + 'version': version, + 'generatedAtMs': generatedAtMs, + 'dayStartHour': RouteHabitModel.serviceDayStartHour, + 'slots': slots.map((slot) => slot.toJson()).toList(), + }; +} + +class SmartRoutePlanner { + const SmartRoutePlanner._(); + + /// A reminder interrupts, so it asks for more than a place on the home + /// screen does: three separate days, and better-than-even odds that today + /// is another. + static const int minSupportDays = 3; + static const double minProbability = 0.5; + + /// A habit not seen for this long is treated as over until it is seen + /// again. Two weeks covers a holiday without reminding anyone of a route + /// they stopped taking last month. + /// + /// The plan is only rebuilt when the app is used, so the probability above + /// cannot be what ends a reminder for somebody who has stopped opening it: + /// nothing would recompute it. Each slot carries this as an expiry instead, + /// which the reader checks against the clock. + /// + /// It is also the one thing a shown reminder never extends. Reminders that + /// are read and not acted on keep the habit from fading, but only opening + /// the route, from a reminder or otherwise, confirms it is still wanted. + /// The reader's last reminders before the expiry say that it is coming. + static const int maxDaysSinceLastUse = 14; + + /// Resolution of the windows. The background check itself only runs every + /// quarter of an hour, so finer than this would be false precision. + static const int gridMinutes = 10; + + static const int maxSlots = 64; + + /// Whether [profile] has been used on enough days to be worth planning + /// for. Callers use this to decide which routes need a route id looked up. + static bool isCandidate(RouteUsageProfile profile, DateTime now) => + profile.pathId != null && + RouteHabitEvidence.of(profile, now).dayCount >= minSupportDays; + + /// [routeIdOf] supplies the route id for a profile; a route it cannot + /// name is left out, since nothing could be fetched for it. + /// + /// [reminders] are the ones already shown. Without them a reminder that + /// did its job would look like a day the rider stayed home, and a tap on + /// one like a routine that had moved earlier; see [RouteHabitEvidence]. + static SmartRoutePlan build({ + required Iterable profiles, + required String? Function(RouteUsageProfile profile) routeIdOf, + Iterable reminders = const [], + Iterable favoriteProfiles = + const [], + Iterable favorites = const [], + required DateTime now, + }) { + final favoriteProfileList = favoriteProfiles.toList(growable: false); + final favoriteList = favorites.toList(growable: false); + final reminderList = reminders.toList(growable: false); + final slots = []; + final seen = {}; + for (final profile in profiles) { + final pathId = profile.pathId; + if (pathId == null || + !seen.add('${profile.provider.name}:${profile.routeKey}:$pathId')) { + continue; + } + final evidence = RouteHabitEvidence.of( + profile, + now, + reminders: [ + for (final reminder in reminderList) + if (reminder.isFor(profile)) + (atMs: reminder.atMs, forMinute: reminder.peakMinute), + ], + ); + if (evidence.dayCount < minSupportDays) { + continue; + } + final routeId = routeIdOf(profile)?.trim() ?? ''; + if (routeId.isEmpty) { + continue; + } + final worthAsking = _minutesNearUse(evidence); + // Today and the six days after it: one of each weekday. Each is judged + // as it will look when it arrives, so a use this morning already counts + // toward tomorrow's reminder instead of waiting for the next rebuild. + for (var ahead = 0; ahead < 7; ahead++) { + final targetDay = evidence.today + ahead; + void close(_Window window) { + // Shown reminders can hold a habit's odds up long after it was + // last confirmed. A slot that would have lapsed before its day + // came is not a slot, and must not take a live one's place. + if (targetDay - window.peak.lastSupportDay! > maxDaysSinceLastUse) { + return; + } + slots.add( + _slot( + profile: profile, + routeId: routeId, + pathId: pathId, + targetDay: targetDay, + window: window, + favoriteProfiles: favoriteProfileList, + favorites: favoriteList, + ), + ); + } + + _Window? window; + for (var index = 0; index < worthAsking.length; index++) { + final minute = index * gridMinutes; + final estimate = worthAsking[index] + ? evidence.estimate(targetDay: targetDay, minute: minute) + : RouteHabitEstimate.none; + final qualifies = + estimate.supportDays >= minSupportDays && + estimate.probability >= minProbability; + if (qualifies) { + (window ??= _Window(minute)).extend(minute, estimate); + } else if (window != null) { + close(window); + window = null; + } + } + if (window != null) { + close(window); + } + } + } + + slots.sort((left, right) => right.confidence.compareTo(left.confidence)); + final kept = slots.take(maxSlots).toList() + ..sort((left, right) { + final weekday = left.weekday.compareTo(right.weekday); + if (weekday != 0) return weekday; + final start = left.startMinute.compareTo(right.startMinute); + if (start != 0) return start; + final route = left.routeKey.compareTo(right.routeKey); + if (route != 0) return route; + return left.pathId.compareTo(right.pathId); + }); + return SmartRoutePlan( + generatedAtMs: now.millisecondsSinceEpoch, + slots: List.unmodifiable(kept), + ); + } + + /// Which grid minutes lie close enough to some use to be worth estimating. + /// Most of the day is nowhere near one, and skipping it is what keeps a + /// rebuild cheap enough to do on every open. + static List _minutesNearUse(RouteHabitEvidence evidence) { + final worthAsking = List.filled( + (24 * 60 / gridMinutes).ceil(), + false, + ); + for (final used in evidence.minutes) { + final first = math.max(0, used - RouteHabitModel.timeCutoffMinutes); + final last = math.min( + 24 * 60 - 1, + used + RouteHabitModel.timeCutoffMinutes, + ); + for ( + var index = (first / gridMinutes).ceil(); + index * gridMinutes <= last; + index++ + ) { + worthAsking[index] = true; + } + } + return worthAsking; + } + + static SmartRoutePlanSlot _slot({ + required RouteUsageProfile profile, + required String routeId, + required int pathId, + required int targetDay, + required _Window window, + required List favoriteProfiles, + required List favorites, + }) { + final peak = window.peak; + return SmartRoutePlanSlot( + provider: profile.provider, + routeKey: profile.routeKey, + routeId: routeId, + pathId: pathId, + routeName: profile.routeName, + weekday: ServiceTime.weekdayOfDay(targetDay), + startMinute: window.startMinute, + endMinute: window.endMinute, + peakMinute: window.peakMinute, + confidence: peak.probability, + supportDays: peak.supportDays, + validUntilMs: ServiceTime.startOfDay( + peak.lastSupportDay! + maxDaysSinceLastUse + 1, + ).millisecondsSinceEpoch, + lastActivityAtMs: profile.latestInteractionAtMs, + stopId: SmartRouteService.chooseBoardingStopId( + profile: profile, + favoriteProfiles: favoriteProfiles, + favorites: favorites, + at: ServiceTime.startOfDay( + targetDay, + ).add(Duration(minutes: window.peakMinute)), + ), + ); + } +} + +class _Window { + _Window(this.startMinute) : endMinute = startMinute, peakMinute = startMinute; + + final int startMinute; + int endMinute; + int peakMinute; + RouteHabitEstimate peak = RouteHabitEstimate.none; + + void extend(int minute, RouteHabitEstimate estimate) { + endMinute = minute; + if (estimate.probability > peak.probability) { + peak = estimate; + peakMinute = minute; + } + } +} diff --git a/lib/core/smart_route_service.dart b/lib/core/smart_route_service.dart index 2071a4f6..43c8df30 100644 --- a/lib/core/smart_route_service.dart +++ b/lib/core/smart_route_service.dart @@ -1,130 +1,191 @@ +import 'dart:math' as math; + import 'package:geolocator/geolocator.dart'; import 'bus_repository.dart'; import 'last_bus_message.dart'; import 'models.dart'; +import 'smart_route_habit.dart'; + +/// Where one route stands among the candidates for a recommendation. +class SmartRouteRanking { + const SmartRouteRanking({ + required this.profile, + required this.score, + required this.estimate, + required this.fromHabit, + }); + + final RouteUsageProfile profile; + + /// Comparable across routes; roughly the chance the route is wanted now. + final double score; + final RouteHabitEstimate estimate; + + /// False when the route only qualified through the undated hourly counters + /// of a profile that predates visit history. + final bool fromHabit; +} class SmartRouteService { const SmartRouteService._(); - static const int minTotalOpensForRecommendation = 3; - static const int minRelevantInteractionsForRecommendation = 2; + /// Used around this time on at least this many separate days. One morning + /// of reopening a page is one day, however many opens it took. + static const int minSupportDaysForRecommendation = 2; - static RouteUsageProfile? chooseProfileForTime( - Iterable profiles, - DateTime now, - ) { - RouteUsageProfile? bestProfile; - double bestScore = 0; + /// Below this the route is not worth a place on the home screen. + static const double minProbabilityForRecommendation = 0.12; - for (final profile in profiles) { - if (profile.pathId == null) { - continue; - } - if (!hasEnoughHistoryForRecommendation(profile, now)) { - continue; - } + /// A profile written before visits were kept needs this many opens, and + /// [minLegacyNearbyOpens] of them within an hour of now, to be recommended + /// from its counters alone. The old scoring asked for the same numbers, + /// except that it let recent taps count toward the second; those carry a + /// date, so they are weighed as habit evidence instead. + static const int minLegacyOpens = 3; + static const int minLegacyNearbyOpens = 2; - final score = scoreProfileForTime(profile, now); - if (score > bestScore) { - bestProfile = profile; - bestScore = score; - } - } - return bestProfile; - } + /// Opens around this hour at which the counters are trusted in full. + static const double legacyFullOpens = 5; + + /// The most the counters alone can score. Kept well under what a real + /// habit reaches, because they cannot tell a Saturday from a Tuesday. + static const double legacyWeight = 0.3; + + /// Days of dated use after which the counters are no longer consulted. + static const int legacyHandoverDays = 6; - static List chooseTopProfilesForTime( + /// A route opened in the last [recentUseWindowMinutes] is probably still + /// the one being waited for, so it is nudged ahead of an equal habit. + static const double recentUseBoost = 0.2; + static const int recentUseWindowMinutes = 90; + + /// Within this distance of a stop the rider is taken to be at it. + static const double atStopMeters = 400; + + /// Within this distance the rider's usual stop is still the one they will + /// walk to, even if another stop of the route happens to be nearer. + static const double usualStopReachMeters = 800; + + /// What it takes for a stop to count as the usual one: about two recent + /// days of opening the route there, and most of the opens that named a stop. + static const double minLearnedStopScore = 1; + static const double minLearnedStopShare = 0.6; + + static RouteUsageProfile? chooseProfileForTime( Iterable profiles, - DateTime now, { - int limit = 3, - }) { - return _rankProfilesForTime( - profiles, - now, - ).take(limit).map((entry) => entry.key).toList(); + DateTime now, + ) { + final ranked = rankProfilesForTime(profiles, now); + return ranked.isEmpty ? null : ranked.first.profile; } - static List> _rankProfilesForTime( + /// Every profile worth recommending at [now], best first, one per route + /// and direction. + static List rankProfilesForTime( Iterable profiles, DateTime now, ) { - final scored = >[]; + final ranked = []; for (final profile in profiles) { - if (profile.pathId == null) { - continue; - } - if (!hasEnoughHistoryForRecommendation(profile, now)) { - continue; - } - final score = scoreProfileForTime(profile, now); - if (score > 0) { - scored.add(MapEntry(profile, score)); + final ranking = rankProfile(profile, now); + if (ranking != null) { + ranked.add(ranking); } } - scored.sort((a, b) => b.value.compareTo(a.value)); - return scored; + ranked.sort((left, right) { + final score = right.score.compareTo(left.score); + if (score != 0) return score; + final support = right.estimate.supportDays.compareTo( + left.estimate.supportDays, + ); + if (support != 0) return support; + final latest = right.profile.latestInteractionAtMs.compareTo( + left.profile.latestInteractionAtMs, + ); + if (latest != 0) return latest; + // List.sort is not stable; without a last word here two equal routes + // could swap places between refreshes. + final route = left.profile.routeKey.compareTo(right.profile.routeKey); + if (route != 0) return route; + return (left.profile.pathId ?? -1).compareTo(right.profile.pathId ?? -1); + }); + + final seen = {}; + return [ + for (final ranking in ranked) + if (seen.add(_identity(ranking.profile))) ranking, + ]; } - static bool hasEnoughHistoryForRecommendation( + /// Where [profile] stands at [now], or null when it should not be + /// recommended at all. + static SmartRouteRanking? rankProfile( RouteUsageProfile profile, DateTime now, ) { - if (profile.totalOpens < minTotalOpensForRecommendation) { - return false; + if (profile.pathId == null) { + return null; + } + final evidence = RouteHabitEvidence.of(profile, now); + final estimate = evidence.estimateNow(now); + final habitScore = + estimate.supportDays >= minSupportDaysForRecommendation && + estimate.probability >= minProbabilityForRecommendation + ? estimate.probability + : 0.0; + final legacyScore = + legacyWeight * + legacyStrength(profile, now, datedDays: evidence.dayCount); + final baseScore = math.max(habitScore, legacyScore); + if (baseScore < minProbabilityForRecommendation) { + return null; } - final currentHour = now.hour; - final previousHour = (currentHour + 23) % 24; - final nextHour = (currentHour + 1) % 24; - final relevantInteractions = - profile.combinedCountAtHour(currentHour, now: now) + - profile.combinedCountAtHour(previousHour, now: now) + - profile.combinedCountAtHour(nextHour, now: now); - return relevantInteractions >= minRelevantInteractionsForRecommendation; - } - - static double scoreProfileForTime(RouteUsageProfile profile, DateTime now) { - final currentHour = now.hour; - final previousHour = (currentHour + 23) % 24; - final nextHour = (currentHour + 1) % 24; - final currentOpenCount = profile.countAtHour(currentHour); - final currentSelectionCount = profile.selectionCountAtHour( - currentHour, - now: now, - ); - final adjacentOpenCount = - profile.countAtHour(previousHour) + profile.countAtHour(nextHour); - final adjacentSelectionCount = - profile.selectionCountAtHour(previousHour, now: now) + - profile.selectionCountAtHour(nextHour, now: now); - final preferredCount = profile.combinedCountAtHour( - profile.preferredHourAt(now: now), - now: now, - ); - final recencyDays = profile.latestInteractionAtMs <= 0 - ? 365 - : now - .difference( - DateTime.fromMillisecondsSinceEpoch( - profile.latestInteractionAtMs, - ), - ) - .inDays; - final recencyBonus = recencyDays <= 2 - ? 1.5 - : recencyDays <= 7 - ? 0.75 + final sinceLastUse = evidence.minutesSinceLastUseToday(now); + final recentBoost = + sinceLastUse != null && sinceLastUse < recentUseWindowMinutes + ? recentUseBoost * (1 - sinceLastUse / recentUseWindowMinutes) : 0.0; + return SmartRouteRanking( + profile: profile, + score: baseScore + recentBoost, + estimate: estimate, + fromHabit: habitScore > 0 && habitScore >= legacyScore, + ); + } - return (currentOpenCount * 5) + - (currentSelectionCount * 3.5) + - (adjacentOpenCount * 2.5) + - (adjacentSelectionCount * 1.5) + - (preferredCount * 0.5) + - (profile.totalOpens * 0.15) + - (profile.totalSelections * 0.1) + - recencyBonus; + /// How much the undated hourly counters of an older profile say about + /// [now], 0..1. + /// + /// They carry a profile across the upgrade to visit history and then step + /// aside: they fade as the moment they describe recedes, and again as dated + /// days accumulate to replace them. + static double legacyStrength( + RouteUsageProfile profile, + DateTime now, { + required int datedDays, + }) { + final asOfMs = profile.legacyAsOfMs; + if (asOfMs == null || profile.totalOpens < minLegacyOpens) { + return 0; + } + final ageDays = + (now.millisecondsSinceEpoch - asOfMs) / Duration.millisecondsPerDay; + if (ageDays > RouteHabitModel.lookbackDays) { + return 0; + } + final hour = now.hour; + final current = profile.countAtHour(hour); + final adjacent = + profile.countAtHour((hour + 23) % 24) + + profile.countAtHour((hour + 1) % 24); + if (current + adjacent < minLegacyNearbyOpens) { + return 0; + } + final volume = math.min(1.0, (current + adjacent / 2) / legacyFullOpens); + final handover = math.max(0.0, 1 - datedDays / legacyHandoverDays); + return volume * RouteHabitModel.decay(ageDays) * handover; } static FavoriteStop? chooseFavoriteForRoute({ @@ -133,14 +194,7 @@ class SmartRouteService { required Iterable favorites, required DateTime now, }) { - final favoritesForRoute = favorites - .where( - (favorite) => - favorite.provider == routeProfile.provider && - favorite.routeKey == routeProfile.routeKey && - favorite.pathId == routeProfile.pathId, - ) - .toList(); + final favoritesForRoute = _favoritesForRoute(routeProfile, favorites); if (favoritesForRoute.isEmpty) { return null; } @@ -222,16 +276,101 @@ class SmartRouteService { recencyBonus; } - static String buildReason(RouteUsageProfile profile, DateTime now) { - // final currentCount = profile.combinedCountAtHour(now.hour); - // if (currentCount > 0) { - // return '你常在這個時段點開這條路線。'; - // } + /// The stop [profile] is usually opened at around the time of day of [at], + /// or null when no single stop stands out. + /// + /// Each day votes once per stop, so a morning spent reopening the page + /// counts the same as a morning that opened it once. + static int? learnedStopId(RouteUsageProfile profile, DateTime at) { + final atMs = at.millisecondsSinceEpoch; + final time = ServiceTime.fromDateTime(at); + final matchByStopAndDay = >{}; + for (final visit in profile.visitsWithin(now: at)) { + final stopId = visit.stopId; + if (stopId == null || visit.atMs > atMs) { + continue; + } + final visited = ServiceTime.fromMs(visit.atMs); + final match = RouteHabitModel.timeMatch( + (visited.minute - time.minute).abs(), + ); + if (match <= 0) { + continue; + } + final byDay = matchByStopAndDay[stopId] ??= {}; + byDay[visited.day] = math.max(byDay[visited.day] ?? 0, match); + } + + int? bestStopId; + var bestScore = 0.0; + var totalScore = 0.0; + for (final entry in matchByStopAndDay.entries) { + var score = 0.0; + entry.value.forEach((day, match) { + score += RouteHabitModel.decay(time.day - day) * match; + }); + totalScore += score; + if (score > bestScore || + (score == bestScore && + (bestStopId == null || entry.key < bestStopId))) { + bestScore = score; + bestStopId = entry.key; + } + } + if (bestStopId == null || + bestScore < minLearnedStopScore || + bestScore < minLearnedStopShare * totalScore) { + return null; + } + return bestStopId; + } + + /// The stop a reminder for [profile] should watch when the device's + /// location is not available: a favorite the rider has been using at this + /// time, else the stop the route is usually opened at, else the route's + /// only favorite. + static int? chooseBoardingStopId({ + required RouteUsageProfile profile, + required Iterable favoriteProfiles, + required Iterable favorites, + required DateTime at, + }) { + final usedFavorite = chooseFavoriteForRoute( + routeProfile: profile, + favoriteProfiles: favoriteProfiles, + favorites: favorites, + now: at, + ); + if (usedFavorite != null) { + return usedFavorite.stopId; + } + final learned = learnedStopId(profile, at); + if (learned != null) { + return learned; + } + final stopIds = _favoritesForRoute( + profile, + favorites, + ).map((favorite) => favorite.stopId).toSet(); + return stopIds.length == 1 ? stopIds.single : null; + } + + static const String _genericReason = '根據你的使用習慣。'; - // final preferredHour = profile.preferredHour; - // final label = preferredHour.toString().padLeft(2, '0'); - // return '你通常會在 $label:00 左右點開這條路線。'; - return '根據你的使用習慣。'; + static String _reasonFor(SmartRouteRanking ranking, DateTime now) { + final typicalMinute = ranking.estimate.typicalMinute; + if (!ranking.fromHabit || typicalMinute == null) { + return _genericReason; + } + // To the nearest five minutes: the spread of a habit is wider than that, + // and "07:38" would claim a precision nobody has. + final clock = ServiceTime.clockMinute((typicalMinute / 5).round() * 5); + final hour = (clock ~/ 60).toString().padLeft(2, '0'); + final minute = (clock % 60).toString().padLeft(2, '0'); + final days = ServiceTime.isWeekend(ServiceTime.fromDateTime(now).weekday) + ? '假日' + : '平日'; + return '你$days常在 $hour:$minute 左右查看這條路線。'; } static SmartRouteSuggestion buildSuggestion({ @@ -241,64 +380,89 @@ class SmartRouteService { required RouteDetailData detail, FavoriteStop? favorite, Position? position, + int? learnedStopId, + Iterable routeFavorites = const [], }) { - FavoriteStop? matchedFavorite; - StopInfo? favoriteStop; - PathInfo? favoritePath; final learnedPath = profile.pathId == null ? null : _findPath(detail, profile.pathId!); - if (favorite != null) { - favoritePath = _findPath(detail, favorite.pathId); - favoriteStop = _findStopInDetail( - detail, - favorite.pathId, - favorite.stopId, - ); - if (favoriteStop != null) { - matchedFavorite = favorite; - } else { - favoritePath = null; + + StopInfo? nearestStop; + double? nearestDistance; + if (position != null && profile.pathId != null) { + for (final stop + in detail.stopsByPath[profile.pathId] ?? const []) { + final distance = _distanceTo(position, stop); + if (distance == null) { + continue; + } + if (nearestDistance == null || distance < nearestDistance) { + nearestDistance = distance; + nearestStop = stop; + } } } - if (position == null) { + // A favorite the rider has been choosing at this time of day comes first: + // it is the one stop they have said, by using it, that they mean. + final usedFavoriteStop = favorite == null + ? null + : _findStopInDetail(detail, favorite.pathId, favorite.stopId); + if (favorite != null && usedFavoriteStop != null) { return SmartRouteSuggestion( profile: profile, score: score, reason: reason, detail: detail, + nearestStop: nearestStop, nearestPath: learnedPath, - favorite: matchedFavorite, - favoriteStop: favoriteStop, - favoritePath: favoritePath, + distanceMeters: nearestDistance, + favorite: favorite, + favoriteStop: usedFavoriteStop, + favoritePath: _findPath(detail, favorite.pathId), ); } - StopInfo? nearestStop; - PathInfo? nearestPath = learnedPath; - double? nearestDistance; - - for (final path in detail.paths.where( - (path) => path.pathId == profile.pathId, - )) { - final stops = detail.stopsByPath[path.pathId] ?? const []; - for (final stop in stops) { - if (stop.lat == 0 || stop.lon == 0) { - continue; - } - - final distance = Geolocator.distanceBetween( - position.latitude, - position.longitude, - stop.lat, - stop.lon, + // Otherwise the stop the route is usually opened at, and failing that a + // saved one. A saved stop nobody has used lately is shown as a plain stop + // rather than as the favorite: opening the favorite would also bring its + // destination along, which the rider has not asked for this time. + final usualStop = profile.pathId == null + ? null + : (learnedStopId == null + ? null + : _findStopInDetail( + detail, + profile.pathId!, + learnedStopId, + )) ?? + _closestFavoriteStop( + detail: detail, + favorites: _favoritesForRoute(profile, routeFavorites), + position: position, + ); + if (usualStop != null) { + final usualDistance = position == null + ? null + : _distanceTo(position, usualStop); + // The usual stop gives way only to a stop the rider is actually at + // while the usual one is out of reach: somebody 200 m from the stop + // before theirs is still going to walk to theirs. + final isElsewhereOnRoute = + nearestDistance != null && + nearestDistance <= atStopMeters && + (usualDistance == null || usualDistance > usualStopReachMeters); + if (!isElsewhereOnRoute) { + return SmartRouteSuggestion( + profile: profile, + score: score, + reason: reason, + detail: detail, + nearestStop: nearestStop, + nearestPath: learnedPath, + distanceMeters: usualDistance, + learnedStop: usualStop, ); - if (nearestDistance == null || distance < nearestDistance) { - nearestDistance = distance; - nearestStop = stop; - nearestPath = path; - } } } @@ -308,11 +472,8 @@ class SmartRouteService { reason: reason, detail: detail, nearestStop: nearestStop, - nearestPath: nearestPath, + nearestPath: learnedPath, distanceMeters: nearestDistance, - favorite: matchedFavorite, - favoriteStop: favoriteStop, - favoritePath: favoritePath, ); } @@ -351,46 +512,72 @@ class SmartRouteService { return const []; } + final favoriteProfileList = favoriteProfiles.toList(growable: false); + final favoriteList = favorites.toList(growable: false); + final ranked = rankProfilesForTime(profiles, now); final suggestions = []; - final seen = {}; - for (final entry in _rankProfilesForTime(profiles, now)) { - final profile = entry.key; - final identity = - '${profile.provider.name}:${profile.routeKey}:${profile.pathId}'; - if (!seen.add(identity)) { - continue; - } - try { - final detail = await repository.getCompleteBusInfo( - profile.routeKey, - provider: profile.provider, - ); - final favorite = chooseFavoriteForRoute( + var next = 0; + // Fetch only as many routes at once as there are places left to fill, in + // rank order. The common case is one round trip instead of [limit] in a + // row, and a route that fails or has run its last bus costs one more + // round rather than a fetch of every profile. + while (suggestions.length < limit && next < ranked.length) { + final batch = ranked.sublist( + next, + math.min(next + limit - suggestions.length, ranked.length), + ); + next += batch.length; + final loaded = await Future.wait( + batch.map( + (ranking) => _loadSuggestion( + repository: repository, + ranking: ranking, + favoriteProfiles: favoriteProfileList, + favorites: favoriteList, + now: now, + position: position, + ), + ), + ); + suggestions.addAll(loaded.whereType()); + } + return List.unmodifiable(suggestions); + } + + static Future _loadSuggestion({ + required BusRepository repository, + required SmartRouteRanking ranking, + required List favoriteProfiles, + required List favorites, + required DateTime now, + required Position? position, + }) async { + final profile = ranking.profile; + try { + final detail = await repository.getCompleteBusInfo( + profile.routeKey, + provider: profile.provider, + ); + final suggestion = buildSuggestion( + profile: profile, + score: ranking.score, + reason: _reasonFor(ranking, now), + detail: detail, + favorite: chooseFavoriteForRoute( routeProfile: profile, favoriteProfiles: favoriteProfiles, favorites: favorites, now: now, - ); - final suggestion = buildSuggestion( - profile: profile, - score: entry.value, - reason: buildReason(profile, now), - detail: detail, - favorite: favorite, - position: position, - ); - if (_isLastBusSuggestion(suggestion)) { - continue; - } - suggestions.add(suggestion); - if (suggestions.length == limit) { - break; - } - } catch (_) { - // Keep scanning lower-ranked profiles until the requested limit is met. - } + ), + position: position, + learnedStopId: learnedStopId(profile, now), + routeFavorites: favorites, + ); + return _isLastBusSuggestion(suggestion) ? null : suggestion; + } catch (_) { + // One route failing to load must not cost the others their place. + return null; } - return List.unmodifiable(suggestions); } static bool _isLastBusSuggestion(SmartRouteSuggestion suggestion) { @@ -412,6 +599,72 @@ class SmartRouteService { ); } + static String _identity(RouteUsageProfile profile) => + '${profile.provider.name}:${profile.routeKey}:${profile.pathId}'; + + static List _favoritesForRoute( + RouteUsageProfile profile, + Iterable favorites, + ) { + return favorites + .where( + (favorite) => + favorite.provider == profile.provider && + favorite.routeKey == profile.routeKey && + favorite.pathId == profile.pathId, + ) + .toList(); + } + + /// The saved stop to show when none has been used lately: the only one on + /// this direction, or the closest of several when the position is known. + /// With several and no position there is nothing to choose between them. + static StopInfo? _closestFavoriteStop({ + required RouteDetailData detail, + required List favorites, + required Position? position, + }) { + final candidates = []; + final seenStopIds = {}; + for (final favorite in favorites) { + final stop = _findStopInDetail(detail, favorite.pathId, favorite.stopId); + if (stop != null && seenStopIds.add(stop.stopId)) { + candidates.add(stop); + } + } + if (candidates.length <= 1) { + return candidates.isEmpty ? null : candidates.single; + } + if (position == null) { + return null; + } + StopInfo? closest; + double? closestDistance; + for (final candidate in candidates) { + final distance = _distanceTo(position, candidate); + if (distance == null) { + continue; + } + if (closestDistance == null || distance < closestDistance) { + closestDistance = distance; + closest = candidate; + } + } + return closest; + } + + static double? _distanceTo(Position position, StopInfo stop) { + if (stop.lat == 0 || stop.lon == 0) { + return null; + } + return Geolocator.distanceBetween( + position.latitude, + position.longitude, + stop.lat, + stop.lon, + ); + } + static StopInfo? _findStopInDetail( RouteDetailData detail, int pathId, diff --git a/lib/core/storage_service.dart b/lib/core/storage_service.dart index b21f26d7..fd0f8523 100644 --- a/lib/core/storage_service.dart +++ b/lib/core/storage_service.dart @@ -17,6 +17,7 @@ class StorageService { static const _favoriteUsageProfilesKey = 'favorite_usage_profiles'; static const _stopVisitProfilesKey = 'stop_visit_profiles'; static const _destinationChoiceProfilesKey = 'destination_choice_profiles'; + static const _smartRoutePlanKey = 'smart_route_plan'; static const _announcementLocalStateKey = 'announcement_local_state'; static const _settingsLastModifiedAtKey = 'app_settings_last_modified_at_ms'; static const _favoritesLastModifiedAtKey = @@ -341,6 +342,19 @@ class StorageService { ); } + /// The reminder plan is read by the Android background worker straight out + /// of the preferences file, under this key with the plugin's `flutter.` + /// prefix. Renaming it means renaming it there as well. + Future saveSmartRoutePlan(Map plan) async { + final prefs = await SharedPreferences.getInstance(); + await prefs.setString(_smartRoutePlanKey, jsonEncode(plan)); + } + + Future clearSmartRoutePlan() async { + final prefs = await SharedPreferences.getInstance(); + await prefs.remove(_smartRoutePlanKey); + } + Future> loadDestinationChoiceProfiles() async { final prefs = await SharedPreferences.getInstance(); final raw = prefs.getString(_destinationChoiceProfilesKey); diff --git a/lib/l10n/app_en.arb b/lib/l10n/app_en.arb index da8fa294..1feea581 100644 --- a/lib/l10n/app_en.arb +++ b/lib/l10n/app_en.arb @@ -100,7 +100,7 @@ "installUnavailable": "This device cannot show an installation prompt right now.", "smartRecommendationsTitle": "Smart recommendations", "smartRecommendationsSubtitle": "Routes suggested from your usage patterns", - "smartRecommendationsEmpty": "There are no recommendations to show yet. Open your usual routes a few times so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.", + "smartRecommendationsEmpty": "There are no recommendations to show yet. Open your usual routes at similar times on different days so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.", "smartRecommendationsDisabled": "This feature is off. When enabled, YABus learns which routes you open at different times and suggests them on the home screen.", "smartRecommendationsGoToSettings": "Go to settings", "smartRecommendationsNeedDatabase": "No local database is downloaded for the current region, so usage-based route suggestions are unavailable. Download it in Databases and downloads. Nearby stops can still be found when location is available.", @@ -236,11 +236,11 @@ "adsDisableDescription": "I have no money :(", "adsKeepEnabled": "Keep them on", "adsDisableConfirm": "Turn off", - "smartRecommendationsDescription": "Suggest routes on the home screen based on how often and when you open or select them. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.", + "smartRecommendationsDescription": "Suggest routes on the home screen from when you usually look them up on weekdays and weekends, showing the stop you usually use first. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.", "autoFavoriteTitle": "Auto-add frequent favorites", "autoFavoriteDescription": "Automatically add a stop to the Frequent favorites group after you select it for boarding several times in a short period. You can organize or remove these stops in Favorites. Turning this off stops new automatic additions and keeps existing favorites.", "smartNotificationTitle": "Smart recommendation notifications", - "smartNotificationDescription": "Check usual routes and nearby stops in the background around the times you often use them, and send arrival reminders when conditions match. Sufficient usage history, notification permission and background location are required. Battery restrictions may delay checks, and notifications are not sent every time.", + "smartNotificationDescription": "Around the time you usually check a route, look up arrivals at your usual stop in the background and remind you when there is a bus you can still catch. Reminders start once you have checked the same route at a similar time on several different days, and pause when you have not opened that route for two weeks (opening it from a reminder counts) until you check it again; the last reminders before a pause say so. Notification permission is required. Background location is optional: when granted, the stop follows where you are, and no reminder is sent when you are far from the route. Battery restrictions may delay checks, and a reminder is not sent every time.", "smartNotificationPermissionRequired": "Notification permission is required for smart recommendation notifications.", "keepScreenAwakeTitle": "Keep screen on for bus routes", "keepScreenAwakeDescription": "Prevent the screen from turning off due to inactivity while viewing route details, so you can watch the countdown while waiting. Normal screen behavior resumes when you leave the page. Keeping the screen on uses more battery.", diff --git a/lib/l10n/app_localizations.dart b/lib/l10n/app_localizations.dart index 4d0ec0a8..51da160f 100644 --- a/lib/l10n/app_localizations.dart +++ b/lib/l10n/app_localizations.dart @@ -648,7 +648,7 @@ abstract class AppLocalizations { /// No description provided for @smartRecommendationsEmpty. /// /// In en, this message translates to: - /// **'There are no recommendations to show yet. Open your usual routes a few times so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.'** + /// **'There are no recommendations to show yet. Open your usual routes at similar times on different days so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.'** String get smartRecommendationsEmpty; /// No description provided for @smartRecommendationsDisabled. @@ -1338,7 +1338,7 @@ abstract class AppLocalizations { /// No description provided for @smartRecommendationsDescription. /// /// In en, this message translates to: - /// **'Suggest routes on the home screen based on how often and when you open or select them. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.'** + /// **'Suggest routes on the home screen from when you usually look them up on weekdays and weekends, showing the stop you usually use first. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.'** String get smartRecommendationsDescription; /// No description provided for @autoFavoriteTitle. @@ -1362,7 +1362,7 @@ abstract class AppLocalizations { /// No description provided for @smartNotificationDescription. /// /// In en, this message translates to: - /// **'Check usual routes and nearby stops in the background around the times you often use them, and send arrival reminders when conditions match. Sufficient usage history, notification permission and background location are required. Battery restrictions may delay checks, and notifications are not sent every time.'** + /// **'Around the time you usually check a route, look up arrivals at your usual stop in the background and remind you when there is a bus you can still catch. Reminders start once you have checked the same route at a similar time on several different days, and pause when you have not opened that route for two weeks (opening it from a reminder counts) until you check it again; the last reminders before a pause say so. Notification permission is required. Background location is optional: when granted, the stop follows where you are, and no reminder is sent when you are far from the route. Battery restrictions may delay checks, and a reminder is not sent every time.'** String get smartNotificationDescription; /// No description provided for @smartNotificationPermissionRequired. diff --git a/lib/l10n/app_localizations_en.dart b/lib/l10n/app_localizations_en.dart index 75ac3856..d23c0bb2 100644 --- a/lib/l10n/app_localizations_en.dart +++ b/lib/l10n/app_localizations_en.dart @@ -328,7 +328,7 @@ class AppLocalizationsEn extends AppLocalizations { @override String get smartRecommendationsEmpty => - 'There are no recommendations to show yet. Open your usual routes a few times so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.'; + 'There are no recommendations to show yet. Open your usual routes at similar times on different days so YABus can learn when you use them. You can also grant location access in Nearby stops, then return and refresh to find nearby routes.'; @override String get smartRecommendationsDisabled => @@ -753,7 +753,7 @@ class AppLocalizationsEn extends AppLocalizations { @override String get smartRecommendationsDescription => - 'Suggest routes on the home screen based on how often and when you open or select them. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.'; + 'Suggest routes on the home screen from when you usually look them up on weekdays and weekends, showing the stop you usually use first. With insufficient history, nearby stops are used when location is available. Usage-based suggestions require a local database for your region. Turning this off hides the card; learning records can be cleared in History and privacy.'; @override String get autoFavoriteTitle => 'Auto-add frequent favorites'; @@ -767,7 +767,7 @@ class AppLocalizationsEn extends AppLocalizations { @override String get smartNotificationDescription => - 'Check usual routes and nearby stops in the background around the times you often use them, and send arrival reminders when conditions match. Sufficient usage history, notification permission and background location are required. Battery restrictions may delay checks, and notifications are not sent every time.'; + 'Around the time you usually check a route, look up arrivals at your usual stop in the background and remind you when there is a bus you can still catch. Reminders start once you have checked the same route at a similar time on several different days, and pause when you have not opened that route for two weeks (opening it from a reminder counts) until you check it again; the last reminders before a pause say so. Notification permission is required. Background location is optional: when granted, the stop follows where you are, and no reminder is sent when you are far from the route. Battery restrictions may delay checks, and a reminder is not sent every time.'; @override String get smartNotificationPermissionRequired => diff --git a/lib/l10n/app_localizations_zh.dart b/lib/l10n/app_localizations_zh.dart index 0e7a7a1d..6aee97e0 100644 --- a/lib/l10n/app_localizations_zh.dart +++ b/lib/l10n/app_localizations_zh.dart @@ -306,7 +306,7 @@ class AppLocalizationsZh extends AppLocalizations { @override String get smartRecommendationsEmpty => - '目前沒有可顯示的推薦。多開啟幾次常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。'; + '目前沒有可顯示的推薦。在不同日子的相近時間開啟常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。'; @override String get smartRecommendationsDisabled => @@ -699,7 +699,7 @@ class AppLocalizationsZh extends AppLocalizations { @override String get smartRecommendationsDescription => - '依照你開啟與選擇路線的次數、常用時段,在首頁推薦可能想搭的路線。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。'; + '依照你平日與假日在各時段查看路線的習慣,在首頁推薦此刻可能想搭的路線,並優先顯示你常用的站牌。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。'; @override String get autoFavoriteTitle => '自動加入常用最愛'; @@ -713,7 +713,7 @@ class AppLocalizationsZh extends AppLocalizations { @override String get smartNotificationDescription => - '在你常查詢路線的時段,於背景檢查常用路線與附近站牌,符合條件時發送到站提醒。需要足夠的使用紀錄、通知權限與背景定位;系統省電限制可能延後檢查,並非每次都會發送通知。'; + '在你平常查看某條路線的時間前後,於背景查詢你常用站牌的到站時間,有趕得上的班次時提醒你。要在不同日子的相近時間多次查看同一條路線才會開始提醒;超過兩週沒有再開啟該路線(從提醒通知點進去查看也算)就會暫停,暫停前的提醒會先告知,再次查看後恢復。需要通知權限。背景定位為選用:授權後會依你當下的位置調整站牌,離路線太遠時不提醒。系統省電限制可能延後檢查,並非每次都會發送通知。'; @override String get smartNotificationPermissionRequired => '需要通知權限才能啓用智慧推薦通知。'; @@ -3638,7 +3638,7 @@ class AppLocalizationsZhTw extends AppLocalizationsZh { @override String get smartRecommendationsEmpty => - '目前沒有可顯示的推薦。多開啟幾次常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。'; + '目前沒有可顯示的推薦。在不同日子的相近時間開啟常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。'; @override String get smartRecommendationsDisabled => @@ -4031,7 +4031,7 @@ class AppLocalizationsZhTw extends AppLocalizationsZh { @override String get smartRecommendationsDescription => - '依照你開啟與選擇路線的次數、常用時段,在首頁推薦可能想搭的路線。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。'; + '依照你平日與假日在各時段查看路線的習慣,在首頁推薦此刻可能想搭的路線,並優先顯示你常用的站牌。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。'; @override String get autoFavoriteTitle => '自動加入常用最愛'; @@ -4045,7 +4045,7 @@ class AppLocalizationsZhTw extends AppLocalizationsZh { @override String get smartNotificationDescription => - '在你常查詢路線的時段,於背景檢查常用路線與附近站牌,符合條件時發送到站提醒。需要足夠的使用紀錄、通知權限與背景定位;系統省電限制可能延後檢查,並非每次都會發送通知。'; + '在你平常查看某條路線的時間前後,於背景查詢你常用站牌的到站時間,有趕得上的班次時提醒你。要在不同日子的相近時間多次查看同一條路線才會開始提醒;超過兩週沒有再開啟該路線(從提醒通知點進去查看也算)就會暫停,暫停前的提醒會先告知,再次查看後恢復。需要通知權限。背景定位為選用:授權後會依你當下的位置調整站牌,離路線太遠時不提醒。系統省電限制可能延後檢查,並非每次都會發送通知。'; @override String get smartNotificationPermissionRequired => '需要通知權限才能啓用智慧推薦通知。'; diff --git a/lib/l10n/app_zh.arb b/lib/l10n/app_zh.arb index c91e015a..dff6b4df 100644 --- a/lib/l10n/app_zh.arb +++ b/lib/l10n/app_zh.arb @@ -100,7 +100,7 @@ "installUnavailable": "這個裝置目前無法顯示安裝提示。", "smartRecommendationsTitle": "智慧推薦", "smartRecommendationsSubtitle": "根據你的使用習慣推薦路線", - "smartRecommendationsEmpty": "目前沒有可顯示的推薦。多開啟幾次常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。", + "smartRecommendationsEmpty": "目前沒有可顯示的推薦。在不同日子的相近時間開啟常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。", "smartRecommendationsDisabled": "這個功能目前已關閉。開啓後,YABus 會學習你在不同時段最常點開的路線,並在首頁直接推薦。", "smartRecommendationsGoToSettings": "前往設定", "smartRecommendationsNeedDatabase": "目前地區尚未下載本地資料庫,無法依使用紀錄產生路線推薦。請到「資料庫與下載」下載目前地區的資料;若有可用定位,仍可查詢附近站牌。", @@ -236,11 +236,11 @@ "adsDisableDescription": "我沒有摳摳 :(", "adsKeepEnabled": "算了不關", "adsDisableConfirm": "確定關閉", - "smartRecommendationsDescription": "依照你開啟與選擇路線的次數、常用時段,在首頁推薦可能想搭的路線。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。", + "smartRecommendationsDescription": "依照你平日與假日在各時段查看路線的習慣,在首頁推薦此刻可能想搭的路線,並優先顯示你常用的站牌。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。", "autoFavoriteTitle": "自動加入常用最愛", "autoFavoriteDescription": "短期內多次選擇同一站牌搭乘時,自動將它加入「常用」最愛群組,減少手動收藏的步驟。自動新增的站牌仍可在最愛頁整理或移除;關閉後會停止自動新增,已加入的最愛會保留。", "smartNotificationTitle": "智慧推薦通知", - "smartNotificationDescription": "在你常查詢路線的時段,於背景檢查常用路線與附近站牌,符合條件時發送到站提醒。需要足夠的使用紀錄、通知權限與背景定位;系統省電限制可能延後檢查,並非每次都會發送通知。", + "smartNotificationDescription": "在你平常查看某條路線的時間前後,於背景查詢你常用站牌的到站時間,有趕得上的班次時提醒你。要在不同日子的相近時間多次查看同一條路線才會開始提醒;超過兩週沒有再開啟該路線(從提醒通知點進去查看也算)就會暫停,暫停前的提醒會先告知,再次查看後恢復。需要通知權限。背景定位為選用:授權後會依你當下的位置調整站牌,離路線太遠時不提醒。系統省電限制可能延後檢查,並非每次都會發送通知。", "smartNotificationPermissionRequired": "需要通知權限才能啓用智慧推薦通知。", "keepScreenAwakeTitle": "進入公車頁保持亮屏", "keepScreenAwakeDescription": "查看路線詳細頁時,避免螢幕因閒置自動熄滅,方便候車時持續看倒數。離開路線頁後恢復一般螢幕行為;長時間保持亮屏會增加耗電。", diff --git a/lib/l10n/app_zh_TW.arb b/lib/l10n/app_zh_TW.arb index f4bc121e..57139a48 100644 --- a/lib/l10n/app_zh_TW.arb +++ b/lib/l10n/app_zh_TW.arb @@ -100,7 +100,7 @@ "installUnavailable": "這個裝置目前無法顯示安裝提示。", "smartRecommendationsTitle": "智慧推薦", "smartRecommendationsSubtitle": "根據你的使用習慣推薦路線", - "smartRecommendationsEmpty": "目前沒有可顯示的推薦。多開啟幾次常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。", + "smartRecommendationsEmpty": "目前沒有可顯示的推薦。在不同日子的相近時間開啟常搭的路線,YABus 就能逐漸學習你的使用時段;也可以到「附近站牌」授權定位,再回來重新整理,查看附近可搭乘的路線。", "smartRecommendationsDisabled": "這個功能目前已關閉。開啓後,YABus 會學習你在不同時段最常點開的路線,並在首頁直接推薦。", "smartRecommendationsGoToSettings": "前往設定", "smartRecommendationsNeedDatabase": "目前地區尚未下載本地資料庫,無法依使用紀錄產生路線推薦。請到「資料庫與下載」下載目前地區的資料;若有可用定位,仍可查詢附近站牌。", @@ -236,11 +236,11 @@ "adsDisableDescription": "我沒有摳摳 :(", "adsKeepEnabled": "算了不關", "adsDisableConfirm": "確定關閉", - "smartRecommendationsDescription": "依照你開啟與選擇路線的次數、常用時段,在首頁推薦可能想搭的路線。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。", + "smartRecommendationsDescription": "依照你平日與假日在各時段查看路線的習慣,在首頁推薦此刻可能想搭的路線,並優先顯示你常用的站牌。使用紀錄不足時會嘗試顯示附近站牌;附近推薦需要定位,依使用紀錄推薦則需要目前地區的本地資料庫。關閉後首頁會隱藏這個區塊,學習紀錄可在「紀錄與隱私」清除。", "autoFavoriteTitle": "自動加入常用最愛", "autoFavoriteDescription": "短期內多次選擇同一站牌搭乘時,自動將它加入「常用」最愛群組,減少手動收藏的步驟。自動新增的站牌仍可在最愛頁整理或移除;關閉後會停止自動新增,已加入的最愛會保留。", "smartNotificationTitle": "智慧推薦通知", - "smartNotificationDescription": "在你常查詢路線的時段,於背景檢查常用路線與附近站牌,符合條件時發送到站提醒。需要足夠的使用紀錄、通知權限與背景定位;系統省電限制可能延後檢查,並非每次都會發送通知。", + "smartNotificationDescription": "在你平常查看某條路線的時間前後,於背景查詢你常用站牌的到站時間,有趕得上的班次時提醒你。要在不同日子的相近時間多次查看同一條路線才會開始提醒;超過兩週沒有再開啟該路線(從提醒通知點進去查看也算)就會暫停,暫停前的提醒會先告知,再次查看後恢復。需要通知權限。背景定位為選用:授權後會依你當下的位置調整站牌,離路線太遠時不提醒。系統省電限制可能延後檢查,並非每次都會發送通知。", "smartNotificationPermissionRequired": "需要通知權限才能啓用智慧推薦通知。", "keepScreenAwakeTitle": "進入公車頁保持亮屏", "keepScreenAwakeDescription": "查看路線詳細頁時,避免螢幕因閒置自動熄滅,方便候車時持續看倒數。離開路線頁後恢復一般螢幕行為;長時間保持亮屏會增加耗電。", diff --git a/lib/screens/route_detail_screen.dart b/lib/screens/route_detail_screen.dart index f2600b8a..14df80c7 100644 --- a/lib/screens/route_detail_screen.dart +++ b/lib/screens/route_detail_screen.dart @@ -25,6 +25,7 @@ import '../core/models.dart'; import '../core/refresh_backoff.dart'; import '../core/route_detail_launch_bridge.dart'; import '../core/samsung_live_notification_prompt_service.dart'; +import '../core/smart_route_service.dart'; import '../core/stop_route_merge.dart'; import '../core/trip_monitor_notifications.dart'; import '../core/twbusforum.dart'; @@ -559,6 +560,7 @@ class _RouteDetailScreenState extends State detail.route, provider: widget.provider, pathId: _currentPathId, + stopId: _usageStopHint(), ), ); }); @@ -3137,6 +3139,38 @@ class _RouteDetailScreenState extends State _currentBoardingCandidateStop(); } + /// The stop this visit should be remembered against, if any. + /// + /// The stop the page was opened on, or one the rider picked, is taken as + /// given. The nearest stop is only a guess at where they will board, and is + /// trusted only when they are close enough to be heading for it: the + /// nearest stop to somebody reading the timetable from across town says + /// nothing about their habits. + int? _usageStopHint() { + final opened = _findStopById(_currentPathStops, widget.initialStopId); + if (opened != null) { + return opened.stopId; + } + final stop = _resolvedBoardingStop(); + if (stop == null) { + return null; + } + if (_currentBoardingCandidateStop()?.stopId != stop.stopId) { + return stop.stopId; + } + final position = _lastPosition; + if (position == null || (stop.lat == 0 && stop.lon == 0)) { + return null; + } + final distance = Geolocator.distanceBetween( + position.latitude, + position.longitude, + stop.lat, + stop.lon, + ); + return distance <= SmartRouteService.atStopMeters ? stop.stopId : null; + } + String? _buildDesktopDiscordArrivalStatus(AppSettings settings) { if (!settings.desktopDiscordShowScreen) { return null; diff --git a/test/fixtures/smart_route_plan_v1.json b/test/fixtures/smart_route_plan_v1.json new file mode 100644 index 00000000..5e0e84a8 --- /dev/null +++ b/test/fixtures/smart_route_plan_v1.json @@ -0,0 +1,102 @@ +{ + "version": 1, + "generatedAtMs": 1775599200000, + "dayStartHour": 4, + "slots": [ + { + "provider": "khh", + "routeKey": 101, + "routeId": "KHH101", + "pathId": 0, + "routeName": "307", + "weekday": 1, + "startMinute": 190, + "endMinute": 250, + "peakMinute": 220, + "confidence": 0.918, + "supportDays": 15, + "validUntilMs": 1776801600000, + "lastActivityAtMs": 1775518800000, + "stopId": 100100128221 + }, + { + "provider": "khh", + "routeKey": 101, + "routeId": "KHH101", + "pathId": 0, + "routeName": "307", + "weekday": 2, + "startMinute": 190, + "endMinute": 250, + "peakMinute": 220, + "confidence": 0.915, + "supportDays": 15, + "validUntilMs": 1776801600000, + "lastActivityAtMs": 1775518800000, + "stopId": 100100128221 + }, + { + "provider": "khh", + "routeKey": 101, + "routeId": "KHH101", + "pathId": 0, + "routeName": "307", + "weekday": 3, + "startMinute": 190, + "endMinute": 250, + "peakMinute": 220, + "confidence": 0.933, + "supportDays": 15, + "validUntilMs": 1776801600000, + "lastActivityAtMs": 1775518800000, + "stopId": 100100128221 + }, + { + "provider": "khh", + "routeKey": 101, + "routeId": "KHH101", + "pathId": 0, + "routeName": "307", + "weekday": 4, + "startMinute": 190, + "endMinute": 250, + "peakMinute": 220, + "confidence": 0.93, + "supportDays": 15, + "validUntilMs": 1776801600000, + "lastActivityAtMs": 1775518800000, + "stopId": 100100128221 + }, + { + "provider": "khh", + "routeKey": 101, + "routeId": "KHH101", + "pathId": 0, + "routeName": "307", + "weekday": 5, + "startMinute": 190, + "endMinute": 250, + "peakMinute": 220, + "confidence": 0.927, + "supportDays": 15, + "validUntilMs": 1776801600000, + "lastActivityAtMs": 1775518800000, + "stopId": 100100128221 + }, + { + "provider": "khh", + "routeKey": 202, + "routeId": "KHH202", + "pathId": 1, + "routeName": "紅12", + "weekday": 6, + "startMinute": 820, + "endMinute": 860, + "peakMinute": 840, + "confidence": 0.763, + "supportDays": 4, + "validUntilMs": 1776542400000, + "lastActivityAtMs": 1775296800000 + } + ] +} diff --git a/test/fixtures/smart_route_reminder_log_v1.json b/test/fixtures/smart_route_reminder_log_v1.json new file mode 100644 index 00000000..7125b0ca --- /dev/null +++ b/test/fixtures/smart_route_reminder_log_v1.json @@ -0,0 +1,16 @@ +[ + { + "provider": "khh", + "routeKey": 101, + "pathId": 0, + "atMs": 1775604360000, + "peakMinute": 220 + }, + { + "provider": "khh", + "routeKey": 202, + "pathId": 1, + "atMs": 1775901000000, + "peakMinute": 840 + } +] diff --git a/test/smart_route_habit_test.dart b/test/smart_route_habit_test.dart new file mode 100644 index 00000000..68f69d1e --- /dev/null +++ b/test/smart_route_habit_test.dart @@ -0,0 +1,444 @@ +import 'package:flutter_test/flutter_test.dart'; +import 'package:taiwanbus_flutter/core/models.dart'; +import 'package:taiwanbus_flutter/core/smart_route_habit.dart'; + +import 'support/route_usage_fixtures.dart'; + +void main() { + // 2026-04-08 is a Wednesday. + final wednesdayMorning = DateTime(2026, 4, 8, 7, 40); + + RouteHabitEstimate estimateAt(RouteUsageProfile profile, DateTime now) => + RouteHabitEvidence.of(profile, now).estimateNow(now); + + group('ServiceTime', () { + test('starts the day at 04:00', () { + final beforeStart = ServiceTime.fromDateTime(DateTime(2026, 4, 8, 3, 59)); + final atStart = ServiceTime.fromDateTime(DateTime(2026, 4, 8, 4)); + + expect(atStart.minute, 0); + expect(atStart.weekday, DateTime.wednesday); + expect(beforeStart.minute, 23 * 60 + 59); + expect(beforeStart.weekday, DateTime.tuesday); + expect(atStart.day, beforeStart.day + 1); + }); + + test('keeps a ride after midnight on the evening it belongs to', () { + // 2026-04-11 is a Saturday; 00:20 that morning is Friday night. + final lateRide = ServiceTime.fromDateTime(DateTime(2026, 4, 11, 0, 20)); + + expect(lateRide.weekday, DateTime.friday); + expect(lateRide.minute, 20 * 60 + 20); + expect(ServiceTime.clockMinute(lateRide.minute), 20); + }); + + test('turns a day index back into the moment that day begins', () { + final time = ServiceTime.fromDateTime(wednesdayMorning); + + expect(ServiceTime.startOfDay(time.day), DateTime(2026, 4, 8, 4)); + expect(ServiceTime.weekdayOfDay(time.day), DateTime.wednesday); + expect(ServiceTime.weekdayOfDay(time.day + 4), DateTime.sunday); + }); + }); + + group('time match', () { + test('falls off smoothly and then stops', () { + expect(RouteHabitModel.timeMatch(0), 1); + expect(RouteHabitModel.timeMatch(30), closeTo(0.607, 0.001)); + expect(RouteHabitModel.timeMatch(60), closeTo(0.135, 0.001)); + expect(RouteHabitModel.timeMatch(75), greaterThan(0)); + expect(RouteHabitModel.timeMatch(76), 0); + }); + + test('does not care which side of an hour a use fell on', () { + // 07:58 and 08:02 are four minutes apart, not one hour bucket apart. + final now = DateTime(2026, 4, 8, 8, 2); + final profile = profileWithVisits( + daysBefore(now, count: 10, hour: 7, minute: 58), + ); + + expect(estimateAt(profile, now).probability, greaterThan(0.75)); + }); + }); + + group('a weekday commute', () { + final commute = profileWithVisits( + daysBefore(wednesdayMorning, count: 15, hour: 7, minute: 40), + ); + + test('is expected at its usual time on a weekday', () { + final estimate = estimateAt(commute, wednesdayMorning); + + expect(estimate.probability, greaterThan(0.8)); + expect(estimate.supportDays, 15); + expect( + estimate.typicalMinute, + // 07:40 is 220 minutes into a day that starts at 04:00. + 220, + ); + }); + + test('is not expected on the weekend', () { + final saturday = DateTime(2026, 4, 11, 7, 40); + + expect(estimateAt(commute, saturday).probability, lessThan(0.1)); + }); + + test('is not expected at another time of day', () { + final afternoon = DateTime(2026, 4, 8, 14); + + final estimate = estimateAt(commute, afternoon); + + expect(estimate.probability, 0); + expect(estimate.supportDays, 0); + }); + + test('weakens the further the clock is from the usual time', () { + final atUsualTime = estimateAt(commute, wednesdayMorning).probability; + final halfHourEarly = estimateAt( + commute, + DateTime(2026, 4, 8, 7, 10), + ).probability; + final anHourEarly = estimateAt( + commute, + DateTime(2026, 4, 8, 6, 40), + ).probability; + + expect(halfHourEarly, lessThan(atUsualTime)); + expect(anHourEarly, lessThan(halfHourEarly)); + expect(halfHourEarly, greaterThan(0.4)); + expect(anHourEarly, lessThan(0.2)); + }); + }); + + test('a class on two weekdays is told apart from the days between', () { + // Three weeks of Tuesdays and Thursdays at 10:00. + final tuesday = DateTime(2026, 4, 7, 10); + final profile = profileWithVisits( + daysBefore( + tuesday, + count: 6, + hour: 10, + minute: 0, + weekdays: const {DateTime.tuesday, DateTime.thursday}, + ), + ); + + final onTuesday = estimateAt(profile, tuesday).probability; + final onWednesday = estimateAt( + profile, + DateTime(2026, 4, 8, 10), + ).probability; + + expect(onTuesday, greaterThan(0.6)); + expect(onWednesday, lessThan(0.25)); + }); + + test('one busy morning is one day of evidence', () { + final yesterday = DateTime(2026, 4, 7, 7, 30); + final profile = profileWithVisits([ + for (var index = 0; index < 5; index++) + yesterday.add(Duration(minutes: index * 25)), + ]); + + expect(profile.visits, hasLength(5)); + expect(estimateAt(profile, wednesdayMorning).supportDays, 1); + }); + + test('a habit that stopped fades instead of lasting forever', () { + // Every weekday until the visits stop, then nothing. + RouteUsageProfile stoppedDaysAgo(int daysAgo) => profileWithVisits( + daysBefore( + wednesdayMorning.subtract(Duration(days: daysAgo)), + count: 15, + hour: 7, + minute: 40, + ), + ); + + final stillGoing = estimateAt(stoppedDaysAgo(0), wednesdayMorning); + final twoWeeksGone = estimateAt(stoppedDaysAgo(14), wednesdayMorning); + final sixWeeksGone = estimateAt(stoppedDaysAgo(42), wednesdayMorning); + + expect(stillGoing.probability, greaterThan(0.9)); + expect(twoWeeksGone.probability, inInclusiveRange(0.25, 0.5)); + expect(sixWeeksGone.probability, lessThan(0.1)); + }); + + test('a new habit is not held back by the days before it began', () { + // An evening trip that only started three days ago, on a route that has + // been a morning trip for weeks. + final evening = DateTime(2026, 4, 8, 18, 30); + final profile = profileWithVisits([ + ...daysBefore(evening, count: 15, hour: 7, minute: 40), + ...daysBefore(evening, count: 3, hour: 18, minute: 30), + ]); + + final estimate = estimateAt(profile, evening); + + expect(estimate.supportDays, 3); + expect(estimate.probability, greaterThan(0.5)); + }); + + test('scattered uses over two months are not a routine', () { + final profile = profileWithVisits([ + DateTime(2026, 2, 17, 7, 40), + DateTime(2026, 3, 10, 7, 40), + DateTime(2026, 3, 31, 7, 40), + ]); + + final estimate = estimateAt(profile, wednesdayMorning); + + expect(estimate.supportDays, 3); + expect(estimate.probability, lessThan(0.25)); + }); + + test('today vouches for tomorrow but not for itself', () { + // Used on Monday, Tuesday and — an hour ago — today. + final now = DateTime(2026, 4, 8, 8, 40); + final profile = profileWithVisits([ + DateTime(2026, 4, 6, 7, 40), + DateTime(2026, 4, 7, 7, 40), + DateTime(2026, 4, 8, 7, 40), + ]); + final evidence = RouteHabitEvidence.of(profile, now); + final usualMinute = ServiceTime.fromDateTime(wednesdayMorning).minute; + + final today = evidence.estimate( + targetDay: evidence.today, + minute: usualMinute, + ); + final tomorrow = evidence.estimate( + targetDay: evidence.today + 1, + minute: usualMinute, + ); + + expect(today.supportDays, 2); + expect(tomorrow.supportDays, 3); + expect(tomorrow.lastSupportDay, evidence.today); + expect(evidence.minutesSinceLastUseToday(now), 60); + }); + + test('a visit that has not happened yet is not evidence', () { + final profile = profileWithVisits([ + DateTime(2026, 4, 6, 7, 40), + DateTime(2026, 4, 7, 7, 40), + DateTime(2026, 4, 9, 7, 40), + ]); + + expect(estimateAt(profile, wednesdayMorning).supportDays, 2); + }); + + test('taps from the last week count alongside opens', () { + final tapped = RouteUsageProfile( + provider: BusProvider.nwt, + routeKey: 202, + pathId: 0, + routeName: '綠3', + totalOpens: 0, + lastOpenedAtMs: 0, + selectionTimestampsMs: [ + for (final tap in daysBefore( + wednesdayMorning, + count: 3, + hour: 7, + minute: 35, + )) + tap.millisecondsSinceEpoch, + ], + ); + + expect(estimateAt(tapped, wednesdayMorning).supportDays, 3); + }); + + group('days a reminder was shown', () { + // Every weekday through Friday the 3rd, then twelve weekdays on which + // the route was never opened, up to Wednesday the 22nd. + final now = DateTime(2026, 4, 22, 7, 40); + final commute = profileWithVisits( + daysBefore(DateTime(2026, 4, 4), count: 15, hour: 7, minute: 40), + ); + List remindersAt(int hour, int minute) => [ + for (final day in daysBefore(now, count: 12, hour: hour, minute: minute)) + (atMs: day.millisecondsSinceEpoch, forMinute: null), + ]; + double probability({ + RouteUsageProfile? profile, + List reminders = const [], + }) => RouteHabitEvidence.of( + profile ?? commute, + now, + reminders: reminders, + ).estimateNow(now).probability; + + test('do not count as days the rider stayed away', () { + expect(probability(), lessThan(0.4)); + expect(probability(reminders: remindersAt(7, 30)), greaterThan(0.75)); + }); + + test('are only excused around the time of the reminder', () { + expect(probability(reminders: remindersAt(18, 0)), probability()); + // Seventy-five minutes either way is as far as a use would count. + expect(probability(reminders: remindersAt(6, 25)), greaterThan(0.75)); + expect(probability(reminders: remindersAt(6, 24)), probability()); + expect(probability(reminders: remindersAt(8, 55)), greaterThan(0.75)); + expect(probability(reminders: remindersAt(8, 56)), probability()); + }); + + test('still count as a use when the route was opened as well', () { + final usedYesterday = commute.recordOpen(DateTime(2026, 4, 21, 7, 40)); + + expect( + probability( + profile: usedYesterday, + reminders: [ + ( + atMs: DateTime(2026, 4, 21, 7, 30).millisecondsSinceEpoch, + forMinute: null, + ), + ], + ), + probability(profile: usedYesterday), + ); + expect(probability(profile: usedYesterday), greaterThan(probability())); + }); + + test('are not evidence of use by themselves', () { + final evidence = RouteHabitEvidence.of( + profileWithVisits(const []), + now, + reminders: remindersAt(7, 30), + ); + + expect(evidence.isEmpty, isTrue); + expect(evidence.estimateNow(now).probability, 0); + }); + }); + + group('a use that answers a reminder', () { + // A 07:40 commute, reminded at 07:26 — ahead of time, as reminders are. + final now = DateTime(2026, 4, 8, 9); + final usualMinute = ServiceTime.fromDateTime( + DateTime(2026, 4, 8, 7, 40), + ).minute; + final history = daysBefore(now, count: 15, hour: 7, minute: 40); + RouteReminderShown reminderOn(DateTime day, {int? forMinute}) => ( + atMs: DateTime( + day.year, + day.month, + day.day, + 7, + 26, + ).millisecondsSinceEpoch, + forMinute: forMinute, + ); + // The last ten of those days opened at [hour]:[minute] instead, each + // after a reminder for 07:40. + RouteHabitEvidence openedAt(int hour, int minute, {bool known = true}) { + final answered = history.skip(5).toList(); + return RouteHabitEvidence.of( + profileWithVisits([ + ...history.take(5), + for (final day in answered) + DateTime(day.year, day.month, day.day, hour, minute), + ]), + now, + reminders: [ + for (final day in answered) + reminderOn(day, forMinute: known ? usualMinute : null), + ], + ); + } + + int? typicalMinute(RouteHabitEvidence evidence) => evidence + .estimate(targetDay: evidence.today, minute: usualMinute) + .typicalMinute; + + test('confirms the time the reminder was for, not the time of the tap', () { + // Tapped a minute after it appeared, every day for two weeks. + expect(typicalMinute(openedAt(7, 27)), usualMinute); + // Without knowing what the reminders were for, the routine would seem + // to have moved toward them. + expect( + typicalMinute(openedAt(7, 27, known: false)), + lessThan(usualMinute - 5), + ); + }); + + test('is anywhere from the reminder to the time it was for', () { + expect(typicalMinute(openedAt(7, 26)), usualMinute); + expect(typicalMinute(openedAt(7, 40)), usualMinute); + }); + + test('is not one made before the reminder or after its time', () { + expect(typicalMinute(openedAt(7, 25)), lessThan(usualMinute - 5)); + expect(typicalMinute(openedAt(7, 55)), greaterThan(usualMinute + 5)); + }); + + test('is still timed from when it was really made', () { + // Tapped at 07:27, three minutes ago; read as agreeing with 07:40. + final justTapped = DateTime(2026, 4, 8, 7, 30); + final evidence = RouteHabitEvidence.of( + profileWithVisits([DateTime(2026, 4, 8, 7, 27)]), + justTapped, + reminders: [reminderOn(justTapped, forMinute: usualMinute)], + ); + + expect(evidence.minutesSinceLastUseToday(justTapped), 3); + expect( + evidence.minutesSinceLastUseToday(DateTime(2026, 4, 8, 8, 30)), + 63, + ); + }); + }); + + group('today', () { + // An evening trip made on Monday, Tuesday and Wednesday, asked about on + // Thursday the 9th with nothing opened yet that day. + final newHabit = profileWithVisits([ + DateTime(2026, 4, 6, 18, 10), + DateTime(2026, 4, 7, 18, 10), + DateTime(2026, 4, 8, 18, 10), + ]); + final usualMinute = ServiceTime.fromDateTime( + DateTime(2026, 4, 9, 18, 10), + ).minute; + double fridayAsSeenAt(int hour, int minute) { + final evidence = RouteHabitEvidence.of( + newHabit, + DateTime(2026, 4, 9, hour, minute), + ); + return evidence + .estimate(targetDay: evidence.today + 1, minute: usualMinute) + .probability; + } + + test('is not held against tomorrow while there is still time', () { + // Three days out of three in the morning; three out of four by night. + expect(fridayAsSeenAt(7, 40), greaterThan(0.55)); + expect(fridayAsSeenAt(21, 0), lessThan(0.5)); + }); + + test('has run out of time once a use would no longer count', () { + // 19:25 is the last minute a use would still match 18:10. + expect(fridayAsSeenAt(19, 25), fridayAsSeenAt(7, 40)); + expect(fridayAsSeenAt(19, 26), fridayAsSeenAt(21, 0)); + }); + }); + + test('a Friday-night habit is found after midnight on Saturday', () { + // 00:20 on four consecutive Saturday mornings. + final saturdayAfterMidnight = DateTime(2026, 4, 11, 0, 10); + final profile = profileWithVisits([ + for (var week = 1; week <= 4; week++) + DateTime(2026, 4, 11 - week * 7, 0, 20), + ]); + + final onFridayNight = estimateAt(profile, saturdayAfterMidnight); + final onMondayNight = estimateAt(profile, DateTime(2026, 4, 7, 0, 10)); + + expect(onFridayNight.supportDays, 4); + expect(onFridayNight.probability, greaterThan(0.6)); + expect(onMondayNight.probability, lessThan(0.2)); + }); +} diff --git a/test/smart_route_plan_controller_test.dart b/test/smart_route_plan_controller_test.dart new file mode 100644 index 00000000..02811ad0 --- /dev/null +++ b/test/smart_route_plan_controller_test.dart @@ -0,0 +1,409 @@ +import 'dart:convert'; + +import 'package:flutter/foundation.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:shared_preferences/shared_preferences.dart'; +import 'package:taiwanbus_flutter/core/app_controller.dart'; +import 'package:taiwanbus_flutter/core/bus_repository.dart'; +import 'package:taiwanbus_flutter/core/models.dart'; + +import 'support/ad_test_controller.dart'; +import 'support/route_usage_fixtures.dart'; + +class _Repository extends BusRepository { + /// Each lookup as `provider:key,key`, keys in ascending order. + final List lookups = []; + bool databaseMissing = false; + + @override + Future> routeIdsForRouteKeys( + BusProvider provider, + Set routeKeys, + ) async { + lookups.add('${provider.name}:${(routeKeys.toList()..sort()).join(',')}'); + if (databaseMissing) { + throw DatabaseNotReadyException('尚未下載路線資料庫。'); + } + return { + for (final routeKey in routeKeys) + if (routeKey != 404) routeKey: '${provider.prefix}$routeKey', + }; + } +} + +const _homeChannel = MethodChannel( + 'tw.avianjay.taiwanbus.flutter/home_integration', +); + +void main() { + TestWidgetsFlutterBinding.ensureInitialized(); + final messenger = + TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger; + late List homeCalls; + + // Fifteen weekday mornings, all at one stop: enough for a reminder on any + // weekday, whatever day and hour the test happens to run at. + RouteUsageProfile commute({ + int routeKey = 101, + BusProvider provider = BusProvider.khh, + }) => profileWithVisits( + daysBefore(DateTime.now(), count: 15, hour: 7, minute: 40), + routeKey: routeKey, + provider: provider, + stopId: 100100128221, + ); + + void seed({ + List profiles = const [], + bool notifications = false, + }) { + SharedPreferences.setMockInitialValues({ + 'flutter.route_usage_profiles': jsonEncode([ + for (final profile in profiles) profile.toJson(), + ]), + 'flutter.app_settings': jsonEncode({ + ...AppSettings.defaults().toJson(), + 'enableSmartRouteNotifications': notifications, + }), + }); + } + + Future?> storedPlan() async { + final raw = (await SharedPreferences.getInstance()).getString( + 'smart_route_plan', + ); + return raw == null ? null : jsonDecode(raw) as Map; + } + + Future start(_Repository repository) async { + final controller = await createAdTestController(repository: repository); + addTearDown(controller.dispose); + await controller.initializeForFirstFrame(); + return controller; + } + + List syncedStates() => [ + for (final call in homeCalls) + if (call.method == 'setSmartRouteNotificationsEnabled') + (call.arguments as Map)['enabled'], + ]; + + setUp(() { + homeCalls = []; + debugDefaultTargetPlatformOverride = TargetPlatform.android; + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + return null; + }); + }); + + tearDown(() { + messenger.setMockMethodCallHandler(_homeChannel, null); + debugDefaultTargetPlatformOverride = null; + }); + + test( + 'turning reminders on writes the plan before the worker is told', + () async { + seed(profiles: [commute()]); + final repository = _Repository(); + final controller = await start(repository); + Map? planWhenScheduled; + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + if (call.method == 'setSmartRouteNotificationsEnabled') { + planWhenScheduled = await storedPlan(); + } + return null; + }); + + await controller.updateEnableSmartRouteNotifications(true); + + // The scheduler decides whether to run by reading the plan, so it has to + // be there already. + expect(planWhenScheduled, isNotNull); + expect(syncedStates(), [true]); + final plan = (await storedPlan())!; + expect(plan['version'], 1); + expect(plan['dayStartHour'], 4); + final slots = (plan['slots'] as List).cast>(); + expect(slots.map((slot) => slot['weekday']).toSet(), {1, 2, 3, 4, 5}); + for (final slot in slots) { + expect(slot['provider'], 'khh'); + expect(slot['routeKey'], 101); + expect(slot['routeId'], 'KHH101'); + expect(slot['pathId'], 0); + expect(slot['peakMinute'], 220); + expect(slot['stopId'], 100100128221); + } + expect(repository.lookups, ['khh:101']); + }, + ); + + test('turning reminders off removes the plan', () async { + seed(profiles: [commute()], notifications: true); + final controller = await start(_Repository()); + await controller.updateEnableSmartRouteNotifications(true); + expect(await storedPlan(), isNotNull); + + await controller.updateEnableSmartRouteNotifications(false); + + expect(await storedPlan(), isNull); + expect(syncedStates(), [true, false]); + }); + + test( + 'a route id is looked up once, and only for routes with a habit', + () async { + seed( + profiles: [ + commute(), + commute(routeKey: 202, provider: BusProvider.tpe), + // Opened on two days only: not worth a lookup. + profileWithVisits( + daysBefore(DateTime.now(), count: 2, hour: 9, minute: 0), + routeKey: 303, + provider: BusProvider.khh, + ), + ], + notifications: true, + ); + final repository = _Repository(); + final controller = await start(repository); + + await controller.updateEnableSmartRouteNotifications(true); + await controller.updateEnableSmartRouteNotifications(true); + + expect(repository.lookups, unorderedEquals(['khh:101', 'tpe:202'])); + final slots = ((await storedPlan())!['slots'] as List) + .cast>(); + expect(slots.map((slot) => slot['routeId']).toSet(), { + 'KHH101', + 'TPE202', + }); + }, + ); + + test( + 'a route the database cannot name is left out and asked about again', + () async { + seed(profiles: [commute(routeKey: 404), commute()], notifications: true); + final repository = _Repository(); + final controller = await start(repository); + + await controller.updateEnableSmartRouteNotifications(true); + await controller.updateEnableSmartRouteNotifications(true); + + final slots = ((await storedPlan())!['slots'] as List) + .cast>(); + expect(slots.map((slot) => slot['routeKey']).toSet(), {101}); + expect(repository.lookups, ['khh:101,404', 'khh:404']); + }, + ); + + test( + 'a missing database leaves an empty plan rather than an error', + () async { + seed(profiles: [commute()], notifications: true); + final repository = _Repository()..databaseMissing = true; + final controller = await start(repository); + + await controller.updateEnableSmartRouteNotifications(true); + + expect((await storedPlan())!['slots'], isEmpty); + expect(syncedStates(), [true]); + }, + ); + + test('a visit is remembered with its stop and refreshes the plan', () async { + seed(profiles: [commute()], notifications: true); + final controller = await start(_Repository()); + await controller.updateEnableSmartRouteNotifications(true); + final before = (await storedPlan())!; + final openedAt = DateTime.now(); + + await controller.recordRouteVisit( + const RouteSummary( + sourceProvider: 'khh', + hashMd5: '', + routeKey: 101, + routeId: 'KHH101', + routeName: '307', + officialRouteName: '307', + description: '', + category: '', + sequence: 0, + rtrip: 0, + ), + provider: BusProvider.khh, + pathId: 0, + stopId: 2002, + openedAt: openedAt, + ); + + final visit = controller.routeUsageProfiles.single.visits.last; + expect(visit.atMs, openedAt.millisecondsSinceEpoch); + expect(visit.stopId, 2002); + final after = (await storedPlan())!; + expect( + after['generatedAtMs'], + greaterThanOrEqualTo(before['generatedAtMs']), + ); + // The worker reads this to know the route has just been looked at. + expect( + ((after['slots'] as List).cast>()) + .map((slot) => slot['lastActivityAtMs']) + .toSet(), + {openedAt.millisecondsSinceEpoch}, + ); + expect(syncedStates(), [true, true]); + }); + + test('a first visit to a route starts its history with that visit', () async { + seed(); + final controller = await start(_Repository()); + final openedAt = DateTime(2026, 4, 8, 7, 40); + + await controller.recordRouteVisit( + const RouteSummary( + sourceProvider: 'khh', + hashMd5: '', + routeKey: 55, + routeId: 'KHH55', + routeName: '紅12', + officialRouteName: '紅12', + description: '', + category: '', + sequence: 0, + rtrip: 0, + ), + provider: BusProvider.khh, + pathId: 1, + stopId: 3003, + openedAt: openedAt, + ); + + final profile = controller.routeUsageProfiles.single; + expect(profile.routeName, '紅12'); + expect(profile.totalOpens, 1); + expect(profile.lastOpenedAtMs, openedAt.millisecondsSinceEpoch); + expect(profile.hourlyOpens, {7: 1}); + expect(profile.visits.single.atMs, openedAt.millisecondsSinceEpoch); + expect(profile.visits.single.stopId, 3003); + // Nothing here predates visit history, so the counters are not consulted. + expect(profile.legacyAsOfMs, isNull); + }); + + test( + 'reminders the worker has shown are read before the plan is made', + () async { + // Opened on three weekdays, then not on the five since: left at that, + // a habit that has all but stopped. + final recent = daysBefore(DateTime.now(), count: 8, hour: 7, minute: 40); + seed( + profiles: [ + profileWithVisits(recent.take(3), provider: BusProvider.khh), + ], + notifications: true, + ); + final controller = await start(_Repository()); + await controller.updateEnableSmartRouteNotifications(true); + final slotsUnreminded = ((await storedPlan())!['slots'] as List).length; + + // The same five days, had a reminder gone out on each of them. + final log = jsonEncode([ + for (final day in recent.skip(3)) + { + 'provider': 'khh', + 'routeKey': 101, + 'pathId': 0, + 'atMs': DateTime( + day.year, + day.month, + day.day, + 7, + 28, + ).millisecondsSinceEpoch, + 'peakMinute': 220, + }, + ]); + homeCalls.clear(); + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + return call.method == 'getSmartRouteReminderLog' ? log : null; + }); + await controller.updateEnableSmartRouteNotifications(true); + + expect( + [ + for (final call in homeCalls) + if (call.method == 'getSmartRouteReminderLog' || + call.method == 'setSmartRouteNotificationsEnabled') + call.method, + ], + ['getSmartRouteReminderLog', 'setSmartRouteNotificationsEnabled'], + ); + expect( + ((await storedPlan())!['slots'] as List).length, + greaterThan(slotsUnreminded), + ); + }, + ); + + test( + 'a worker that cannot say what it showed does not hold the plan up', + () async { + seed(profiles: [commute()], notifications: true); + final controller = await start(_Repository()); + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + if (call.method == 'getSmartRouteReminderLog') { + throw PlatformException(code: 'unavailable'); + } + return null; + }); + + await controller.updateEnableSmartRouteNotifications(true); + + expect((await storedPlan())!['slots'], isNotEmpty); + expect(syncedStates(), [true]); + }, + ); + + test( + 'clearing what was learned clears the reminders that came of it', + () async { + seed(profiles: [commute()], notifications: true); + final controller = await start(_Repository()); + await controller.updateEnableSmartRouteNotifications(true); + expect((await storedPlan())!['slots'], isNotEmpty); + homeCalls.clear(); + + await controller.clearRouteUsageProfiles(); + + expect(controller.routeUsageProfiles, isEmpty); + expect((await storedPlan())!['slots'], isEmpty); + expect( + homeCalls.map((call) => call.method), + contains('forgetSmartRouteReminders'), + ); + }, + ); + + test('where there is no background check, no plan is written', () async { + debugDefaultTargetPlatformOverride = TargetPlatform.iOS; + seed(profiles: [commute()], notifications: true); + final repository = _Repository(); + final controller = await start(repository); + + await controller.updateEnableSmartRouteNotifications(true); + + expect(await storedPlan(), isNull); + expect(repository.lookups, isEmpty); + + await controller.clearRouteUsageProfiles(); + + expect(homeCalls, isEmpty); + }); +} diff --git a/test/smart_route_plan_test.dart b/test/smart_route_plan_test.dart new file mode 100644 index 00000000..77b9b73d --- /dev/null +++ b/test/smart_route_plan_test.dart @@ -0,0 +1,501 @@ +import 'dart:convert'; +import 'dart:io'; + +import 'package:flutter_test/flutter_test.dart'; +import 'package:taiwanbus_flutter/core/models.dart'; +import 'package:taiwanbus_flutter/core/smart_route_plan.dart'; + +import 'support/route_usage_fixtures.dart'; + +void main() { + // 2026-04-08 is a Wednesday. + final wednesdayEarly = DateTime(2026, 4, 8, 6); + + String? routeIdOf(RouteUsageProfile profile) => 'KHH${profile.routeKey}'; + + RouteUsageProfile commute({int? stopId, DateTime? before}) => + profileWithVisits( + daysBefore(before ?? wednesdayEarly, count: 15, hour: 7, minute: 40), + stopId: stopId, + ); + + test('a weekday commute is planned for weekdays, around its usual time', () { + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [commute(stopId: 1001)], + now: wednesdayEarly, + ); + + expect(plan.slots.map((slot) => slot.weekday), [ + DateTime.monday, + DateTime.tuesday, + DateTime.wednesday, + DateTime.thursday, + DateTime.friday, + ]); + for (final slot in plan.slots) { + // 07:10 to 08:10, in minutes since 04:00. + expect(slot.startMinute, 190); + expect(slot.endMinute, 250); + expect(slot.peakMinute, 220); + expect(slot.confidence, greaterThan(0.85)); + expect(slot.supportDays, 15); + expect(slot.stopId, 1001); + expect(slot.routeKey, 101); + expect(slot.routeId, 'KHH101'); + expect(slot.pathId, 0); + } + expect(plan.generatedAtMs, wednesdayEarly.millisecondsSinceEpoch); + }); + + test('a slot expires two weeks after the habit was last seen', () { + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [commute()], + now: wednesdayEarly, + ); + + // Last seen on Tuesday the 7th; good through the service day of the 21st, + // which ends at 04:00 on the 22nd. + expect(plan.slots.map((slot) => slot.validUntilMs).toSet(), { + DateTime(2026, 4, 22, 4).millisecondsSinceEpoch, + }); + expect(plan.slots.map((slot) => slot.lastActivityAtMs).toSet(), { + DateTime(2026, 4, 7, 7, 40).millisecondsSinceEpoch, + }); + }); + + test('two days of use are not enough to interrupt anyone', () { + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [ + profileWithVisits( + daysBefore(wednesdayEarly, count: 2, hour: 7, minute: 40), + ), + ], + now: wednesdayEarly, + ); + + expect(plan.slots, isEmpty); + }); + + test('a use this morning counts toward tomorrow, not toward today', () { + final afterTodaysRide = DateTime(2026, 4, 8, 9); + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [ + profileWithVisits([ + DateTime(2026, 4, 6, 7, 40), + DateTime(2026, 4, 7, 7, 40), + DateTime(2026, 4, 8, 7, 40), + ]), + ], + now: afterTodaysRide, + ); + + expect(plan.slots.map((slot) => slot.weekday), [ + DateTime.monday, + DateTime.tuesday, + DateTime.thursday, + DateTime.friday, + ]); + expect(plan.slots.map((slot) => slot.supportDays).toSet(), {3}); + }); + + test('separate habits on one route get separate windows', () { + final now = DateTime(2026, 4, 8, 5); + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [ + profileWithVisits([ + ...daysBefore(now, count: 10, hour: 7, minute: 40), + ...daysBefore(now, count: 10, hour: 18, minute: 10), + ]), + ], + now: now, + ); + + final wednesday = plan.slots + .where((slot) => slot.weekday == DateTime.wednesday) + .toList(); + expect(wednesday.map((slot) => slot.peakMinute), [ + // 07:40 and 18:10. + 220, + 850, + ]); + expect(wednesday.first.endMinute, lessThan(wednesday.last.startMinute)); + }); + + test('a route that cannot be named is left out', () { + final plan = SmartRoutePlanner.build( + profiles: [ + commute(), + profileWithVisits( + daysBefore(wednesdayEarly, count: 15, hour: 9, minute: 0), + routeKey: 303, + ), + ], + routeIdOf: (profile) => profile.routeKey == 303 ? ' ' : 'KHH101', + now: wednesdayEarly, + ); + + expect(plan.slots.map((slot) => slot.routeKey).toSet(), {101}); + }); + + test('says which routes are worth looking a route id up for', () { + expect(SmartRoutePlanner.isCandidate(commute(), wednesdayEarly), isTrue); + expect( + SmartRoutePlanner.isCandidate( + profileWithVisits( + daysBefore(wednesdayEarly, count: 2, hour: 7, minute: 40), + ), + wednesdayEarly, + ), + isFalse, + ); + expect( + SmartRoutePlanner.isCandidate( + profileWithVisits( + daysBefore(wednesdayEarly, count: 15, hour: 7, minute: 40), + pathId: null, + ), + wednesdayEarly, + ), + isFalse, + ); + }); + + test('routes without a direction, and repeats, are left out', () { + final plan = SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [ + profileWithVisits( + daysBefore(wednesdayEarly, count: 15, hour: 7, minute: 40), + pathId: null, + ), + commute(), + commute(), + ], + now: wednesdayEarly, + ); + + expect(plan.slots, hasLength(5)); + }); + + test('the stop is the one in use at the time of the window', () { + final now = DateTime(2026, 4, 8, 5); + var profile = profileWithVisits( + daysBefore(now, count: 10, hour: 7, minute: 40), + stopId: 1001, + ); + for (final visit in daysBefore(now, count: 10, hour: 18, minute: 10)) { + profile = profile.recordOpen(visit, stopId: 2002); + } + + final plan = SmartRoutePlanner.build( + profiles: [profile], + routeIdOf: routeIdOf, + now: now, + ); + + final wednesday = plan.slots + .where((slot) => slot.weekday == DateTime.wednesday) + .toList(); + expect(wednesday.map((slot) => slot.stopId), [1001, 2002]); + }); + + test('keeps the most confident slots when there are too many', () { + final now = DateTime(2026, 4, 8, 5); + final profiles = [ + // Fifteen daily routes, each with five weekday slots: 75 in all. + for (var index = 0; index < 15; index++) + profileWithVisits( + daysBefore( + now, + count: index < 3 ? 15 : 4, + hour: 6 + index, + minute: 0, + ), + routeKey: 100 + index, + ), + ]; + + final plan = SmartRoutePlanner.build( + profiles: profiles, + routeIdOf: routeIdOf, + now: now, + ); + + expect(plan.slots, hasLength(SmartRoutePlanner.maxSlots)); + // The three routes with the longest record keep every one of theirs. + for (final routeKey in [100, 101, 102]) { + expect(plan.slots.where((slot) => slot.routeKey == routeKey).length, 5); + } + }); + + test('a plan drawn up before the usual time does not count today out', () { + // An evening trip made on Monday, Tuesday and Wednesday. On Thursday + // morning the evening is still to come; by Thursday night it was missed. + final newHabit = profileWithVisits([ + DateTime(2026, 4, 6, 18, 10), + DateTime(2026, 4, 7, 18, 10), + DateTime(2026, 4, 8, 18, 10), + ]); + Set weekdaysPlannedAt(DateTime now) => SmartRoutePlanner.build( + profiles: [newHabit], + routeIdOf: routeIdOf, + now: now, + ).slots.map((slot) => slot.weekday).toSet(); + + expect(weekdaysPlannedAt(DateTime(2026, 4, 9, 7, 40)), {1, 2, 3, 4, 5}); + expect(weekdaysPlannedAt(DateTime(2026, 4, 9, 21)), {1, 2, 3, 4}); + }); + + group('reminders already shown', () { + // A commuter who, once reminders began on Monday the 6th, opened the + // route on only three of the weekdays since: the 8th, 14th and 20th. + final commuter = profileWithVisits([ + ...daysBefore(DateTime(2026, 4, 4), count: 15, hour: 7, minute: 40), + DateTime(2026, 4, 8, 7, 40), + DateTime(2026, 4, 14, 7, 40), + DateTime(2026, 4, 20, 7, 40), + ]); + // One on every weekday from the 6th up to, but not on, the day of [now]. + List shownBefore( + DateTime now, { + int routeKey = 101, + int pathId = 0, + BusProvider provider = BusProvider.nwt, + }) => [ + for (final day in daysBefore(now, count: 40, hour: 7, minute: 30)) + if (!day.isBefore(DateTime(2026, 4, 6))) + SmartRouteReminder( + provider: provider, + routeKey: routeKey, + pathId: pathId, + atMs: day.millisecondsSinceEpoch, + peakMinute: 220, + ), + ]; + SmartRoutePlan planAt( + DateTime now, { + List reminders = const [], + }) => SmartRoutePlanner.build( + profiles: [commuter], + routeIdOf: routeIdOf, + reminders: reminders, + now: now, + ); + Set weekdays(SmartRoutePlan plan) => + plan.slots.map((slot) => slot.weekday).toSet(); + + final wednesday = DateTime(2026, 4, 22, 6); + + test('keep a habit from fading on the days they did its job', () { + // Read as nine days of staying home, the habit drops below the bar on + // most weekdays; read as nine days of being told, it holds on all five. + expect(weekdays(planAt(wednesday)), {1, 3}); + expect(weekdays(planAt(wednesday, reminders: shownBefore(wednesday))), { + 1, + 2, + 3, + 4, + 5, + }); + }); + + test('do not put off the day an unconfirmed habit lapses', () { + final plan = planAt(wednesday, reminders: shownBefore(wednesday)); + + // Last opened on Monday the 20th, reminders or no: good through the + // service day of May the 4th. + expect(plan.slots.map((slot) => slot.validUntilMs).toSet(), { + DateTime(2026, 5, 5, 4).millisecondsSinceEpoch, + }); + }); + + test('cannot carry a habit past that day', () { + final lastDay = DateTime(2026, 5, 4, 6); + final dayAfter = DateTime(2026, 5, 5, 6); + + // Monday the 4th can still be reminded of; no day after it can, so + // none is planned, however sure the habit looks. + expect(weekdays(planAt(lastDay, reminders: shownBefore(lastDay))), {1}); + expect(planAt(dayAfter, reminders: shownBefore(dayAfter)).slots, isEmpty); + }); + + test('that are tapped do not draw the next one earlier', () { + // Reminded at 07:26 for 07:40 on each of the last ten weekdays, and + // tapped a minute later every time. + final days = daysBefore(wednesday, count: 15, hour: 7, minute: 40); + final answered = days.skip(5).toList(); + final tapper = profileWithVisits([ + ...days.take(5), + for (final day in answered) + DateTime(day.year, day.month, day.day, 7, 27), + ]); + Set peaks({required bool saidWhatFor}) => SmartRoutePlanner.build( + profiles: [tapper], + routeIdOf: routeIdOf, + reminders: [ + for (final day in answered) + SmartRouteReminder( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 0, + atMs: DateTime( + day.year, + day.month, + day.day, + 7, + 26, + ).millisecondsSinceEpoch, + peakMinute: saidWhatFor ? 220 : null, + ), + ], + now: wednesday, + ).slots.map((slot) => slot.peakMinute).toSet(); + + // 07:40 still. Taken at face value the taps say 07:30, the next round + // of reminders would go out for that, and so on down the morning. + expect(peaks(saidWhatFor: true), {220}); + expect(peaks(saidWhatFor: false), {210}); + }); + + test('for another route, direction or city change nothing', () { + final elsewhere = [ + ...shownBefore(wednesday, routeKey: 999), + ...shownBefore(wednesday, pathId: 1), + ...shownBefore(wednesday, provider: BusProvider.tpe), + ]; + + expect( + jsonEncode(planAt(wednesday, reminders: elsewhere).toJson()), + jsonEncode(planAt(wednesday).toJson()), + ); + }); + + test('are read from the log the worker keeps', () { + // The same file SmartRouteReminderRulesTest expects the worker to + // write. If it has to change here, it has to change there. + final reminders = SmartRouteReminder.parseLog( + File( + 'test/fixtures/smart_route_reminder_log_v1.json', + ).readAsStringSync(), + ); + + expect( + reminders.map( + (entry) => ( + entry.provider, + entry.routeKey, + entry.pathId, + entry.atMs, + entry.peakMinute, + ), + ), + [ + (BusProvider.khh, 101, 0, 1775604360000, 220), + (BusProvider.khh, 202, 1, 1775901000000, 840), + ], + ); + }); + + test('are skipped one by one when an entry cannot be read', () { + Map entry([Map changes = const {}]) => { + 'provider': 'nwt', + 'routeKey': 101, + 'pathId': 0, + 'atMs': 1775604360000, + 'peakMinute': 220, + ...changes, + }; + final reminders = SmartRouteReminder.parseLog( + jsonEncode([ + entry(), + entry({'routeKey': '101'}), + entry({'pathId': null}), + entry({'atMs': 0}), + entry({'atMs': 1775604360000.5}), + // Not a name the plan could have written; not anyone's reminder. + entry({'provider': 'twn'}), + entry({'provider': 7}), + 'not an entry', + // What it was for is worth having, but not worth losing it over. + entry({'atMs': 2, 'peakMinute': 1440}), + entry({'atMs': 3, 'peakMinute': -1}), + entry({'atMs': 4})..remove('peakMinute'), + ]), + ); + + expect(reminders.map((entry) => (entry.atMs, entry.peakMinute)), [ + (1775604360000, 220), + (2, null), + (3, null), + (4, null), + ]); + expect(reminders.every((entry) => entry.isFor(commuter)), isTrue); + }); + + test('are none when there is no log to read', () { + expect(SmartRouteReminder.parseLog(null), isEmpty); + expect(SmartRouteReminder.parseLog(''), isEmpty); + expect(SmartRouteReminder.parseLog('[]'), isEmpty); + expect(SmartRouteReminder.parseLog('{"provider": "nwt"}'), isEmpty); + expect(SmartRouteReminder.parseLog('[{'), isEmpty); + }); + }); + + test('matches the shape the Android worker is tested against', () { + // The same file is parsed by SmartRoutePlanTest on the Kotlin side. If + // this test needs the file changed, that reader needs to change with it. + final fixture = + jsonDecode( + File('test/fixtures/smart_route_plan_v1.json').readAsStringSync(), + ) + as Map; + final commuter = profileWithVisits( + daysBefore(wednesdayEarly, count: 15, hour: 7, minute: 40), + provider: BusProvider.khh, + stopId: 100100128221, + ); + final saturdays = profileWithVisits( + [ + for (var week = 1; week <= 4; week++) + DateTime(2026, 4, 11 - week * 7, 18), + ], + routeKey: 202, + pathId: 1, + routeName: '紅12', + provider: BusProvider.khh, + ); + + final plan = + jsonDecode( + jsonEncode( + SmartRoutePlanner.build( + routeIdOf: routeIdOf, + profiles: [commuter, saturdays], + now: wednesdayEarly, + ).toJson(), + ), + ) + as Map; + + // Instants depend on the zone the test runs in; everything else is fixed. + Map withoutInstants(Map source) => { + ...source, + 'generatedAtMs': 0, + 'slots': [ + for (final slot in source['slots'] as List) + { + ...slot as Map, + 'validUntilMs': 0, + 'lastActivityAtMs': 0, + }, + ], + }; + expect(withoutInstants(plan), withoutInstants(fixture)); + expect(plan.keys.toSet(), fixture.keys.toSet()); + }); +} diff --git a/test/smart_route_service_test.dart b/test/smart_route_service_test.dart index 9b0358c0..7445f546 100644 --- a/test/smart_route_service_test.dart +++ b/test/smart_route_service_test.dart @@ -1,9 +1,41 @@ +import 'dart:async'; +import 'dart:convert'; +import 'dart:math' as math; + import 'package:flutter_test/flutter_test.dart'; import 'package:geolocator/geolocator.dart'; import 'package:taiwanbus_flutter/core/bus_repository.dart'; import 'package:taiwanbus_flutter/core/models.dart'; import 'package:taiwanbus_flutter/core/smart_route_service.dart'; +import 'support/route_usage_fixtures.dart'; + +RouteDetailData _detail( + int routeKey, { + BusProvider provider = BusProvider.nwt, + String? routeName, + List paths = const [], + Map> stopsByPath = const {}, +}) { + return RouteDetailData( + route: RouteSummary( + sourceProvider: provider.name, + hashMd5: '', + routeKey: routeKey, + routeId: '$routeKey', + routeName: routeName ?? '$routeKey', + officialRouteName: routeName ?? '$routeKey', + description: '', + category: '', + sequence: 0, + rtrip: 0, + ), + paths: paths, + stopsByPath: stopsByPath, + hasLiveData: true, + ); +} + class _PartiallyFailingRepository extends BusRepository { @override Future getCompleteBusInfo( @@ -15,23 +47,7 @@ class _PartiallyFailingRepository extends BusRepository { if (routeKey == 1) { throw StateError('route unavailable'); } - return RouteDetailData( - route: RouteSummary( - sourceProvider: provider.name, - hashMd5: '', - routeKey: routeKey, - routeId: '$routeKey', - routeName: routeNameHint ?? '$routeKey', - officialRouteName: routeNameHint ?? '$routeKey', - description: '', - category: '', - sequence: 0, - rtrip: 0, - ), - paths: const [], - stopsByPath: const {}, - hasLiveData: true, - ); + return _detail(routeKey, provider: provider, routeName: routeNameHint); } } @@ -46,19 +62,10 @@ class _LastBusRepository extends BusRepository { String? routeNameHint, }) async { requestedRouteKeys.add(routeKey); - return RouteDetailData( - route: RouteSummary( - sourceProvider: provider.name, - hashMd5: '', - routeKey: routeKey, - routeId: '$routeKey', - routeName: routeNameHint ?? '$routeKey', - officialRouteName: routeNameHint ?? '$routeKey', - description: '', - category: '', - sequence: 0, - rtrip: 0, - ), + return _detail( + routeKey, + provider: provider, + routeName: routeNameHint, paths: [PathInfo(routeKey: routeKey, pathId: 0, name: '往測試站')], stopsByPath: { 0: [ @@ -75,289 +82,742 @@ class _LastBusRepository extends BusRepository { ), ], }, - hasLiveData: true, ); } } +/// Holds every request open until [release] is called, so a test can see how +/// many were asked for before the first one came back. +class _GatedRepository extends BusRepository { + final Completer _gate = Completer(); + int inFlight = 0; + int mostInFlight = 0; + + void release() => _gate.complete(); + + @override + Future getCompleteBusInfo( + int routeKey, { + required BusProvider provider, + String? routeIdHint, + String? routeNameHint, + }) async { + inFlight += 1; + if (inFlight > mostInFlight) { + mostInFlight = inFlight; + } + await _gate.future; + inFlight -= 1; + return _detail(routeKey, provider: provider, routeName: routeNameHint); + } +} + +Position _position(double latitude, double longitude) => Position( + latitude: latitude, + longitude: longitude, + timestamp: DateTime(2026, 9, 21), + accuracy: 1, + altitude: 0, + altitudeAccuracy: 0, + heading: 0, + headingAccuracy: 0, + speed: 0, + speedAccuracy: 0, +); + void main() { - test('recordOpen increments total and hourly counters', () { - const profile = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 0, - routeName: '307', - totalOpens: 2, - lastOpenedAtMs: 0, - hourlyOpens: {7: 2}, - ); + // 2026-04-08 is a Wednesday, 2026-04-11 a Saturday. + final wednesdayMorning = DateTime(2026, 4, 8, 7, 20); + final saturdayMorning = DateTime(2026, 4, 11, 7, 20); - final updated = profile.recordOpen( - DateTime(2026, 4, 4, 7, 30), - routeName: '307', - ); + RouteUsageProfile commute({ + int routeKey = 101, + int? pathId = 0, + String routeName = '307', + int days = 10, + int hour = 7, + int minute = 40, + DateTime? before, + int? stopId, + }) => profileWithVisits( + daysBefore( + before ?? wednesdayMorning, + count: days, + hour: hour, + minute: minute, + ), + routeKey: routeKey, + pathId: pathId, + routeName: routeName, + stopId: stopId, + ); - expect(updated.totalOpens, 3); - expect(updated.countAtHour(7), 3); - expect(updated.preferredHour, 7); - }); + group('recording use', () { + test('recordOpen increments total and hourly counters', () { + const profile = RouteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 0, + routeName: '307', + totalOpens: 2, + lastOpenedAtMs: 0, + hourlyOpens: {7: 2}, + ); - test('recordSelection increments selection counters', () { - const profile = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 0, - routeName: '307', - totalOpens: 0, - lastOpenedAtMs: 0, - ); + final updated = profile.recordOpen( + DateTime(2026, 4, 4, 7, 30), + routeName: '307', + ); - final updated = profile.recordSelection( - DateTime(2026, 4, 4, 18, 10), - routeName: '307', - ); + expect(updated.totalOpens, 3); + expect(updated.countAtHour(7), 3); + expect(updated.preferredHour, 7); + expect(updated.visits.single.atMs, updated.lastOpenedAtMs); + }); - final now = DateTime(2026, 4, 4, 18, 10); - expect(updated.totalSelectionsAt(now: now), 1); - expect(updated.selectionCountAtHour(18, now: now), 1); - expect(updated.preferredHourAt(now: now), 18); - }); + test('opens within twenty minutes are one visit', () { + final first = DateTime(2026, 4, 4, 7, 30); + final profile = profileWithVisits([ + first, + first.add(const Duration(minutes: 5)), + first.add(const Duration(minutes: 19)), + first.add(const Duration(minutes: 21)), + ]); - test('recordSelection prunes entries older than seven days', () { - final now = DateTime(2026, 4, 10, 18, 10); - final profile = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 0, - routeName: '307', - totalOpens: 0, - lastOpenedAtMs: 0, - selectionTimestampsMs: [ - now.subtract(const Duration(days: 8)).millisecondsSinceEpoch, - now.subtract(const Duration(days: 2)).millisecondsSinceEpoch, - ], - ); + expect(profile.totalOpens, 4); + expect(profile.visits.map((visit) => visit.atMs), [ + first.millisecondsSinceEpoch, + first.add(const Duration(minutes: 21)).millisecondsSinceEpoch, + ]); + }); - final updated = profile.recordSelection(now, routeName: '307'); + test('a visit takes its stop from whichever open knew it', () { + final first = DateTime(2026, 4, 4, 7, 30); + final profile = profileWithVisits([first]) + .recordOpen(first.add(const Duration(minutes: 2)), stopId: 1001) + .recordOpen(first.add(const Duration(minutes: 4)), stopId: 2002); - expect(updated.totalSelectionsAt(now: now), 2); - expect(updated.selectionCountAtHour(18, now: now), 2); - }); + expect(profile.visits.single.atMs, first.millisecondsSinceEpoch); + expect(profile.visits.single.stopId, 1001); + }); - test('chooseProfileForTime prefers the route used in this time window', () { - const morningRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 101, - pathId: 0, - routeName: '307', - totalOpens: 8, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {7: 5, 8: 2}, - ); - const nightRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 102, - pathId: 0, - routeName: '300', - totalOpens: 20, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {21: 10}, - ); + test('visits older than eight weeks are dropped', () { + final now = DateTime(2026, 4, 8, 7, 40); + final profile = profileWithVisits([ + now.subtract(const Duration(days: 57)), + now.subtract(const Duration(days: 55)), + ]).recordOpen(now); - final result = SmartRouteService.chooseProfileForTime(const [ - morningRoute, - nightRoute, - ], DateTime(2026, 4, 4, 7, 20)); + expect(profile.visits.map((visit) => visit.atMs), [ + now.subtract(const Duration(days: 55)).millisecondsSinceEpoch, + now.millisecondsSinceEpoch, + ]); + }); - expect(result?.routeKey, 101); - }); + test('recordSelection increments selection counters', () { + const profile = RouteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 0, + routeName: '307', + totalOpens: 0, + lastOpenedAtMs: 0, + ); - test('chooseProfileForTime returns null outside learned hours', () { - const morningRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 101, - pathId: 0, - routeName: '307', - totalOpens: 8, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {7: 5, 8: 2}, - ); + final updated = profile.recordSelection( + DateTime(2026, 4, 4, 18, 10), + routeName: '307', + ); - final result = SmartRouteService.chooseProfileForTime(const [ - morningRoute, - ], DateTime(2026, 4, 4, 14, 00)); + final now = DateTime(2026, 4, 4, 18, 10); + expect(updated.totalSelectionsAt(now: now), 1); + expect(updated.selectionCountAtHour(18, now: now), 1); + expect(updated.preferredHourAt(now: now), 18); + }); - expect(result, isNull); - }); + test('recordSelection prunes entries older than seven days', () { + final now = DateTime(2026, 4, 10, 18, 10); + final profile = RouteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 0, + routeName: '307', + totalOpens: 0, + lastOpenedAtMs: 0, + selectionTimestampsMs: [ + now.subtract(const Duration(days: 8)).millisecondsSinceEpoch, + now.subtract(const Duration(days: 2)).millisecondsSinceEpoch, + ], + ); - test('chooseProfileForTime ignores legacy directionless history', () { - const legacyProfile = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 101, - routeName: '307', - totalOpens: 10, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {7: 10}, - ); + final updated = profile.recordSelection(now, routeName: '307'); - final result = SmartRouteService.chooseProfileForTime(const [ - legacyProfile, - ], DateTime(2026, 4, 4, 7, 20)); + expect(updated.totalSelectionsAt(now: now), 2); + expect(updated.selectionCountAtHour(18, now: now), 2); + }); - expect(result, isNull); - }); + test('clearing selections keeps the visits', () { + final now = DateTime.now(); + final profile = profileWithVisits([ + now.subtract(const Duration(days: 1)), + ], stopId: 1001).recordSelection(now); - test('chooseProfileForTime also uses selection history', () { - const selectedRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 202, - pathId: 0, - routeName: '綠3', - totalOpens: 3, - lastOpenedAtMs: 1712000000000, - totalSelections: 4, - lastSelectedAtMs: 1712000000000, - hourlyOpens: {18: 1, 17: 1, 19: 1}, - hourlySelections: {18: 4}, - ); - const weakerRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 303, - pathId: 0, - routeName: '綠5', - totalOpens: 3, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {18: 2, 17: 1}, - ); + final cleared = profile.clearSelections(); - final result = SmartRouteService.chooseProfileForTime(const [ - selectedRoute, - weakerRoute, - ], DateTime(2026, 4, 4, 18, 15)); + expect(cleared.totalSelectionsAt(now: now), 0); + expect(cleared.visits.single.stopId, 1001); + }); - expect(result?.routeKey, 202); - }); + test('visits and their stops survive being saved and loaded', () { + final now = DateTime.now(); + final profile = profileWithVisits([ + now.subtract(const Duration(days: 2)), + now.subtract(const Duration(days: 1)), + ], stopId: 100100128221); - test('chooseProfileForTime ignores expired selection history', () { - final now = DateTime(2026, 4, 10, 18, 15); - final expiredSelectionRoute = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 202, - pathId: 0, - routeName: '綠3', - totalOpens: 3, - lastOpenedAtMs: now - .subtract(const Duration(days: 1)) - .millisecondsSinceEpoch, - hourlyOpens: const {9: 3}, - selectionTimestampsMs: [ - now.subtract(const Duration(days: 8)).millisecondsSinceEpoch, - now - .subtract(const Duration(days: 8, minutes: 5)) - .millisecondsSinceEpoch, - ], - ); + final restored = RouteUsageProfile.fromJson( + jsonDecode(jsonEncode(profile.toJson())) as Map, + ); + + expect( + restored.visits.map((visit) => (visit.atMs, visit.stopId)), + profile.visits.map((visit) => (visit.atMs, visit.stopId)), + ); + expect(restored.legacyAsOfMs, isNull); + }); - final result = SmartRouteService.chooseProfileForTime([ - expiredSelectionRoute, - ], now); + test('a profile saved before visits existed starts from its last open', () { + final lastOpened = DateTime.now().subtract(const Duration(days: 1)); + final restored = RouteUsageProfile.fromJson({ + 'provider': 'nwt', + 'routeKey': 101, + 'pathId': 0, + 'routeName': '307', + 'totalOpens': 8, + 'lastOpenedAtMs': lastOpened.millisecondsSinceEpoch, + 'hourlyOpens': {'7': 6, '8': 2}, + }); - expect(result, isNull); + expect(restored.visits.single.atMs, lastOpened.millisecondsSinceEpoch); + expect(restored.legacyAsOfMs, lastOpened.millisecondsSinceEpoch); + + // Once saved in the new shape it keeps that date rather than moving it + // forward with every later open. + final reopened = RouteUsageProfile.fromJson( + jsonDecode(jsonEncode(restored.recordOpen(DateTime.now()).toJson())) + as Map, + ); + expect(reopened.legacyAsOfMs, lastOpened.millisecondsSinceEpoch); + expect(reopened.visits, hasLength(2)); + }); }); - test('chooseProfileForTime requires enough actual opens', () { - const notLearnedEnough = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 88, - pathId: 0, - routeName: '11', - totalOpens: 1, - lastOpenedAtMs: 1712000000000, - totalSelections: 4, - lastSelectedAtMs: 1712000000000, - hourlyOpens: {7: 1}, - hourlySelections: {7: 4}, - ); + group('choosing a route', () { + test('prefers the route used in this time window', () { + final morningRoute = commute(); + final nightRoute = commute( + routeKey: 102, + routeName: '300', + hour: 21, + minute: 0, + days: 20, + ); - final result = SmartRouteService.chooseProfileForTime(const [ - notLearnedEnough, - ], DateTime(2026, 4, 4, 7, 10)); + final result = SmartRouteService.chooseProfileForTime([ + nightRoute, + morningRoute, + ], wednesdayMorning); - expect(result, isNull); - }); + expect(result?.routeKey, 101); + }); + + test('returns nothing outside learned hours', () { + final result = SmartRouteService.chooseProfileForTime([ + commute(), + ], DateTime(2026, 4, 8, 14)); + + expect(result, isNull); + }); + + test('ignores history that has no direction', () { + final result = SmartRouteService.chooseProfileForTime([ + commute(pathId: null), + ], wednesdayMorning); + + expect(result, isNull); + }); + + test('does not offer a weekday commute on a Saturday', () { + final result = SmartRouteService.chooseProfileForTime([ + commute(before: saturdayMorning), + ], saturdayMorning); - test( - 'chooseFavoriteForRoute prefers the favorite used in this time window', - () { - final now = DateTime(2026, 4, 4, 18, 15); - final routeProfile = RouteUsageProfile( + expect(result, isNull); + }); + + test('does not take one busy morning for a habit', () { + final yesterday = DateTime(2026, 4, 7, 7, 0); + final busyMorning = profileWithVisits([ + for (var index = 0; index < 5; index++) + yesterday.add(Duration(minutes: index * 25)), + ]); + + expect(busyMorning.totalOpens, 5); + expect( + SmartRouteService.chooseProfileForTime([busyMorning], wednesdayMorning), + isNull, + ); + }); + + test('needs the route on two separate days', () { + expect( + SmartRouteService.chooseProfileForTime([ + commute(days: 1), + ], wednesdayMorning), + isNull, + ); + expect( + SmartRouteService.chooseProfileForTime([ + commute(days: 2), + ], wednesdayMorning)?.routeKey, + 101, + ); + }); + + test('also uses selection history', () { + final tapped = RouteUsageProfile( provider: BusProvider.nwt, - routeKey: 12, - pathId: 1, - routeName: '307', - totalOpens: 6, - lastOpenedAtMs: now - .subtract(const Duration(hours: 1)) - .millisecondsSinceEpoch, - hourlyOpens: const {18: 4, 17: 1, 19: 1}, + routeKey: 202, + pathId: 0, + routeName: '綠3', + totalOpens: 0, + lastOpenedAtMs: 0, + selectionTimestampsMs: [ + for (final tap in daysBefore( + wednesdayMorning, + count: 3, + hour: 7, + minute: 30, + )) + tap.millisecondsSinceEpoch, + ], ); - final eveningFavoriteProfile = FavoriteUsageProfile( + + final result = SmartRouteService.chooseProfileForTime([ + tapped, + ], wednesdayMorning); + + expect(result?.routeKey, 202); + }); + + test('ignores expired selection history', () { + final now = DateTime(2026, 4, 10, 18, 15); + final expiredSelectionRoute = RouteUsageProfile( provider: BusProvider.nwt, - routeKey: 12, - pathId: 1, - stopId: 1001, + routeKey: 202, + pathId: 0, + routeName: '綠3', + totalOpens: 3, + lastOpenedAtMs: now + .subtract(const Duration(days: 1)) + .millisecondsSinceEpoch, + hourlyOpens: const {9: 3}, selectionTimestampsMs: [ - now.subtract(const Duration(days: 1)).millisecondsSinceEpoch, + now.subtract(const Duration(days: 8)).millisecondsSinceEpoch, now - .subtract(const Duration(days: 2, minutes: 10)) + .subtract(const Duration(days: 9, minutes: 5)) .millisecondsSinceEpoch, ], ); - final morningFavoriteProfile = FavoriteUsageProfile( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 2, - stopId: 2002, - selectionTimestampsMs: [ - DateTime(2026, 4, 4, 7, 20).millisecondsSinceEpoch, - DateTime(2026, 4, 3, 7, 10).millisecondsSinceEpoch, - DateTime(2026, 4, 2, 7, 0).millisecondsSinceEpoch, - ], + + final result = SmartRouteService.chooseProfileForTime([ + expiredSelectionRoute, + ], now); + + expect(result, isNull); + }); + + test('puts the steadier habit first', () { + final everyWeekday = commute(routeKey: 1, days: 20); + final threeDaysAWeek = profileWithVisits( + daysBefore( + wednesdayMorning, + count: 12, + hour: 7, + minute: 40, + weekdays: const { + DateTime.monday, + DateTime.wednesday, + DateTime.friday, + }, + ), + routeKey: 2, + ); + + final ranked = SmartRouteService.rankProfilesForTime([ + threeDaysAWeek, + everyWeekday, + ], wednesdayMorning); + + expect(ranked.map((entry) => entry.profile.routeKey), [1, 2]); + expect(ranked.first.score, greaterThan(ranked.last.score)); + }); + + test('nudges a route opened a moment ago ahead of an equal habit', () { + final now = DateTime(2026, 4, 8, 7, 45); + final untouched = commute(routeKey: 1, before: now); + final justOpened = commute( + routeKey: 2, + before: now, + ).recordOpen(now.subtract(const Duration(minutes: 5))); + + final ranked = SmartRouteService.rankProfilesForTime([ + untouched, + justOpened, + ], now); + + expect(ranked.map((entry) => entry.profile.routeKey), [2, 1]); + expect( + ranked.first.score - ranked.last.score, + closeTo(SmartRouteService.recentUseBoost * (1 - 5 / 90), 1e-9), + ); + }); + + test('lists a route and direction once', () { + final ranked = SmartRouteService.rankProfilesForTime([ + commute(routeKey: 1, days: 10), + commute(routeKey: 1, days: 6), + commute(routeKey: 1, pathId: 1, days: 8), + ], wednesdayMorning); + + expect( + ranked.map((entry) => (entry.profile.routeKey, entry.profile.pathId)), + [(1, 0), (1, 1)], + ); + expect(ranked.first.estimate.supportDays, 10); + }); + }); + + group('a profile from before visits were kept', () { + RouteUsageProfile legacy({ + required DateTime lastOpened, + Map hourlyOpens = const {'7': 6, '8': 2}, + int totalOpens = 8, + }) => RouteUsageProfile.fromJson({ + 'provider': 'nwt', + 'routeKey': 101, + 'pathId': 0, + 'routeName': '307', + 'totalOpens': totalOpens, + 'lastOpenedAtMs': lastOpened.millisecondsSinceEpoch, + 'hourlyOpens': hourlyOpens, + }); + + // fromJson measures retention against the real clock, so these are placed + // relative to it rather than on a fixed date. + final today = DateTime.now(); + final thisMorning = DateTime(today.year, today.month, today.day, 7, 20); + final yesterdayMorning = thisMorning.subtract( + const Duration(hours: 23, minutes: 50), + ); + + test('is still recommended at the hour it used to be opened', () { + final ranking = SmartRouteService.rankProfile( + legacy(lastOpened: yesterdayMorning), + thisMorning, + ); + + expect(ranking, isNotNull); + expect(ranking!.fromHabit, isFalse); + expect(ranking.score, lessThanOrEqualTo(SmartRouteService.legacyWeight)); + expect(ranking.score, greaterThan(0.2)); + }); + + test('is not recommended at other hours', () { + expect( + SmartRouteService.rankProfile( + legacy(lastOpened: yesterdayMorning), + thisMorning.add(const Duration(hours: 7)), + ), + isNull, ); + }); - final result = SmartRouteService.chooseFavoriteForRoute( - routeProfile: routeProfile, - favoriteProfiles: [eveningFavoriteProfile, morningFavoriteProfile], - favorites: const [ - FavoriteStop( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 1, - stopId: 1001, - destinationPathId: 1, - destinationStopId: 1010, - destinationStopName: '市政府', + test('needs the opens the old rule asked for', () { + expect( + SmartRouteService.rankProfile( + legacy( + lastOpened: yesterdayMorning, + totalOpens: 2, + hourlyOpens: const {'7': 2}, ), - FavoriteStop( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 2, - stopId: 2002, - destinationPathId: 2, - destinationStopId: 2020, - destinationStopName: '捷運站', + thisMorning, + ), + isNull, + ); + expect( + SmartRouteService.rankProfile( + legacy( + lastOpened: yesterdayMorning, + totalOpens: 9, + hourlyOpens: const {'7': 1, '15': 8}, ), - ], - now: now, + thisMorning, + ), + isNull, ); + }); - expect(result?.pathId, 1); - expect(result?.stopId, 1001); - expect(result?.destinationStopId, 1010); - }, - ); + test('is forgotten once its counters are stale', () { + final profile = legacy( + lastOpened: thisMorning.subtract(const Duration(days: 30)), + ); + + // Thirty days is a little over two half-lives. + expect( + SmartRouteService.legacyStrength(profile, thisMorning, datedDays: 0), + closeTo(math.pow(0.5, 30 / 14), 0.005), + ); + expect(SmartRouteService.rankProfile(profile, thisMorning), isNull); + }); + + test('hands over to dated history as it builds up', () { + final profile = legacy(lastOpened: yesterdayMorning); - test('buildSuggestion promotes matched favorite stop', () { + final atFirst = SmartRouteService.legacyStrength( + profile, + thisMorning, + datedDays: 0, + ); + final halfway = SmartRouteService.legacyStrength( + profile, + thisMorning, + datedDays: 3, + ); + final handedOver = SmartRouteService.legacyStrength( + profile, + thisMorning, + datedDays: SmartRouteService.legacyHandoverDays, + ); + + expect(atFirst, greaterThan(0.9)); + expect(halfway, closeTo(atFirst / 2, 1e-9)); + expect(handedOver, 0); + }); + + test('counters alone do not qualify a profile that has visits', () { + // Five opens in one hour on a profile created after visits were kept: + // the counters look like a habit, the visits show it was one morning. + final yesterday = thisMorning.subtract(const Duration(days: 1)); + final busyMorning = profileWithVisits([ + for (var index = 0; index < 5; index++) + yesterday.add(Duration(minutes: index * 2)), + ]); + + expect(busyMorning.countAtHour(7), 5); + expect(busyMorning.legacyAsOfMs, isNull); + expect(SmartRouteService.rankProfile(busyMorning, thisMorning), isNull); + }); + }); + + group('choosing a stop', () { + test( + 'chooseFavoriteForRoute prefers the favorite used in this time window', + () { + final now = DateTime(2026, 4, 4, 18, 15); + final routeProfile = RouteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 1, + routeName: '307', + totalOpens: 6, + lastOpenedAtMs: now + .subtract(const Duration(hours: 1)) + .millisecondsSinceEpoch, + hourlyOpens: const {18: 4, 17: 1, 19: 1}, + ); + final eveningFavoriteProfile = FavoriteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 1, + stopId: 1001, + selectionTimestampsMs: [ + now.subtract(const Duration(days: 1)).millisecondsSinceEpoch, + now + .subtract(const Duration(days: 2, minutes: 10)) + .millisecondsSinceEpoch, + ], + ); + final morningFavoriteProfile = FavoriteUsageProfile( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 2, + stopId: 2002, + selectionTimestampsMs: [ + DateTime(2026, 4, 4, 7, 20).millisecondsSinceEpoch, + DateTime(2026, 4, 3, 7, 10).millisecondsSinceEpoch, + DateTime(2026, 4, 2, 7, 0).millisecondsSinceEpoch, + ], + ); + + final result = SmartRouteService.chooseFavoriteForRoute( + routeProfile: routeProfile, + favoriteProfiles: [eveningFavoriteProfile, morningFavoriteProfile], + favorites: const [ + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 1, + stopId: 1001, + destinationPathId: 1, + destinationStopId: 1010, + destinationStopName: '市政府', + ), + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 2, + stopId: 2002, + destinationPathId: 2, + destinationStopId: 2020, + destinationStopName: '捷運站', + ), + ], + now: now, + ); + + expect(result?.pathId, 1); + expect(result?.stopId, 1001); + expect(result?.destinationStopId, 1010); + }, + ); + + test('learns the stop a route is usually opened at', () { + final profile = profileWithVisits( + daysBefore(wednesdayMorning, count: 4, hour: 7, minute: 40), + stopId: 1001, + ).recordOpen(DateTime(2026, 4, 1, 7, 45), stopId: 2002); + + expect( + SmartRouteService.learnedStopId(profile, DateTime(2026, 4, 8, 7, 40)), + 1001, + ); + }); + + test('learns a different stop for a different time of day', () { + final evening = DateTime(2026, 4, 8, 18, 0); + var profile = commute(stopId: 1001, before: evening); + for (final visit in daysBefore(evening, count: 5, hour: 18, minute: 0)) { + profile = profile.recordOpen(visit, stopId: 2002); + } + + expect( + SmartRouteService.learnedStopId(profile, DateTime(2026, 4, 8, 7, 40)), + 1001, + ); + expect(SmartRouteService.learnedStopId(profile, evening), 2002); + }); + + test('learns no stop from a single day or an even split', () { + final now = DateTime(2026, 4, 8, 7, 40); + final oneDay = profileWithVisits([ + DateTime(2026, 4, 7, 7, 40), + ], stopId: 1001); + var evenSplit = profileWithVisits(const []); + final days = daysBefore(now, count: 6, hour: 7, minute: 40); + for (var index = 0; index < days.length; index++) { + evenSplit = evenSplit.recordOpen( + days[index], + stopId: index.isEven ? 1001 : 2002, + ); + } + + expect(SmartRouteService.learnedStopId(oneDay, now), isNull); + expect(SmartRouteService.learnedStopId(evenSplit, now), isNull); + }); + + group('for a reminder', () { + final at = DateTime(2026, 4, 8, 7, 40); + const favoriteAt3003 = FavoriteStop( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 0, + stopId: 3003, + ); + const favoriteAt4004 = FavoriteStop( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 0, + stopId: 4004, + ); + + test('takes a favorite in use over a learned stop', () { + final result = SmartRouteService.chooseBoardingStopId( + profile: commute(stopId: 1001, before: at), + favoriteProfiles: [ + FavoriteUsageProfile( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 0, + stopId: 3003, + selectionTimestampsMs: [ + at.subtract(const Duration(days: 1)).millisecondsSinceEpoch, + ], + ), + ], + favorites: const [favoriteAt3003], + at: at, + ); + + expect(result, 3003); + }); + + test('takes a learned stop over a favorite nobody is using', () { + final result = SmartRouteService.chooseBoardingStopId( + profile: commute(stopId: 1001, before: at), + favoriteProfiles: const [], + favorites: const [favoriteAt3003], + at: at, + ); + + expect(result, 1001); + }); + + test('falls back to the only saved stop on the direction', () { + expect( + SmartRouteService.chooseBoardingStopId( + profile: commute(before: at), + favoriteProfiles: const [], + favorites: const [ + favoriteAt3003, + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 1, + stopId: 5005, + ), + ], + at: at, + ), + 3003, + ); + }); + + test('does not guess between two saved stops', () { + expect( + SmartRouteService.chooseBoardingStopId( + profile: commute(before: at), + favoriteProfiles: const [], + favorites: const [favoriteAt3003, favoriteAt4004], + at: at, + ), + isNull, + ); + }); + }); + }); + + group('buildSuggestion', () { const profile = RouteUsageProfile( provider: BusProvider.nwt, routeKey: 12, @@ -367,290 +827,310 @@ void main() { lastOpenedAtMs: 1712000000000, hourlyOpens: {18: 5}, ); - const favorite = FavoriteStop( - provider: BusProvider.nwt, + + // Three stops up one road, about 220 m and then 2 km apart. + const usualStop = StopInfo( routeKey: 12, pathId: 1, stopId: 1001, - destinationPathId: 1, - destinationStopId: 1010, - destinationStopName: '市政府', + stopName: '常用站', + sequence: 1, + lon: 121.565, + lat: 25.040, + sec: 120, ); - const detail = RouteDetailData( - route: RouteSummary( - sourceProvider: 'nwt', - hashMd5: '', - routeKey: 12, - routeId: '307', - routeName: '307', - officialRouteName: '307', - description: '忠孝幹線', - category: '', - sequence: 0, - rtrip: 0, - ), - paths: [PathInfo(routeKey: 12, pathId: 1, name: '往市政府')], - stopsByPath: { - 1: [ - StopInfo( - routeKey: 12, - pathId: 1, - stopId: 1001, - stopName: '捷運國父紀念館站', - sequence: 1, - lon: 121.553, - lat: 25.041, - sec: 120, - ), - ], + const nextStop = StopInfo( + routeKey: 12, + pathId: 1, + stopId: 1002, + stopName: '下一站', + sequence: 2, + lon: 121.565, + lat: 25.042, + sec: 180, + ); + const farStop = StopInfo( + routeKey: 12, + pathId: 1, + stopId: 1003, + stopName: '遠方站', + sequence: 3, + lon: 121.565, + lat: 25.060, + sec: 600, + ); + final roadDetail = _detail( + 12, + routeName: '307', + paths: const [PathInfo(routeKey: 12, pathId: 1, name: '往市政府')], + stopsByPath: const { + 1: [usualStop, nextStop, farStop], }, - hasLiveData: true, ); - final suggestion = SmartRouteService.buildSuggestion( + SmartRouteSuggestion build({ + RouteDetailData? detail, + FavoriteStop? favorite, + Position? position, + int? learnedStopId, + List routeFavorites = const [], + }) => SmartRouteService.buildSuggestion( profile: profile, score: 12, reason: '根據使用習慣。', - detail: detail, + detail: detail ?? roadDetail, favorite: favorite, + position: position, + learnedStopId: learnedStopId, + routeFavorites: routeFavorites, ); - expect(suggestion.favorite?.stopId, 1001); - expect(suggestion.favorite?.destinationStopId, 1010); - expect(suggestion.recommendedStop?.stopId, 1001); - expect(suggestion.recommendedPath?.pathId, 1); - }); - - test( - 'buildSuggestion includes the nearest stop when location is available', - () { - const profile = RouteUsageProfile( + test('promotes matched favorite stop', () { + const favorite = FavoriteStop( provider: BusProvider.nwt, routeKey: 12, pathId: 1, + stopId: 1001, + destinationPathId: 1, + destinationStopId: 1010, + destinationStopName: '市政府', + ); + + final suggestion = build(favorite: favorite, learnedStopId: 1002); + + expect(suggestion.favorite?.stopId, 1001); + expect(suggestion.favorite?.destinationStopId, 1010); + expect(suggestion.recommendedStop?.stopId, 1001); + expect(suggestion.recommendedPath?.pathId, 1); + }); + + test('includes the nearest stop when location is available', () { + final suggestion = build(position: _position(25.0421, 121.5651)); + + expect(suggestion.recommendedStop?.stopName, '下一站'); + expect(suggestion.recommendedPath?.pathId, 1); + expect(suggestion.distanceMeters, lessThan(50)); + }); + + test('only searches the learned direction', () { + final detail = _detail( + 12, routeName: '307', - totalOpens: 5, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {18: 5}, - ); - const detail = RouteDetailData( - route: RouteSummary( - sourceProvider: 'nwt', - hashMd5: '', - routeKey: 12, - routeId: '307', - routeName: '307', - officialRouteName: '307', - description: '', - category: '', - sequence: 0, - rtrip: 0, - ), - paths: [PathInfo(routeKey: 12, pathId: 1, name: '往市政府')], - stopsByPath: { - 1: [ + paths: const [ + PathInfo(routeKey: 12, pathId: 0, name: '往反方向'), + PathInfo(routeKey: 12, pathId: 1, name: '往市政府'), + ], + stopsByPath: const { + 0: [ StopInfo( routeKey: 12, - pathId: 1, - stopId: 1001, - stopName: '最近站牌', + pathId: 0, + stopId: 1, + stopName: '較近但方向錯誤', sequence: 1, - lon: 121.5654, - lat: 25.033, - sec: 120, + lon: 121.5655, + lat: 25.0331, + sec: 60, ), + ], + 1: [ StopInfo( routeKey: 12, pathId: 1, - stopId: 1002, - stopName: '較遠站牌', - sequence: 2, - lon: 121.6, - lat: 25.06, - sec: 300, + stopId: 2, + stopName: '正確方向', + sequence: 1, + lon: 121.57, + lat: 25.04, + sec: 120, ), ], }, - hasLiveData: true, - ); - final position = Position( - latitude: 25.0331, - longitude: 121.5655, - timestamp: DateTime(2026, 9, 21), - accuracy: 1, - altitude: 0, - altitudeAccuracy: 0, - heading: 0, - headingAccuracy: 0, - speed: 0, - speedAccuracy: 0, - ); - - final suggestion = SmartRouteService.buildSuggestion( - profile: profile, - score: 12, - reason: '根據使用習慣。', + ); + + final suggestion = build( detail: detail, - position: position, + position: _position(25.0331, 121.5655), ); - expect(suggestion.recommendedStop?.stopName, '最近站牌'); expect(suggestion.recommendedPath?.pathId, 1); - }, - ); + expect(suggestion.recommendedStop?.stopId, 2); + }); - test('buildSuggestion only searches the learned direction', () { - const profile = RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 12, - pathId: 1, - routeName: '307', - totalOpens: 5, - lastOpenedAtMs: 1712000000000, - hourlyOpens: {18: 5}, - ); - const detail = RouteDetailData( - route: RouteSummary( - sourceProvider: 'nwt', - hashMd5: '', + test('shows the usual stop when the position is unknown', () { + final suggestion = build(learnedStopId: 1001); + + expect(suggestion.recommendedStop?.stopId, 1001); + expect(suggestion.favorite, isNull); + expect(suggestion.distanceMeters, isNull); + }); + + test('keeps the usual stop when another is nearer but it is in reach', () { + // Standing at the next stop, 220 m from the usual one. + final suggestion = build( + learnedStopId: 1001, + position: _position(25.042, 121.565), + ); + + expect(suggestion.nearestStop?.stopId, 1002); + expect(suggestion.recommendedStop?.stopId, 1001); + expect(suggestion.distanceMeters, closeTo(222, 5)); + }); + + test('shows the stop the rider is at when the usual one is far off', () { + final suggestion = build( + learnedStopId: 1001, + position: _position(25.0601, 121.565), + ); + + expect(suggestion.recommendedStop?.stopId, 1003); + expect(suggestion.learnedStop, isNull); + expect(suggestion.distanceMeters, lessThan(50)); + }); + + test('keeps the usual stop when the rider is at no stop at all', () { + // A kilometre past the far stop: nowhere near any of them. + final suggestion = build( + learnedStopId: 1001, + position: _position(25.070, 121.565), + ); + + expect(suggestion.nearestStop?.stopId, 1003); + expect(suggestion.recommendedStop?.stopId, 1001); + }); + + test('ignores a learned stop that is not on this direction', () { + final suggestion = build( + learnedStopId: 9999, + position: _position(25.0421, 121.5651), + ); + + expect(suggestion.learnedStop, isNull); + expect(suggestion.recommendedStop?.stopId, 1002); + }); + + test('shows a saved stop nobody has used lately as a plain stop', () { + const saved = FavoriteStop( + provider: BusProvider.nwt, routeKey: 12, - routeId: '307', - routeName: '307', - officialRouteName: '307', - description: '', - category: '', - sequence: 0, - rtrip: 0, - ), - paths: [ - PathInfo(routeKey: 12, pathId: 0, name: '往反方向'), - PathInfo(routeKey: 12, pathId: 1, name: '往市政府'), - ], - stopsByPath: { - 0: [ - StopInfo( - routeKey: 12, - pathId: 0, - stopId: 1, - stopName: '較近但方向錯誤', - sequence: 1, - lon: 121.5655, - lat: 25.0331, - sec: 60, - ), - ], - 1: [ - StopInfo( - routeKey: 12, - pathId: 1, - stopId: 2, - stopName: '正確方向', - sequence: 1, - lon: 121.57, - lat: 25.04, - sec: 120, - ), - ], - }, - hasLiveData: true, - ); - final position = Position( - latitude: 25.0331, - longitude: 121.5655, - timestamp: DateTime(2026, 9, 21), - accuracy: 1, - altitude: 0, - altitudeAccuracy: 0, - heading: 0, - headingAccuracy: 0, - speed: 0, - speedAccuracy: 0, - ); + pathId: 1, + stopId: 1002, + destinationPathId: 1, + destinationStopId: 1003, + ); - final suggestion = SmartRouteService.buildSuggestion( - profile: profile, - score: 12, - reason: '根據使用習慣。', - detail: detail, - position: position, - ); + final suggestion = build(routeFavorites: const [saved]); + + expect(suggestion.recommendedStop?.stopId, 1002); + // Not offered as the favorite: that would carry its destination along. + expect(suggestion.favorite, isNull); + expect(suggestion.favoriteStop, isNull); + }); + + test('picks the closest of several saved stops, or none without a fix', () { + const savedStops = [ + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 1, + stopId: 1001, + ), + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 1, + stopId: 1003, + ), + // The other direction's saved stop must not be considered. + FavoriteStop( + provider: BusProvider.nwt, + routeKey: 12, + pathId: 0, + stopId: 1002, + ), + ]; + + final withoutFix = build(routeFavorites: savedStops); + final nearFarStop = build( + routeFavorites: savedStops, + position: _position(25.066, 121.565), + ); - expect(suggestion.recommendedPath?.pathId, 1); - expect(suggestion.recommendedStop?.stopId, 2); + expect(withoutFix.recommendedStop, isNull); + expect(nearFarStop.recommendedStop?.stopId, 1003); + }); }); - test( - 'loadSuggestions keeps successful routes when one route fails', - () async { - final now = DateTime(2026, 9, 21, 8); + group('loadSuggestions', () { + final now = DateTime(2026, 9, 21, 8); + + RouteUsageProfile used(int routeKey, int days) => profileWithVisits( + daysBefore(now, count: days, hour: 8, minute: 0), + routeKey: routeKey, + routeName: '$routeKey', + ); + + test('keeps successful routes when one route fails', () async { final suggestions = await SmartRouteService.loadSuggestions( repository: _PartiallyFailingRepository(), - profiles: [ - RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 1, - pathId: 0, - routeName: '失敗路線', - totalOpens: 4, - lastOpenedAtMs: now.millisecondsSinceEpoch, - hourlyOpens: const {8: 4}, - ), - RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: 2, - pathId: 0, - routeName: '成功路線', - totalOpens: 3, - lastOpenedAtMs: now.millisecondsSinceEpoch, - hourlyOpens: const {8: 3}, - ), - ], + profiles: [used(1, 10), used(2, 5)], now: now, limit: 1, ); expect(suggestions, hasLength(1)); expect(suggestions.single.profile.routeKey, 2); - }, - ); + }); - test( - 'loadSuggestions skips duplicate last-bus candidates and fills limit', - () async { - final now = DateTime(2026, 9, 21, 8); + test('skips duplicate last-bus candidates and fills limit', () async { final repository = _LastBusRepository(); - final position = Position( - latitude: 25.0331, - longitude: 121.5655, - timestamp: now, - accuracy: 1, - altitude: 0, - altitudeAccuracy: 0, - heading: 0, - headingAccuracy: 0, - speed: 0, - speedAccuracy: 0, - ); - RouteUsageProfile profile(int routeKey, int opens) => RouteUsageProfile( - provider: BusProvider.nwt, - routeKey: routeKey, - pathId: 0, - routeName: '$routeKey', - totalOpens: opens, - lastOpenedAtMs: now.millisecondsSinceEpoch, - hourlyOpens: {8: opens}, - ); final suggestions = await SmartRouteService.loadSuggestions( repository: repository, - profiles: [profile(1, 5), profile(1, 4), profile(2, 3)], + profiles: [used(1, 10), used(1, 8), used(2, 5)], now: now, - position: position, + position: _position(25.0331, 121.5655), limit: 1, ); expect(suggestions.single.profile.routeKey, 2); expect(repository.requestedRouteKeys, [1, 2]); - }, - ); + }); + + test('asks for the top routes together, and no more of them', () async { + final repository = _GatedRepository(); + + final pending = SmartRouteService.loadSuggestions( + repository: repository, + profiles: [used(1, 10), used(2, 8), used(3, 6), used(4, 4)], + now: now, + limit: 3, + ); + await Future.delayed(Duration.zero); + + expect(repository.inFlight, 3); + + repository.release(); + final suggestions = await pending; + + expect(suggestions.map((entry) => entry.profile.routeKey), [1, 2, 3]); + expect(repository.mostInFlight, 3); + }); + + test('says when the route is usually opened', () async { + final suggestions = await SmartRouteService.loadSuggestions( + repository: _LastBusRepository(), + profiles: [ + profileWithVisits( + daysBefore(now, count: 10, hour: 7, minute: 38), + routeKey: 2, + ), + ], + now: DateTime(2026, 9, 21, 7, 30), + limit: 1, + ); + + expect(suggestions.single.reason, '你平日常在 07:40 左右查看這條路線。'); + }); + }); } diff --git a/test/support/route_usage_fixtures.dart b/test/support/route_usage_fixtures.dart new file mode 100644 index 00000000..c391bef7 --- /dev/null +++ b/test/support/route_usage_fixtures.dart @@ -0,0 +1,50 @@ +import 'package:taiwanbus_flutter/core/models.dart'; + +/// The [count] most recent days before [now] whose weekday is in [weekdays], +/// each at [hour]:[minute], oldest first. Never includes the day of [now]. +List daysBefore( + DateTime now, { + required int count, + required int hour, + required int minute, + Set weekdays = const { + DateTime.monday, + DateTime.tuesday, + DateTime.wednesday, + DateTime.thursday, + DateTime.friday, + }, +}) { + final days = []; + for (var back = 1; days.length < count; back++) { + final day = DateTime(now.year, now.month, now.day - back, hour, minute); + if (weekdays.contains(day.weekday)) { + days.add(day); + } + } + return days.reversed.toList(); +} + +/// A profile whose only history is the given visits, as one written by a +/// version that keeps them would look. +RouteUsageProfile profileWithVisits( + Iterable visits, { + int routeKey = 101, + int? pathId = 0, + String routeName = '307', + BusProvider provider = BusProvider.nwt, + int? stopId, +}) { + var profile = RouteUsageProfile( + provider: provider, + routeKey: routeKey, + pathId: pathId, + routeName: routeName, + totalOpens: 0, + lastOpenedAtMs: 0, + ); + for (final visit in visits.toList()..sort()) { + profile = profile.recordOpen(visit, stopId: stopId); + } + return profile; +} From 7849fc4b87f92e2d2127196bcb511dc467cb8332 Mon Sep 17 00:00:00 2001 From: AvianJay Date: Fri, 20 Nov 2026 00:31:07 +0800 Subject: [PATCH 2/5] fix: address review of smart route reminders - Serialize reminder plan rebuilds; an overtaken rebuild writes nothing, and a failed one leaves no plan rather than an outdated one. - Rebuild the plan after logout, favourite changes and database downloads. - Clearing learned history attempts every step, forgets the reminder log before the rebuild, and reports the first failure at the end. - Clearing selection history also drops the stop of each visit. - A boarding stop the rider picks takes precedence when recording a visit. - Cap plan slots per provider. - Home recommendations read the reminder log as the plan does. - Legacy hourly counters hand over by dated use around the asked time. - Count feed ETAs down from eta_reference_at and reject old references. - Re-read the plan before posting; skip blocked channels and a foreground app without logging a reminder. - Only cancel the periodic work under a lock, from the plan as it is now. --- .../SmartRouteNotificationScheduler.kt | 76 +++- .../flutter/SmartRouteNotificationWorker.kt | 114 +++++- .../flutter/SmartRouteReminderRules.kt | 98 ++++- .../SmartRouteNotificationSchedulerTest.kt | 89 +++++ .../flutter/SmartRouteReminderRulesTest.kt | 111 ++++++ .../flutter/SmartRouteReminderStoreTest.kt | 115 ++++++ lib/core/app_controller.dart | 174 +++++++- lib/core/models.dart | 5 +- lib/core/smart_route_habit.dart | 92 +++++ lib/core/smart_route_plan.dart | 116 ++---- lib/core/smart_route_service.dart | 44 +- lib/screens/route_detail_screen.dart | 84 ++-- test/route_detail_screen_loading_test.dart | 79 ++++ test/smart_route_plan_controller_test.dart | 376 +++++++++++++++++- test/smart_route_plan_test.dart | 36 ++ test/smart_route_service_test.dart | 148 ++++++- 16 files changed, 1547 insertions(+), 210 deletions(-) create mode 100644 android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationSchedulerTest.kt diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt index a13e18f3..2f4d565d 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationScheduler.kt @@ -9,38 +9,70 @@ import androidx.work.WorkManager import java.util.concurrent.TimeUnit object SmartRouteNotificationScheduler { - private const val WORK_NAME = "smart_route_notification_refresh" + /** The name the work is scheduled under. */ + internal const val WORK_NAME = "smart_route_notification_refresh" + + /** + * Held while the plan is read and the work scheduled or cancelled to + * match it, by the app and by the background check alike. + * + * The app writes a plan and only then asks for the work to be synced, so + * a decision taken under this lock from a plan that has since been + * replaced is always followed by one taken from the new plan, and + * WorkManager carries both out in the order they were asked for. Without + * it, a check that read the old plan could cancel the work after the app + * had rescheduled it for the new one. + */ + private val lock = Any() /** * Runs the background check only while there is something for it to do: * the setting is on and the plan still holds a habit that has not lapsed. */ fun sync(context: Context, enabled: Boolean) { - val plan = if (enabled) SmartRouteNotificationSupport.loadPlan(context) else null - if (plan == null || - !SmartRouteReminderRules.hasLiveSlots(plan, System.currentTimeMillis()) - ) { - cancel(context) - return + synchronized(lock) { + val plan = if (enabled) SmartRouteNotificationSupport.loadPlan(context) else null + if (plan == null || + !SmartRouteReminderRules.hasLiveSlots(plan, System.currentTimeMillis()) + ) { + cancelUnlocked(context) + return + } + + val request = PeriodicWorkRequestBuilder( + 15, + TimeUnit.MINUTES, + ).setConstraints( + Constraints.Builder() + .setRequiredNetworkType(NetworkType.CONNECTED) + .build(), + ).build() + + WorkManager.getInstance(context).enqueueUniquePeriodicWork( + WORK_NAME, + ExistingPeriodicWorkPolicy.UPDATE, + request, + ) } + } - val request = PeriodicWorkRequestBuilder( - 15, - TimeUnit.MINUTES, - ).setConstraints( - Constraints.Builder() - .setRequiredNetworkType(NetworkType.CONNECTED) - .build(), - ).build() - - WorkManager.getInstance(context).enqueueUniquePeriodicWork( - WORK_NAME, - ExistingPeriodicWorkPolicy.UPDATE, - request, - ) + /** + * Stops the background check if the plan as it is now has nothing left + * that could fire — not the plan the caller read some time ago, which the + * app may have replaced since with one that does. + */ + fun cancelIfNothingLive(context: Context) { + synchronized(lock) { + val plan = SmartRouteNotificationSupport.loadPlan(context) + if (plan == null || + !SmartRouteReminderRules.hasLiveSlots(plan, System.currentTimeMillis()) + ) { + cancelUnlocked(context) + } + } } - fun cancel(context: Context) { + private fun cancelUnlocked(context: Context) { WorkManager.getInstance(context).cancelUniqueWork(WORK_NAME) } } diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt index 5aa82400..ca39a313 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt @@ -54,8 +54,9 @@ class SmartRouteNotificationWorker( val now = System.currentTimeMillis() if (!SmartRouteReminderRules.hasLiveSlots(plan, now)) { // Every habit in the plan has lapsed. Nothing can fire until - // the app is opened and writes a new one, which reschedules. - SmartRouteNotificationScheduler.cancel(applicationContext) + // the app is opened and writes a new one, which reschedules — + // unless it already has, which this checks under the lock. + SmartRouteNotificationScheduler.cancelIfNothingLive(applicationContext) return Result.success() } val dueSlots = SmartRouteReminderRules.dueSlots(plan, settings.provider, now) @@ -94,32 +95,34 @@ class SmartRouteNotificationWorker( routeId = slot.routeId, pathId = slot.pathId, rawStopId = choice.stop.rawStopId, - nowMs = now, ) ?: continue val decision = SmartRouteReminderRules.decide(liveStop, choice.distanceMeters) ?: continue - SmartRouteNotificationSupport.showNotification( + // Whether or not it went out, this run is done. The next one + // starts again from the plan as it is then. + SmartRouteNotificationSupport.remind( context = applicationContext, slot = slot, stop = choice.stop, - text = SmartRouteReminderRules.buildText( - routeName = slot.routeName, - pathName = routeData.pathName, - stopName = choice.stop.stopName, - decision = decision, - distanceMeters = choice.distanceMeters, - slot = slot, - dayStartHour = plan.dayStartHour, - nowMs = now, - ), + text = { current -> + SmartRouteReminderRules.buildText( + routeName = current.routeName, + pathName = routeData.pathName, + stopName = choice.stop.stopName, + decision = decision, + distanceMeters = choice.distanceMeters, + slot = current, + dayStartHour = plan.dayStartHour, + // The arrival time is counted from when the feed + // was read, which is what its seconds are as of. + nowMs = liveStop.asOfMs, + ) + }, timeoutMs = SmartRouteReminderRules.timeoutMs(decision), - ) - SmartRouteNotificationSupport.saveReminder( - context = applicationContext, - slot = slot, history = SmartRouteReminderRules.afterReminder(history, now, clock.day), nowMs = now, + checkedAtMs = System.currentTimeMillis(), ) break } @@ -147,7 +150,7 @@ internal object SmartRouteNotificationSupport { private const val REMINDER_COUNT_KEY = "reminder_count" private const val LAST_ROUTE_REMINDER_KEY_PREFIX = "last_route_reminder_" private const val REMINDER_LOG_KEY = "reminder_log" - private const val CHANNEL_ID = "smart_route_recommendation" + internal const val CHANNEL_ID = "smart_route_recommendation" private const val CHANNEL_NAME = "智慧推薦提醒" private const val CHANNEL_DESCRIPTION = "在你常查看某條路線的時間點附近,依常用或最近站牌的到站時間主動提醒。" @@ -248,6 +251,49 @@ internal object SmartRouteNotificationSupport { fun loadReminderLog(context: Context): String = notificationPreferences(context).getString(REMINDER_LOG_KEY, null) ?: "[]" + /** + * Shows a reminder for [slot] and records it, against the limits and in + * the log the Flutter side learns from — if it can still go out, and be + * seen, at [checkedAtMs]. + * + * A run reads the plan once and then waits on the location and the + * network, and the app can replace the plan meanwhile: the rider clears + * what it learned, or opens the route. So the plan is read again here, + * and only what it says now goes out; see [SmartRouteReminderRules.stillDue]. + * [text] is written for the slot as that plan has it. + * + * One that cannot be seen — this channel turned off while the app's + * other notifications stay on — is recorded nowhere. The habit model + * reads a logged reminder as one that told the rider what they would + * have opened the route for, and one nobody saw would excuse a day they + * simply did not go. + * + * Returns whether it was shown. + */ + fun remind( + context: Context, + slot: SmartPlanSlot, + stop: SmartRouteStop, + text: (SmartPlanSlot) -> SmartReminderText, + timeoutMs: Long, + history: SmartReminderHistory, + nowMs: Long, + checkedAtMs: Long, + ): Boolean { + val current = SmartRouteReminderRules.stillDue(loadPlan(context), slot, checkedAtMs) + ?: return false + // Opened while this run waited: the rider is looking at the app. + if (AppRuntimeStateStore.isAppInForeground(context)) { + return false + } + if (!canPostNotifications(context)) { + return false + } + showNotification(context, current, stop, text(current), timeoutMs) + saveReminder(context, current, history, nowMs) + return true + } + /** * Drops every trace of reminders already shown: the log, and what holds * the next one back. For when the rider clears what the app has learned @@ -452,11 +498,14 @@ internal object SmartRouteNotificationSupport { return results[0].toDouble() } + /** + * The live state of one stop, counted down to the moment the response + * arrived; see [SmartRouteReminderRules.parseLiveStop]. + */ fun fetchLiveStop( routeId: String, pathId: Int, rawStopId: String, - nowMs: Long, ): SmartLiveStop? { val encodedRouteId = URLEncoder.encode(routeId, Charsets.UTF_8.name()) val connection = try { @@ -480,7 +529,12 @@ internal object SmartRouteNotificationSupport { val jsonText = connection.inputStream.bufferedReader(Charsets.UTF_8).use { reader -> reader.readText() } - SmartRouteReminderRules.parseLiveStop(jsonText, pathId, rawStopId, nowMs) + SmartRouteReminderRules.parseLiveStop( + jsonText, + pathId, + rawStopId, + System.currentTimeMillis(), + ) } } catch (_: Exception) { null @@ -489,6 +543,10 @@ internal object SmartRouteNotificationSupport { } } + /** + * Posts the reminder. Whether it will be seen is for the caller to have + * checked; see [remind]. + */ fun showNotification( context: Context, slot: SmartPlanSlot, @@ -532,8 +590,20 @@ internal object SmartRouteNotificationSupport { ) } + /** + * Whether a reminder posted now would be shown: notifications allowed + * for the app, and this channel not turned off on its own. With the + * channel off the system drops the reminder without a word. + */ fun canPostNotifications(context: Context): Boolean { - if (!NotificationManagerCompat.from(context).areNotificationsEnabled()) { + val manager = NotificationManagerCompat.from(context) + if (!manager.areNotificationsEnabled()) { + return false + } + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O && + manager.getNotificationChannel(CHANNEL_ID)?.importance == + NotificationManager.IMPORTANCE_NONE + ) { return false } if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) { diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt index 39233b3a..9f9c32ac 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt @@ -1,5 +1,9 @@ package tw.avianjay.taiwanbus.flutter +import java.time.LocalDateTime +import java.time.OffsetDateTime +import java.time.ZoneId +import java.time.format.DateTimeParseException import java.util.Calendar import java.util.Locale import java.util.TimeZone @@ -86,6 +90,8 @@ internal data class SmartLiveStop( val msg: String?, /** Every timed arrival the feed lists for the stop, in seconds. */ val arrivals: List = emptyList(), + /** The moment the seconds above count from: when the feed was read. */ + val asOfMs: Long = 0L, ) /** A bus worth telling the rider about. */ @@ -257,6 +263,34 @@ internal object SmartRouteReminderRules { return slot.lastActivityAtMs >= windowStartMs - SEEN_BEFORE_WINDOW_MS } + /** + * [slot] as [plan] has it now, or null if [plan] no longer has it due — + * replaced by a plan without it, with the route opened since, or with a + * different stop to watch. + * + * A run of the background check reads the plan once and then waits on + * the location and the network. The app can rewrite the plan in that + * time: the rider clears what it learned, or opens the route. What goes + * out is decided by the plan as it is when the reminder is about to. + */ + fun stillDue( + plan: SmartRoutePlan?, + slot: SmartPlanSlot, + nowMs: Long, + zone: TimeZone = TimeZone.getDefault(), + ): SmartPlanSlot? { + plan ?: return null + val current = dueSlots(plan, slot.provider, nowMs, zone).firstOrNull { + it.routeKey == slot.routeKey && it.pathId == slot.pathId + } ?: return null + // The stop already looked up was picked with the old one in mind. + if (current.stopId != slot.stopId) { + return null + } + val minute = serviceClock(nowMs, plan.dayStartHour, zone).minute + return current.takeUnless { wasSeenForWindow(it, nowMs, minute) } + } + fun mayRemind(history: SmartReminderHistory, nowMs: Long, today: Long): Boolean { if (nowMs - history.lastAnyMs < MIN_GAP_MS) { return false @@ -352,11 +386,19 @@ internal object SmartRouteReminderRules { } /** - * Reads one stop out of a `/routes/{id}/realtime` response. + * Reads one stop out of a `/routes/{id}/realtime` response received at + * [nowMs]. * * Only [pathId] is searched. The same stop id can sit on both directions * of a route, and the other direction's bus is the one going the wrong * way. + * + * The seconds in the feed count from its `eta_reference_at`, which can be + * well before the response arrives: the backend serves a cached response + * without counting it down. They are counted down to [nowMs] here, so that + * whether a bus can still be caught is judged on how far off it is now. + * A feed without that field is taken to be as of [nowMs], as the rest of + * the app takes it. */ fun parseLiveStop( jsonText: String, @@ -380,20 +422,33 @@ internal object SmartRouteReminderRules { if (stop["stopid"].asText() != wanted) { continue } - if (isOutdated(stop["updated_at"].asLong(), nowMs)) { + val referenceMs = stop["eta_reference_at"].asEpochMs() + if (isOutdated(stop["updated_at"].asLong(), nowMs) || + (referenceMs != null && nowMs - referenceMs > MAX_FEED_AGE_MS) + ) { return null } + // A reference ahead of the device's clock is that clock being + // behind, not an estimate from the future. + val elapsed = referenceMs?.let { ((nowMs - it) / 1000).toInt() } + ?.coerceAtLeast(0) + ?: 0 + fun countedDown(seconds: Int?) = + seconds?.let { if (it > 0) max(0, it - elapsed) else it } return SmartLiveStop( - sec = stop["eta"].asInt(), + sec = countedDown(stop["eta"].asInt()), msg = stop["message"].asText(), arrivals = (stop["etas"] as? JsonArray).orEmpty().mapNotNull { eta -> // An arrival that comes with a message is a status, // not a time: "未發車" may still carry a timetable guess. - (eta as? JsonObject) - ?.takeIf { it["message"].asText() == null } - ?.get("eta") - .asInt() + countedDown( + (eta as? JsonObject) + ?.takeIf { it["message"].asText() == null } + ?.get("eta") + .asInt(), + ) }, + asOfMs = nowMs, ) } } @@ -407,6 +462,9 @@ internal object SmartRouteReminderRules { * The first bus the rider could still catch, if it is close enough to be * worth saying so. * + * [liveStop] has to have been read at the moment this is decided; see + * [parseLiveStop]. + * * A stop that carries a message instead of a time is in some state — not * yet departed, not served today, last bus gone — and none of those is a * reason to tell anyone to leave the house. Only a timed arrival counts. @@ -525,4 +583,30 @@ internal object SmartRouteReminderRules { asText()?.let { it.toLongOrNull() ?: it.toDoubleOrNull()?.toLong() } private fun JsonElement?.asInt(): Int? = asLong()?.toInt() + + /** + * A moment as the backend writes one: epoch seconds or milliseconds, or + * an ISO-8601 time. Null when it is none of those. + */ + private fun JsonElement?.asEpochMs(): Long? { + val text = asText() ?: return null + (text.toLongOrNull() ?: text.toDoubleOrNull()?.toLong())?.let { value -> + return when { + value > 1_000_000_000_000L -> value + value > 1_000_000_000L -> value * 1000 + else -> null + } + } + return try { + OffsetDateTime.parse(text).toInstant().toEpochMilli() + } catch (_: DateTimeParseException) { + try { + // Without an offset it is a time on the device's own clock, + // as Dart's DateTime.parse takes it. + LocalDateTime.parse(text).atZone(ZoneId.systemDefault()).toInstant().toEpochMilli() + } catch (_: DateTimeParseException) { + null + } + } + } } diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationSchedulerTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationSchedulerTest.kt new file mode 100644 index 00000000..df35946e --- /dev/null +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationSchedulerTest.kt @@ -0,0 +1,89 @@ +package tw.avianjay.taiwanbus.flutter + +import android.content.Context +import androidx.work.WorkInfo +import androidx.work.WorkManager +import java.util.concurrent.TimeUnit +import kotlinx.serialization.encodeToString +import kotlinx.serialization.json.Json +import org.junit.Assert.assertTrue +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.annotation.Config + +/** Whether the background check is scheduled, and who may stop it. */ +@RunWith(RobolectricTestRunner::class) +@Config(sdk = [34], application = YABusApplication::class) +class SmartRouteNotificationSchedulerTest { + private lateinit var context: Context + + private val liveSlot = SmartPlanSlot( + provider = "khh", + routeKey = 101, + routeId = "KHH101", + pathId = 0, + weekday = 3, + startMinute = 190, + endMinute = 250, + peakMinute = 220, + validUntilMs = Long.MAX_VALUE, + ) + + @Before + fun setUp() { + context = RuntimeEnvironment.getApplication() + } + + private fun writePlan(vararg slots: SmartPlanSlot) { + context.getSharedPreferences("FlutterSharedPreferences", Context.MODE_PRIVATE) + .edit() + .putString( + "flutter.smart_route_plan", + Json.encodeToString(SmartRoutePlan(version = 1, slots = slots.toList())), + ) + .commit() + } + + /** Queued after whatever was asked of WorkManager before it, so it sees that done. */ + private fun work(): List = WorkManager.getInstance(context) + .getWorkInfosForUniqueWork(SmartRouteNotificationScheduler.WORK_NAME) + .get(10, TimeUnit.SECONDS) + + private fun isScheduled() = work().let { infos -> + infos.isNotEmpty() && infos.any { !it.state.isFinished } + } + + @Test + fun aPlanWithSomethingLeftToFireIsScheduledAndNothingElse() { + writePlan(liveSlot) + SmartRouteNotificationScheduler.sync(context, enabled = true) + assertTrue(isScheduled()) + + SmartRouteNotificationScheduler.sync(context, enabled = false) + assertTrue(!isScheduled()) + + writePlan(liveSlot.copy(validUntilMs = 1L)) + SmartRouteNotificationScheduler.sync(context, enabled = true) + assertTrue(!isScheduled()) + } + + @Test + fun aCheckThatReadAnOldPlanDoesNotStopTheNewOne() { + // A check read a plan with nothing left in it. Before it got round + // to stopping itself, the app wrote a new plan and rescheduled. + writePlan(liveSlot) + SmartRouteNotificationScheduler.sync(context, enabled = true) + + SmartRouteNotificationScheduler.cancelIfNothingLive(context) + + assertTrue(isScheduled()) + + // With the plan really empty, it does stop. + writePlan(liveSlot.copy(validUntilMs = 1L)) + SmartRouteNotificationScheduler.cancelIfNothingLive(context) + assertTrue(!isScheduled()) + } +} diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt index 951b4b20..164104c7 100644 --- a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt @@ -239,6 +239,27 @@ class SmartRouteReminderRulesTest { assertTrue(seen(at(8, 7, 30))) } + @Test + fun aReminderGoesOutOnlyIfThePlanAsItIsNowStillHasItDue() { + val now = at(8, 7, 40) + val read = slot() + fun stillDue(plan: SmartRoutePlan?) = + SmartRouteReminderRules.stillDue(plan, read, now, taipei) + + assertEquals(read, stillDue(plan(read))) + // Cleared, switched off, or rebuilt without the route. + assertNull(stillDue(null)) + assertNull(stillDue(plan())) + assertNull(stillDue(plan(slot(routeKey = 202)))) + // The route was opened while the check was waiting on the feed. + assertNull(stillDue(plan(slot(lastActivityAtMs = at(8, 7, 35))))) + // The stop it looked up is no longer the one to watch. + assertNull(stillDue(plan(slot(stopId = 2002L)))) + // Rebuilt with the same habit: the new plan's slot is what goes out. + val rebuilt = slot(confidence = 0.95, validUntilMs = at(23, 4, 0)) + assertEquals(rebuilt, stillDue(plan(rebuilt))) + } + @Test fun remindersKeepApartAndStopAfterSixInADay() { val now = at(8, 7, 40) @@ -591,6 +612,96 @@ class SmartRouteReminderRulesTest { assertNull(SmartRouteReminderRules.parseLiveStop("""{"paths": 3}""", 0, "1", feedTime)) } + private fun referencedFeed(reference: String, eta: Int = 190) = """ + {"paths": [{"pathid": 0, "stops": [ + {"stopid": "1", "eta": $eta, "message": null, "eta_reference_at": $reference, + "etas": [{"eta": $eta}, {"eta": 900}, {"eta": 0}, {"eta": -1}]} + ]}]} + """.trimIndent() + + @Test + fun anEstimateIsCountedDownFromWhenItWasMade() { + // The backend serves a cached response as it was: 190 s made fifteen + // seconds ago is 175 s now, under the three minutes it takes to be + // catchable. + val live = SmartRouteReminderRules.parseLiveStop( + referencedFeed("${feedTime / 1000 - 15}"), + 0, + "1", + feedTime, + )!! + + assertEquals(175, live.sec) + // A bus at the stop or with no estimate stays as the feed said. + assertEquals(listOf(175, 885, 0, -1), live.arrivals) + assertEquals(feedTime, live.asOfMs) + assertEquals( + SmartEtaDecision(etaSeconds = 885, followingEtaSeconds = null), + SmartRouteReminderRules.decide(live, distanceMeters = null), + ) + } + + @Test + fun theReferenceIsReadInEveryFormTheBackendWritesIt() { + val fifteenSecondsAgo = feedTime - 15_000 + listOf( + "${fifteenSecondsAgo / 1000}", + "$fifteenSecondsAgo", + "\"${fifteenSecondsAgo / 1000}\"", + "\"${java.time.Instant.ofEpochMilli(fifteenSecondsAgo)}\"", + "\"${java.time.Instant.ofEpochMilli(fifteenSecondsAgo).atOffset(java.time.ZoneOffset.ofHours(8))}\"", + ).forEach { reference -> + assertEquals( + reference, + 175, + SmartRouteReminderRules.parseLiveStop(referencedFeed(reference), 0, "1", feedTime)?.sec, + ) + } + } + + @Test + fun withoutAReferenceTheEstimateIsTakenAsOfNow() { + listOf("null", "\"\"", "\"soon\"", "12").forEach { reference -> + assertEquals( + reference, + 190, + SmartRouteReminderRules.parseLiveStop(referencedFeed(reference), 0, "1", feedTime)?.sec, + ) + } + // Nor does a device clock behind the server's add time to it. + assertEquals( + 190, + SmartRouteReminderRules.parseLiveStop( + referencedFeed("${feedTime / 1000 + 20}"), + 0, + "1", + feedTime, + )?.sec, + ) + } + + @Test + fun anEstimateMadeTooLongAgoIsNoEstimate() { + val fiveMinutes = 5 * 60L + + assertNotNull( + SmartRouteReminderRules.parseLiveStop( + referencedFeed("${feedTime / 1000 - fiveMinutes}", eta = 900), + 0, + "1", + feedTime, + ), + ) + assertNull( + SmartRouteReminderRules.parseLiveStop( + referencedFeed("${feedTime / 1000 - fiveMinutes - 1}", eta = 900), + 0, + "1", + feedTime, + ), + ) + } + // --- whether there is a bus worth mentioning ---------------------------- @Test diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt index 53797515..fdc64c9c 100644 --- a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderStoreTest.kt @@ -1,13 +1,22 @@ package tw.avianjay.taiwanbus.flutter +import android.Manifest import android.app.Application +import android.app.NotificationChannel +import android.app.NotificationManager import android.content.Context +import java.util.Calendar +import kotlinx.serialization.encodeToString +import kotlinx.serialization.json.Json import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue import org.junit.Before import org.junit.Test import org.junit.runner.RunWith import org.robolectric.RobolectricTestRunner import org.robolectric.RuntimeEnvironment +import org.robolectric.Shadows.shadowOf import org.robolectric.annotation.Config /** What the worker keeps about the reminders it has shown, and for whom. */ @@ -106,4 +115,110 @@ class SmartRouteReminderStoreTest { assertEquals(SmartReminderHistory(), SmartRouteNotificationSupport.loadHistory(context)) assertEquals(0L, SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot)) } + + // --- sending one -------------------------------------------------------- + + /** A Wednesday at 07:40 on this machine's clock: [slot] is due. */ + private val wednesdayMorning = Calendar.getInstance().apply { + clear() + set(2026, Calendar.APRIL, 8, 7, 40) + }.timeInMillis + + private fun writePlan(vararg slots: SmartPlanSlot) { + context.getSharedPreferences("FlutterSharedPreferences", Context.MODE_PRIVATE) + .edit() + .putString( + "flutter.smart_route_plan", + Json.encodeToString(SmartRoutePlan(version = 1, slots = slots.toList())), + ) + .commit() + } + + private fun remind(read: SmartPlanSlot = slot): Boolean { + val texts = mutableListOf() + return SmartRouteNotificationSupport.remind( + context = context, + slot = read, + stop = SmartRouteStop(0, "100100128221", "常用站", 1, 120.3, 22.6), + text = { current -> + texts += current + SmartReminderText("307 約 8 分後到站", current.routeName, current.routeName) + }, + timeoutMs = 60_000L, + history = history, + nowMs = wednesdayMorning, + checkedAtMs = wednesdayMorning, + ) + } + + private fun posted() = shadowOf( + context.getSystemService(NotificationManager::class.java), + ).allNotifications + + private fun allowNotifications() { + shadowOf(context as Application).grantPermissions(Manifest.permission.POST_NOTIFICATIONS) + SmartRouteNotificationSupport.ensureChannel(context) + } + + @Test + fun aReminderStillDueIsShownAndRemembered() { + allowNotifications() + writePlan(slot.copy(routeName = "307 新")) + + assertTrue(remind()) + + // Shown as the plan has it now, not as it was first read. + assertEquals("307 新", posted().single().extras.getString("android.text")) + assertEquals( + listOf(SmartReminderLogEntry("khh", 101, 0, wednesdayMorning, peakMinute = 220)), + loggedReminders(), + ) + } + + @Test + fun aReminderThePlanNoLongerHasIsNeitherShownNorRemembered() { + allowNotifications() + // Read from a plan that has since been cleared, or rebuilt after the + // route was opened. + writePlan() + assertFalse(remind()) + writePlan(slot.copy(lastActivityAtMs = wednesdayMorning - 60_000L)) + assertFalse(remind()) + + assertTrue(posted().isEmpty()) + assertEquals("[]", SmartRouteNotificationSupport.loadReminderLog(context)) + assertEquals(SmartReminderHistory(), SmartRouteNotificationSupport.loadHistory(context)) + } + + @Test + fun aReminderIsNotSentToARiderWhoHasTheAppOpen() { + allowNotifications() + writePlan(slot) + AppRuntimeStateStore.setAppInForeground(context, true) + + assertFalse(remind()) + assertTrue(posted().isEmpty()) + assertEquals("[]", SmartRouteNotificationSupport.loadReminderLog(context)) + } + + @Test + fun aReminderOnAChannelTurnedOffIsNotRemembered() { + // Notifications are on for the app, but the rider turned this kind + // off: the system would drop it, so nobody saw it. + shadowOf(context as Application).grantPermissions(Manifest.permission.POST_NOTIFICATIONS) + context.getSystemService(NotificationManager::class.java).createNotificationChannel( + NotificationChannel( + SmartRouteNotificationSupport.CHANNEL_ID, + "智慧推薦提醒", + NotificationManager.IMPORTANCE_NONE, + ), + ) + writePlan(slot) + + assertFalse(SmartRouteNotificationSupport.canPostNotifications(context)) + assertFalse(remind()) + assertTrue(posted().isEmpty()) + assertEquals("[]", SmartRouteNotificationSupport.loadReminderLog(context)) + assertEquals(0L, SmartRouteNotificationSupport.loadLastReminderForRoute(context, slot)) + } } diff --git a/lib/core/app_controller.dart b/lib/core/app_controller.dart index 897c3e60..e212408d 100644 --- a/lib/core/app_controller.dart +++ b/lib/core/app_controller.dart @@ -160,6 +160,11 @@ class AppController extends ChangeNotifier { /// Route ids already looked up for the reminder plan, by provider and /// route key. They do not change, so one lookup per route is enough. final Map _smartRouteIds = {}; + + /// The reminder plan being rebuilt, if one is, and whether what it is + /// built from has changed since that rebuild began. + Future? _smartRoutePlanSync; + bool _smartRoutePlanStale = false; Object? _lastRecommendationRoutes; Object? _lastRecommendationFavorites; Object? _lastRecommendationUsage; @@ -801,6 +806,9 @@ class AppController extends ChangeNotifier { if (scheduleSync) { _scheduleChangeDrivenAccountSync(); } + // A reminder with no stop of its own watches the route's favourite, so + // one that is gone must not be watched any more. + await _refreshSmartRoutePlan(); } Future _loadAccountSyncLocalState() async { @@ -846,6 +854,9 @@ class AppController extends ChangeNotifier { await storage.saveHistory(_history); await storage.saveRouteUsageProfiles(_routeUsageProfiles); await storage.saveDestinationChoiceProfiles(_destinationChoiceProfiles); + // The plan was made from the merged history, other devices' routes and + // all. Those are not this device's to be reminded of any more. + await _refreshSmartRoutePlan(); } Future setAccountSyncEnabled( @@ -1291,7 +1302,9 @@ class AppController extends ChangeNotifier { await AndroidHomeIntegration.updateFavoriteWidgetAutoRefreshMinutes( _settings.favoriteWidgetAutoRefreshMinutes, ); - await _syncSmartRouteNotifications(); + // Not allowed to fail the rest: applying a synced document still has its + // bookkeeping to do after this. + await _refreshSmartRoutePlan(evenIfDisabled: true); await desktopDiscordPresenceService.refresh(settings: _settings); await _syncWearOsSnapshot(requestRefresh: false); } @@ -2230,36 +2243,120 @@ class AppController extends ChangeNotifier { /// Works out when a reminder is worth sending and hands that to the /// platform, which only has to follow it. /// + /// Called whenever something the plan is built from changes. Rebuilds run + /// one at a time, and one that finds its inputs changed while it was + /// waiting writes nothing: the rebuild queued behind it will. Otherwise a + /// rebuild started before the rider cleared their history could finish + /// after the clearing and write the old plan back. + /// + /// The returned future completes once a rebuild that started after this + /// call has finished. + Future _syncSmartRouteNotifications() { + _smartRoutePlanStale = true; + // Started as a microtask so the drain is recorded before any of it runs: + // a drain that somehow finished at once would otherwise clear the field + // before it was set, and leave every later call waiting on a finished + // drain instead of starting a rebuild. + return _smartRoutePlanSync ??= Future.microtask( + _drainSmartRoutePlanSyncs, + ); + } + + Future _drainSmartRoutePlanSyncs() async { + try { + while (true) { + _smartRoutePlanStale = false; + try { + await _syncSmartRouteNotificationsOnce(); + } catch (_) { + // A rebuild that has been overtaken does not get the last word, + // failure included: the one after it may well succeed. + if (!_smartRoutePlanStale) rethrow; + } + if (!_smartRoutePlanStale) return; + } + } finally { + // Cleared in the same step as the last check of the flag, so no call + // can join a drain that has already decided to stop. + _smartRoutePlanSync = null; + } + } + + /// Rebuilds the reminder plan after a change made for some other reason — + /// favourites, a database, logging out, synced settings. That change has + /// already happened and is not to be reported as failed because the plan + /// could not follow it; a rebuild that fails leaves no plan rather than an + /// outdated one. + /// + /// With reminders off there is no plan to keep up to date, unless the + /// change may be the one that turned them off: [evenIfDisabled]. + Future _refreshSmartRoutePlan({bool evenIfDisabled = false}) async { + if (!evenIfDisabled && !_settings.enableSmartRouteNotifications) { + return; + } + try { + await _syncSmartRouteNotifications(); + } catch (_) { + // See above. + } + } + /// The plan is written before the scheduler is told anything, because the /// scheduler decides whether to run at all by looking for one. - Future _syncSmartRouteNotifications() async { + Future _syncSmartRouteNotificationsOnce() async { final enabled = _settings.enableSmartRouteNotifications; if (AndroidHomeIntegration.supportsSmartRouteNotifications) { - if (enabled) { - await ensureRecommendationDataReady(); - final now = DateTime.now(); - await _resolveSmartRouteIds(now); - await storage.saveSmartRoutePlan( - SmartRoutePlanner.build( + try { + if (enabled) { + await ensureRecommendationDataReady(); + final now = DateTime.now(); + await _resolveSmartRouteIds(now); + final reminders = await _loadSmartRouteReminders(); + if (_smartRoutePlanStale) { + return; + } + // Read only now, after the last wait, so the plan is of what is + // current rather than of what was when this rebuild began. + final plan = SmartRoutePlanner.build( profiles: _routeUsageProfiles, routeIdOf: (profile) => _smartRouteIds[_smartRouteIdKey(profile)], - reminders: SmartRouteReminder.parseLog( - await AndroidHomeIntegration.loadSmartRouteReminderLog(), - ), + reminders: reminders, favoriteProfiles: _favoriteUsageProfiles, favorites: _favoriteGroups.values .expand((group) => group) .whereType(), now: now, - ).toJson(), - ); - } else { - await storage.clearSmartRoutePlan(); + ); + await storage.saveSmartRoutePlan(plan.toJson()); + } else { + await storage.clearSmartRoutePlan(); + } + } catch (_) { + // A plan that could not be brought up to date is one about routes, + // stops or a history that may no longer be the rider's. None at all + // is the safer thing to leave behind. + try { + await storage.clearSmartRoutePlan(); + await AndroidHomeIntegration.syncSmartRouteNotifications(enabled); + } catch (_) { + // The error worth reporting is the first one. + } + rethrow; } } + if (_smartRoutePlanStale) { + return; + } await AndroidHomeIntegration.syncSmartRouteNotifications(enabled); } + /// The reminders the background check has shown, for anything that reads + /// a habit; see [SmartRouteReminder]. None where there is no such check. + Future> _loadSmartRouteReminders() async => + SmartRouteReminder.parseLog( + await AndroidHomeIntegration.loadSmartRouteReminderLog(), + ); + static String _smartRouteIdKey(RouteUsageProfile profile) => '${profile.provider.name}:${profile.routeKey}'; @@ -2595,9 +2692,11 @@ class AppController extends ChangeNotifier { } _downloadingDatabase = true; notifyListeners(); + var downloadedAny = false; try { for (final provider in targets) { await repository.downloadDatabase(provider); + downloadedAny = true; _databaseReadyByProvider = { ..._databaseReadyByProvider, provider: true, @@ -2614,6 +2713,12 @@ class AppController extends ChangeNotifier { } finally { _downloadingDatabase = false; notifyListeners(); + if (downloadedAny) { + // Routes that could not be named without the database were left out + // of the reminder plan. Nothing else would put them back before the + // app is next used, which for a reminder may be too late. + await _refreshSmartRoutePlan(); + } } } @@ -3120,14 +3225,37 @@ class AppController extends ChangeNotifier { _favoriteUsageProfiles = const []; _stopVisitProfiles = const []; _destinationChoiceProfiles = const []; - await _persistSmartRouteProfiles(); - await storage.saveDestinationChoiceProfiles(const []); - await _updateRouteHistoryDevicePayload( - profiles: const [], - destinationChoices: const [], + // Each step removes part of what was learned, so each is tried whatever + // becomes of the others; the first failure is reported once all have + // been. The reminder log goes before the plan is rebuilt, so the new + // plan is not made from it. + final failures = <(Object, StackTrace)>[]; + Future attempt(Future Function() step) async { + try { + await step(); + } catch (error, stackTrace) { + failures.add((error, stackTrace)); + } + } + + await attempt(() => storage.saveRouteUsageProfiles(const [])); + await attempt(() => storage.saveFavoriteUsageProfiles(const [])); + await attempt(() => storage.saveStopVisitProfiles(const [])); + await attempt(() => storage.saveDestinationChoiceProfiles(const [])); + await attempt( + () => _updateRouteHistoryDevicePayload( + profiles: const [], + destinationChoices: const [], + ), ); // Which routes a reminder went out for, and when, was learned too. - await AndroidHomeIntegration.forgetSmartRouteReminders(); + await attempt(AndroidHomeIntegration.forgetSmartRouteReminders); + await attempt(_syncSmartRouteNotifications); + unawaited(_pushSmartSuggestionToWearOsIfNeeded()); + notifyListeners(); + if (failures.isNotEmpty) { + Error.throwWithStackTrace(failures.first.$1, failures.first.$2); + } } Future clearRouteSelectionHistory() async { @@ -3495,7 +3623,7 @@ class AppController extends ChangeNotifier { if (stopVisitsChanged) { await storage.saveStopVisitProfiles(_stopVisitProfiles); } - await _syncSmartRouteNotifications(); + await _refreshSmartRoutePlan(); unawaited(_pushSmartSuggestionToWearOsIfNeeded()); notifyListeners(); } @@ -3554,6 +3682,7 @@ class AppController extends ChangeNotifier { .expand((group) => group) .whereType() .where((favorite) => favorite.provider == _settings.provider), + reminders: await _loadSmartRouteReminders(), now: now ?? DateTime.now(), position: position, ); @@ -3584,6 +3713,7 @@ class AppController extends ChangeNotifier { .expand((group) => group) .whereType() .where((favorite) => favorite.provider == _settings.provider), + reminders: await _loadSmartRouteReminders(), now: now ?? DateTime.now(), position: position, limit: limit, diff --git a/lib/core/models.dart b/lib/core/models.dart index 74ae305c..06a76a32 100644 --- a/lib/core/models.dart +++ b/lib/core/models.dart @@ -1684,6 +1684,9 @@ class RouteUsageProfile { ); } + /// Forgets the taps, and which stop each visit was at: clearing selection + /// history promises to clear stop usage too. When each visit was is kept, + /// along with the open counts it stands for. RouteUsageProfile clearSelections() { return RouteUsageProfile( provider: provider, @@ -1693,7 +1696,7 @@ class RouteUsageProfile { totalOpens: totalOpens, lastOpenedAtMs: lastOpenedAtMs, hourlyOpens: hourlyOpens, - visits: visits, + visits: [for (final visit in visits) RouteVisit(atMs: visit.atMs)], legacyAsOfMs: legacyAsOfMs, ); } diff --git a/lib/core/smart_route_habit.dart b/lib/core/smart_route_habit.dart index e3b07b51..cf3a93ce 100644 --- a/lib/core/smart_route_habit.dart +++ b/lib/core/smart_route_habit.dart @@ -1,3 +1,4 @@ +import 'dart:convert'; import 'dart:math' as math; import 'models.dart'; @@ -94,6 +95,97 @@ class RouteHabitEstimate { /// sent for — the peak of its window — where that is known. typedef RouteReminderShown = ({int atMs, int? forMinute}); +/// A reminder the background check actually showed, as it logs them. +/// +/// Everything that reads a habit has to be given these — the reminder plan +/// and the home screen alike. Without them a reminder that did its job looks +/// like a day the rider stayed home, and a tap on one like a routine that +/// moved earlier; see [RouteHabitEvidence]. +class SmartRouteReminder { + const SmartRouteReminder({ + required this.provider, + required this.routeKey, + required this.pathId, + required this.atMs, + this.peakMinute, + }); + + final BusProvider provider; + final int routeKey; + final int pathId; + final int atMs; + + /// The peak minute of the plan slot it was shown for. + final int? peakMinute; + + bool isFor(RouteUsageProfile profile) => + provider == profile.provider && + routeKey == profile.routeKey && + pathId == profile.pathId; + + /// The ones among [reminders] that were for [profile], in the form + /// [RouteHabitEvidence.of] takes them. + static List shownFor( + RouteUsageProfile profile, + Iterable reminders, + ) => [ + for (final reminder in reminders) + if (reminder.isFor(profile)) + (atMs: reminder.atMs, forMinute: reminder.peakMinute), + ]; + + /// Reads the log the platform side keeps. Anything unreadable is skipped: + /// a lost entry only makes the model a little more cautious. + static List parseLog(String? raw) { + if (raw == null || raw.trim().isEmpty) { + return const []; + } + final Object? decoded; + try { + decoded = jsonDecode(raw); + } catch (_) { + return const []; + } + if (decoded is! List) { + return const []; + } + final providers = BusProvider.values.asNameMap(); + final reminders = []; + for (final entry in decoded) { + if (entry is! Map) { + continue; + } + // The name the plan gave the worker, and nothing looser: a reminder + // that cannot be placed must not be pinned on some other city's route. + final provider = providers[entry['provider']]; + final routeKey = entry['routeKey']; + final pathId = entry['pathId']; + final atMs = entry['atMs']; + final peakMinute = entry['peakMinute']; + if (provider == null || + routeKey is! int || + pathId is! int || + atMs is! int || + atMs <= 0) { + continue; + } + reminders.add( + SmartRouteReminder( + provider: provider, + routeKey: routeKey, + pathId: pathId, + atMs: atMs, + peakMinute: + peakMinute is int && peakMinute >= 0 && peakMinute < 24 * 60 + ? peakMinute + : null, + ), + ); + } + return reminders; + } +} + /// The times a route was used, arranged for [RouteHabitModel]. class RouteHabitEvidence { RouteHabitEvidence._( diff --git a/lib/core/smart_route_plan.dart b/lib/core/smart_route_plan.dart index 3263a071..d314f214 100644 --- a/lib/core/smart_route_plan.dart +++ b/lib/core/smart_route_plan.dart @@ -1,10 +1,11 @@ -import 'dart:convert'; import 'dart:math' as math; import 'models.dart'; import 'smart_route_habit.dart'; import 'smart_route_service.dart'; +export 'smart_route_habit.dart' show SmartRouteReminder; + /// One stretch of one weekday during which a route is worth a reminder. class SmartRoutePlanSlot { const SmartRoutePlanSlot({ @@ -73,81 +74,6 @@ class SmartRoutePlanSlot { }; } -/// A reminder the background check actually showed, as it logs them. -class SmartRouteReminder { - const SmartRouteReminder({ - required this.provider, - required this.routeKey, - required this.pathId, - required this.atMs, - this.peakMinute, - }); - - final BusProvider provider; - final int routeKey; - final int pathId; - final int atMs; - - /// The [SmartRoutePlanSlot.peakMinute] of the slot it was shown for. - final int? peakMinute; - - bool isFor(RouteUsageProfile profile) => - provider == profile.provider && - routeKey == profile.routeKey && - pathId == profile.pathId; - - /// Reads the log the platform side keeps. Anything unreadable is skipped: - /// a lost entry only makes the model a little more cautious. - static List parseLog(String? raw) { - if (raw == null || raw.trim().isEmpty) { - return const []; - } - final Object? decoded; - try { - decoded = jsonDecode(raw); - } catch (_) { - return const []; - } - if (decoded is! List) { - return const []; - } - final providers = BusProvider.values.asNameMap(); - final reminders = []; - for (final entry in decoded) { - if (entry is! Map) { - continue; - } - // The name the plan gave the worker, and nothing looser: a reminder - // that cannot be placed must not be pinned on some other city's route. - final provider = providers[entry['provider']]; - final routeKey = entry['routeKey']; - final pathId = entry['pathId']; - final atMs = entry['atMs']; - final peakMinute = entry['peakMinute']; - if (provider == null || - routeKey is! int || - pathId is! int || - atMs is! int || - atMs <= 0) { - continue; - } - reminders.add( - SmartRouteReminder( - provider: provider, - routeKey: routeKey, - pathId: pathId, - atMs: atMs, - peakMinute: - peakMinute is int && peakMinute >= 0 && peakMinute < 24 * 60 - ? peakMinute - : null, - ), - ); - } - return reminders; - } -} - /// Everything the background reminder needs to know, worked out ahead of /// time so the platform side never has to score a habit itself. class SmartRoutePlan { @@ -195,6 +121,7 @@ class SmartRoutePlanner { /// quarter of an hour, so finer than this would be false precision. static const int gridMinutes = 10; + /// The most slots kept for any one provider; see [build]. static const int maxSlots = 64; /// Whether [profile] has been used on enough days to be worth planning @@ -232,11 +159,7 @@ class SmartRoutePlanner { final evidence = RouteHabitEvidence.of( profile, now, - reminders: [ - for (final reminder in reminderList) - if (reminder.isFor(profile)) - (atMs: reminder.atMs, forMinute: reminder.peakMinute), - ], + reminders: SmartRouteReminder.shownFor(profile, reminderList), ); if (evidence.dayCount < minSupportDays) { continue; @@ -293,17 +216,28 @@ class SmartRoutePlanner { } } + // The cap is per provider. The background check only acts on the slots + // of the provider in use, so one shared cap would let another city's + // habits crowd out every slot the rider could actually be reminded of. slots.sort((left, right) => right.confidence.compareTo(left.confidence)); - final kept = slots.take(maxSlots).toList() - ..sort((left, right) { - final weekday = left.weekday.compareTo(right.weekday); - if (weekday != 0) return weekday; - final start = left.startMinute.compareTo(right.startMinute); - if (start != 0) return start; - final route = left.routeKey.compareTo(right.routeKey); - if (route != 0) return route; - return left.pathId.compareTo(right.pathId); - }); + final keptPerProvider = {}; + final kept = []; + for (final slot in slots) { + final count = keptPerProvider[slot.provider] ?? 0; + if (count < maxSlots) { + keptPerProvider[slot.provider] = count + 1; + kept.add(slot); + } + } + kept.sort((left, right) { + final weekday = left.weekday.compareTo(right.weekday); + if (weekday != 0) return weekday; + final start = left.startMinute.compareTo(right.startMinute); + if (start != 0) return start; + final route = left.routeKey.compareTo(right.routeKey); + if (route != 0) return route; + return left.pathId.compareTo(right.pathId); + }); return SmartRoutePlan( generatedAtMs: now.millisecondsSinceEpoch, slots: List.unmodifiable(kept), diff --git a/lib/core/smart_route_service.dart b/lib/core/smart_route_service.dart index 43c8df30..a7de6ae6 100644 --- a/lib/core/smart_route_service.dart +++ b/lib/core/smart_route_service.dart @@ -74,21 +74,27 @@ class SmartRouteService { static RouteUsageProfile? chooseProfileForTime( Iterable profiles, - DateTime now, - ) { - final ranked = rankProfilesForTime(profiles, now); + DateTime now, { + Iterable reminders = const [], + }) { + final ranked = rankProfilesForTime(profiles, now, reminders: reminders); return ranked.isEmpty ? null : ranked.first.profile; } /// Every profile worth recommending at [now], best first, one per route /// and direction. + /// + /// [reminders] are the ones the background check has shown; see + /// [SmartRouteReminder]. static List rankProfilesForTime( Iterable profiles, - DateTime now, - ) { + DateTime now, { + Iterable reminders = const [], + }) { + final reminderList = reminders.toList(growable: false); final ranked = []; for (final profile in profiles) { - final ranking = rankProfile(profile, now); + final ranking = rankProfile(profile, now, reminders: reminderList); if (ranking != null) { ranked.add(ranking); } @@ -122,21 +128,29 @@ class SmartRouteService { /// recommended at all. static SmartRouteRanking? rankProfile( RouteUsageProfile profile, - DateTime now, - ) { + DateTime now, { + Iterable reminders = const [], + }) { if (profile.pathId == null) { return null; } - final evidence = RouteHabitEvidence.of(profile, now); + final evidence = RouteHabitEvidence.of( + profile, + now, + reminders: SmartRouteReminder.shownFor(profile, reminders), + ); final estimate = evidence.estimateNow(now); final habitScore = estimate.supportDays >= minSupportDaysForRecommendation && estimate.probability >= minProbabilityForRecommendation ? estimate.probability : 0.0; + // Handed over only as dated use builds up around this time of day. Use + // at other times says nothing about whether the counters for this one + // are still needed. final legacyScore = legacyWeight * - legacyStrength(profile, now, datedDays: evidence.dayCount); + legacyStrength(profile, now, datedDays: estimate.supportDays); final baseScore = math.max(habitScore, legacyScore); if (baseScore < minProbabilityForRecommendation) { return null; @@ -159,8 +173,9 @@ class SmartRouteService { /// [now], 0..1. /// /// They carry a profile across the upgrade to visit history and then step - /// aside: they fade as the moment they describe recedes, and again as dated - /// days accumulate to replace them. + /// aside: they fade as the moment they describe recedes, and again as + /// [datedDays] — days of dated use around the time of [now] — accumulate + /// to replace them. static double legacyStrength( RouteUsageProfile profile, DateTime now, { @@ -483,6 +498,7 @@ class SmartRouteService { Iterable favoriteProfiles = const [], Iterable favorites = const [], + Iterable reminders = const [], required DateTime now, Position? position, }) async { @@ -491,6 +507,7 @@ class SmartRouteService { profiles: profiles, favoriteProfiles: favoriteProfiles, favorites: favorites, + reminders: reminders, now: now, position: position, limit: 1, @@ -504,6 +521,7 @@ class SmartRouteService { Iterable favoriteProfiles = const [], Iterable favorites = const [], + Iterable reminders = const [], required DateTime now, Position? position, int limit = 3, @@ -514,7 +532,7 @@ class SmartRouteService { final favoriteProfileList = favoriteProfiles.toList(growable: false); final favoriteList = favorites.toList(growable: false); - final ranked = rankProfilesForTime(profiles, now); + final ranked = rankProfilesForTime(profiles, now, reminders: reminders); final suggestions = []; var next = 0; // Fetch only as many routes at once as there are places left to fill, in diff --git a/lib/screens/route_detail_screen.dart b/lib/screens/route_detail_screen.dart index 14df80c7..b8b152ca 100644 --- a/lib/screens/route_detail_screen.dart +++ b/lib/screens/route_detail_screen.dart @@ -71,6 +71,35 @@ StopInfo? resolveLearnedDestinationStop({ : null; } +/// The stop a visit to a route should be remembered against, if any. +/// +/// A stop the rider chose comes first, whatever else is known: it is the one +/// they have said they board at, even when it also happens to be the nearest. +/// Next the stop the page was opened on. The nearest stop is only a guess at +/// where they will board, and is trusted only when they are close enough to +/// be heading for it: the nearest stop to somebody reading the timetable +/// from across town says nothing about their habits. +@visibleForTesting +int? usageStopIdFor({ + required int? pickedStopId, + required int? openedStopId, + required int? nearestStopId, + required double? nearestDistanceMeters, +}) { + if (pickedStopId != null) { + return pickedStopId; + } + if (openedStopId != null) { + return openedStopId; + } + if (nearestStopId == null || + nearestDistanceMeters == null || + nearestDistanceMeters > SmartRouteService.atStopMeters) { + return null; + } + return nearestStopId; +} + class RouteDetailScreen extends StatefulWidget { const RouteDetailScreen({ required this.routeKey, @@ -205,6 +234,11 @@ class _RouteDetailScreenState extends State int? _requestedDestinationStopId; int? _boardingStopId; String? _boardingStopName; + + /// The boarding stop the rider chose themselves. [_boardingStopId] is also + /// filled in from the nearest stop and from the stop the page was opened + /// on, and only this tells a choice apart from those. + int? _riderPickedBoardingStopId; int? _destinationStopId; String? _destinationStopName; bool _hasExplicitDestinationRequest = false; @@ -2703,6 +2737,7 @@ class _RouteDetailScreenState extends State } _boardingStopId = stop.stopId; _boardingStopName = stop.stopName; + _riderPickedBoardingStopId = stop.stopId; }); await _applyLearnedDestinationIfPossible(); await _configureBackgroundTripMonitorIfNeeded(); @@ -2798,6 +2833,7 @@ class _RouteDetailScreenState extends State } _boardingStopId = null; _boardingStopName = null; + _riderPickedBoardingStopId = null; }); await _configureBackgroundTripMonitorIfNeeded(); if (!mounted) { @@ -3139,36 +3175,30 @@ class _RouteDetailScreenState extends State _currentBoardingCandidateStop(); } - /// The stop this visit should be remembered against, if any. - /// - /// The stop the page was opened on, or one the rider picked, is taken as - /// given. The nearest stop is only a guess at where they will board, and is - /// trusted only when they are close enough to be heading for it: the - /// nearest stop to somebody reading the timetable from across town says - /// nothing about their habits. + /// The stop this visit should be remembered against, if any; see + /// [usageStopIdFor]. int? _usageStopHint() { - final opened = _findStopById(_currentPathStops, widget.initialStopId); - if (opened != null) { - return opened.stopId; - } - final stop = _resolvedBoardingStop(); - if (stop == null) { - return null; - } - if (_currentBoardingCandidateStop()?.stopId != stop.stopId) { - return stop.stopId; - } + final nearest = _currentBoardingCandidateStop(); final position = _lastPosition; - if (position == null || (stop.lat == 0 && stop.lon == 0)) { - return null; - } - final distance = Geolocator.distanceBetween( - position.latitude, - position.longitude, - stop.lat, - stop.lon, + return usageStopIdFor( + pickedStopId: _findStopById( + _currentPathStops, + _riderPickedBoardingStopId, + )?.stopId, + openedStopId: _findStopById(_currentPathStops, _requestedStopId)?.stopId, + nearestStopId: nearest?.stopId, + nearestDistanceMeters: + nearest == null || + position == null || + (nearest.lat == 0 && nearest.lon == 0) + ? null + : Geolocator.distanceBetween( + position.latitude, + position.longitude, + nearest.lat, + nearest.lon, + ), ); - return distance <= SmartRouteService.atStopMeters ? stop.stopId : null; } String? _buildDesktopDiscordArrivalStatus(AppSettings settings) { diff --git a/test/route_detail_screen_loading_test.dart b/test/route_detail_screen_loading_test.dart index 4dc2f009..f07bc31e 100644 --- a/test/route_detail_screen_loading_test.dart +++ b/test/route_detail_screen_loading_test.dart @@ -250,6 +250,7 @@ void _screenTest( int initialFrameCount = 5, RouteDetailData? Function()? recentDetail, RouteDetailData? Function()? initialTopology, + int? initialStopId, }) { testWidgets(name, (tester) async { SharedPreferences.setMockInitialValues({}); @@ -274,6 +275,7 @@ void _screenTest( routeIdHint: 'TPE500', routeNameHint: '標題提示', initialPathId: 1, + initialStopId: initialStopId, initialTopologyFuture: initialTopology == null ? null : Future.value(initialTopology()), @@ -386,6 +388,32 @@ void main() { ); }); + test('a visit is remembered at the stop the rider chose, if any', () { + int? stopFor({ + int? picked, + int? opened, + int? nearest = 9, + double? nearestDistance = 50, + }) => usageStopIdFor( + pickedStopId: picked, + openedStopId: opened, + nearestStopId: nearest, + nearestDistanceMeters: nearestDistance, + ); + + // Opened on stop 3, then stop 7 picked before the visit was counted: 7 + // is what the rider said. + expect(stopFor(picked: 7, opened: 3), 7); + // A pick that is also the nearest stop is still a pick, however far. + expect(stopFor(picked: 9, nearestDistance: 5000), 9); + // Otherwise the stop the page was opened on. + expect(stopFor(opened: 3), 3); + // The nearest stop only when the rider is close enough to board there. + expect(stopFor(nearestDistance: 400), 9); + expect(stopFor(nearestDistance: 401), isNull); + expect(stopFor(nearestDistance: null), isNull); + }); + _screenTest('shows Chinese route, path, and stop names without overflow', ( tester, repository, @@ -886,6 +914,57 @@ void main() { expect(sessions.last['destinationStopId'], 5); }); + _screenTest( + 'a visit is remembered at the boarding stop picked, not the one opened on', + (tester, repository) async { + debugDefaultTargetPlatformOverride = TargetPlatform.android; + GeolocatorPlatform.instance = _BackgroundLocation(); + const channel = MethodChannel( + 'tw.avianjay.taiwanbus.flutter/trip_monitor', + ); + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + (call) async => call.method == 'isTripMonitorPaused' ? false : null, + ); + addTearDown(() { + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + null, + ); + }); + final controller = AppControllerScope.read( + tester.element(find.byType(RouteDetailScreen)), + ); + await controller.updateEnableRouteBackgroundMonitor(true); + repository.topologyRequests.single.complete(_detail()); + repository.primaryRequests.single.complete(_detail(eta: 300)); + await _frames(tester, 8); + repository.familyRequests.single.completer.complete( + repository.familyRequests.single.selected, + ); + await _frames(tester); + + // Opened on stop 3; stop 5 chosen before the visit is counted. + await tester.tap(find.byTooltip('背景乘車提醒')); + await _frames(tester); + await tester.tap(find.text('變更上車站')); + await _frames(tester); + await tester.tap( + find.descendant( + of: find.byType(BottomSheet), + matching: find.text('返程站5'), + ), + ); + await _frames(tester, 8); + await tester.pump(const Duration(seconds: 10)); + await _frames(tester, 8); + + final visit = controller.routeUsageProfiles.single.visits.single; + expect(visit.stopId, 5); + }, + initialStopId: 3, + ); + _screenTest('a new refresh rejects late family results', ( tester, repository, diff --git a/test/smart_route_plan_controller_test.dart b/test/smart_route_plan_controller_test.dart index 02811ad0..e633ebf5 100644 --- a/test/smart_route_plan_controller_test.dart +++ b/test/smart_route_plan_controller_test.dart @@ -1,14 +1,24 @@ +import 'dart:async'; import 'dart:convert'; import 'package:flutter/foundation.dart'; import 'package:flutter/services.dart'; import 'package:flutter_test/flutter_test.dart'; +import 'package:http/http.dart' as http; +import 'package:http/testing.dart'; import 'package:shared_preferences/shared_preferences.dart'; +import 'package:taiwanbus_flutter/core/account_sync_models.dart'; +import 'package:taiwanbus_flutter/core/account_sync_service.dart'; +import 'package:taiwanbus_flutter/core/app_analytics.dart'; +import 'package:taiwanbus_flutter/core/app_build_info.dart'; import 'package:taiwanbus_flutter/core/app_controller.dart'; +import 'package:taiwanbus_flutter/core/app_update_installer.dart'; +import 'package:taiwanbus_flutter/core/app_update_service.dart'; +import 'package:taiwanbus_flutter/core/auth_service.dart'; import 'package:taiwanbus_flutter/core/bus_repository.dart'; import 'package:taiwanbus_flutter/core/models.dart'; +import 'package:taiwanbus_flutter/core/storage_service.dart'; -import 'support/ad_test_controller.dart'; import 'support/route_usage_fixtures.dart'; class _Repository extends BusRepository { @@ -16,12 +26,16 @@ class _Repository extends BusRepository { final List lookups = []; bool databaseMissing = false; + /// While set, lookups wait for it: a rebuild can be held mid-way. + Completer? gate; + @override Future> routeIdsForRouteKeys( BusProvider provider, Set routeKeys, ) async { lookups.add('${provider.name}:${(routeKeys.toList()..sort()).join(',')}'); + await gate?.future; if (databaseMissing) { throw DatabaseNotReadyException('尚未下載路線資料庫。'); } @@ -30,6 +44,83 @@ class _Repository extends BusRepository { if (routeKey != 404) routeKey: '${provider.prefix}$routeKey', }; } + + @override + Future downloadDatabase(BusProvider provider) async { + databaseMissing = false; + } + + @override + Future databaseExists(BusProvider provider) async => !databaseMissing; + + @override + Future getCompleteBusInfo( + int routeKey, { + required BusProvider provider, + String? routeIdHint, + String? routeNameHint, + }) async => RouteDetailData( + route: RouteSummary( + sourceProvider: provider.name, + hashMd5: '', + routeKey: routeKey, + routeId: '${provider.prefix}$routeKey', + routeName: '307', + officialRouteName: '307', + description: '', + category: '', + sequence: 0, + rtrip: 0, + ), + paths: [PathInfo(routeKey: routeKey, pathId: 0, name: '往市區')], + stopsByPath: { + 0: [ + StopInfo( + routeKey: routeKey, + pathId: 0, + stopId: 1, + stopName: '站', + sequence: 1, + lon: 120.3, + lat: 22.6, + sec: 300, + ), + ], + }, + hasLiveData: true, + ); +} + +/// Logging out without asking a server about it. +class _OfflineAuthService extends AuthService { + @override + Future logout() async {} +} + +/// Fails to write the reminder plan while [failPlan] is set. +class _Storage extends StorageService { + bool failPlan = false; + bool failProfiles = false; + + /// Every plan written, in order. + final List> savedPlans = []; + + @override + Future saveSmartRoutePlan(Map plan) async { + if (failPlan) { + throw StateError('disk full'); + } + savedPlans.add(plan); + await super.saveSmartRoutePlan(plan); + } + + @override + Future saveRouteUsageProfiles(List profiles) async { + if (failProfiles) { + throw StateError('disk full'); + } + await super.saveRouteUsageProfiles(profiles); + } } const _homeChannel = MethodChannel( @@ -57,6 +148,7 @@ void main() { void seed({ List profiles = const [], bool notifications = false, + Map extra = const {}, }) { SharedPreferences.setMockInitialValues({ 'flutter.route_usage_profiles': jsonEncode([ @@ -66,6 +158,7 @@ void main() { ...AppSettings.defaults().toJson(), 'enableSmartRouteNotifications': notifications, }), + ...extra, }); } @@ -76,8 +169,39 @@ void main() { return raw == null ? null : jsonDecode(raw) as Map; } - Future start(_Repository repository) async { - final controller = await createAdTestController(repository: repository); + Future>> storedSlots() async => + ((await storedPlan())!['slots'] as List).cast>(); + + Future start( + _Repository repository, { + StorageService? storage, + AuthService? authService, + }) async { + const buildInfo = AppBuildInfo( + version: '1.0.0', + buildNumber: '1', + gitSha: 'test', + defaultUpdateChannel: AppUpdateChannel.release, + ); + final client = MockClient((_) async => http.Response('{}', 200)); + final previousPlatform = debugDefaultTargetPlatformOverride; + final AppAnalytics analytics; + try { + debugDefaultTargetPlatformOverride = TargetPlatform.windows; + analytics = await AppAnalytics.initialize(); + } finally { + debugDefaultTargetPlatformOverride = previousPlatform; + } + final controller = AppController( + repository: repository, + storage: storage ?? StorageService(), + analytics: analytics, + buildInfo: buildInfo, + appUpdateService: AppUpdateService(buildInfo: buildInfo, client: client), + appUpdateInstaller: createAppUpdateInstaller(), + authService: authService ?? AuthService(), + accountSyncService: AccountSyncService(client: client), + ); addTearDown(controller.dispose); await controller.initializeForFirstFrame(); return controller; @@ -406,4 +530,250 @@ void main() { expect(homeCalls, isEmpty); }); + + test( + 'a rebuild overtaken by clearing the history does not write it back', + () async { + seed(profiles: [commute()], notifications: true); + final repository = _Repository(); + final storage = _Storage(); + final controller = await start(repository, storage: storage); + await controller.updateEnableSmartRouteNotifications(true); + expect(await storedSlots(), isNotEmpty); + + // A rebuild that has read the history and is waiting on the platform + // when the rider clears it. + final logRequested = Completer(); + final releaseLog = Completer(); + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + if (call.method == 'getSmartRouteReminderLog' && + !logRequested.isCompleted) { + logRequested.complete(); + return releaseLog.future; + } + return null; + }); + final slowRebuild = controller.updateEnableSmartRouteNotifications(true); + await logRequested.future; + homeCalls.clear(); + final plansBefore = storage.savedPlans.length; + final clearing = controller.clearRouteUsageProfiles(); + // Until the clearing has done all it can without the rebuild. + for ( + var turn = 0; + turn < 100 && + !homeCalls.any( + (call) => call.method == 'forgetSmartRouteReminders', + ); + turn++ + ) { + await Future.delayed(Duration.zero); + } + await Future.delayed(Duration.zero); + releaseLog.complete('[]'); + await slowRebuild; + await clearing; + + expect(await storedSlots(), isEmpty); + // Only the rebuild that began after the clearing wrote anything: the + // overtaken one, made from a reminder log read before the clearing, + // never reached the worker even for a moment. + expect(storage.savedPlans.length - plansBefore, 1); + final methods = homeCalls.map((call) => call.method).toList(); + // The reminder log went before the plan that was written after it. + expect( + methods.indexOf('forgetSmartRouteReminders'), + lessThan(methods.lastIndexOf('getSmartRouteReminderLog')), + ); + expect(syncedStates().last, isTrue); + }, + ); + + test('clearing goes on past a step that fails, then reports it', () async { + seed(profiles: [commute()], notifications: true); + final storage = _Storage(); + final controller = await start(_Repository(), storage: storage); + await controller.updateEnableSmartRouteNotifications(true); + expect(await storedSlots(), isNotEmpty); + homeCalls.clear(); + + storage.failProfiles = true; + await expectLater(controller.clearRouteUsageProfiles(), throwsStateError); + + // The steps after the failed one were still taken. + expect( + homeCalls.map((call) => call.method), + contains('forgetSmartRouteReminders'), + ); + expect(await storedSlots(), isEmpty); + }); + + test( + 'a failed plan write leaves no plan and still clears everything', + () async { + seed(profiles: [commute()], notifications: true); + final storage = _Storage(); + final controller = await start(_Repository(), storage: storage); + await controller.updateEnableSmartRouteNotifications(true); + expect(await storedSlots(), isNotEmpty); + homeCalls.clear(); + + storage.failPlan = true; + await expectLater(controller.clearRouteUsageProfiles(), throwsStateError); + + expect(controller.routeUsageProfiles, isEmpty); + expect(await StorageService().loadRouteUsageProfiles(), isEmpty); + expect( + homeCalls.map((call) => call.method), + contains('forgetSmartRouteReminders'), + ); + // What was there is gone rather than left to remind of a cleared + // history. + expect(await storedPlan(), isNull); + expect(syncedStates(), isNotEmpty); + }, + ); + + test('a favourite removed is no longer a stop to watch', () async { + // A route opened without a stop, whose only favourite is what a + // reminder would watch. + seed( + profiles: [ + profileWithVisits( + daysBefore(DateTime.now(), count: 15, hour: 7, minute: 40), + provider: BusProvider.khh, + ), + ], + notifications: true, + ); + final controller = await start(_Repository()); + const favorite = FavoriteStop( + provider: BusProvider.khh, + routeKey: 101, + pathId: 0, + stopId: 4004, + ); + await controller.addFavoriteStop(favorite); + expect((await storedSlots()).map((slot) => slot['stopId']).toSet(), {4004}); + + await controller.removeFavoriteStop( + AppController.defaultFavoriteGroupName, + favorite, + ); + + expect((await storedSlots()).map((slot) => slot['stopId']).toSet(), {null}); + }); + + test( + 'routes left out for want of a database come back once it is downloaded', + () async { + seed(profiles: [commute()], notifications: true); + final repository = _Repository()..databaseMissing = true; + final controller = await start(repository); + await controller.updateEnableSmartRouteNotifications(true); + expect(await storedSlots(), isEmpty); + homeCalls.clear(); + + await controller.downloadProviderDatabases([BusProvider.khh]); + + expect((await storedSlots()).map((slot) => slot['routeId']).toSet(), { + 'KHH101', + }); + expect(syncedStates(), [true]); + }, + ); + + test('logging out takes other devices\' routes out of the plan', () async { + final otherDevicesRoute = commute(routeKey: 202); + final ownRoute = commute(); + seed( + profiles: [ownRoute, otherDevicesRoute], + notifications: true, + extra: { + 'flutter.auth_token': 'token', + 'flutter.auth_account_id': 'account', + 'flutter.auth_device_id': 'device', + // What this device contributed before it was merged with others. + 'flutter.account_sync_state:account': jsonEncode( + AccountSyncLocalState.empty() + .copyWith( + routeHistoryDevicePayload: { + 'modifiedAtMs': 1, + 'history': const [], + 'routeUsageProfiles': [ownRoute.toJson()], + }, + ) + .toJson(), + ), + }, + ); + final controller = await start( + _Repository(), + authService: _OfflineAuthService(), + ); + await controller.updateEnableSmartRouteNotifications(true); + expect((await storedSlots()).map((slot) => slot['routeKey']).toSet(), { + 101, + 202, + }); + + await controller.logoutAuth(); + + expect(controller.routeUsageProfiles.map((profile) => profile.routeKey), [ + 101, + ]); + expect((await storedSlots()).map((slot) => slot['routeKey']).toSet(), { + 101, + }); + }); + + test('the home screen reads the reminders already shown', () async { + // Every weekday a reminder went out at 07:26 for a habit centred on + // 07:40, and the rider opened the route from it at 07:27. Read without + // the reminders, the habit looks like 07:27. + final ask = daysBefore( + DateTime.now(), + count: 1, + hour: 7, + minute: 35, + ).single; + final days = daysBefore(ask, count: 10, hour: 7, minute: 27); + seed( + profiles: [profileWithVisits(days, provider: BusProvider.khh)], + extra: { + 'flutter.app_settings': jsonEncode({ + ...AppSettings.defaults().toJson(), + 'provider': 'khh', + }), + }, + ); + final log = jsonEncode([ + for (final day in days) + { + 'provider': 'khh', + 'routeKey': 101, + 'pathId': 0, + 'atMs': day + .subtract(const Duration(minutes: 1)) + .millisecondsSinceEpoch, + 'peakMinute': 220, + }, + ]); + final controller = await start(_Repository()); + Future reason({required bool withLog}) async { + messenger.setMockMethodCallHandler(_homeChannel, (call) async { + homeCalls.add(call); + return call.method == 'getSmartRouteReminderLog' && withLog + ? log + : null; + }); + return (await controller.getSmartRouteSuggestions( + now: ask, + )).single.reason; + } + + expect(await reason(withLog: false), '你平日常在 07:25 左右查看這條路線。'); + expect(await reason(withLog: true), '你平日常在 07:40 左右查看這條路線。'); + }); } diff --git a/test/smart_route_plan_test.dart b/test/smart_route_plan_test.dart index 77b9b73d..9f785f6f 100644 --- a/test/smart_route_plan_test.dart +++ b/test/smart_route_plan_test.dart @@ -233,6 +233,42 @@ void main() { } }); + test('each provider has a cap of its own', () { + // The background check only acts on the provider in use. Fifteen routes + // in one city, each surer than the one route in the other, must not + // leave that one without a slot. + final now = DateTime(2026, 4, 8, 5); + final plan = SmartRoutePlanner.build( + profiles: [ + for (var index = 0; index < 15; index++) + profileWithVisits( + daysBefore(now, count: 15, hour: 6 + index, minute: 0), + routeKey: 100 + index, + provider: BusProvider.tpe, + ), + profileWithVisits( + daysBefore(now, count: 4, hour: 7, minute: 40), + routeKey: 500, + provider: BusProvider.khh, + ), + ], + routeIdOf: routeIdOf, + now: now, + ); + + expect( + plan.slots.where((slot) => slot.provider == BusProvider.tpe).length, + SmartRoutePlanner.maxSlots, + ); + expect( + plan.slots + .where((slot) => slot.provider == BusProvider.khh) + .map((slot) => slot.routeKey) + .toSet(), + {500}, + ); + }); + test('a plan drawn up before the usual time does not count today out', () { // An evening trip made on Monday, Tuesday and Wednesday. On Thursday // morning the evening is still to come; by Thursday night it was missed. diff --git a/test/smart_route_service_test.dart b/test/smart_route_service_test.dart index 7445f546..eac68853 100644 --- a/test/smart_route_service_test.dart +++ b/test/smart_route_service_test.dart @@ -6,6 +6,7 @@ import 'package:flutter_test/flutter_test.dart'; import 'package:geolocator/geolocator.dart'; import 'package:taiwanbus_flutter/core/bus_repository.dart'; import 'package:taiwanbus_flutter/core/models.dart'; +import 'package:taiwanbus_flutter/core/smart_route_habit.dart'; import 'package:taiwanbus_flutter/core/smart_route_service.dart'; import 'support/route_usage_fixtures.dart'; @@ -256,16 +257,42 @@ void main() { expect(updated.selectionCountAtHour(18, now: now), 2); }); - test('clearing selections keeps the visits', () { + test('clearing selections keeps the visits but not their stops', () { final now = DateTime.now(); final profile = profileWithVisits([ + now.subtract(const Duration(days: 2)), now.subtract(const Duration(days: 1)), ], stopId: 1001).recordSelection(now); final cleared = profile.clearSelections(); expect(cleared.totalSelectionsAt(now: now), 0); - expect(cleared.visits.single.stopId, 1001); + // Stop usage was promised gone; when the route was opened was not. + expect( + cleared.visits.map((visit) => visit.atMs), + profile.visits.map((visit) => visit.atMs), + ); + expect(cleared.visits.map((visit) => visit.stopId), [null, null]); + expect(cleared.toJson()['visits'], everyElement(isNot(contains('s')))); + }); + + test('a stop learned before clearing selections is not used after', () { + final now = DateTime(2026, 4, 8, 7, 40); + final profile = commute(stopId: 1001, before: now); + expect(SmartRouteService.learnedStopId(profile, now), 1001); + + final cleared = profile.clearSelections(); + + expect(SmartRouteService.learnedStopId(cleared, now), isNull); + expect( + SmartRouteService.chooseBoardingStopId( + profile: cleared, + favoriteProfiles: const [], + favorites: const [], + at: now, + ), + isNull, + ); }); test('visits and their stops survive being saved and loaded', () { @@ -496,6 +523,71 @@ void main() { ); expect(ranked.first.estimate.supportDays, 10); }); + + test('a stop learned before selections were cleared is gone after', () { + final now = DateTime(2026, 4, 8, 7, 40); + final profile = commute(stopId: 1001, before: now); + expect(SmartRouteService.learnedStopId(profile, now), 1001); + + final cleared = profile.clearSelections(); + + expect(SmartRouteService.learnedStopId(cleared, now), isNull); + expect( + SmartRouteService.chooseBoardingStopId( + profile: cleared, + favoriteProfiles: const [], + favorites: const [], + at: now, + ), + isNull, + ); + }); + + test('a reminder tapped early does not move the habit earlier', () { + // Each weekday a reminder went out at 07:26 for a habit centred on + // 07:40, and the route was opened from it at 07:27. An hour later the + // habit is still around 07:40, and still recommended. + final now = DateTime(2026, 4, 8, 8, 37); + final opens = daysBefore(now, count: 10, hour: 7, minute: 27); + final profile = profileWithVisits(opens); + final reminders = [ + for (final open in opens) + SmartRouteReminder( + provider: BusProvider.nwt, + routeKey: 101, + pathId: 0, + atMs: open + .subtract(const Duration(minutes: 1)) + .millisecondsSinceEpoch, + peakMinute: 220, + ), + // Another route's reminders are not this one's. + SmartRouteReminder( + provider: BusProvider.nwt, + routeKey: 102, + pathId: 0, + atMs: now.millisecondsSinceEpoch, + peakMinute: 300, + ), + ]; + + expect(SmartRouteService.rankProfile(profile, now), isNull); + final ranking = SmartRouteService.rankProfile( + profile, + now, + reminders: reminders, + ); + expect(ranking?.fromHabit, isTrue); + expect(ranking!.estimate.supportDays, 10); + expect( + SmartRouteService.chooseProfileForTime( + [profile], + now, + reminders: reminders, + )?.routeKey, + 101, + ); + }); }); group('a profile from before visits were kept', () { @@ -605,6 +697,58 @@ void main() { expect(handedOver, 0); }); + test('is not handed over by use at other times of day', () { + // Upgraded with a long morning record, then used only in the evening + // for a week: those evenings say nothing about the mornings. + final evenings = daysBefore(thisMorning, count: 6, hour: 18, minute: 0); + final profile = RouteUsageProfile.fromJson({ + 'provider': 'nwt', + 'routeKey': 101, + 'pathId': 0, + 'routeName': '307', + 'totalOpens': 8, + 'lastOpenedAtMs': evenings.first + .subtract(const Duration(hours: 11)) + .millisecondsSinceEpoch, + 'hourlyOpens': const {'7': 6, '8': 2}, + }); + var upgraded = profile; + for (final evening in evenings) { + upgraded = upgraded.recordOpen(evening); + } + + final ranking = SmartRouteService.rankProfile(upgraded, thisMorning); + + // Counted as handed over, the counters would be worth nothing and the + // morning route would not be recommended at all. + expect(ranking, isNotNull); + expect(ranking!.fromHabit, isFalse); + expect( + ranking.score, + greaterThanOrEqualTo(SmartRouteService.minProbabilityForRecommendation), + ); + }); + + test('is handed over by use around the same time of day', () { + final mornings = daysBefore( + thisMorning, + count: SmartRouteService.legacyHandoverDays, + hour: 7, + minute: 20, + weekdays: const {1, 2, 3, 4, 5, 6, 7}, + ); + var upgraded = legacy( + lastOpened: mornings.first.subtract(const Duration(days: 1)), + ); + for (final morning in mornings) { + upgraded = upgraded.recordOpen(morning); + } + + final ranking = SmartRouteService.rankProfile(upgraded, thisMorning); + + expect(ranking?.fromHabit, isTrue); + }); + test('counters alone do not qualify a profile that has visits', () { // Five opens in one hour on a profile created after visits were kept: // the counters look like a habit, the visits show it was one morning. From 046ea520c0c6aaef022ab22c27a4342f3b5618ef Mon Sep 17 00:00:00 2001 From: AvianJay Date: Fri, 20 Nov 2026 08:01:51 +0800 Subject: [PATCH 3/5] fix: address follow-up reminder review --- .../flutter/SmartRouteNotificationWorker.kt | 68 +++++++-- .../flutter/SmartRouteReminderRules.kt | 23 +++ .../flutter/SmartRouteReminderRulesTest.kt | 28 ++++ lib/core/app_controller.dart | 50 ++++++- lib/core/models.dart | 28 ++++ lib/screens/route_detail_screen.dart | 27 +++- test/favorite_groups_sync_test.dart | 102 ++++++++++++++ test/models_test.dart | 30 ++++ test/route_detail_screen_loading_test.dart | 133 +++++++++++++++++- 9 files changed, 469 insertions(+), 20 deletions(-) diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt index ca39a313..869c34e7 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteNotificationWorker.kt @@ -70,18 +70,33 @@ class SmartRouteNotificationWorker( return Result.success() } + var activePlan = plan + var activeNow = now + var activeClock = clock + var activeHistory = history + var candidates = dueSlots + val attempted = mutableSetOf>() + // Asked for at most once, and only once a slot has got this far: // a fix costs battery, and most runs end before needing one. val currentLocation by lazy { SmartRouteNotificationSupport.loadCurrentLocation(applicationContext) } - for (slot in dueSlots) { - if (SmartRouteReminderRules.wasSeenForWindow(slot, now, clock.minute)) continue + while (true) { + val slot = candidates.firstOrNull { + attempted.add(it.routeKey to it.pathId) + } ?: break + if (SmartRouteReminderRules.wasSeenForWindow( + slot, + activeNow, + activeClock.minute, + ) + ) continue val lastForRoute = SmartRouteNotificationSupport.loadLastReminderForRoute( applicationContext, slot, ) - if (!SmartRouteReminderRules.mayRemindRoute(lastForRoute, now)) continue + if (!SmartRouteReminderRules.mayRemindRoute(lastForRoute, activeNow)) continue val routeData = SmartRouteNotificationSupport.loadRouteData( applicationContext, slot, @@ -99,9 +114,7 @@ class SmartRouteNotificationWorker( val decision = SmartRouteReminderRules.decide(liveStop, choice.distanceMeters) ?: continue - // Whether or not it went out, this run is done. The next one - // starts again from the plan as it is then. - SmartRouteNotificationSupport.remind( + val shown = SmartRouteNotificationSupport.remind( context = applicationContext, slot = slot, stop = choice.stop, @@ -113,18 +126,53 @@ class SmartRouteNotificationWorker( decision = decision, distanceMeters = choice.distanceMeters, slot = current, - dayStartHour = plan.dayStartHour, + dayStartHour = activePlan.dayStartHour, // The arrival time is counted from when the feed // was read, which is what its seconds are as of. nowMs = liveStop.asOfMs, ) }, timeoutMs = SmartRouteReminderRules.timeoutMs(decision), - history = SmartRouteReminderRules.afterReminder(history, now, clock.day), - nowMs = now, + history = SmartRouteReminderRules.afterReminder( + activeHistory, + activeNow, + activeClock.day, + ), + nowMs = activeNow, checkedAtMs = System.currentTimeMillis(), ) - break + if (shown) break + + // A route can stop being due while its feed is in flight. A + // different candidate may still be valid, but foreground and + // channel checks are global and must stop the whole run. + if (AppRuntimeStateStore.isAppInForeground(applicationContext) || + !SmartRouteNotificationSupport.canPostNotifications(applicationContext) + ) { + break + } + val refreshedPlan = SmartRouteNotificationSupport.loadPlan(applicationContext) + ?: break + val refreshedNow = System.currentTimeMillis() + val refreshedHistory = SmartRouteNotificationSupport.loadHistory( + applicationContext, + ) + val refreshedCandidates = + SmartRouteReminderRules.dueSlotsAfterCandidateFailure( + plan = refreshedPlan, + provider = settings.provider, + nowMs = refreshedNow, + history = refreshedHistory, + attempted = attempted, + ) + activePlan = refreshedPlan + activeNow = refreshedNow + activeClock = SmartRouteReminderRules.serviceClock( + refreshedNow, + refreshedPlan.dayStartHour, + ) + activeHistory = refreshedHistory + candidates = refreshedCandidates } Result.success() } catch (_: Exception) { diff --git a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt index 9f9c32ac..d513688c 100644 --- a/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt +++ b/android/app/src/main/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRules.kt @@ -298,6 +298,29 @@ internal object SmartRouteReminderRules { return history.countDay != today || history.countThatDay < MAX_PER_DAY } + /** + * Re-reads the candidates after one candidate became invalid while its + * feed was being fetched. The attempted set prevents that same candidate + * from being retried, while a still-due route can take its place. + */ + fun dueSlotsAfterCandidateFailure( + plan: SmartRoutePlan?, + provider: String, + nowMs: Long, + history: SmartReminderHistory, + attempted: Set>, + zone: TimeZone = TimeZone.getDefault(), + ): List { + plan ?: return emptyList() + val clock = serviceClock(nowMs, plan.dayStartHour, zone) + if (!mayRemind(history, nowMs, clock.day)) { + return emptyList() + } + return dueSlots(plan, provider, nowMs, zone).filterNot { + (it.routeKey to it.pathId) in attempted + } + } + fun mayRemindRoute(lastForRouteMs: Long, nowMs: Long): Boolean = nowMs - lastForRouteMs >= ROUTE_COOLDOWN_MS diff --git a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt index 164104c7..e5c6de1d 100644 --- a/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt +++ b/android/app/src/test/kotlin/tw/avianjay/taiwanbus/flutter/SmartRouteReminderRulesTest.kt @@ -221,6 +221,34 @@ class SmartRouteReminderRulesTest { assertFalse(SmartRouteReminderRules.hasLiveSlots(plan(), now)) } + @Test + fun aCandidateThatFailedAfterThePlanChangedDoesNotHideAnotherCandidate() { + val now = at(8, 7, 40) + val attempted = setOf(101 to 0) + + assertEquals( + listOf(202 to 0), + SmartRouteReminderRules.dueSlotsAfterCandidateFailure( + plan(slot(routeKey = 202)), + "khh", + now, + SmartReminderHistory(), + attempted, + taipei, + ).map { it.routeKey to it.pathId }, + ) + assertTrue( + SmartRouteReminderRules.dueSlotsAfterCandidateFailure( + plan(slot(routeKey = 202)), + "khh", + now, + SmartReminderHistory(countDay = 2026098L, countThatDay = 6), + attempted, + taipei, + ).isEmpty(), + ) + } + // --- holding a reminder back -------------------------------------------- @Test diff --git a/lib/core/app_controller.dart b/lib/core/app_controller.dart index e212408d..f5ee40a4 100644 --- a/lib/core/app_controller.dart +++ b/lib/core/app_controller.dart @@ -3279,6 +3279,7 @@ class AppController extends ChangeNotifier { await _updateRouteHistoryDevicePayload( profiles: deviceProfiles, destinationChoices: const [], + selectionHistoryClearedAtMs: DateTime.now().millisecondsSinceEpoch, ); } @@ -4144,8 +4145,9 @@ class AppController extends ChangeNotifier { required List profiles, required List destinationChoices, int? modifiedAtMs, + int? selectionHistoryClearedAtMs, }) { - return { + final payload = { 'modifiedAtMs': modifiedAtMs ?? DateTime.now().millisecondsSinceEpoch, 'history': history.map((entry) => entry.toJson()).toList(growable: false), 'routeUsageProfiles': profiles @@ -4155,6 +4157,10 @@ class AppController extends ChangeNotifier { .map((profile) => profile.toJson()) .toList(growable: false), }; + if (selectionHistoryClearedAtMs case final clearedAtMs?) { + payload['selectionHistoryClearedAtMs'] = clearedAtMs; + } + return payload; } List _historyFromRouteHistoryDevice(Object? value) { @@ -4177,6 +4183,13 @@ class AppController extends ChangeNotifier { return entries; } + int? _selectionHistoryClearedAtMs(Object? value) { + final payload = _stringMap(value); + final clearedAtMs = (payload?['selectionHistoryClearedAtMs'] as num?) + ?.toInt(); + return clearedAtMs != null && clearedAtMs > 0 ? clearedAtMs : null; + } + List _profilesFromRouteHistoryDevice(Object? value) { final payload = _stringMap(value); final raw = payload?['routeUsageProfiles']; @@ -4318,6 +4331,7 @@ class AppController extends ChangeNotifier { List? history, List? profiles, List? destinationChoices, + int? selectionHistoryClearedAtMs, }) async { if (!_tracksDeviceRouteHistory) return; final current = _accountSyncLocalState.routeHistoryDevicePayload; @@ -4334,6 +4348,9 @@ class AppController extends ChangeNotifier { destinationChoices ?? _destinationChoicesFromRouteHistoryDevice(current), modifiedAtMs: nowMs, + selectionHistoryClearedAtMs: + selectionHistoryClearedAtMs ?? + _selectionHistoryClearedAtMs(current), ), ); await _saveAccountSyncLocalState(); @@ -4367,6 +4384,20 @@ class AppController extends ChangeNotifier { } if (devices.isEmpty) return; + final localSelectionHistoryClearedAtMs = _selectionHistoryClearedAtMs( + _accountSyncLocalState.routeHistoryDevicePayload, + ); + final remoteOwnPayload = _stringMap(devices[deviceId]); + final remoteSelectionHistoryClearedAtMs = _selectionHistoryClearedAtMs( + remoteOwnPayload, + ); + int? selectionHistoryClearedAtMs = localSelectionHistoryClearedAtMs; + if (remoteSelectionHistoryClearedAtMs != null && + (selectionHistoryClearedAtMs == null || + remoteSelectionHistoryClearedAtMs > selectionHistoryClearedAtMs)) { + selectionHistoryClearedAtMs = remoteSelectionHistoryClearedAtMs; + } + final historyByRoute = {}; final profileParts = >{}; final destinationChoiceParts = >{}; @@ -4379,9 +4410,13 @@ class AppController extends ChangeNotifier { } } for (final profile in _profilesFromRouteHistoryDevice(devicePayload)) { + final effectiveProfile = selectionHistoryClearedAtMs == null + ? profile + : profile.clearStopUsageBefore(selectionHistoryClearedAtMs); final key = - '${profile.provider.name}:${profile.routeKey}:${profile.pathId}'; - (profileParts[key] ??= []).add(profile); + '${effectiveProfile.provider.name}:${effectiveProfile.routeKey}:' + '${effectiveProfile.pathId}'; + (profileParts[key] ??= []).add(effectiveProfile); } for (final profile in _destinationChoicesFromRouteHistoryDevice( devicePayload, @@ -4396,8 +4431,15 @@ class AppController extends ChangeNotifier { final ownPayload = _stringMap(devices[deviceId]); if (ownPayload != null) { + final effectiveOwnPayload = Map.from(ownPayload); + if (selectionHistoryClearedAtMs != null) { + // A response may echo an older copy of this device's bucket. Keep the + // local clear marker so a later merge cannot resurrect old stop ids. + effectiveOwnPayload['selectionHistoryClearedAtMs'] = + selectionHistoryClearedAtMs; + } _accountSyncLocalState = _accountSyncLocalState.copyWith( - routeHistoryDevicePayload: ownPayload, + routeHistoryDevicePayload: effectiveOwnPayload, ); } diff --git a/lib/core/models.dart b/lib/core/models.dart index 06a76a32..1373dcdf 100644 --- a/lib/core/models.dart +++ b/lib/core/models.dart @@ -1701,6 +1701,34 @@ class RouteUsageProfile { ); } + /// Removes selection and stop knowledge from data that existed when the + /// rider cleared selection history, while retaining the visits themselves + /// as route-open evidence. Data made afterwards still belongs to the new + /// history. + RouteUsageProfile clearStopUsageBefore(int clearedAtMs) { + return RouteUsageProfile( + provider: provider, + routeKey: routeKey, + pathId: pathId, + routeName: routeName, + totalOpens: totalOpens, + lastOpenedAtMs: lastOpenedAtMs, + hourlyOpens: hourlyOpens, + selectionTimestampsMs: [ + for (final timestamp in selectionTimestampsMs) + if (timestamp > clearedAtMs) timestamp, + ], + visits: [ + for (final visit in visits) + RouteVisit( + atMs: visit.atMs, + stopId: visit.atMs > clearedAtMs ? visit.stopId : null, + ), + ], + legacyAsOfMs: legacyAsOfMs, + ); + } + RouteUsageProfile pruneSelectionHistory({DateTime? now}) { return RouteUsageProfile( provider: provider, diff --git a/lib/screens/route_detail_screen.dart b/lib/screens/route_detail_screen.dart index b8b152ca..649c270f 100644 --- a/lib/screens/route_detail_screen.dart +++ b/lib/screens/route_detail_screen.dart @@ -239,6 +239,11 @@ class _RouteDetailScreenState extends State /// filled in from the nearest stop and from the stop the page was opened /// on, and only this tells a choice apart from those. int? _riderPickedBoardingStopId; + + /// True after the rider explicitly returns to the location-based candidate. + /// The candidate may be filled into [_boardingStopId] again later, but the + /// old opened stop must not become the visit's source again. + bool _boardingStopUsesCurrentLocation = false; int? _destinationStopId; String? _destinationStopName; bool _hasExplicitDestinationRequest = false; @@ -1479,8 +1484,12 @@ class _RouteDetailScreenState extends State return; } + final requestedBoardingStop = _findStopById( + pathStops, + _requestedStopId, + ); final boardingStop = - _findStopById(pathStops, _requestedStopId) ?? + requestedBoardingStop ?? _findStopById(pathStops, _boardingStopId) ?? _findStopById(pathStops, _nearestStopByPath[resolvedPathId]); @@ -1498,6 +1507,13 @@ class _RouteDetailScreenState extends State _destinationStopName = destinationStop.stopName; _boardingStopId = boardingStop?.stopId; _boardingStopName = boardingStop?.stopName; + // A launch action with an explicit boarding stop replaces an earlier + // manual choice; do not let that stale choice win when the visit is + // recorded later. + if (requestedBoardingStop != null) { + _riderPickedBoardingStopId = null; + _boardingStopUsesCurrentLocation = false; + } }); await _configureBackgroundTripMonitorIfNeeded(); @@ -2738,6 +2754,7 @@ class _RouteDetailScreenState extends State _boardingStopId = stop.stopId; _boardingStopName = stop.stopName; _riderPickedBoardingStopId = stop.stopId; + _boardingStopUsesCurrentLocation = false; }); await _applyLearnedDestinationIfPossible(); await _configureBackgroundTripMonitorIfNeeded(); @@ -2834,6 +2851,7 @@ class _RouteDetailScreenState extends State _boardingStopId = null; _boardingStopName = null; _riderPickedBoardingStopId = null; + _boardingStopUsesCurrentLocation = true; }); await _configureBackgroundTripMonitorIfNeeded(); if (!mounted) { @@ -3133,6 +3151,7 @@ class _RouteDetailScreenState extends State setState(() { _boardingStopId = boardingStop.stopId; _boardingStopName = boardingStop.stopName; + _boardingStopUsesCurrentLocation = true; }); unawaited(_configureBackgroundTripMonitorIfNeeded()); } @@ -3185,7 +3204,11 @@ class _RouteDetailScreenState extends State _currentPathStops, _riderPickedBoardingStopId, )?.stopId, - openedStopId: _findStopById(_currentPathStops, _requestedStopId)?.stopId, + // Clearing the manual boarding stop means "use my current location"; + // the stop that opened the page is no longer a current source. + openedStopId: _boardingStopUsesCurrentLocation + ? null + : _findStopById(_currentPathStops, _requestedStopId)?.stopId, nearestStopId: nearest?.stopId, nearestDistanceMeters: nearest == null || diff --git a/test/favorite_groups_sync_test.dart b/test/favorite_groups_sync_test.dart index 257c0ae6..b71518e1 100644 --- a/test/favorite_groups_sync_test.dart +++ b/test/favorite_groups_sync_test.dart @@ -362,6 +362,108 @@ void main() { expect(controller.history.map((entry) => entry.routeKey), [12]); }, ); + + test( + 'a local stop-history clear survives a later merge from another device', + () async { + final oldVisitAt = DateTime.now() + .subtract(const Duration(hours: 1)) + .millisecondsSinceEpoch; + final remoteProfile = RouteUsageProfile( + provider: BusProvider.tpe, + routeKey: 500, + pathId: 0, + routeName: '500', + totalOpens: 1, + lastOpenedAtMs: oldVisitAt, + visits: [RouteVisit(atMs: oldVisitAt, stopId: 7)], + ); + final syncService = _FakeAccountSyncService( + remotePreferences: { + 'routeHistory': { + 'version': 3, + 'devices': { + 'remote-device': { + 'modifiedAtMs': 1, + 'history': const [], + 'routeUsageProfiles': [remoteProfile.toJson()], + 'destinationChoiceProfiles': const [], + }, + }, + }, + }, + ); + final buildInfo = AppBuildInfo( + version: '1.0.0', + buildNumber: '1', + gitSha: 'test', + defaultUpdateChannel: AppUpdateChannel.release, + ); + final controller = AppController( + repository: BusRepository(), + storage: StorageService(), + analytics: await AppAnalytics.initialize(), + buildInfo: buildInfo, + appUpdateService: AppUpdateService(buildInfo: buildInfo), + appUpdateInstaller: createAppUpdateInstaller(), + authService: _FakeAuthService(), + accountSyncService: syncService, + ); + addTearDown(controller.dispose); + await controller.completeAuthCallback( + const AppLaunchAction( + target: AppLaunchTarget.authCallback, + authToken: 'test-token', + authAccountId: 'test-account', + authDeviceId: 'test-device', + authRole: 'user', + authProvider: 'test', + authDisplayName: 'Test User', + ), + ); + + const route = RouteSummary( + sourceProvider: 'TPE', + hashMd5: '', + routeKey: 500, + routeId: 'TPE500', + routeName: '500', + officialRouteName: '500', + description: '', + category: '', + sequence: 0, + rtrip: 0, + ); + await controller.setRouteHistorySyncEnabled(true); + await controller.recordRouteVisit( + route, + provider: BusProvider.tpe, + pathId: 0, + stopId: 7, + openedAt: DateTime.fromMillisecondsSinceEpoch(oldVisitAt), + ); + await controller.clearRouteSelectionHistory(); + await controller.setAccountSyncEnabled(true); + + expect( + controller.routeUsageProfiles + .expand((profile) => profile.visits) + .where((visit) => visit.atMs <= oldVisitAt) + .map((visit) => visit.stopId), + everyElement(isNull), + ); + // The clear is local policy, not a request to erase the other device's + // cloud bucket. + final sentDevices = + (syncService.preferencePayload!['routeHistory'] as Map)['devices'] + as Map; + final sentRemote = sentDevices['remote-device'] as Map; + final sentVisit = + ((sentRemote['routeUsageProfiles'] as List).single as Map)['visits'] + as List; + expect((sentVisit.single as Map)['s'], 7); + }, + ); } class _FakeAuthService extends AuthService { diff --git a/test/models_test.dart b/test/models_test.dart index e6493588..c90d485b 100644 --- a/test/models_test.dart +++ b/test/models_test.dart @@ -3,6 +3,36 @@ import 'package:taiwanbus_flutter/core/account_sync_models.dart'; import 'package:taiwanbus_flutter/core/models.dart'; void main() { + test( + 'a local stop clear keeps route-open evidence but drops old stop ids', + () { + final clearedAt = DateTime(2026, 11, 20, 9).millisecondsSinceEpoch; + final profile = RouteUsageProfile( + provider: BusProvider.tpe, + routeKey: 500, + pathId: 0, + routeName: '500', + totalOpens: 2, + lastOpenedAtMs: clearedAt + 1, + selectionTimestampsMs: [clearedAt - 1, clearedAt + 1], + visits: [ + RouteVisit(atMs: clearedAt - 1, stopId: 7), + RouteVisit(atMs: clearedAt + 1, stopId: 9), + ], + ); + + final cleared = profile.clearStopUsageBefore(clearedAt); + + expect(cleared.visits.map((visit) => visit.atMs), [ + clearedAt - 1, + clearedAt + 1, + ]); + expect(cleared.visits.map((visit) => visit.stopId), [null, 9]); + expect(cleared.selectionTimestampsMs, [clearedAt + 1]); + expect(cleared.totalOpens, profile.totalOpens); + }, + ); + test('search history round trips route stop and destination identity', () { const entry = SearchHistoryEntry( provider: BusProvider.nwt, diff --git a/test/route_detail_screen_loading_test.dart b/test/route_detail_screen_loading_test.dart index f07bc31e..b08bc106 100644 --- a/test/route_detail_screen_loading_test.dart +++ b/test/route_detail_screen_loading_test.dart @@ -13,8 +13,10 @@ import 'package:taiwanbus_flutter/core/account_sync_service.dart'; import 'package:taiwanbus_flutter/core/app_analytics.dart'; import 'package:taiwanbus_flutter/core/app_build_info.dart'; import 'package:taiwanbus_flutter/core/app_controller.dart'; +import 'package:taiwanbus_flutter/core/app_launch_service.dart'; import 'package:taiwanbus_flutter/core/app_route_observer.dart'; import 'package:taiwanbus_flutter/core/app_update_installer.dart'; +import 'package:taiwanbus_flutter/core/route_detail_launch_bridge.dart'; import 'package:taiwanbus_flutter/core/app_update_service.dart'; import 'package:taiwanbus_flutter/core/auth_service.dart'; import 'package:taiwanbus_flutter/core/bus_repository.dart'; @@ -406,10 +408,12 @@ void main() { expect(stopFor(picked: 7, opened: 3), 7); // A pick that is also the nearest stop is still a pick, however far. expect(stopFor(picked: 9, nearestDistance: 5000), 9); - // Otherwise the stop the page was opened on. - expect(stopFor(opened: 3), 3); - // The nearest stop only when the rider is close enough to board there. - expect(stopFor(nearestDistance: 400), 9); + // A new launch action replaces an earlier manual pick, so the new + // opened stop is used rather than the stale picked source. + expect(stopFor(picked: null, opened: 3), 3); + // After "use my current location" clears the manual source, the old + // opened stop is no longer passed in and the nearby candidate wins. + expect(stopFor(opened: null, nearestDistance: 400), 9); expect(stopFor(nearestDistance: 401), isNull); expect(stopFor(nearestDistance: null), isNull); }); @@ -965,6 +969,127 @@ void main() { initialStopId: 3, ); + _screenTest( + 'returning to the current location does not restore the opened stop', + (tester, repository) async { + debugDefaultTargetPlatformOverride = TargetPlatform.android; + GeolocatorPlatform.instance = _BackgroundLocation(); + const channel = MethodChannel( + 'tw.avianjay.taiwanbus.flutter/trip_monitor', + ); + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + (call) async => call.method == 'isTripMonitorPaused' ? false : null, + ); + addTearDown(() { + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + null, + ); + }); + final controller = AppControllerScope.read( + tester.element(find.byType(RouteDetailScreen)), + ); + await controller.updateEnableRouteBackgroundMonitor(true); + repository.topologyRequests.single.complete(_detail()); + repository.primaryRequests.single.complete(_detail(eta: 300)); + await _frames(tester, 8); + repository.familyRequests.single.completer.complete( + repository.familyRequests.single.selected, + ); + await _frames(tester); + + await tester.tap(find.byTooltip('背景乘車提醒')); + await _frames(tester); + await tester.tap(find.text('變更上車站')); + await _frames(tester); + await tester.tap( + find.descendant( + of: find.byType(BottomSheet), + matching: find.text('返程站5'), + ), + ); + await _frames(tester, 8); + + await tester.tap(find.byTooltip('背景乘車提醒')); + await _frames(tester); + await tester.tap(find.text('清除手動上車站')); + await _frames(tester, 8); + await tester.pump(const Duration(seconds: 10)); + await _frames(tester, 8); + + final visit = controller.routeUsageProfiles.single.visits.single; + expect(visit.stopId, isNull); + }, + initialStopId: 3, + ); + + _screenTest( + 'a new launch boarding stop replaces an earlier manual choice', + (tester, repository) async { + debugDefaultTargetPlatformOverride = TargetPlatform.android; + GeolocatorPlatform.instance = _BackgroundLocation(); + const channel = MethodChannel( + 'tw.avianjay.taiwanbus.flutter/trip_monitor', + ); + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + (call) async => call.method == 'isTripMonitorPaused' ? false : null, + ); + addTearDown(() { + tester.binding.defaultBinaryMessenger.setMockMethodCallHandler( + channel, + null, + ); + }); + final controller = AppControllerScope.read( + tester.element(find.byType(RouteDetailScreen)), + ); + await controller.updateEnableRouteBackgroundMonitor(true); + repository.topologyRequests.single.complete(_detail()); + repository.primaryRequests.single.complete(_detail(eta: 300)); + await _frames(tester, 8); + repository.familyRequests.single.completer.complete( + repository.familyRequests.single.selected, + ); + await _frames(tester); + + await tester.tap(find.byTooltip('背景乘車提醒')); + await _frames(tester); + await tester.tap(find.text('變更上車站')); + await _frames(tester); + await tester.tap( + find.descendant( + of: find.byType(BottomSheet), + matching: find.text('返程站5'), + ), + ); + await _frames(tester, 8); + + expect( + await RouteDetailLaunchBridge.instance.tryHandle( + const AppLaunchAction( + target: AppLaunchTarget.routeDetail, + provider: BusProvider.tpe, + routeKey: 500, + pathId: 1, + stopId: 3, + destinationPathId: 1, + destinationStopId: 9, + ), + ), + isTrue, + ); + await _frames(tester, 8); + await tester.pump(const Duration(seconds: 10)); + await _frames(tester, 8); + + final visit = controller.routeUsageProfiles.single.visits.single; + expect(visit.stopId, 3); + }, + initialStopId: 3, + ); + _screenTest('a new refresh rejects late family results', ( tester, repository, From 51d010179ca1ccadbd6b0ed9b5280934a491b2b6 Mon Sep 17 00:00:00 2001 From: AvianJay Date: Fri, 20 Nov 2026 20:05:45 +0800 Subject: [PATCH 4/5] fix: address automated review follow-ups --- lib/core/app_controller.dart | 104 ++++++++++---- lib/core/models.dart | 18 +++ lib/core/storage_service.dart | 16 +++ lib/screens/route_detail_screen.dart | 14 ++ test/favorite_groups_sync_test.dart | 155 +++++++++++++++++++++ test/models_test.dart | 18 +++ test/route_detail_screen_loading_test.dart | 4 +- 7 files changed, 302 insertions(+), 27 deletions(-) diff --git a/lib/core/app_controller.dart b/lib/core/app_controller.dart index f5ee40a4..bb73e03d 100644 --- a/lib/core/app_controller.dart +++ b/lib/core/app_controller.dart @@ -120,6 +120,7 @@ class AppController extends ChangeNotifier { List _favoriteUsageProfiles = const []; List _stopVisitProfiles = const []; List _destinationChoiceProfiles = const []; + int? _selectionHistoryClearedAtMs; int? _settingsLastModifiedAtMs; int? _favoriteGroupsLastModifiedAtMs; bool _initialized = false; @@ -424,6 +425,8 @@ class AppController extends ChangeNotifier { final history = await storage.loadHistory(); final routes = await storage.loadRouteUsageProfiles(); final destinations = await storage.loadDestinationChoiceProfiles(); + _selectionHistoryClearedAtMs = await storage + .loadSelectionHistoryClearedAtMs(); _history = history; _routeUsageProfiles = routes; _destinationChoiceProfiles = destinations; @@ -843,14 +846,39 @@ class AppController extends ChangeNotifier { if (payload == null) { return; } + final payloadClearedAtMs = _selectionHistoryClearMarkerFromPayload(payload); + int? clearedAtMs = _selectionHistoryClearedAtMs; + if (payloadClearedAtMs != null && + (clearedAtMs == null || payloadClearedAtMs > clearedAtMs)) { + clearedAtMs = payloadClearedAtMs; + _selectionHistoryClearedAtMs = clearedAtMs; + await storage.saveSelectionHistoryClearedAtMs(clearedAtMs); + } _history = _historyFromRouteHistoryDevice( payload, ).take(_settings.maxHistory).toList(growable: false); - _routeUsageProfiles = _profilesFromRouteHistoryDevice(payload) - ..sort(_compareRouteUsageProfiles); - _destinationChoiceProfiles = _destinationChoicesFromRouteHistoryDevice( - payload, - ); + _routeUsageProfiles = + _profilesFromRouteHistoryDevice(payload) + .map( + (profile) => clearedAtMs == null + ? profile + : profile.clearStopUsageBefore(clearedAtMs), + ) + .toList() + ..sort(_compareRouteUsageProfiles); + _destinationChoiceProfiles = + _destinationChoicesFromRouteHistoryDevice(payload) + .map( + (profile) => clearedAtMs == null + ? profile + : profile.clearSelectionsBefore(clearedAtMs), + ) + .where( + (profile) => + clearedAtMs == null || + profile.selectionTimestampsMs.isNotEmpty, + ) + .toList(); await storage.saveHistory(_history); await storage.saveRouteUsageProfiles(_routeUsageProfiles); await storage.saveDestinationChoiceProfiles(_destinationChoiceProfiles); @@ -3271,6 +3299,12 @@ class AppController extends ChangeNotifier { _favoriteUsageProfiles = const []; _stopVisitProfiles = const []; _destinationChoiceProfiles = const []; + final clearedAtMs = math.max( + DateTime.now().millisecondsSinceEpoch, + (_selectionHistoryClearedAtMs ?? 0) + 1, + ); + _selectionHistoryClearedAtMs = clearedAtMs; + await storage.saveSelectionHistoryClearedAtMs(clearedAtMs); await _persistSmartRouteProfiles(); await storage.saveDestinationChoiceProfiles(const []); final deviceProfiles = _profilesFromRouteHistoryDevice( @@ -3279,7 +3313,7 @@ class AppController extends ChangeNotifier { await _updateRouteHistoryDevicePayload( profiles: deviceProfiles, destinationChoices: const [], - selectionHistoryClearedAtMs: DateTime.now().millisecondsSinceEpoch, + selectionHistoryClearedAtMs: clearedAtMs, ); } @@ -4147,6 +4181,8 @@ class AppController extends ChangeNotifier { int? modifiedAtMs, int? selectionHistoryClearedAtMs, }) { + final effectiveSelectionHistoryClearedAtMs = + selectionHistoryClearedAtMs ?? _selectionHistoryClearedAtMs; final payload = { 'modifiedAtMs': modifiedAtMs ?? DateTime.now().millisecondsSinceEpoch, 'history': history.map((entry) => entry.toJson()).toList(growable: false), @@ -4157,7 +4193,7 @@ class AppController extends ChangeNotifier { .map((profile) => profile.toJson()) .toList(growable: false), }; - if (selectionHistoryClearedAtMs case final clearedAtMs?) { + if (effectiveSelectionHistoryClearedAtMs case final clearedAtMs?) { payload['selectionHistoryClearedAtMs'] = clearedAtMs; } return payload; @@ -4183,7 +4219,7 @@ class AppController extends ChangeNotifier { return entries; } - int? _selectionHistoryClearedAtMs(Object? value) { + int? _selectionHistoryClearMarkerFromPayload(Object? value) { final payload = _stringMap(value); final clearedAtMs = (payload?['selectionHistoryClearedAtMs'] as num?) ?.toInt(); @@ -4350,7 +4386,7 @@ class AppController extends ChangeNotifier { modifiedAtMs: nowMs, selectionHistoryClearedAtMs: selectionHistoryClearedAtMs ?? - _selectionHistoryClearedAtMs(current), + _selectionHistoryClearMarkerFromPayload(current), ), ); await _saveAccountSyncLocalState(); @@ -4384,18 +4420,31 @@ class AppController extends ChangeNotifier { } if (devices.isEmpty) return; - final localSelectionHistoryClearedAtMs = _selectionHistoryClearedAtMs( - _accountSyncLocalState.routeHistoryDevicePayload, - ); + int? selectionHistoryClearedAtMs = _selectionHistoryClearedAtMs; + final localPayloadSelectionHistoryClearedAtMs = + _selectionHistoryClearMarkerFromPayload( + _accountSyncLocalState.routeHistoryDevicePayload, + ); final remoteOwnPayload = _stringMap(devices[deviceId]); - final remoteSelectionHistoryClearedAtMs = _selectionHistoryClearedAtMs( - remoteOwnPayload, - ); - int? selectionHistoryClearedAtMs = localSelectionHistoryClearedAtMs; - if (remoteSelectionHistoryClearedAtMs != null && - (selectionHistoryClearedAtMs == null || - remoteSelectionHistoryClearedAtMs > selectionHistoryClearedAtMs)) { - selectionHistoryClearedAtMs = remoteSelectionHistoryClearedAtMs; + final remoteSelectionHistoryClearedAtMs = + _selectionHistoryClearMarkerFromPayload(remoteOwnPayload); + for (final candidate in [ + localPayloadSelectionHistoryClearedAtMs, + remoteSelectionHistoryClearedAtMs, + ]) { + if (candidate != null && + (selectionHistoryClearedAtMs == null || + candidate > selectionHistoryClearedAtMs)) { + selectionHistoryClearedAtMs = candidate; + } + } + if (selectionHistoryClearedAtMs != null && + (_selectionHistoryClearedAtMs == null || + selectionHistoryClearedAtMs > _selectionHistoryClearedAtMs!)) { + _selectionHistoryClearedAtMs = selectionHistoryClearedAtMs; + await storage.saveSelectionHistoryClearedAtMs( + selectionHistoryClearedAtMs, + ); } final historyByRoute = {}; @@ -4421,11 +4470,18 @@ class AppController extends ChangeNotifier { for (final profile in _destinationChoicesFromRouteHistoryDevice( devicePayload, )) { + final effectiveProfile = selectionHistoryClearedAtMs == null + ? profile + : profile.clearSelectionsBefore(selectionHistoryClearedAtMs); + if (selectionHistoryClearedAtMs != null && + effectiveProfile.selectionTimestampsMs.isEmpty) { + continue; + } final key = - '${profile.provider.name}:${profile.routeKey}:' - '${profile.departurePathId}:${profile.boardingStopId}:' - '${profile.destinationPathId}:${profile.destinationStopId}'; - (destinationChoiceParts[key] ??= []).add(profile); + '${effectiveProfile.provider.name}:${effectiveProfile.routeKey}:' + '${effectiveProfile.departurePathId}:${effectiveProfile.boardingStopId}:' + '${effectiveProfile.destinationPathId}:${effectiveProfile.destinationStopId}'; + (destinationChoiceParts[key] ??= []).add(effectiveProfile); } } diff --git a/lib/core/models.dart b/lib/core/models.dart index 1373dcdf..23e7bc44 100644 --- a/lib/core/models.dart +++ b/lib/core/models.dart @@ -984,6 +984,24 @@ class DestinationChoiceProfile { ); } + /// Keeps the choice itself but forgets selections made at or before a local + /// history clear. An empty result is no longer a learned choice. + DestinationChoiceProfile clearSelectionsBefore(int clearedAtMs) { + return DestinationChoiceProfile( + provider: provider, + routeKey: routeKey, + departurePathId: departurePathId, + boardingStopId: boardingStopId, + destinationPathId: destinationPathId, + destinationStopId: destinationStopId, + destinationStopName: destinationStopName, + selectionTimestampsMs: [ + for (final timestamp in selectionTimestampsMs) + if (timestamp > clearedAtMs) timestamp, + ], + ); + } + Map toJson() => { 'provider': provider.name, 'routeKey': routeKey, diff --git a/lib/core/storage_service.dart b/lib/core/storage_service.dart index fd0f8523..5c252879 100644 --- a/lib/core/storage_service.dart +++ b/lib/core/storage_service.dart @@ -17,6 +17,8 @@ class StorageService { static const _favoriteUsageProfilesKey = 'favorite_usage_profiles'; static const _stopVisitProfilesKey = 'stop_visit_profiles'; static const _destinationChoiceProfilesKey = 'destination_choice_profiles'; + static const _selectionHistoryClearedAtKey = + 'route_selection_history_cleared_at_ms'; static const _smartRoutePlanKey = 'smart_route_plan'; static const _announcementLocalStateKey = 'announcement_local_state'; static const _settingsLastModifiedAtKey = 'app_settings_last_modified_at_ms'; @@ -392,6 +394,20 @@ class StorageService { ); } + /// The local clear boundary is kept separately from the synced device + /// payload, so clearing before route-history sync is first enabled still + /// prevents an old cloud snapshot from being imported later. + Future loadSelectionHistoryClearedAtMs() async { + final prefs = await SharedPreferences.getInstance(); + final value = prefs.getInt(_selectionHistoryClearedAtKey); + return value != null && value > 0 ? value : null; + } + + Future saveSelectionHistoryClearedAtMs(int clearedAtMs) async { + final prefs = await SharedPreferences.getInstance(); + await prefs.setInt(_selectionHistoryClearedAtKey, clearedAtMs); + } + Future loadAnnouncementLocalState() async { final prefs = await SharedPreferences.getInstance(); final raw = prefs.getString(_announcementLocalStateKey); diff --git a/lib/screens/route_detail_screen.dart b/lib/screens/route_detail_screen.dart index 649c270f..d736378a 100644 --- a/lib/screens/route_detail_screen.dart +++ b/lib/screens/route_detail_screen.dart @@ -1359,6 +1359,14 @@ class _RouteDetailScreenState extends State requestedPathId: requestedPathId, requestedStopId: requestedStopId, ); + final requestedBoardingStop = detail == null || resolvedPathId == null + ? null + : _findStopById( + detail.stopsByPath[resolvedPathId] ?? const [], + requestedStopId, + ); + final replacesBoardingSource = requestedStopId != null && + (detail == null || requestedBoardingStop != null); setState(() { _requestedPathId = resolvedPathId; @@ -1371,6 +1379,12 @@ class _RouteDetailScreenState extends State _targetInitialPathId = resolvedPathId; _didScrollToInitialStop = requestedStopId == null; _autoScrolledPathId = null; + if (replacesBoardingSource) { + _boardingStopId = requestedStopId; + _boardingStopName = requestedBoardingStop?.stopName; + _riderPickedBoardingStopId = null; + _boardingStopUsesCurrentLocation = false; + } }); if (detail != null && _tabController != null && resolvedPathId != null) { diff --git a/test/favorite_groups_sync_test.dart b/test/favorite_groups_sync_test.dart index b71518e1..c924eec3 100644 --- a/test/favorite_groups_sync_test.dart +++ b/test/favorite_groups_sync_test.dart @@ -464,6 +464,161 @@ void main() { expect((sentVisit.single as Map)['s'], 7); }, ); + + test( + 'a clear before first sync tombstones old destination choices', + () async { + final oldSelectionAt = DateTime.now() + .subtract(const Duration(hours: 1)) + .millisecondsSinceEpoch; + final remoteChoice = DestinationChoiceProfile( + provider: BusProvider.tpe, + routeKey: 500, + departurePathId: 0, + boardingStopId: 7, + destinationPathId: 0, + destinationStopId: 12, + selectionTimestampsMs: [oldSelectionAt], + ); + final syncService = _FakeAccountSyncService( + remotePreferences: { + 'routeHistory': { + 'version': 3, + 'devices': { + 'remote-device': { + 'modifiedAtMs': 1, + 'history': const [], + 'routeUsageProfiles': const [], + 'destinationChoiceProfiles': [remoteChoice.toJson()], + }, + }, + }, + }, + ); + final storage = StorageService(); + final buildInfo = AppBuildInfo( + version: '1.0.0', + buildNumber: '1', + gitSha: 'test', + defaultUpdateChannel: AppUpdateChannel.release, + ); + final controller = AppController( + repository: BusRepository(), + storage: storage, + analytics: await AppAnalytics.initialize(), + buildInfo: buildInfo, + appUpdateService: AppUpdateService(buildInfo: buildInfo), + appUpdateInstaller: createAppUpdateInstaller(), + authService: _FakeAuthService(), + accountSyncService: syncService, + ); + addTearDown(controller.dispose); + await controller.completeAuthCallback( + const AppLaunchAction( + target: AppLaunchTarget.authCallback, + authToken: 'test-token', + authAccountId: 'test-account', + authDeviceId: 'test-device', + authRole: 'user', + authProvider: 'test', + authDisplayName: 'Test User', + ), + ); + + await controller.clearRouteSelectionHistory(); + await controller.setRouteHistorySyncEnabled(true); + await controller.setAccountSyncEnabled(true); + + expect(controller.destinationChoiceProfiles, isEmpty); + final devices = + (syncService.preferencePayload!['routeHistory'] as Map)['devices'] + as Map; + expect( + (devices['test-device'] as Map)['selectionHistoryClearedAtMs'], + isNotNull, + ); + // The local tombstone filters the imported result; it does not erase the + // other device's cloud bucket from the document. + expect( + ((devices['remote-device'] as Map)['destinationChoiceProfiles'] + as List), + hasLength(1), + ); + }, + ); + + test('logout restore applies the local clear tombstone', () async { + final oldAt = DateTime.now() + .subtract(const Duration(hours: 1)) + .millisecondsSinceEpoch; + final clearedAt = DateTime.now().millisecondsSinceEpoch; + final routeProfile = RouteUsageProfile( + provider: BusProvider.tpe, + routeKey: 500, + pathId: 0, + routeName: '500', + totalOpens: 1, + lastOpenedAtMs: oldAt, + visits: [RouteVisit(atMs: oldAt, stopId: 7)], + ); + final destinationProfile = DestinationChoiceProfile( + provider: BusProvider.tpe, + routeKey: 500, + departurePathId: 0, + boardingStopId: 7, + destinationPathId: 0, + destinationStopId: 12, + selectionTimestampsMs: [oldAt], + ); + final storage = StorageService(); + await storage.saveAccountSyncLocalState( + 'test-account', + AccountSyncLocalState.empty().copyWith( + routeHistorySyncEnabled: true, + routeHistoryModifiedAtMs: clearedAt, + routeHistoryDevicePayload: { + 'modifiedAtMs': clearedAt, + 'selectionHistoryClearedAtMs': clearedAt, + 'history': const [], + 'routeUsageProfiles': [routeProfile.toJson()], + 'destinationChoiceProfiles': [destinationProfile.toJson()], + }, + ), + ); + final buildInfo = AppBuildInfo( + version: '1.0.0', + buildNumber: '1', + gitSha: 'test', + defaultUpdateChannel: AppUpdateChannel.release, + ); + final controller = AppController( + repository: BusRepository(), + storage: storage, + analytics: await AppAnalytics.initialize(), + buildInfo: buildInfo, + appUpdateService: AppUpdateService(buildInfo: buildInfo), + appUpdateInstaller: createAppUpdateInstaller(), + authService: _FakeAuthService(), + accountSyncService: _FakeAccountSyncService(), + ); + addTearDown(controller.dispose); + await controller.completeAuthCallback( + const AppLaunchAction( + target: AppLaunchTarget.authCallback, + authToken: 'test-token', + authAccountId: 'test-account', + authDeviceId: 'test-device', + authRole: 'user', + authProvider: 'test', + authDisplayName: 'Test User', + ), + ); + + await controller.logoutAuth(); + + expect(controller.routeUsageProfiles.single.visits.single.stopId, isNull); + expect(controller.destinationChoiceProfiles, isEmpty); + }); } class _FakeAuthService extends AuthService { diff --git a/test/models_test.dart b/test/models_test.dart index c90d485b..3806edbd 100644 --- a/test/models_test.dart +++ b/test/models_test.dart @@ -33,6 +33,24 @@ void main() { }, ); + test('a local clear drops old destination choice selections', () { + final clearedAt = DateTime(2026, 11, 20, 9).millisecondsSinceEpoch; + final profile = DestinationChoiceProfile( + provider: BusProvider.tpe, + routeKey: 500, + departurePathId: 0, + boardingStopId: 7, + destinationPathId: 0, + destinationStopId: 12, + selectionTimestampsMs: [clearedAt - 1, clearedAt + 1], + ); + + final cleared = profile.clearSelectionsBefore(clearedAt); + + expect(cleared.selectionTimestampsMs, [clearedAt + 1]); + expect(cleared.destinationStopId, profile.destinationStopId); + }); + test('search history round trips route stop and destination identity', () { const entry = SearchHistoryEntry( provider: BusProvider.nwt, diff --git a/test/route_detail_screen_loading_test.dart b/test/route_detail_screen_loading_test.dart index b08bc106..f8a7a5a1 100644 --- a/test/route_detail_screen_loading_test.dart +++ b/test/route_detail_screen_loading_test.dart @@ -1025,7 +1025,7 @@ void main() { ); _screenTest( - 'a new launch boarding stop replaces an earlier manual choice', + 'a boarding-only launch replaces an earlier manual choice', (tester, repository) async { debugDefaultTargetPlatformOverride = TargetPlatform.android; GeolocatorPlatform.instance = _BackgroundLocation(); @@ -1074,8 +1074,6 @@ void main() { routeKey: 500, pathId: 1, stopId: 3, - destinationPathId: 1, - destinationStopId: 9, ), ), isTrue, From a8f62c6d30b9023c2ee330fa9287e70d1150d8df Mon Sep 17 00:00:00 2001 From: AvianJay Date: Sat, 21 Nov 2026 09:43:07 +0800 Subject: [PATCH 5/5] fix: address latest Hermes review --- lib/core/account_sync_models.dart | 16 ++++++++++ lib/core/app_controller.dart | 44 ++++++++++++++++++++++++---- lib/core/storage_service.dart | 16 ---------- lib/screens/route_detail_screen.dart | 16 +++++++++- test/models_test.dart | 2 ++ 5 files changed, 71 insertions(+), 23 deletions(-) diff --git a/lib/core/account_sync_models.dart b/lib/core/account_sync_models.dart index 57e6f908..36bf40c1 100644 --- a/lib/core/account_sync_models.dart +++ b/lib/core/account_sync_models.dart @@ -324,6 +324,7 @@ class AccountSyncLocalState { this.routeHistorySyncEnabled = false, this.routeHistoryDeletionPending = false, this.routeHistoryModifiedAtMs, + this.routeHistorySelectionHistoryClearedAtMs, this.routeHistoryDevicePayload, }); @@ -333,6 +334,7 @@ class AccountSyncLocalState { final bool routeHistorySyncEnabled; final bool routeHistoryDeletionPending; final int? routeHistoryModifiedAtMs; + final int? routeHistorySelectionHistoryClearedAtMs; final Map? routeHistoryDevicePayload; factory AccountSyncLocalState.empty() { @@ -370,6 +372,9 @@ class AccountSyncLocalState { routeHistoryModifiedAtMs: _jsonIntOrNull( json['route_history_modified_at_ms'], ), + routeHistorySelectionHistoryClearedAtMs: _jsonIntOrNull( + json['route_history_selection_history_cleared_at_ms'], + ), routeHistoryDevicePayload: json['route_history_device_payload'] is Map ? (json['route_history_device_payload'] as Map).map( (key, value) => MapEntry(key.toString(), _deepCloneJson(value)), @@ -397,6 +402,8 @@ class AccountSyncLocalState { routeHistorySyncEnabled: routeHistorySyncEnabled, routeHistoryDeletionPending: routeHistoryDeletionPending, routeHistoryModifiedAtMs: routeHistoryModifiedAtMs, + routeHistorySelectionHistoryClearedAtMs: + routeHistorySelectionHistoryClearedAtMs, routeHistoryDevicePayload: routeHistoryDevicePayload, ), AccountSyncNamespace.preferences => AccountSyncLocalState( @@ -406,6 +413,8 @@ class AccountSyncLocalState { routeHistorySyncEnabled: routeHistorySyncEnabled, routeHistoryDeletionPending: routeHistoryDeletionPending, routeHistoryModifiedAtMs: routeHistoryModifiedAtMs, + routeHistorySelectionHistoryClearedAtMs: + routeHistorySelectionHistoryClearedAtMs, routeHistoryDevicePayload: routeHistoryDevicePayload, ), }; @@ -419,6 +428,7 @@ class AccountSyncLocalState { bool? routeHistoryDeletionPending, int? routeHistoryModifiedAtMs, bool clearRouteHistoryModifiedAtMs = false, + int? routeHistorySelectionHistoryClearedAtMs, Map? routeHistoryDevicePayload, bool clearRouteHistoryDevicePayload = false, }) { @@ -435,6 +445,9 @@ class AccountSyncLocalState { routeHistoryModifiedAtMs: clearRouteHistoryModifiedAtMs ? null : (routeHistoryModifiedAtMs ?? this.routeHistoryModifiedAtMs), + routeHistorySelectionHistoryClearedAtMs: + routeHistorySelectionHistoryClearedAtMs ?? + this.routeHistorySelectionHistoryClearedAtMs, routeHistoryDevicePayload: clearRouteHistoryDevicePayload ? null : (routeHistoryDevicePayload ?? this.routeHistoryDevicePayload), @@ -450,6 +463,9 @@ class AccountSyncLocalState { 'route_history_deletion_pending': routeHistoryDeletionPending, if (routeHistoryModifiedAtMs != null) 'route_history_modified_at_ms': routeHistoryModifiedAtMs, + if (routeHistorySelectionHistoryClearedAtMs != null) + 'route_history_selection_history_cleared_at_ms': + routeHistorySelectionHistoryClearedAtMs, if (routeHistoryDevicePayload != null) 'route_history_device_payload': jsonDecode( jsonEncode(routeHistoryDevicePayload), diff --git a/lib/core/app_controller.dart b/lib/core/app_controller.dart index bb73e03d..148d18b4 100644 --- a/lib/core/app_controller.dart +++ b/lib/core/app_controller.dart @@ -422,14 +422,16 @@ class AppController extends ChangeNotifier { _favoriteGroupKinds = kinds; _favoriteGroupsLastModifiedAtMs = modifiedAt; case AppLocalData.routeHistory: + await ensureAccountReady(); final history = await storage.loadHistory(); final routes = await storage.loadRouteUsageProfiles(); final destinations = await storage.loadDestinationChoiceProfiles(); - _selectionHistoryClearedAtMs = await storage - .loadSelectionHistoryClearedAtMs(); + _selectionHistoryClearedAtMs = + _accountSyncLocalState.routeHistorySelectionHistoryClearedAtMs; _history = history; _routeUsageProfiles = routes; _destinationChoiceProfiles = destinations; + await _applySelectionHistoryClearToLoadedData(); case AppLocalData.smartUsage: final favorites = await storage.loadFavoriteUsageProfiles(); final visits = await storage.loadStopVisitProfiles(); @@ -818,13 +820,19 @@ class AppController extends ChangeNotifier { final accountId = _authSession?.accountId.trim() ?? ''; if (accountId.isEmpty) { _accountSyncLocalState = AccountSyncLocalState.empty(); + _selectionHistoryClearedAtMs = null; _accountSyncSummary = null; _accountSyncError = null; return; } _accountSyncLocalState = await storage.loadAccountSyncLocalState(accountId); + _selectionHistoryClearedAtMs = + _accountSyncLocalState.routeHistorySelectionHistoryClearedAtMs; _accountSyncSummary = null; _accountSyncError = null; + if (routeHistoryReady) { + await _applySelectionHistoryClearToLoadedData(); + } } Future _saveAccountSyncLocalState() async { @@ -837,10 +845,27 @@ class AppController extends ChangeNotifier { void _clearAccountSyncSessionData() { _accountSyncLocalState = AccountSyncLocalState.empty(); + _selectionHistoryClearedAtMs = null; _accountSyncSummary = null; _accountSyncError = null; } + Future _applySelectionHistoryClearToLoadedData() async { + final clearedAtMs = _selectionHistoryClearedAtMs; + if (clearedAtMs == null) { + return; + } + _routeUsageProfiles = _routeUsageProfiles + .map((profile) => profile.clearStopUsageBefore(clearedAtMs)) + .toList(growable: false); + _destinationChoiceProfiles = _destinationChoiceProfiles + .map((profile) => profile.clearSelectionsBefore(clearedAtMs)) + .where((profile) => profile.selectionTimestampsMs.isNotEmpty) + .toList(growable: false); + await storage.saveRouteUsageProfiles(_routeUsageProfiles); + await storage.saveDestinationChoiceProfiles(_destinationChoiceProfiles); + } + Future _restoreDeviceLocalRouteHistory() async { final payload = _accountSyncLocalState.routeHistoryDevicePayload; if (payload == null) { @@ -852,7 +877,10 @@ class AppController extends ChangeNotifier { (clearedAtMs == null || payloadClearedAtMs > clearedAtMs)) { clearedAtMs = payloadClearedAtMs; _selectionHistoryClearedAtMs = clearedAtMs; - await storage.saveSelectionHistoryClearedAtMs(clearedAtMs); + _accountSyncLocalState = _accountSyncLocalState.copyWith( + routeHistorySelectionHistoryClearedAtMs: clearedAtMs, + ); + await _saveAccountSyncLocalState(); } _history = _historyFromRouteHistoryDevice( payload, @@ -3304,7 +3332,10 @@ class AppController extends ChangeNotifier { (_selectionHistoryClearedAtMs ?? 0) + 1, ); _selectionHistoryClearedAtMs = clearedAtMs; - await storage.saveSelectionHistoryClearedAtMs(clearedAtMs); + _accountSyncLocalState = _accountSyncLocalState.copyWith( + routeHistorySelectionHistoryClearedAtMs: clearedAtMs, + ); + await _saveAccountSyncLocalState(); await _persistSmartRouteProfiles(); await storage.saveDestinationChoiceProfiles(const []); final deviceProfiles = _profilesFromRouteHistoryDevice( @@ -4442,9 +4473,10 @@ class AppController extends ChangeNotifier { (_selectionHistoryClearedAtMs == null || selectionHistoryClearedAtMs > _selectionHistoryClearedAtMs!)) { _selectionHistoryClearedAtMs = selectionHistoryClearedAtMs; - await storage.saveSelectionHistoryClearedAtMs( - selectionHistoryClearedAtMs, + _accountSyncLocalState = _accountSyncLocalState.copyWith( + routeHistorySelectionHistoryClearedAtMs: selectionHistoryClearedAtMs, ); + await _saveAccountSyncLocalState(); } final historyByRoute = {}; diff --git a/lib/core/storage_service.dart b/lib/core/storage_service.dart index 5c252879..fd0f8523 100644 --- a/lib/core/storage_service.dart +++ b/lib/core/storage_service.dart @@ -17,8 +17,6 @@ class StorageService { static const _favoriteUsageProfilesKey = 'favorite_usage_profiles'; static const _stopVisitProfilesKey = 'stop_visit_profiles'; static const _destinationChoiceProfilesKey = 'destination_choice_profiles'; - static const _selectionHistoryClearedAtKey = - 'route_selection_history_cleared_at_ms'; static const _smartRoutePlanKey = 'smart_route_plan'; static const _announcementLocalStateKey = 'announcement_local_state'; static const _settingsLastModifiedAtKey = 'app_settings_last_modified_at_ms'; @@ -394,20 +392,6 @@ class StorageService { ); } - /// The local clear boundary is kept separately from the synced device - /// payload, so clearing before route-history sync is first enabled still - /// prevents an old cloud snapshot from being imported later. - Future loadSelectionHistoryClearedAtMs() async { - final prefs = await SharedPreferences.getInstance(); - final value = prefs.getInt(_selectionHistoryClearedAtKey); - return value != null && value > 0 ? value : null; - } - - Future saveSelectionHistoryClearedAtMs(int clearedAtMs) async { - final prefs = await SharedPreferences.getInstance(); - await prefs.setInt(_selectionHistoryClearedAtKey, clearedAtMs); - } - Future loadAnnouncementLocalState() async { final prefs = await SharedPreferences.getInstance(); final raw = prefs.getString(_announcementLocalStateKey); diff --git a/lib/screens/route_detail_screen.dart b/lib/screens/route_detail_screen.dart index d736378a..5c9d4ecd 100644 --- a/lib/screens/route_detail_screen.dart +++ b/lib/screens/route_detail_screen.dart @@ -1206,11 +1206,20 @@ class _RouteDetailScreenState extends State if (_tabController!.indexIsChanging) { return; } + final boardingStop = _findStopById(_currentPathStops, _boardingStopId); + if (_boardingStopId != null && boardingStop == null) { + _boardingStopId = null; + _boardingStopName = null; + if (_riderPickedBoardingStopId != null) { + _riderPickedBoardingStopId = null; + _boardingStopUsesCurrentLocation = true; + } + _resetLiveActivityRideState(); + } if (_destinationStopId != null && _currentPathStops.every( (stop) => stop.stopId != _destinationStopId, )) { - final boardingStop = _findStopById(_currentPathStops, _boardingStopId); _boardingStopId = boardingStop?.stopId; _boardingStopName = boardingStop?.stopName; _destinationStopId = null; @@ -1380,10 +1389,15 @@ class _RouteDetailScreenState extends State _didScrollToInitialStop = requestedStopId == null; _autoScrolledPathId = null; if (replacesBoardingSource) { + _resetLiveActivityRideState(); + _resetLiveActivityDestinationState(); _boardingStopId = requestedStopId; _boardingStopName = requestedBoardingStop?.stopName; _riderPickedBoardingStopId = null; _boardingStopUsesCurrentLocation = false; + _destinationStopId = null; + _destinationStopName = null; + _hasExplicitDestinationRequest = requestedDestinationStopId != null; } }); diff --git a/test/models_test.dart b/test/models_test.dart index 3806edbd..1fefc01d 100644 --- a/test/models_test.dart +++ b/test/models_test.dart @@ -469,6 +469,7 @@ void main() { syncEnabled: true, routeHistorySyncEnabled: true, routeHistoryModifiedAtMs: 1716000000100, + routeHistorySelectionHistoryClearedAtMs: 1716000000200, routeHistoryDevicePayload: const { 'modifiedAtMs': 1716000000100, 'history': [], @@ -494,6 +495,7 @@ void main() { expect(restored.syncEnabled, isTrue); expect(restored.routeHistorySyncEnabled, isTrue); expect(restored.routeHistoryModifiedAtMs, 1716000000100); + expect(restored.routeHistorySelectionHistoryClearedAtMs, 1716000000200); expect(restored.routeHistoryDevicePayload?['history'], isEmpty); expect(restored.preferences.lastSyncedServerRevision, 4); expect(