feat(gridfinder): VUCC 网格寻线实地导航 + LoTW 上传台址预填联动 + 移除地图入口

- GridGeometry 网格线/点几何 + QthConverter grid4/grid8；golden vectors 单测
- 独立定位流 ILocationRepo/LocationRepo（stop 时 removeUpdates），不自动写台址
- feature/gridfinder 模块：罗盘表盘、极坐标近距图、线上/点上精度门控（连续 3 次 ≤6.1m）
- 「设为 LoTW 上传台址」：跳证书配置页并预填当前网格（1/2/4 格），只改台站 grid 字段
- 地图页入口移除，设置页单入口；顶部间距改 ScreenColumn 结构（与设置页同构）
- 术语统一「最近网格点」（中英）

core/data/src/main/java/com/rtbishop/look4sat/core/data/injection/MainContainer.kt

@@ -17,11 +17,14 @@
  */
 package com.rtbishop.look4sat.core.data.injection
 
+import android.Manifest
 import android.bluetooth.BluetoothManager
 import android.content.Context
+import android.content.pm.PackageManager
 import android.hardware.SensorManager
 import android.hardware.display.DisplayManager
 import android.location.LocationManager
+import androidx.core.content.ContextCompat
 import androidx.room.Room
 import com.rtbishop.look4sat.core.data.database.Look4SatDb
 import com.rtbishop.look4sat.core.data.database.MIGRATION_1_2
@@ -43,6 +46,7 @@ import com.rtbishop.look4sat.core.data.repository.SensorsRepo
 import com.rtbishop.look4sat.core.data.repository.SettingsRepo
 import com.rtbishop.look4sat.core.data.repository.UpdateRepository
 import com.rtbishop.look4sat.core.data.repository.LoTWRepository
+import com.rtbishop.look4sat.core.data.repository.LocationRepo
 import com.rtbishop.look4sat.core.data.repository.WavelogRepository
 import com.rtbishop.look4sat.core.data.source.LocalSource
 import com.rtbishop.look4sat.core.data.source.RemoteSource
@@ -59,6 +63,7 @@ import com.rtbishop.look4sat.core.domain.repository.IRadioController
 import com.rtbishop.look4sat.core.domain.repository.IRadioTrackingService
 import com.rtbishop.look4sat.core.domain.repository.IReporter
 import com.rtbishop.look4sat.core.domain.repository.ILoTWRepository
+import com.rtbishop.look4sat.core.domain.repository.ILocationRepo
 import com.rtbishop.look4sat.core.domain.repository.ISatelliteRepo
 import com.rtbishop.look4sat.core.domain.repository.ISelectionRepo
 import com.rtbishop.look4sat.core.domain.repository.ISensorsRepo
@@ -107,13 +112,25 @@ class MainContainer(private val context: Context) : IMainContainer {
         val manager = context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
         RadioTrackingService(appScope, manager, satelliteRepo, settingsRepo)
     }
+    override val locationRepo: ILocationRepo by lazy {
+        val manager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
+        LocationRepo(manager) {
+            ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) ==
+                PackageManager.PERMISSION_GRANTED
+        }
+    }
 
     private val _mutualPassData = MutableStateFlow(MutualPassData())
     override val mutualPassData: StateFlow<MutualPassData> = _mutualPassData.asStateFlow()
+    private val _pendingLoTWStationGrid = MutableStateFlow<String?>(null)
+    override val pendingLoTWStationGrid: StateFlow<String?> = _pendingLoTWStationGrid.asStateFlow()
 
     override fun setMutualPassData(data: MutualPassData) {
         _mutualPassData.value = data
     }
+    override fun setPendingLoTWStationGrid(grid: String?) {
+        _pendingLoTWStationGrid.value = grid
+    }
 
     override fun provideAddToCalendar(): IAddToCalendar = AddToCalendar(context)
 

core/data/src/main/java/com/rtbishop/look4sat/core/data/repository/LocationRepo.kt

