feat: mutual pass FM/Linear transponder filters (AMSAT Live source)

Mutual match page gains FM/Linear transponder-type filters. The
authoritative source is AMSAT's human-maintained Live FM/Linear
Satellites pages, fetched during data sync and stored as catnum sets;
filters resolve to those sets (falling back to DB mode filter when
empty), and unchecking both shows a prompt instead of querying.

- DataParser.parseAmSatLivePage: table rows to satellite names,
  TEVEL2-1 thru TEVEL2-9 range expansion, bracket-alias matching
- SettingsRepo: AMSAT FM/Linear catnum sets persisted in prefs
- DatabaseRepo: fetch AMSAT pages in updateFromRemote, best-effort
  (failure keeps previous list, never blocks the update)
- getIdsWithModes: AND isAlive = 1
- MutualScreen: FilterChip row inside MatchSearchCard
- Tests: parser (4) + viewmodel (3) + repo fakes

feature/mutual/src/main/java/com/rtbishop/look4sat/feature/mutual/MutualScreen.kt

@@ -174,6 +174,8 @@ fun MutualScreen(
             onStationBMinElev = viewModel::onStationBMinElev,
             onUseCurrentPosition = viewModel::onUseCurrentPosition,
             onHoursAhead = viewModel::onHoursAhead,
+            onFilterFM = viewModel::onFilterFM,
+            onFilterLinear = viewModel::onFilterLinear,
             onClearError = viewModel::clearError
         )
     }
