merge: integrate complete MapKit runtime refresh

# Conflicts:
#	App/MapHomeView.swift
#	Shared/CoordinateConverter.swift
#	Tests/PaopaoLocationSpooferTests/FavoriteLocationStoreTests.swift
#	Tests/map_refactor_contract_test.sh

App/MapHomeView.swift

@@ -79,19 +79,20 @@ struct MapHomeView: View {
     @State private var wifiChangeObserverToken: UUID?
     @State private var wifiVerificationTask: Task<Void, Never>?
     @State private var wifiVerificationID: UUID?
-    @State private var copyConfirmed = false
+    @State private var copiedCoordinateSystem: CoordinateConverter.MapCoordinateSystem?
     @State private var spoofState: SpoofState = .idle
     @State private var locationOperationTask: Task<Void, Never>?
     @State private var locationOperationID: UInt64 = 0
+    @State private var mapCoordinateSystemRefreshTask: Task<Void, Never>?
+    @State private var mapCoordinateSystemRefreshID: UInt64 = 0
+    @State private var bluePointRefreshPending = false
+    @State private var realtimeButtonTask: Task<Void, Never>?
+    @State private var favoriteSaveTask: Task<Void, Never>?
     // 激活时的坐标（本地存，绕过 C 桥接层精度丢失）
     @State private var activeSpoofLat: Double?
     @State private var activeSpoofLon: Double?
     @State private var lastSpoofDiagnosisSystem: CoordinateConverter.MapCoordinateSystem?
     @State private var hasLoggedSpoofDiagnosis = false
-    @State private var coordinateSystemRefreshTask: Task<Void, Never>?
-    @State private var coordinateSystemRefreshTaskID: UUID?
-    @State private var coordinateSystemRefreshAttempts = 0
-    @State private var lastCoordinateSystemRefreshAt: Date?
 
     init(setup: SetupCoordinator) {
         self.setup = setup
@@ -237,7 +238,7 @@ struct MapHomeView: View {
                                     .shadow(color: .black.opacity(0.2), radius: 6, y: 3)
                             }
                         }
-                        .disabled(realtimeRequestTask != nil || realtime.isRequesting)
+                        .disabled(realtimeButtonTask != nil || realtimeRequestTask != nil || realtime.isRequesting)
                     }
                 }
                 .padding(.trailing, 16)