@@ -0,0 +1,134 @@
+/*
+ * Look4Sat. Amateur radio satellite tracker and pass predictor.
+ * Copyright (C) 2019-2026 Arty Bishop and contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.rtbishop.look4sat.core.data.repository
+
+import android.location.Location
+import android.location.LocationListener
+import android.location.LocationManager
+import androidx.core.location.LocationManagerCompat
+import com.rtbishop.look4sat.core.domain.repository.ILocationRepo
+import com.rtbishop.look4sat.core.domain.repository.LocationFix
+import com.rtbishop.look4sat.core.domain.repository.LocationState
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+private const val UPDATE_INTERVAL_MS = 1_000L
+private const val UPDATE_MIN_DISTANCE_M = 0f
+
+/**
+ * Live-location adapter for the field tools. Deliberately independent of
+ * [SettingsRepo]'s station position: a walk around a grid corner must not
+ * rewrite the station that every pass prediction is built on.
+ *
+ * Unlike [SettingsRepo.setStationPosition], this class always calls
+ * [LocationManager.removeUpdates] in [stopUpdates], so the listener is only
+ * alive while a screen is actually collecting fixes.
+ */
+class LocationRepo(
+    private val locationManager: LocationManager,
+    private val permissionGranted: () -> Boolean
+) : ILocationRepo, LocationListener {
+
+    private val _state = MutableStateFlow(initialState())
+    override val state: StateFlow<LocationState> = _state.asStateFlow()
+
+    private var isRegistered = false
+
+    override fun hasPermission(): Boolean = permissionGranted()
+
+    override fun startUpdates() {
+        if (isRegistered) return
+        val request = describeProvider() ?: return
+        if (!request.permissionGranted || !request.providerEnabled) return
+        try {
+            // A last-known fix is better than an empty screen while GPS warms up.
+            locationManager.getLastKnownLocation(request.provider)?.let(::publish)
+            locationManager.requestLocationUpdates(
+                request.provider, UPDATE_INTERVAL_MS, UPDATE_MIN_DISTANCE_M, this
+            )
+            isRegistered = true
+        } catch (exception: SecurityException) {
+            println("LocationRepo: no permission - $exception")
+        } catch (exception: IllegalArgumentException) {
+            println("LocationRepo: provider unavailable - $exception")
+        }
+    }
+
+    override fun stopUpdates() {
+        if (!isRegistered) return
+        isRegistered = false
+        try {
+            locationManager.removeUpdates(this)
+        } catch (exception: SecurityException) {
+            println("LocationRepo: removing updates without permission - $exception")
+        }
+    }
+
+    override fun onLocationChanged(location: Location) = publish(location)
+
+    override fun onProviderDisabled(provider: String) = refreshWaitingState()
+
+    override fun onProviderEnabled(provider: String) = refreshWaitingState()
+
+    private fun publish(location: Location) {
+        _state.value = LocationState.Fix(
+            LocationFix(
+                latitude = location.latitude,
+                longitude = location.longitude,
+                altitudeMeters = location.altitude.takeIf { location.hasAltitude() } ?: 0.0,
+                // Providers that cannot report accuracy use -1; treat that as
+                // useless rather than perfect.
+                accuracyMeters = location.accuracy.takeIf { location.hasAccuracy() } ?: Float.MAX_VALUE,
+                epochMs = location.time.takeIf { it > 0L } ?: System.currentTimeMillis()
+            )
+        )
+    }
+
+    private fun initialState(): LocationState {
+        val request = describeProvider()
+        return LocationState.Waiting(
+            permissionGranted = request?.permissionGranted ?: false,
+            providerEnabled = request?.providerEnabled ?: false
+        )
+    }
+
+    private fun refreshWaitingState() {
+        if (_state.value is LocationState.Fix) return
+        _state.value = initialState()
+    }
+
+    private fun describeProvider(): ProviderRequest? {
+        if (!permissionGranted()) {
+            return ProviderRequest(LocationManager.GPS_PROVIDER, false, false)
+        }
+        val enabled = LocationManagerCompat.isLocationEnabled(locationManager)
+        val provider = when {
+            locationManager.allProviders.contains(LocationManager.GPS_PROVIDER) -> LocationManager.GPS_PROVIDER
+            locationManager.allProviders.contains(LocationManager.NETWORK_PROVIDER) -> LocationManager.NETWORK_PROVIDER
+            else -> null
+        } ?: return null
+        return ProviderRequest(provider, true, enabled)
+    }
+
+    private data class ProviderRequest(
+        val provider: String,
+        val permissionGranted: Boolean,
+        val providerEnabled: Boolean
+    )
+}

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/repository/ILocationRepo.kt

@@ -0,0 +1,65 @@
+/*
+ * Look4Sat. Amateur radio satellite tracker and pass predictor.
+ * Copyright (C) 2019-2026 Arty Bishop and contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.rtbishop.look4sat.core.domain.repository
+
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * A single position fix from the device's location provider, with the
+ * horizontal accuracy reported by the platform.
+ */
+data class LocationFix(
+    val latitude: Double,
+    val longitude: Double,
+    val altitudeMeters: Double = 0.0,
+    val accuracyMeters: Float,
+    val epochMs: Long
+) {
+    /** ARRL VUCC work needs a fix good to the 20 ft (6.1 m) rule. */
+    fun isPreciseEnough(limitMeters: Float): Boolean = accuracyMeters in 0f..limitMeters
+}
+
+/** What the live-location source is currently able to give. */
+sealed interface LocationState {
+    /** No fix yet - either permission is missing or the provider is warming up. */
+    data class Waiting(val permissionGranted: Boolean, val providerEnabled: Boolean) : LocationState
+
+    data class Fix(val location: LocationFix) : LocationState
+}
+
+/**
+ * Live device position for field tools (currently the Grid Finder). Kept
+ * separate from [ISettingsRepo.stationPosition] on purpose: collecting fixes
+ * here must never move the user's station, which is what drives every pass
+ * prediction in the app.
+ *
+ * Callers register with [startUpdates] while their screen is alive and MUST
+ * call [stopUpdates] when it goes away.
+ */
+interface ILocationRepo {
+    val state: StateFlow<LocationState>
+
+    /** Whether the app currently holds the fine-location permission. */
+    fun hasPermission(): Boolean
+
+    /** Begins delivering fixes; no-op when permission is missing. */
+    fun startUpdates()
+
+    /** Stops delivering fixes and releases the platform listener. */
+    fun stopUpdates()
+}

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/repository/IMainContainer.kt