@@ -197,6 +199,8 @@ private fun MutualContent(
     onStationBMinElev: (Double) -> Unit,
     onUseCurrentPosition: () -> Unit,
     onHoursAhead: (Int) -> Unit,
+    onFilterFM: (Boolean) -> Unit,
+    onFilterLinear: (Boolean) -> Unit,
     onClearError: () -> Unit
 ) {
     val timeFormat = remember(state.isUtc) {
@@ -353,6 +357,10 @@ private fun MutualContent(
             MatchSearchCard(
                 hoursAhead = state.hoursAhead,
                 isCalculating = state.isCalculating,
+                filterFM = state.filterFM,
+                filterLinear = state.filterLinear,
+                onFilterFM = onFilterFM,
+                onFilterLinear = onFilterLinear,
                 onHoursAhead = onHoursAhead,
                 onQuery = onQuery
             )
@@ -570,6 +578,10 @@ private fun StationInputCard(
 private fun MatchSearchCard(
     hoursAhead: Int,
     isCalculating: Boolean,
+    filterFM: Boolean,
+    filterLinear: Boolean,
+    onFilterFM: (Boolean) -> Unit,
+    onFilterLinear: (Boolean) -> Unit,
     onHoursAhead: (Int) -> Unit,
     onQuery: () -> Unit,
     modifier: Modifier = Modifier
@@ -596,6 +608,28 @@ private fun MatchSearchCard(
                     )
                 }
             }
+            // 转发器类型筛选: 只匹配 AMSAT Live 清单里的 FM 话音 / 线性转发器卫星,
+            // 防止选入大量无转发器卫星占用匹配页.
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.spacedBy(8.dp),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                Text(
+                    text = stringResource(R.string.mutual_filter_transponder),
+                    style = MaterialTheme.typography.labelLarge
+                )
+                FilterChip(
+                    selected = filterFM,
+                    onClick = { onFilterFM(!filterFM) },
+                    label = { Text(stringResource(R.string.mutual_filter_fm)) }
+                )
+                FilterChip(
+                    selected = filterLinear,
+                    onClick = { onFilterLinear(!filterLinear) },
+                    label = { Text(stringResource(R.string.mutual_filter_linear)) }
+                )
+            }
             Button(
                 onClick = onQuery,
                 enabled = !isCalculating,

feature/mutual/src/main/java/com/rtbishop/look4sat/feature/mutual/MutualViewModel.kt

@@ -55,6 +55,10 @@ data class MutualUiState(
     /** 历史过境回看窗口(小时), 跟随主页面 Passes 设置; 匹配查询从
      *  now-hoursBefore 开始, 使设置过历史回看时匹配页也包含历史过境. */
     val hoursBefore: Int = 0,
+    /** 转发器类型筛选: 只匹配搭载 FM 话音转发器的卫星. 默认开启. */
+    val filterFM: Boolean = true,
+    /** 转发器类型筛选: 只匹配搭载线性(USB/LSB/CW/SSB)转发器的卫星. 默认开启. */
+    val filterLinear: Boolean = true,
     val mutualPasses: List<MutualPass> = emptyList(),
     val isCalculating: Boolean = false,
     val hasSearched: Boolean = false,
@@ -201,6 +205,8 @@ class MutualViewModel(
         ) }
     }
     fun onHoursAhead(value: Int) = _uiState.update { it.copy(hoursAhead = value) }
+    fun onFilterFM(value: Boolean) = _uiState.update { it.copy(filterFM = value) }
+    fun onFilterLinear(value: Boolean) = _uiState.update { it.copy(filterLinear = value) }
     fun onSelectPass(index: Int) = _uiState.update { it.copy(selectedPassIndex = index) }
 
     /**
@@ -264,6 +270,17 @@ class MutualViewModel(
             return
         }
 
+        // 转发器类型筛选: 至少勾选一种(默认 FM + Linear 都开), 否则提示不查询.
+        // 防止用户选入大量无转发器卫星占用匹配页.
+        if (!state.filterFM && !state.filterLinear) {
+            _uiState.update { it.copy(errorMessage = "Select at least one transponder type (FM / Linear) to run the match.") }
+            return
+        }
+        // AMSAT Live 清单(同步自 AMSAT "Live FM/Linear Satellites" 页面)是本过滤的
+        // 权威来源: 只匹配当前在轨且话音/线性转发器实际工作的卫星. 清单为空
+        // (从未成功同步过)时回退到数据库 downlinkMode 过滤, 避免首启匹配页空结果.
+        // 过滤本身在下面的协程里执行 (getSatelliteIdsWithModes 是 suspend).
+
         _uiState.update {
             it.copy(
                 isCalculating = true,
@@ -286,6 +303,24 @@ class MutualViewModel(
 
         viewModelScope.launch {
             val now = System.currentTimeMillis()
+            // 转发器类型过滤(协程上下文): AMSAT Live 清单优先, 为空时回退数据库.
+            val amSatFm = settingsRepo.getAmSatFmCatnums()
+            val amSatLinear = settingsRepo.getAmSatLinearCatnums()
+            val filteredSatellites = if (amSatFm.isEmpty() && amSatLinear.isEmpty()) {
+                val filterModes = buildList {
+                    if (state.filterFM) add("FM")
+                    if (state.filterLinear) addAll(listOf("USB", "LSB", "CW", "SSB"))
+                }
+                val idsWithModes = satelliteRepo.getSatelliteIdsWithModes(filterModes)
+                if (idsWithModes.isEmpty()) satellites
+                else satellites.filter { it.data.catnum in idsWithModes }
+            } else {
+                val allowed = buildSet {
+                    if (state.filterFM) addAll(amSatFm)
+                    if (state.filterLinear) addAll(amSatLinear)
+                }
+                satellites.filter { it.data.catnum in allowed }
+            }
             // 历史回看: 查询窗口起点 = now - hoursBefore (跟随主页面 Passes 设置),
             // 终点 = now + hoursAhead 不变.
             val time = now - state.hoursBefore * 60L * 60L * 1000L
@@ -295,7 +330,7 @@ class MutualViewModel(
 
             val results = try {
                 withContext(computeDispatcher) {
-                    findMutualPasses(satellites, posA, posB, minElevA, minElevB, time, hours, state.hoursBefore)
+                    findMutualPasses(filteredSatellites, posA, posB, minElevA, minElevB, time, hours, state.hoursBefore)
                 }
             } catch (t: Throwable) {
                 // Never leave the query stuck in "calculating" (which would also
@@ -350,7 +385,10 @@ class MutualViewModel(
         // Use the main page's pass list for AOS/LOS times, then sample the curves
         // using the actual positions. The passes list is already computed by getLeoPass
         // and its AOS/LOS times match the Passes page exactly.
-        val existingPasses = satelliteRepo.passes.value
+        // The satellites argument may be a subset (transponder-type filter), so
+        // only passes belonging to the filtered satellites are reused.
+        val allowedCatnums = satellites.map { it.data.catnum }.toSet()
+        val existingPasses = satelliteRepo.passes.value.filter { it.catNum in allowedCatnums }
         val results = findMutualPassesFromList(existingPasses, satellites, posA, posB,
             minElevADeg, minElevBDeg, time, endTime, sampleInterval)
         if (results.isNotEmpty()) return results

feature/mutual/src/test/java/com/rtbishop/look4sat/feature/mutual/Fakes.kt

@@ -44,13 +44,18 @@ class FakeSatelliteRepo(
     override suspend fun getTrack(sat: OrbitalObject, pos: GeoPos, start: Long, end: Long): List<OrbitalPos> = TODO()
     override suspend fun getRadios(sat: OrbitalObject, pos: GeoPos, radios: List<SatRadio>, time: Long): List<SatRadio> = TODO()
     override suspend fun getRadiosWithId(id: Int): List<SatRadio> = TODO()
+    override suspend fun getSatelliteIdsWithModes(modes: List<String>): List<Int> = emptyList()
 }
 
 /**
  * Test fake for ISettingsRepo. Only [stationPosition] is backed by mutable
  * state; everything else the ViewModel never touches fails loudly.
  */
-class FakeSettingsRepo(initialPosition: GeoPos = GeoPos(23.13, 113.26)) : ISettingsRepo {
+class FakeSettingsRepo(
+    initialPosition: GeoPos = GeoPos(23.13, 113.26),
+    val amSatFm: Set<Int> = emptySet(),
+    val amSatLinear: Set<Int> = emptySet()
+) : ISettingsRepo {
 
     override val stationPosition = MutableStateFlow(initialPosition)
 
@@ -103,6 +108,10 @@ class FakeSettingsRepo(initialPosition: GeoPos = GeoPos(23.13, 113.26)) : ISetti
 
     override fun updateDataSourcesStatus(status: Map<String, Int>) = TODO()
 
+    override fun getAmSatFmCatnums(): Set<Int> = amSatFm
+    override fun getAmSatLinearCatnums(): Set<Int> = amSatLinear
+    override fun setAmSatCatnums(fmCatnums: Set<Int>, linearCatnums: Set<Int>) = TODO()
+
     override fun updateRadioControlSettings(settings: RadioControlSettings) = TODO()
     override fun getSatelliteOffset(catnum: Int): String = ""
     override fun setSatelliteOffset(catnum: Int, offset: String) = TODO()

feature/mutual/src/test/java/com/rtbishop/look4sat/feature/mutual/MutualViewModelTest.kt

@@ -31,10 +31,12 @@ class MutualViewModelTest {
     private fun TestScope.createVm(
         satellites: List<OrbitalObject> = emptyList(),
         passes: List<OrbitalPass> = emptyList(),
-        position: GeoPos = TestOrbits.GUANGZHOU
+        position: GeoPos = TestOrbits.GUANGZHOU,
+        amSatFm: Set<Int> = emptySet(),
+        amSatLinear: Set<Int> = emptySet()
     ): MutualViewModel = MutualViewModel(
         satelliteRepo = FakeSatelliteRepo(satellites, passes),
-        settingsRepo = FakeSettingsRepo(position),
+        settingsRepo = FakeSettingsRepo(position, amSatFm, amSatLinear),
         computeDispatcher = StandardTestDispatcher(mainDispatcherRule.dispatcher.scheduler)
     )
 
@@ -320,4 +322,67 @@ class MutualViewModelTest {
         assertEquals(4, vm.listScrollIndex)
         assertEquals(137, vm.listScrollOffset)
     }
+
+    // --------------------------------------------- transponder filters (AMSAT)
+
+    @Test
+    fun `both filters off sets an error and does not search`() = runTest(mainDispatcherRule.dispatcher.scheduler) {
+        val windows = TestOrbits.findPassWindows()
+        val vm = createVm(satellites = listOf(TestOrbits.ISS), passes = windows)
+        vm.onStationBGrid("OL62")
+        vm.onFilterFM(false)
+        vm.onFilterLinear(false)
+
+        queryAndSettle(vm)
+
+        assertEquals(
+            "Select at least one transponder type (FM / Linear) to run the match.",
+            vm.uiState.value.errorMessage
+        )
+        assertFalse(vm.uiState.value.hasSearched)
+    }
+
+    @Test
+    fun `AMSAT filter restricts results to listed catnums`() = runTest(mainDispatcherRule.dispatcher.scheduler) {
+        val windows = TestOrbits.findPassWindows(hoursAhead = 24) +
+            TestOrbits.findPassWindows(sat = TestOrbits.ISS_VARIANT, hoursAhead = 24)
+        assertTrue("fixture must produce windows", windows.isNotEmpty())
+        // Only ISS (25544) is on the AMSAT live FM list; ISS_VARIANT (25545) is not.
+        val vm = createVm(
+            satellites = listOf(TestOrbits.ISS, TestOrbits.ISS_VARIANT),
+            passes = windows,
+            amSatFm = setOf(25544)
+        )
+        vm.onStationBGrid("OL62")
+        vm.onHoursAhead(24)
+
+        queryAndSettle(vm)
+
+        val state = vm.uiState.value
+        assertNull(state.errorMessage)
+        assertTrue(state.mutualPasses.isNotEmpty())
+        assertTrue("only AMSAT-listed satellites should appear", state.mutualPasses.all { it.catNum == 25544 })
+    }
+
+    @Test
+    fun `AMSAT filter off for one type excludes its satellites`() = runTest(mainDispatcherRule.dispatcher.scheduler) {
+        val windows = TestOrbits.findPassWindows(hoursAhead = 24) +
+            TestOrbits.findPassWindows(sat = TestOrbits.ISS_VARIANT, hoursAhead = 24)
+        // FM filter off, Linear on: neither sat is linear-listed -> nothing matches.
+        val vm = createVm(
+            satellites = listOf(TestOrbits.ISS, TestOrbits.ISS_VARIANT),
+            passes = windows,
+            amSatFm = setOf(25544),
+            amSatLinear = setOf(25545)
+        )
+        vm.onStationBGrid("OL62")
+        vm.onHoursAhead(24)
+        vm.onFilterFM(false)
+
+        queryAndSettle(vm)
+
+        val state = vm.uiState.value
+        assertNull(state.errorMessage)
+        assertTrue("only linear-listed satellites should appear", state.mutualPasses.all { it.catNum == 25545 })
+    }
 }