@@ -284,19 +285,24 @@ struct MapHomeView: View {
             wifiVerificationTask?.cancel()
             wifiVerificationTask = nil
             wifiVerificationID = nil
-            resetMapCoordinateSystemRefresh()
+            mapCoordinateSystemRefreshTask?.cancel()
+            mapCoordinateSystemRefreshTask = nil
+            bluePointRefreshPending = false
+            realtimeButtonTask?.cancel()
+            realtimeButtonTask = nil
+            favoriteSaveTask?.cancel()
+            favoriteSaveTask = nil
         }
         .onChange(of: scenePhase) { phase in
             guard phase == .active else { return }
-            resetMapCoordinateSystemRefresh()
-            refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: "App回到前台")
+            Task { @MainActor in
+                await awaitCoordinatedMapCoordinateSystemRefresh(reason: "App回到前台")
+            }
         }
         .onChange(of: proxy.isRunning) { running in
             if runtimeMode.mode == .localWiFi, !running && spoofState == .active {
                 spoofState = .idle
                 actions.clear()
-                resetMapCoordinateSystemRefresh()
-                refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: "本机代理意外停止")
             }
         }
         .onChange(of: runtimeMode.mode) { mode in
@@ -309,7 +315,6 @@ struct MapHomeView: View {
             }
             wifiVerificationTask?.cancel()
             wifiVerificationTask = nil
-            resetMapCoordinateSystemRefresh()
             activeSpoofLat = nil
             activeSpoofLon = nil
             if mode == .localWiFi {
@@ -426,27 +431,8 @@ struct MapHomeView: View {
             HStack {
                 VStack(alignment: .leading, spacing: 3) {
                     Text(mapState.displayName ?? "当前选点").font(.subheadline.weight(.semibold)).lineLimit(1)
-                    Text(String(format: "%.6f, %.6f", mapState.selection.coordinate.latitude, mapState.selection.coordinate.longitude))
-                        .font(.caption.monospaced())
-                        .foregroundStyle(copyConfirmed ? .green : .secondary)
-                        .onTapGesture {
-                            let text = String(format: "%.6f, %.6f", mapState.selection.coordinate.latitude, mapState.selection.coordinate.longitude)
-                            UIPasteboard.general.string = text
-                            RuntimeLogger.info("APP", "地图", "已复制坐标")
-                            copyConfirmed = true
-                            DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) { copyConfirmed = false }
-                        }
-                        .overlay(alignment: .top) {
-                            if copyConfirmed {
-                                Text("已复制")
-                                    .font(.caption2.bold())
-                                    .foregroundStyle(.white)
-                                    .padding(.horizontal, 8)
-                                    .padding(.vertical, 2)
-                                    .background(.green, in: Capsule())
-                                    .offset(y: -24)
-                            }
-                        }
+                    coordinateRow(label: "国内标准 GCJ-02", system: .gcj02)
+                    coordinateRow(label: "国际标准 WGS-84", system: .wgs84)
                 }
                 Spacer()
                 // 帮助说明按钮
@@ -471,23 +457,7 @@ struct MapHomeView: View {
                         favorites.select(nil)
                         return
                     }
-                    let snapshot = currentSelectionFavorite
-                    RuntimeLogger.info("APP", "坐标转换", "保存当前选点为收藏", details: [
-                        "当前地图标准": CoordinateConverter.currentMapCoordinateSystem.diagnosticName,
-                        "输入字段": CoordinateConverter.currentMapCoordinateSystem.diagnosticName,
-                        "持久化字段": "国际标准(WGS-84)+国内标准(GCJ-02)"
-                    ])
-                    let favorite = favorites.save(
-                        name: snapshot.name,
-                        mapCoordinate: mapState.selection.coordinate,
-                        mapCoordinateSystem: CoordinateConverter.currentMapCoordinateSystem,
-                        accuracy: snapshot.accuracy
-                    )
-                    mapState.selectFavorite(
-                        favorite.coordinatePair.coordinate(for: CoordinateConverter.currentMapCoordinateSystem),
-                        id: favorite.id,
-                        name: favorite.name
-                    )
+                    saveCurrentSelectionAsFavorite()
                 } label: {
                     Image(systemName: favorites.selectedFavoriteID != nil ? "star.fill" : "star")
                         .font(.system(size: 18, weight: .semibold))
@@ -496,6 +466,7 @@ struct MapHomeView: View {
                 }
                 .buttonStyle(.plain)
                 .foregroundStyle(favorites.selectedFavoriteID != nil ? .orange : .gray)
+                .disabled(favoriteSaveTask != nil)
                 .accessibilityLabel(favorites.selectedFavoriteID != nil ? "已收藏，点击取消收藏" : "收藏当前选点")
             }
             // 收藏
@@ -616,7 +587,6 @@ struct MapHomeView: View {
                     spoofState = .active
                     activeSpoofLat = response.latitude
                     activeSpoofLon = response.longitude
-                    resetMapCoordinateSystemRefresh()
                     RuntimeLogger.info("APP", "定位", "第三方代理坐标同步成功", details: [
                         "坐标标准": "WGS-84",
                         "客户端模式": "测试模式",
@@ -655,7 +625,6 @@ struct MapHomeView: View {
                     activeSpoofLon = target.longitude
                     lastSpoofDiagnosisSystem = nil
                     hasLoggedSpoofDiagnosis = false
-                    resetMapCoordinateSystemRefresh()
                 }
                 RuntimeLogger.info("APP", "定位", "验证结果", details: [
                     "success": "true",
@@ -695,8 +664,6 @@ struct MapHomeView: View {
                     spoofState = .idle
                     activeSpoofLat = nil
                     activeSpoofLon = nil
-                    resetMapCoordinateSystemRefresh()
-                    refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: "第三方虚拟定位已停用")
                     presentSuccessfulOperationTip(.deactivation)
                 } catch {
                     spoofState = .active
@@ -713,8 +680,6 @@ struct MapHomeView: View {
         activeSpoofLon = nil
         lastSpoofDiagnosisSystem = nil
         hasLoggedSpoofDiagnosis = false
-        resetMapCoordinateSystemRefresh()
-        refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: "APP虚拟定位已停用")
         presentSuccessfulOperationTip(.deactivation)
     }
 
@@ -781,6 +746,58 @@ struct MapHomeView: View {
         )
     }
 
+    private var currentSelectionPair: CoordinatePair {
+        if let stored = LastCoordinateStore.load(),
+           stored.coordinate(for: CoordinateConverter.currentMapCoordinateSystem)
+            .isApproximatelyEqual(to: mapState.selection.coordinate) {
+            return stored.coordinatePair
+        }
+        return CoordinatePair(
+            mapCoordinate: mapState.selection.coordinate,
+            mapCoordinateSystem: CoordinateConverter.currentMapCoordinateSystem
+        )
+    }
+
+    private func coordinateRow(
+        label: String,
+        system: CoordinateConverter.MapCoordinateSystem
+    ) -> some View {
+        let coordinate = currentSelectionPair.coordinate(for: system)
+        let text = String(format: "%.6f, %.6f", coordinate.latitude, coordinate.longitude)
+        return HStack(spacing: 6) {
+            Text(label)
+                .font(.caption2.weight(.medium))
+                .foregroundStyle(.secondary)
+                .frame(width: 112, alignment: .leading)
+            Text(text)
+                .font(.caption.monospaced())
+                .foregroundStyle(copiedCoordinateSystem == system ? .green : .secondary)
+                .lineLimit(1)
+        }
+        .contentShape(Rectangle())
+        .onTapGesture {
+            UIPasteboard.general.string = text
+            copiedCoordinateSystem = system
+            RuntimeLogger.info("APP", "地图", "已复制坐标", details: [
+                "坐标标准": system.diagnosticName
+            ])
+            DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) {
+                if copiedCoordinateSystem == system { copiedCoordinateSystem = nil }
+            }
+        }
+        .overlay(alignment: .topTrailing) {
+            if copiedCoordinateSystem == system {
+                Text("已复制")
+                    .font(.caption2.bold())
+                    .foregroundStyle(.white)
+                    .padding(.horizontal, 8)
+                    .padding(.vertical, 2)
+                    .background(.green, in: Capsule())
+                    .offset(y: -24)
+            }
+        }
+    }
+
     private var testFavorite: FavoriteLocation { currentSelectionFavorite }
 
     private func startMapRuntimeOnce() {
@@ -794,19 +811,152 @@ struct MapHomeView: View {
         scheduleGeocode(pair: pair, revision: mapState.selection.revision)
     }
 
-    private func reprojectMapSelection(for change: CoordinateConverter.MapCoordinateSystemChange) {
+    @discardableResult
+    private func reprojectMapSelection(for change: CoordinateConverter.MapCoordinateSystemChange) -> Bool {
         // Every current selection is persisted as a complete coordinate pair at
         // its input boundary. Replaying the matching stored representation
         // avoids a second GCJ/WGS conversion and its accumulated offset.
         guard let stored = LastCoordinateStore.load() else {
             RuntimeLogger.warning("APP", "坐标转换", "地图坐标标准切换时未找到当前选点缓存")
-            return
+            return false
         }
         mapState.reprojectSelectionForMapCoordinateSystemChange(stored.coordinate(for: change.current))
         RuntimeLogger.info("APP", "坐标转换", "地图坐标标准切换后已使用缓存坐标对回显当前选点", details: [
             "from": change.previous.rawValue,
             "to": change.current.rawValue
         ])
+        return true
+    }
+
+    private func applyRuntimeMapCoordinateSystemChange(
+        _ change: CoordinateConverter.MapCoordinateSystemChange,
+        reason: String
+    ) {
+        geocodeDebounceTask?.cancel()
+        reverseGeocodeTask?.cancel()
+        searchRequestID &+= 1
+        isSearching = false
+        searchResults = []
+        searchError = ""
+        realtimeRequestTask?.cancel()
+        realtimeRequestTask = nil
+        realtimeRequestContext = nil
+        mapState.clearRealtimeLocationForMapCoordinateSystemChange()
+        let pinWasReprojected = reprojectMapSelection(for: change)
+        if let stored = LastCoordinateStore.load() {
+            scheduleGeocode(pair: stored.coordinatePair, revision: mapState.selection.revision)
+        }
+        RuntimeLogger.warning("APP", "坐标转换", "地图坐标类型已变化", details: [
+            "触发原因": reason,
+            "旧类型": change.previous.diagnosticName,
+            "新类型": change.current.diagnosticName,
+            "图钉已按新类型重设": String(pinWasReprojected),
+            "蓝点缓存": "已清理",
+            "搜索结果": "已清理",
+            "异步地理编码": "已重置"
+        ])
+    }
+
+    @discardableResult
+    private func refreshRuntimeMapCoordinateSystem(reason: String) async -> Bool {
+        let result = await CoordinateConverter.refreshRuntimeMapCoordinateSystem(reason: reason)
+        guard !Task.isCancelled else { return false }
+        switch result {
+        case .changed(let change):
+            applyRuntimeMapCoordinateSystemChange(change, reason: reason)
+            return true
+        case .unchanged:
+            return true
+        case .unavailable, .cancelled:
+            return false
+        }
+    }
+
+    private func scheduleBluePointMapCoordinateSystemRefresh() {
+        guard mapCoordinateSystemRefreshTask == nil else {
+            bluePointRefreshPending = true
+            return
+        }
+        mapCoordinateSystemRefreshID &+= 1
+        let refreshID = mapCoordinateSystemRefreshID
+        mapCoordinateSystemRefreshTask = Task { @MainActor in
+            defer {
+                if refreshID == mapCoordinateSystemRefreshID {
+                    let needsAnotherRefresh = bluePointRefreshPending && !Task.isCancelled
+                    mapCoordinateSystemRefreshTask = nil
+                    bluePointRefreshPending = false
+                    if needsAnotherRefresh {
+                        scheduleBluePointMapCoordinateSystemRefresh()
+                    }
+                }
+            }
+            // Coalesce the didUpdate/regionDidChange pair generated by one
+            // native location sample without caching the probe result.
+            try? await Task.sleep(nanoseconds: 350_000_000)
+            guard !Task.isCancelled, refreshID == mapCoordinateSystemRefreshID else { return }
+            var attempt = 0
+            repeat {
+                bluePointRefreshPending = false
+                _ = await refreshRuntimeMapCoordinateSystem(reason: "MapKit蓝点新样本")
+                attempt += 1
+            } while !Task.isCancelled
+                && refreshID == mapCoordinateSystemRefreshID
+                && bluePointRefreshPending
+                && attempt < 2
+        }
+    }
+
+    private func awaitCoordinatedMapCoordinateSystemRefresh(reason: String) async {
+        if let pendingRefresh = mapCoordinateSystemRefreshTask {
+            await pendingRefresh.value
+            return
+        }
+        mapCoordinateSystemRefreshID &+= 1
+        let refreshID = mapCoordinateSystemRefreshID
+        let task = Task { @MainActor in
+            _ = await refreshRuntimeMapCoordinateSystem(reason: reason)
+        }
+        mapCoordinateSystemRefreshTask = task
+        await task.value
+        if refreshID == mapCoordinateSystemRefreshID {
+            mapCoordinateSystemRefreshTask = nil
+        }
+    }
+
+    private func saveCurrentSelectionAsFavorite() {
+        guard favoriteSaveTask == nil else { return }
+        let snapshot = currentSelectionFavorite
+        // Preserve the pair created when this selection entered the map. If
+        // the runtime probe changes type, replay its other stored field instead
+        // of reinterpreting the old visible coordinate as the new type.
+        let pair = currentSelectionPair
+        let selectionRevision = mapState.selection.revision
+        favoriteSaveTask = Task { @MainActor in
+            defer { favoriteSaveTask = nil }
+            await awaitCoordinatedMapCoordinateSystemRefresh(reason: "保存收藏")
+            guard !Task.isCancelled else {
+                return
+            }
+            guard mapState.selection.revision == selectionRevision else {
+                RuntimeLogger.info("APP", "坐标转换", "取消保存收藏：检测期间当前选点已变化")
+                return
+            }
+            RuntimeLogger.info("APP", "坐标转换", "保存当前选点为收藏", details: [
+                "当前地图标准": CoordinateConverter.currentMapCoordinateSystem.diagnosticName,
+                "持久化字段": "国际标准(WGS-84)+国内标准(GCJ-02)"
+            ])
+            let favorite = favorites.save(
+                name: snapshot.name,
+                coordinatePair: pair,
+                accuracy: snapshot.accuracy
+            )
+            mapState.selectFavorite(
+                pair.coordinate(for: CoordinateConverter.currentMapCoordinateSystem),
+                id: favorite.id,
+                name: favorite.name
+            )
+            LastCoordinateStore.save(coordinatePair: pair, zoomMeters: mapState.viewportMeters)
+        }
     }
 
     private func registerWiFiChangeObserver() {
@@ -936,6 +1086,18 @@ struct MapHomeView: View {
     }
 
     private func requestRealtimeLocation() {
+        guard realtimeButtonTask == nil else { return }
+        realtimeButtonTask = Task { @MainActor in
+            defer { realtimeButtonTask = nil }
+            await awaitCoordinatedMapCoordinateSystemRefresh(reason: "点击实时定位")
+            guard !Task.isCancelled else {
+                return
+            }
+            performRealtimeLocationRequest()
+        }
+    }
+
+    private func performRealtimeLocationRequest() {
         let intent = mapState.beginRealtimeIntent()
         RuntimeLogger.info("APP", "实时定位", "用户点击实时定位", details: [
             "intentID": String(intent.id),
@@ -971,6 +1133,7 @@ struct MapHomeView: View {
     private func handleNativeRealtimeLocation(_ location: CLLocation) {
         mapState.updateRealtimeLocation(location)
         logSpoofCoordinateDiagnosisIfNeeded(location)
+        scheduleBluePointMapCoordinateSystemRefresh()
         guard let context = realtimeRequestContext else {
             return
         }
@@ -1005,17 +1168,12 @@ struct MapHomeView: View {
             lon: longitude,
             mapCoordinateSystem: .wgs84
         )
-        let maximumTargetDistance = max(1_000, location.horizontalAccuracy * 4)
         let diagnosis = CoordinateConverter.diagnoseRepresentation(
             sample: location.coordinate,
             pair: targetPair,
-            maximumDistance: maximumTargetDistance,
+            maximumDistance: max(1_000, location.horizontalAccuracy * 4),
             minimumSeparation: max(30, location.horizontalAccuracy)
         )
-        let nearestTargetDistance = min(diagnosis.distanceToWGS84, diagnosis.distanceToGCJ02)
-        if nearestTargetDistance <= maximumTargetDistance {
-            refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: "虚拟定位蓝点已到达目标")
-        }
         let shouldLog = !hasLoggedSpoofDiagnosis
             || diagnosis.inferredSystem != lastSpoofDiagnosisSystem
         guard shouldLog else { return }
@@ -1027,52 +1185,10 @@ struct MapHomeView: View {
             "蓝点回调更接近": diagnosis.inferredName,
             "蓝点距WGS目标米": String(format: "%.1f", diagnosis.distanceToWGS84),
             "蓝点距GCJ目标米": String(format: "%.1f", diagnosis.distanceToGCJ02),
-            "蓝点已到达目标": String(nearestTargetDistance <= maximumTargetDistance),
             "日志策略": "每次开启首次或判定变化"
         ])
     }
 
-    private func resetMapCoordinateSystemRefresh() {
-        coordinateSystemRefreshTask?.cancel()
-        coordinateSystemRefreshTask = nil
-        coordinateSystemRefreshTaskID = nil
-        coordinateSystemRefreshAttempts = 0
-        lastCoordinateSystemRefreshAt = nil
-    }
-
-    private func refreshMapCoordinateSystemAfterLocationEnvironmentChange(trigger: String) {
-        guard coordinateSystemRefreshTask == nil,
-              coordinateSystemRefreshAttempts < 3 else { return }
-        if let lastCoordinateSystemRefreshAt,
-           Date().timeIntervalSince(lastCoordinateSystemRefreshAt) < 2 {
-            return
-        }
-        coordinateSystemRefreshAttempts += 1
-        lastCoordinateSystemRefreshAt = Date()
-        let attempt = coordinateSystemRefreshAttempts
-        let taskID = UUID()
-        coordinateSystemRefreshTaskID = taskID
-        coordinateSystemRefreshTask = Task { @MainActor in
-            defer {
-                if coordinateSystemRefreshTaskID == taskID {
-                    coordinateSystemRefreshTask = nil
-                    coordinateSystemRefreshTaskID = nil
-                }
-            }
-            let change = await CoordinateConverter.refreshMapCoordinateSystem()
-            guard !Task.isCancelled, coordinateSystemRefreshTaskID == taskID else { return }
-            if let change {
-                reprojectMapSelection(for: change)
-            }
-            RuntimeLogger.info("APP", "坐标转换", "运行期地图坐标标准刷新请求结束", details: [
-                "触发": trigger,
-                "尝试": String(attempt),
-                "发生切换": String(change != nil),
-                "当前标准": CoordinateConverter.currentMapCoordinateSystem.rawValue
-            ])
-        }
-    }
-
     private func startRealtimeLocationRequest(
         source: String,
         showFailureAlert: Bool,
@@ -1146,14 +1262,7 @@ struct MapHomeView: View {
         sourceDescription: String
     ) {
         let currentViewport = mapState.viewportMeters
-        let previousMapCoordinateSystem = CoordinateConverter.currentMapCoordinateSystem
         let sourceCoordinateSystem = source.coordinateSystem
-        let mapCoordinateSystemChange = source == .coreLocation
-            ? CoordinateConverter.correctMapCoordinateSystemUsingRealtime(coordinate)
-            : nil
-        if let change = mapCoordinateSystemChange {
-            reprojectMapSelection(for: change)
-        }
         let pair = CoordinateConverter.coordinatePair(
             lat: coordinate.latitude,
             lon: coordinate.longitude,
@@ -1170,9 +1279,7 @@ struct MapHomeView: View {
             "intentID": String(intent.id),
             "intent选点revision": String(intent.selectionRevision),
             "当前选点revision": String(mapState.selection.revision),
-            "修正前地图标准": previousMapCoordinateSystem.rawValue,
-            "修正后地图标准": CoordinateConverter.currentMapCoordinateSystem.rawValue,
-            "地图标准发生修正": String(mapCoordinateSystemChange != nil),
+            "App已确认地图标准": CoordinateConverter.currentMapCoordinateSystem.rawValue,
             "accepted": String(accepted),
             "显示坐标字段": CoordinateConverter.currentMapCoordinateSystem.rawValue,
             "持久化字段": "WGS-84+GCJ-02"

App/MapLocationState.swift

@@ -222,6 +222,13 @@ final class MapLocationState: ObservableObject {
         if coordinate == nil { realtimeLocation = nil }
     }
 
+    /// Discards a blue-point sample represented in a superseded MapKit
+    /// coordinate system. The next native callback repopulates the cache.
+    func clearRealtimeLocationForMapCoordinateSystemChange() {
+        realtimeLocation = nil
+        realtimeCoordinate = nil
+    }
+
     func updateExplicitName(_ name: String, forFavoriteID favoriteID: UUID) {
         guard selection.source == .favorite(favoriteID) else { return }
         selection = MapSelection(