@@ -38,8 +38,12 @@ interface IMainContainer {
     val qsoRepository: IQsoRepository
     val lotwUploadRepository: ILoTWUploadRepository
     val radioTrackingService: IRadioTrackingService
+    val locationRepo: ILocationRepo
     val mutualPassData: StateFlow<MutualPassData>
+    /** Grid Finder → LoTW station page prefill, consumed once by that page. */
+    val pendingLoTWStationGrid: StateFlow<String?>
     fun setMutualPassData(data: MutualPassData)
+    fun setPendingLoTWStationGrid(grid: String?)
     fun provideAddToCalendar(): IAddToCalendar
     fun provideShowToast(): IShowToast
     fun provideBluetoothReporter(): IReporter

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/GridGeometry.kt

@@ -0,0 +1,189 @@
+/*
+ * Look4Sat. Amateur radio satellite tracker and pass predictor.
+ * Copyright (C) 2019-2026 Arty Bishop and contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.rtbishop.look4sat.core.domain.utility
+
+import kotlin.math.abs
+import kotlin.math.atan2
+import kotlin.math.cos
+import kotlin.math.hypot
+import kotlin.math.round
+
+/**
+ * Grid-line / grid-corner geometry for the 4-character Maidenhead squares that
+ * VUCC credits, used by the Grid Finder field tool.
+ *
+ * A 4-character square is 1 degree tall (boundaries at integer latitudes) and
+ * 2 degrees wide (boundaries at even offsets from the -180 degree antimeridian),
+ * so a station's distance to the nearest VUCC line and corner is a matter of
+ * simple planar geometry at the station's latitude.
+ *
+ * Geometry ported from OrbitDeck for iOS (MIT License, (c) 2026 Paul Stoetzer,
+ * N8HM) - `GridGeometry` in `Views/HomeView.swift` and `vuccGrids` in
+ * `Engine/FeatureEngine.swift`. Golden values are pinned by GridGeometryTest.
+ */
+
+/** ARRL VUCC "20 ft rule": a fix within this distance of a boundary counts as on it. */
+const val VUCC_BOUNDARY_TOLERANCE_METERS = 20.0 * 0.3048
+
+/** One degree of latitude in metres; 4-character squares are 1 degree tall. */
+private const val METERS_PER_DEGREE_LATITUDE = 111_320.0
+
+/** Nudge used to name the square on the far side of a boundary (display only). */
+private const val NEIGHBOUR_NUDGE_DEGREES = 0.0005
+
+/** Nudge used by [vuccClaimableGrids] so the neighbour lands squarely across. */
+private const val CLAIM_NEIGHBOUR_NUDGE_DEGREES = 0.001
+
+private const val DEG_TO_RAD = 0.017453292519943295
+private const val RAD_TO_DEG = 57.29577951308232
+
+/** Where the nearest 4-character boundary lies relative to the fix. */
+enum class GridBoundaryDirection { NORTH, SOUTH, EAST, WEST }
+
+/** ARRL VUCC standing of a fix, derived from how many squares it may claim. */
+enum class GridFixStatus { INSIDE_GRID, ON_GRID_LINE, ON_GRID_CORNER }
+
+/**
+ * Distance and bearing to the nearest 4-character grid corner and grid line,
+ * plus the locators of the squares that meet there. All distances are metres
+ * computed on a flat approximation local to the fix (the same approximation
+ * the source implementation uses; over the <=100 km distances involved the
+ * error is far below a GPS fix's own accuracy).
+ */
+data class GridGeometry(
+    val grid4: String,
+    val grid6: String,
+    val grid8: String,
+    val latLineMeters: Double,
+    val latLineDirection: GridBoundaryDirection,
+    val lonLineMeters: Double,
+    val lonLineDirection: GridBoundaryDirection,
+    val cornerMeters: Double,
+    val cornerBearingDegrees: Double,
+    val cornerGrids: List<String>,
+    val nearestLineMeters: Double,
+    val nearestLineBearingDegrees: Double,
+    val nearestLineIsLatitude: Boolean,
+    val nearestLineGrids: List<String>
+)
+
+/**
+ * The geometry of the VUCC (4-character) grid around a position, or null when
+ * the position is out of range.
+ */
+fun gridGeometry(latitude: Double, longitude: Double): GridGeometry? {
+    val grid4 = positionToGrid4(latitude, longitude) ?: return null
+    val grid6 = positionToQth(latitude, longitude) ?: return null
+    val grid8 = positionToGrid8(latitude, longitude) ?: return null
+
+    // 4-character boundaries: integer latitudes, even-degree longitudes.
+    val latBoundary = round(latitude)
+    val lonBoundary = round((longitude + 180.0) / 2.0) * 2.0 - 180.0
+
+    val metersPerDegreeLon = METERS_PER_DEGREE_LATITUDE * cos(latitude * DEG_TO_RAD)
+    val dNorth = (latBoundary - latitude) * METERS_PER_DEGREE_LATITUDE
+    val dEast = (lonBoundary - longitude) * metersPerDegreeLon
+
+    val otherLat = latBoundary - if (latitude >= latBoundary) NEIGHBOUR_NUDGE_DEGREES else -NEIGHBOUR_NUDGE_DEGREES
+    val otherLon = lonBoundary - if (longitude >= lonBoundary) NEIGHBOUR_NUDGE_DEGREES else -NEIGHBOUR_NUDGE_DEGREES
+
+    val cornerGrids = setOfNotNull(
+        positionToGrid4(latitude, longitude),
+        positionToGrid4(otherLat, longitude),
+        positionToGrid4(latitude, otherLon),
+        positionToGrid4(otherLat, otherLon)
+    ).sorted()
+
+    val onLatitude = abs(dNorth) <= abs(dEast)
+    val nearestLineGrids = if (onLatitude) {
+        setOfNotNull(grid4, positionToGrid4(otherLat, longitude)).sorted()
+    } else {
+        setOfNotNull(grid4, positionToGrid4(latitude, otherLon)).sorted()
+    }
+
+    return GridGeometry(
+        grid4 = grid4,
+        grid6 = grid6,
+        grid8 = grid8,
+        latLineMeters = abs(dNorth),
+        latLineDirection = if (dNorth >= 0) GridBoundaryDirection.NORTH else GridBoundaryDirection.SOUTH,
+        lonLineMeters = abs(dEast),
+        lonLineDirection = if (dEast >= 0) GridBoundaryDirection.EAST else GridBoundaryDirection.WEST,
+        cornerMeters = hypot(dNorth, dEast),
+        cornerBearingDegrees = bearingDegrees(dNorth, dEast),
+        cornerGrids = cornerGrids,
+        nearestLineMeters = if (onLatitude) abs(dNorth) else abs(dEast),
+        nearestLineBearingDegrees = if (onLatitude) {
+            if (dNorth >= 0) 0.0 else 180.0
+        } else {
+            if (dEast >= 0) 90.0 else 270.0
+        },
+        nearestLineIsLatitude = onLatitude,
+        nearestLineGrids = nearestLineGrids
+    )
+}
+
+/**
+ * The 4-character squares a station at this position may claim under ARRL VUCC
+ * rules: normally one, but two when the fix is on the line between two squares
+ * and four when it is on the corner where four squares meet. A fix within
+ * [toleranceMeters] of a boundary is considered to be on it (the 20 ft rule).
+ */
+fun vuccClaimableGrids(
+    latitude: Double,
+    longitude: Double,
+    toleranceMeters: Double = VUCC_BOUNDARY_TOLERANCE_METERS
+): List<String> {
+    val own = positionToGrid4(latitude, longitude) ?: return emptyList()
+    val grids = mutableSetOf(own)
+
+    val latBoundary = round(latitude)
+    val lonBoundary = round((longitude + 180.0) / 2.0) * 2.0 - 180.0
+    val metersPerDegreeLon = METERS_PER_DEGREE_LATITUDE * cos(latitude * DEG_TO_RAD)
+
+    val onLatitude = abs(latitude - latBoundary) * METERS_PER_DEGREE_LATITUDE <= toleranceMeters
+    val onLongitude = abs(longitude - lonBoundary) * metersPerDegreeLon <= toleranceMeters
+    if (!onLatitude && !onLongitude) return grids.sorted()
+
+    // Step just past the boundary so the neighbour's locator is unambiguous.
+    val otherLat = latBoundary - if (latitude >= latBoundary) CLAIM_NEIGHBOUR_NUDGE_DEGREES else -CLAIM_NEIGHBOUR_NUDGE_DEGREES
+    val otherLon = lonBoundary - if (longitude >= lonBoundary) CLAIM_NEIGHBOUR_NUDGE_DEGREES else -CLAIM_NEIGHBOUR_NUDGE_DEGREES
+
+    if (onLatitude) {
+        positionToGrid4(otherLat, longitude)?.let(grids::add)
+    }
+    if (onLongitude) {
+        positionToGrid4(latitude, otherLon)?.let(grids::add)
+    }
+    if (onLatitude && onLongitude) {
+        positionToGrid4(otherLat, otherLon)?.let(grids::add)
+    }
+    return grids.sorted()
+}
+
+/** VUCC standing implied by the number of squares a fix may claim. */
+fun gridFixStatus(claimableGrids: List<String>): GridFixStatus = when {
+    claimableGrids.size >= 4 -> GridFixStatus.ON_GRID_CORNER
+    claimableGrids.size >= 2 -> GridFixStatus.ON_GRID_LINE
+    else -> GridFixStatus.INSIDE_GRID
+}
+
+private fun bearingDegrees(dNorth: Double, dEast: Double): Double {
+    val bearing = atan2(dEast, dNorth) * RAD_TO_DEG
+    return if (bearing < 0.0) bearing + 360.0 else bearing
+}

core/domain/src/main/java/com/rtbishop/look4sat/core/domain/utility/QthConverter.kt

@@ -69,6 +69,45 @@ fun positionToQth(latitude: Double, longitude: Double): String? {
     return "$lonFirst$latFirst$lonSecond$latSecond$lonThird$latThird"
 }
 
+/**
+ * Convert a position to its 4-char Maidenhead locator (field + square), the
+ * square VUCC credits, upper-cased. Returns null outside the Maidenhead grid
+ * (lat >= 90 is out of range: the top row is 80..90 N). The longitude is
+ * wrapped into [-180, 180) first, so fixes either side of the antimeridian
+ * resolve to the square they are actually in.
+ */
+fun positionToGrid4(latitude: Double, longitude: Double): String? {
+    if (latitude < -90.0 || latitude >= 90.0) return null
+    val normalizedLon = normalizeLongitude(longitude)
+    val fieldLat = ((latitude + 90.0) / 10.0).toInt().coerceIn(0, 17)
+    val fieldLon = ((normalizedLon + 180.0) / 20.0).toInt().coerceIn(0, 17)
+    val subLat = ((latitude + 90.0) % 10.0).toInt()
+    val subLon = ((normalizedLon + 180.0) % 20.0 / 2.0).toInt()
+    return "${'A' + fieldLon}${'A' + fieldLat}$subLon$subLat"
+}
+
+/**
+ * Convert a position to its 8-char Maidenhead locator: the 6-char locator plus
+ * the numeric extended-square pair (the Maidenhead maximum). Returns null for
+ * out-of-range positions.
+ */
+fun positionToGrid8(latitude: Double, longitude: Double): String? {
+    val normalizedLon = normalizeLongitude(longitude)
+    val base = positionToQth(latitude, normalizedLon) ?: return null
+    val latitudeOffset = latitude.coerceIn(-90.0, 89.999999) + 90.0
+    val longitudeOffset = normalizedLon.coerceIn(-180.0, 179.999999) + 180.0
+    val subLon = 2.0 / 24.0
+    val subLat = 1.0 / 24.0
+    val lonDigit = minOf(9, ((longitudeOffset % subLon) / subLon * 10).toInt())
+    val latDigit = minOf(9, ((latitudeOffset % subLat) / subLat * 10).toInt())
+    return "$base$lonDigit$latDigit"
+}
+
+/** Wrap any longitude into [-180, 180). */
+private fun normalizeLongitude(longitude: Double): Double {
+    return ((longitude + 180.0) % 360.0 + 360.0) % 360.0 - 180.0
+}
+
 private fun isValidPosition(lat: Double, lon: Double): Boolean {
     return (lat >= -90.0 && lat <= 90.0) && (lon >= -180.0 && lon <= 360.0)
 }

core/domain/src/test/java/com/rtbishop/look4sat/core/domain/utility/GridGeometryTest.kt

@@ -0,0 +1,171 @@
+/*
+ * Look4Sat. Amateur radio satellite tracker and pass predictor.
+ * Copyright (C) 2019-2026 Arty Bishop and contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package com.rtbishop.look4sat.core.domain.utility
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Golden values were produced by a line-by-line port of the reference
+ * implementation (OrbitDeck for iOS, MIT) covering four hemispheres/quadrant
+ * cases plus the two awkward longitudes: the Greenwich meridian and the
+ * antimeridian.
+ */
+class GridGeometryTest {
+
+    private val meterDelta = 0.5
+    private val bearingDelta = 0.05
+
+    @Test
+    fun `station at home square reports both boundaries and the corner`() {
+        val geometry = requireNotNull(gridGeometry(22.3542, 113.6250))
+        assertEquals("OL62", geometry.grid4)
+        assertEquals("OL62TI", geometry.grid6)
+        assertEquals("OL62TI55", geometry.grid8)
+        assertEquals(39429.5, geometry.latLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.SOUTH, geometry.latLineDirection)
+        assertEquals(38607.9, geometry.lonLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
+        assertEquals(55183.8, geometry.cornerMeters, meterDelta)
+        assertEquals(135.60, geometry.cornerBearingDegrees, bearingDelta)
+        assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), geometry.cornerGrids)
+        assertEquals(38607.9, geometry.nearestLineMeters, meterDelta)
+        assertEquals(90.0, geometry.nearestLineBearingDegrees, bearingDelta)
+        assertEquals(false, geometry.nearestLineIsLatitude)
+        assertEquals(listOf("OL62", "OL72"), geometry.nearestLineGrids)
+    }
+
+    @Test
+    fun `fix on the 114 east line sits on the boundary itself`() {
+        val geometry = requireNotNull(gridGeometry(22.3542, 114.0000))
+        assertEquals("OL72", geometry.grid4)
+        assertEquals("OL72AI", geometry.grid6)
+        assertEquals("OL72AI05", geometry.grid8)
+        assertEquals(39429.5, geometry.latLineMeters, meterDelta)
+        assertEquals(0.0, geometry.lonLineMeters, meterDelta)
+        assertEquals(39429.5, geometry.cornerMeters, meterDelta)
+        assertEquals(180.00, geometry.cornerBearingDegrees, bearingDelta)
+        assertEquals(listOf("OL62", "OL72"), geometry.nearestLineGrids)
+    }
+
+    @Test
+    fun `fix on the 22 north 114 east corner names all four squares`() {
+        val geometry = requireNotNull(gridGeometry(22.00002, 114.00003))
+        assertEquals("OL72", geometry.grid4)
+        assertEquals(2.2, geometry.latLineMeters, meterDelta)
+        assertEquals(3.1, geometry.lonLineMeters, meterDelta)
+        assertEquals(3.8, geometry.cornerMeters, meterDelta)
+        assertEquals(234.28, geometry.cornerBearingDegrees, bearingDelta)
+        assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), geometry.cornerGrids)
+        assertEquals("OL71", geometry.nearestLineGrids.first())
+    }
+
+    @Test
+    fun `greenwich meridian fix reports a zero distance latitude line to the north`() {
+        val geometry = requireNotNull(gridGeometry(45.0000, -0.0004))
+        assertEquals("IN95", geometry.grid4)
+        assertEquals("IN95XA", geometry.grid6)
+        assertEquals("IN95XA90", geometry.grid8)
+        assertEquals(0.0, geometry.latLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.NORTH, geometry.latLineDirection)
+        assertEquals(31.5, geometry.lonLineMeters, meterDelta)
+        assertEquals(listOf("IN94", "IN95", "JN04", "JN05"), geometry.cornerGrids)
+        assertEquals(true, geometry.nearestLineIsLatitude)
+        assertEquals(listOf("IN94", "IN95"), geometry.nearestLineGrids)
+    }
+
+    @Test
+    fun `antimeridian fix wraps into the eastern square`() {
+        val geometry = requireNotNull(gridGeometry(0.05, 179.9998))
+        assertEquals("RJ90", geometry.grid4)
+        assertEquals("RJ90XB", geometry.grid6)
+        assertEquals("RJ90XB92", geometry.grid8)
+        assertEquals(22.3, geometry.lonLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
+        assertEquals(179.77, geometry.cornerBearingDegrees, bearingDelta)
+        // The corner's four squares straddle the antimeridian, so the western
+        // pair rolls over to the A-series fields.
+        assertEquals(listOf("AI09", "AJ00", "RI99", "RJ90"), geometry.cornerGrids)
+        assertEquals(listOf("AJ00", "RJ90"), geometry.nearestLineGrids)
+    }
+
+    @Test
+    fun `southern hemisphere fix keeps its bearings right way round`() {
+        val geometry = requireNotNull(gridGeometry(-33.86, 151.21))
+        assertEquals("QF56", geometry.grid4)
+        assertEquals("QF56OD", geometry.grid6)
+        assertEquals(15584.8, geometry.latLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.SOUTH, geometry.latLineDirection)
+        assertEquals(73027.8, geometry.lonLineMeters, meterDelta)
+        assertEquals(GridBoundaryDirection.EAST, geometry.lonLineDirection)
+        assertEquals(102.05, geometry.cornerBearingDegrees, bearingDelta)
+        assertEquals(180.0, geometry.nearestLineBearingDegrees, bearingDelta)
+    }
+
+    @Test
+    fun `out of range positions yield no geometry`() {
+        assertNull(gridGeometry(90.0, 0.0))
+        assertNull(gridGeometry(-91.0, 0.0))
+    }
+
+    @Test
+    fun `vucc claims one square when the fix is inside`() {
+        assertEquals(listOf("OL62"), vuccClaimableGrids(22.3542, 113.6250))
+        assertEquals(GridFixStatus.INSIDE_GRID, gridFixStatus(vuccClaimableGrids(22.3542, 113.6250)))
+    }
+
+    @Test
+    fun `vucc claims both squares on a line`() {
+        val claimed = vuccClaimableGrids(22.3542, 114.0000)
+        assertEquals(listOf("OL62", "OL72"), claimed)
+        assertEquals(GridFixStatus.ON_GRID_LINE, gridFixStatus(claimed))
+    }
+
+    @Test
+    fun `vucc claims all four squares on a corner`() {
+        val claimed = vuccClaimableGrids(22.00002, 114.00003)
+        assertEquals(listOf("OL61", "OL62", "OL71", "OL72"), claimed)
+        assertEquals(GridFixStatus.ON_GRID_CORNER, gridFixStatus(claimed))
+    }
+
+    @Test
+    fun `vucc claims nothing extra just outside the 20 foot tolerance`() {
+        // Same corner, but ~38 m away: outside the 20 ft (6.096 m) rule.
+        val claimed = vuccClaimableGrids(22.0002, 114.0003)
+        assertEquals(listOf("OL72"), claimed)
+        assertEquals(GridFixStatus.INSIDE_GRID, gridFixStatus(claimed))
+    }
+
+    @Test
+    fun `vucc tolerance boundary is 20 feet`() {
+        assertEquals(6.096, VUCC_BOUNDARY_TOLERANCE_METERS, 0.0001)
+        // 5 m north of the 22 N line: inside the tolerance for a custom, tighter
+        // call, outside it when the caller demands sub-metre precision.
+        assertTrue(vuccClaimableGrids(22.00005, 113.62).size >= 2)
+        assertEquals(1, vuccClaimableGrids(22.00005, 113.62, toleranceMeters = 1.0).size)
+    }
+
+    @Test
+    fun `grid4 ignores longitudes beyond the antimeridian`() {
+        assertNull(positionToGrid4(91.0, 0.0))
+        // A longitude of 200 degrees is the same meridian as -160 degrees.
+        assertEquals(positionToGrid4(30.0, -160.0), positionToGrid4(30.0, 200.0))
+    }
+}

core/presentation/src/main/java/com/rtbishop/look4sat/core/presentation/Navigation.kt

@@ -45,6 +45,14 @@ sealed class Screen(val iconResId: Int, val titleResId: Int) : NavKey {
 @Serializable
 data object RadarDestination : NavKey
 
+/** Full-screen field tool: guides the operator onto a VUCC grid line or corner. */
+@Serializable
+data object GridFinderDestination : NavKey
+
+/** LoTW upload certificate + station location page, reached from the Grid Finder. */
+@Serializable
+data object LoTWUploadDestination : NavKey
+
 interface IDeeplinkMatcher {
     fun match(deeplink: String): NavKey?
 }

core/presentation/src/main/res/drawable/ic_grid_finder.xml

@@ -0,0 +1,13 @@
+<!--
+  Grid Finder icon: a GPS crosshair.
+  Ported from Material Design Icons (crosshairs-gps), Apache License 2.0.
+-->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:fillColor="@android:color/white"
+        android:pathData="M12,8A4,4 0 0,1 16,12A4,4 0 0,1 12,16A4,4 0 0,1 8,12A4,4 0 0,1 12,8M3.05,13H1V11H3.05C3.5,6.83 6.83,3.5 11,3.05V1H13V3.05C17.17,3.5 20.5,6.83 20.95,11H23V13H20.95C20.5,17.17 17.17,20.5 13,20.95V23H11V20.95C6.83,20.5 3.5,17.17 3.05,13M12,5A7,7 0 0,0 5,12A7,7 0 0,0 12,19A7,7 0 0,0 19,12A7,7 0 0,0 12,5Z" />
+</vector>

core/presentation/src/main/res/values-zh/strings.xml

@@ -416,4 +416,61 @@
     <string name="qso_edit_satellite_official">保存并签名时使用 %1$s</string>
     <string name="qso_edit_warn_no_freq">没有上行频率：LoTW 要求 BAND，补上频率前这条无法上传</string>
 
+    <!-- 网格寻线（VUCC 网格线／网格角实地导航） -->
+    <string name="gridfinder_title">网格寻线</string>
+    <string name="gridfinder_status_corner">位于网格点上</string>
+    <string name="gridfinder_status_line">位于网格线上</string>
+    <string name="gridfinder_status_inside">在网格内部</string>
+    <string name="gridfinder_status_unknown">位置不可用</string>
+    <string name="gridfinder_status_waiting">正在获取定位…</string>
+    <string name="gridfinder_status_blocked">需要定位权限</string>
+    <string name="gridfinder_status_disabled">本机定位服务未开启</string>
+    <string name="gridfinder_status_confirmed">已由 %1$d 次连续满足 20 英尺规则的定位确认</string>
+    <string name="gridfinder_status_unconfirmed">尚未确认：精度达 6.1 m 的连续定位 %1$d/%2$d 次</string>
+    <string name="gridfinder_grant_permission">授予定位权限</string>
+    <string name="gridfinder_card_location">位置</string>
+    <string name="gridfinder_card_corner">最近网格点引导</string>
+    <string name="gridfinder_card_line">最近网格线引导</string>
+    <string name="gridfinder_card_lines">两条边界线</string>
+    <string name="gridfinder_card_map">近距离网格图</string>
+    <string name="gridfinder_card_fix">定位质量</string>
+    <string name="gridfinder_card_compass">罗盘</string>
+    <string name="gridfinder_label_claimable">此处可计分的网格</string>
+    <string name="gridfinder_label_grid4">网格 (4)</string>
+    <string name="gridfinder_label_grid6">网格 (6)</string>
+    <string name="gridfinder_label_grid8">网格 (8)</string>
+    <string name="gridfinder_label_latitude">纬度</string>
+    <string name="gridfinder_label_longitude">经度</string>
+    <string name="gridfinder_label_altitude">海拔</string>
+    <string name="gridfinder_label_accuracy">水平精度</string>
+    <string name="gridfinder_label_fix_age">定位时刻</string>
+    <string name="gridfinder_label_provider">定位来源</string>
+    <string name="gridfinder_value_provider_on">已开启</string>
+    <string name="gridfinder_value_provider_off">未开启</string>
+    <string name="gridfinder_label_distance">距离</string>
+    <string name="gridfinder_label_bearing">方位角</string>
+    <string name="gridfinder_label_direction">方向</string>
+    <string name="gridfinder_label_grids">网格</string>
+    <string name="gridfinder_label_lat_line">纬线</string>
+    <string name="gridfinder_label_lon_line">经线</string>
+    <string name="gridfinder_line_value">位于%2$s方向 %1$s</string>
+    <string name="gridfinder_line_latitude">这是纬度边界，东西走向</string>
+    <string name="gridfinder_line_longitude">这是经度边界，南北走向</string>
+    <string name="gridfinder_label_heading">朝向</string>
+    <string name="gridfinder_label_compass_accuracy">罗盘精度</string>
+    <string name="gridfinder_action_set_station">设为我的台址</string>
+    <string name="gridfinder_action_station_saved">台址已更新 —— 过境预报将使用这个位置</string>
+    <string name="gridfinder_action_calibrate">校准罗盘</string>
+    <string name="gridfinder_map_legend">中心点是你的位置，虚线是正北与正东，直线是两条网格边界，绿点是最近的网格点，圆环是最近网格线的垂足，红色指针是你的朝向</string>
+    <string name="gridfinder_compass_disabled_hint">设置里未开启罗盘，表盘按正北朝上显示。方位角数字仍可引导你</string>
+    <string name="gridfinder_compass_unavailable_hint">本机没有磁力传感器 —— 请按方位角数字导航</string>
+    <string name="gridfinder_compass_hint">请平持手机，箭头指向应走的方向</string>
+    <string name="gridfinder_vucc_rule_note">VUCC 20 英尺规则：%1$.1f m</string>
+    <string name="gridfinder_direction_north">北</string>
+    <string name="gridfinder_direction_south">南</string>
+    <string name="gridfinder_direction_east">东</string>
+    <string name="gridfinder_direction_west">西</string>
+    <string name="gridfinder_action_set_lotw_station">设为 LoTW 上传台址（%1$s）</string>
+    <string name="gridfinder_lotw_station_hint">预填上传台站网格：上传时 LoTW 按这些格记录（线上 2 格、角上 4 格）；证书呼号保持不变。</string>
+
 </resources>

core/presentation/src/main/res/values/strings.xml

@@ -444,4 +444,61 @@ Upstream: https://github.com/rt-bishop/Look4Sat</string>
     <string name="qso_edit_satellite_official">Saved and signed as %1$s</string>
     <string name="qso_edit_warn_no_freq">No uplink frequency: LoTW requires a band, so this QSO cannot be uploaded yet</string>
 
+    <!-- Grid Finder (VUCC grid line / corner field guide) -->
+    <string name="gridfinder_title">Grid Finder</string>
+    <string name="gridfinder_status_corner">ON GRID POINT</string>
+    <string name="gridfinder_status_line">ON GRID LINE</string>
+    <string name="gridfinder_status_inside">INSIDE GRID</string>
+    <string name="gridfinder_status_unknown">Position unavailable</string>
+    <string name="gridfinder_status_waiting">Waiting for a fix…</string>
+    <string name="gridfinder_status_blocked">Location permission required</string>
+    <string name="gridfinder_status_disabled">Location services are off on this device</string>
+    <string name="gridfinder_status_confirmed">Confirmed by %1$d consecutive fixes inside the 20 ft rule</string>
+    <string name="gridfinder_status_unconfirmed">Not confirmed yet: %1$d of %2$d consecutive fixes good to 6.1 m</string>
+    <string name="gridfinder_grant_permission">Grant location access</string>
+    <string name="gridfinder_card_location">Location</string>
+    <string name="gridfinder_card_corner">Guide to the nearest grid point</string>
+    <string name="gridfinder_card_line">Guide to the nearest grid line</string>
+    <string name="gridfinder_card_lines">Both boundary lines</string>
+    <string name="gridfinder_card_map">Close-up grid map</string>
+    <string name="gridfinder_card_fix">Fix quality</string>
+    <string name="gridfinder_card_compass">Compass</string>
+    <string name="gridfinder_label_claimable">VUCC grids here</string>
+    <string name="gridfinder_label_grid4">Grid (4)</string>
+    <string name="gridfinder_label_grid6">Grid (6)</string>
+    <string name="gridfinder_label_grid8">Grid (8)</string>
+    <string name="gridfinder_label_latitude">Latitude</string>
+    <string name="gridfinder_label_longitude">Longitude</string>
+    <string name="gridfinder_label_altitude">Altitude</string>
+    <string name="gridfinder_label_accuracy">Horizontal accuracy</string>
+    <string name="gridfinder_label_fix_age">Fix age</string>
+    <string name="gridfinder_label_provider">Location provider</string>
+    <string name="gridfinder_value_provider_on">On</string>
+    <string name="gridfinder_value_provider_off">Off</string>
+    <string name="gridfinder_label_distance">Distance</string>
+    <string name="gridfinder_label_bearing">Bearing</string>
+    <string name="gridfinder_label_direction">Direction</string>
+    <string name="gridfinder_label_grids">Grids</string>
+    <string name="gridfinder_label_lat_line">Latitude line</string>
+    <string name="gridfinder_label_lon_line">Longitude line</string>
+    <string name="gridfinder_line_value">%1$s to the %2$s</string>
+    <string name="gridfinder_line_latitude">This is the latitude boundary, which runs east to west</string>
+    <string name="gridfinder_line_longitude">This is the longitude boundary, which runs north to south</string>
+    <string name="gridfinder_label_heading">Heading</string>
+    <string name="gridfinder_label_compass_accuracy">Compass accuracy</string>
+    <string name="gridfinder_action_set_station">Set as my station</string>
+    <string name="gridfinder_action_station_saved">Station position updated — pass predictions now use this fix</string>
+    <string name="gridfinder_action_calibrate">Calibrate compass</string>
+    <string name="gridfinder_map_legend">The centre dot is you, dashed axes are north and east, the straight lines are the two grid boundaries, the green dot is the nearest grid point, the ring is the closest point of the nearest line and the red needle is your heading</string>
+    <string name="gridfinder_compass_disabled_hint">The compass is switched off in Settings, so the dials stay north-up. The bearing numbers still guide you</string>
+    <string name="gridfinder_compass_unavailable_hint">This device has no magnetic sensor — navigate with the bearing numbers</string>
+    <string name="gridfinder_compass_hint">Hold the phone flat; the arrow points the way to walk</string>
+    <string name="gridfinder_vucc_rule_note">VUCC 20 ft rule: %1$.1f m</string>
+    <string name="gridfinder_direction_north">north</string>
+    <string name="gridfinder_direction_south">south</string>
+    <string name="gridfinder_direction_east">east</string>
+    <string name="gridfinder_direction_west">west</string>
+    <string name="gridfinder_action_set_lotw_station">Set as LoTW station (%1$s)</string>
+    <string name="gridfinder_lotw_station_hint">Prefills the upload station grid — LoTW then records these squares (2 on a line, 4 on a corner). The certificate callsign stays unchanged.</string>
+
 </resources>