chore: prepare v1.0.2 release

docs: refresh installation and feature previews
fix: improve coordinate selection feedback
2026-09-22 14:50:43 +08:00 · 2026-08-07 17:01:54 +08:00 · 2026-08-07 16:45:02 +08:00 · 2026-08-07 16:43:34 +08:00 · 2026-08-07 15:01:17 +08:00 · 2026-08-07 14:54:03 +08:00
19 changed files with 1215 additions and 361 deletions
@@ -46,6 +46,7 @@ private enum RealtimeCoordinateSource: Equatable {
 }

 struct MapHomeView: View {
+    @Environment(\.scenePhase) private var scenePhase
    @ObservedObject var setup: SetupCoordinator
    @StateObject private var favorites: FavoriteLocationStore
    @StateObject private var actions = LocationActionCoordinator()
@@ -78,10 +79,15 @@ 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?
@@ -232,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)
@@ -279,6 +285,19 @@ struct MapHomeView: View {
            wifiVerificationTask?.cancel()
            wifiVerificationTask = nil
            wifiVerificationID = nil
+            mapCoordinateSystemRefreshTask?.cancel()
+            mapCoordinateSystemRefreshTask = nil
+            bluePointRefreshPending = false
+            realtimeButtonTask?.cancel()
+            realtimeButtonTask = nil
+            favoriteSaveTask?.cancel()
+            favoriteSaveTask = nil
+        }
+        .onChange(of: scenePhase) { phase in
+            guard phase == .active else { return }
+            Task { @MainActor in
+                await awaitCoordinatedMapCoordinateSystemRefresh(reason: "App回到前台")
+            }
        }
        .onChange(of: proxy.isRunning) { running in
            if runtimeMode.mode == .localWiFi, !running && spoofState == .active {
@@ -412,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()
                // 帮助说明按钮
@@ -457,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))
@@ -482,6 +466,7 @@ struct MapHomeView: View {
                }
                .buttonStyle(.plain)
                .foregroundStyle(favorites.selectedFavoriteID != nil ? .orange : .gray)
+                .disabled(favoriteSaveTask != nil)
                .accessibilityLabel(favorites.selectedFavoriteID != nil ? "已收藏，点击取消收藏" : "收藏当前选点")
            }
            // 收藏
@@ -761,6 +746,62 @@ 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)
+                .lineLimit(1)
+                .fixedSize(horizontal: true, vertical: false)
+            Text(text)
+                .font(.caption.monospaced())
+                .foregroundStyle(copiedCoordinateSystem == system ? .green : .secondary)
+                .lineLimit(1)
+                .minimumScaleFactor(0.72)
+                .allowsTightening(true)
+                .layoutPriority(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() {
@@ -774,19 +815,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() {
@@ -916,6 +1090,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),
@@ -951,6 +1137,7 @@ struct MapHomeView: View {
    private func handleNativeRealtimeLocation(_ location: CLLocation) {
        mapState.updateRealtimeLocation(location)
        logSpoofCoordinateDiagnosisIfNeeded(location)
+        scheduleBluePointMapCoordinateSystemRefresh()
        guard let context = realtimeRequestContext else {
            return
        }
@@ -1079,14 +1266,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,
@@ -1103,9 +1283,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"
@@ -1122,7 +1300,7 @@ struct MapHomeView: View {
        mapState.focusSelection(distanceMeters: currentViewport)
        // Persist both forms once from the explicitly typed input boundary.
        LastCoordinateStore.save(coordinatePair: pair, zoomMeters: currentViewport)
-        favorites.select(nil)
+        favorites.selectMatching(coordinatePair: pair)
        scheduleGeocode(pair: pair, revision: mapState.selection.revision)
    }

@@ -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(
@@ -2,174 +2,393 @@

 # 📍 Location Spoofer

-### iOS Location Spoofer · DingTalk · WeChat · Apple Watch Region Unlock · Fake GPS
+### iOS Location Service Research & Testing Framework

-**No jailbreak — use App Mode's on-device Wi-Fi HTTP proxy or Third-party Proxy Mode (Wi-Fi/4G/5G) to rewrite Apple location responses.**<br>
-Works with DingTalk check-in, WeChat location sharing, and any app that uses system location. Map selection, real-time location, environment verification, certificate setup, and runtime logs in a single app.
+An open-source project for **iOS location-service research, software development testing, and QA validation**.
+
+The project uses either an on-device proxy or a third-party proxy client to simulate selected Apple location-service
+responses in a controlled test environment.

 [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
-[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml)
-[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod)
-[![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
-[![App Mode](https://img.shields.io/badge/App%20Mode-No%20VPN-16A34A)](#why-no-vpn)
+[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
+[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
+[![Version](https://img.shields.io/badge/version-v1.0.2-2563EB)](docs/CHANGELOG.md)

-[Features](#key-features) · [Quick Start](#quick-start) · [中文](README.md) · [Changelog](docs/CHANGELOG.md)
-
-<img src="images/主界面.jpg" alt="Location Spoofer iOS Fake GPS main interface" width="380">
+[Features](#feature-overview) ·
+[How It Works](#how-it-works) ·
+[Quick Start](#quick-start) ·
+[Build](#building-the-project) ·
+[中文](README.md)

 </div>

 > [!IMPORTANT]
-> This project is intended for education, security research, and testing on your own devices. App Mode installs a locally generated CA and requires a manual HTTP proxy on the current Wi-Fi network. In Third-party Proxy Mode, the selected client owns certificate, MITM, and proxy/VPN setup. Please understand the risks and follow applicable laws and service terms.
+> Use this project only for education, research, testing on devices you own, software development, and QA validation.
+>
+> Use it only on devices, networks, and software environments that you own or are authorized to test. Follow applicable
+> laws, network policies, and service terms.
+>
+> The project does not guarantee compatibility with every iOS version or third-party app, and it does not promise to
+> bypass third-party security controls, business restrictions, or service rules.

-## Credits
+## Project Scope

-The core location-response rewriting approach and Go implementation are based on [Yu9191/wloc](https://github.com/Yu9191/wloc). This project adds a SwiftUI interface, MapKit selection, certificate and proxy guidance, environment verification, favorites, and diagnostics.
+Location Spoofer is a tool for studying iOS location-service behavior and testing location-dependent software.

-## Why Location Spoofer?
+It provides:

-Unlike tools that require a computer to stay connected, a VPN tunnel, or a jailbroken device, Location Spoofer keeps the control flow on the iPhone itself.
+- Native map selection and location-scenario switching;
+- Controlled simulation of selected Apple location-service responses;
+- App Mode and Third-party Proxy Mode;
+- Map coordinate detection with paired WGS-84 and GCJ-02 values;
+- Environment checks, runtime logs, and diagnostics;
+- Favorite locations and restoration of the previous map state.

-| Feature | Description |
+The project does not modify the target app's source code and does not provide telemetry, remote control, or data
+collection services.
+
+## Feature Overview
+
+- **Native map interaction**
+  - Uses MapKit for the map and system blue dot;
+  - Supports search, map taps, center-point dragging, and zooming;
+  - Supports favorites and restoration of the latest selection;
+  - Shows both domestic and international coordinate representations with separate copy actions.
+
+- **Location-service response simulation**
+  - Processes only the Apple location-service requests defined by the project;
+  - Returns the selected coordinates in a controlled test environment;
+  - Does not require changes to the target app.
+
+- **Two runtime modes**
+  - App Mode: runs the Go proxy on-device and covers only the current Wi-Fi network;
+  - Third-party Proxy Mode: uses a supported proxy client and may cover Wi-Fi, 4G, or 5G depending on that client.
+
+- **Environment checks**
+  - App Mode checks the local proxy, CA trust, and request path;
+  - Third-party Proxy Mode checks the WLOC configuration API and module response;
+  - Failures route to the relevant setup or diagnostics screen.
+
+- **Development diagnostics**
+  - Runtime logs;
+  - Log copy and cleanup;
+  - Map coordinate-system change records;
+  - Sanitized issue-report generation.
+
+## How It Works
+
+### App Mode
+
+App Mode runs the local Go proxy inside the app. A manual HTTP proxy on the current Wi-Fi routes the selected requests
+through that on-device proxy.
+
+```text
+iOS location request
+      │
+      │ Manual HTTP proxy on the current Wi-Fi
+      ▼
+On-device wloccore Go proxy
+      │
+      │ Handle selected Apple location-service requests
+      ▼
+Apple location-service response
+      │
+      │ Test coordinate response
+      ▼
+The system and apps read the location result
+```
+
+App Mode:
+
+- Does not create a Network Extension;
+- Does not display or occupy the system VPN slot;
+- Covers only the current Wi-Fi network;
+- Requires a manual HTTP proxy on that Wi-Fi network;
+- Requires installation and trust of the CA generated by the app;
+- Handles only the Apple location-service and environment-verification traffic defined by the project. It is not a
+  general-purpose packet capture tool.
+
+### Third-party Proxy Mode
+
+Third-party Proxy Mode does not start the app's Go proxy and does not use the CA generated by the app.
+
+```text
+Map selection
+  │
+  │ WGS-84 coordinates
+  ▼
+WLOC configuration API
+  │
+  ▼
+Third-party proxy client stores the configuration
+  │
+  ▼
+Third-party client processes location-service requests
+```
+
+In this mode:
+
+- The app owns map selection, favorites, coordinate synchronization, and coordinate clearing;
+- The third-party client owns proxy/VPN, MITM, certificates, and rule execution;
+- The third-party client owns coordinate persistence;
+- Wi-Fi, 4G, and 5G support depends on the client;
+- The configuration may remain active after Location Spoofer closes.
+
+Do not enable App Mode interception and Third-party Proxy Mode interception at the same time.
+
+## Runtime Modes
+
+### App Mode
+
+Suitable for:
+
+- Wi-Fi-only device testing;
+- Local testing without a third-party proxy client;
+- Workflows that need in-app proxy, certificate, and environment guidance.
+
+Requirements:
+
+- An iOS device;
+- A Wi-Fi network that permits manual HTTP proxy configuration;
+- Installation and trust of the local CA;
+- Completion of the in-app proxy and environment checks.
+
+### Third-party Proxy Mode
+
+Suitable for:
+
+- Tests that need Wi-Fi, 4G, or 5G coverage;
+- Existing supported proxy-client workflows;
+- Cases where the third-party client should keep the proxy configuration active.
+
+Current client status:
+
+| Client | Status |
 |---|---|
-| 🔀 **Two runtime modes** | Stable App Mode, plus a Third-party Proxy Mode under testing for Wi-Fi, 4G, and 5G. |
-| 📱 **No jailbreak** | Can be installed through self-signing; minimum deployment target is iOS 15. |
-| 🗺️ **Native Maps experience** | The same blue dot and selection gestures as Apple Maps — search, tap, and drag. |
-| 📍 **System-level location spoofing** | Works with DingTalk, WeChat, Apple Maps, Amap, and other apps for real-time fake GPS. |
-| 🔍 **Visible map scale** | Left-side controls show the current visible range; place name adapts to zoom level. |
-| 🧪 **Environment verification** | Checks proxy, CA trust, Wi‑Fi interception, coordinate write, and response rewrite. |
-| 🧾 **Diagnostics** | Per-entry copy for easy sharing and debugging. |
+| Shadowrocket | Currently used for on-device testing |
+| Surge | Configuration provided, not fully verified |
+| Quantumult X | Configuration provided, not fully verified |
+| Loon | Configuration provided, not fully verified |
+| Stash | Configuration provided, not fully verified |
+| Egern | Uses the Surge module, not fully verified |

-## Screenshots
+Module snapshots and provenance:

-| Main Interface | Apple Maps | Amap | Apple Watch |
-|---|---|---|---|
-| ![Location Spoofer main interface](images/主界面.jpg) | ![Apple Maps result](images/Apple%20Map.jpg) | ![Amap result](images/高德地图.jpg) | ![Apple Watch region feature](images/高血压.jpg) |
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)

-## Key Features
-
- **iOS Location Spoofer / Fake GPS**: Apply the selected coordinate to the local proxy that rewrites location responses, compatible with DingTalk check-in, WeChat location sharing, and more.
- **Native real-time location**: The map displays MapKit's own blue dot — no extra "fake real-time" overlay.
- **Concurrency-safe selection**: Pan, tap, search, favorites, and async location respect the user's latest intent; stale results won't overwrite newer selections.
- **Hierarchical place names**: POI, street, or road at close zoom; neighborhood, district, city, or province at wider zoom.
- **Map scale display**: Zoom controls show the current visible range.
- **Favorites with quick switch**: Save frequent coordinates and see which location is about to be applied.
- **Mode-specific setup**: Choose a mode first; App Mode guides local proxy and CA setup, while Third-party Proxy Mode guides client selection, configuration import, and API verification.
- **Built-in diagnostics**: Verification flow and structured runtime logs.
- **Third-party Proxy Mode (testing)**: Send a favorite or current pin as WGS-84 to a supported proxy module; the proxy client persists it after this App exits.
+The selected client owns its certificates, MITM configuration, and proxy switches. Review third-party modules and
+scripts before importing them.

 ## Quick Start

 ### 1. Install the App

- Download a build from [Releases](https://github.com/xweiba/location-spoofer/releases) and self-sign; or
- Build from source on macOS with Xcode — see the [build guide](docs/BUILD.md).
+You can use:

-The release asset is an unsigned IPA. Sign it with [Impact](https://github.com/claration/Impactor) before installation. Keep the app Bundle ID `com.paopaolabs.location-spoofer`, the App Group `group.com.paopaolabs.location-spoofer`, and the declared entitlements unchanged. A free Apple ID signature normally expires after seven days and must then be renewed.
+- Your own Apple Developer signing environment;
+- A self-signing tool suitable for personal testing;
+- The unsigned IPA published in Releases;
+- A source build produced on macOS using the [build guide](docs/BUILD.md).

-### 2. Choose a Runtime Mode
+Free self-signing environments may not provide Network Extension capabilities. App Mode therefore uses an on-device
+proxy plus a manual Wi-Fi HTTP proxy and does not depend on a VPN component.

-#### App Mode
+#### Self-Signing Instructions

-Choose App Mode during first launch, then configure `127.0.0.1:8888` and fully trust the locally generated CA. It has no third-party client dependency but supports Wi-Fi only. Free self-signed apps cannot use the VPN/Network Extension capability required for cellular interception, so this mode uses the current Wi-Fi's manual HTTP proxy.
+Release assets are unsigned IPA files and must be installed on an iPhone with a self-signing tool:

-#### Third-party Proxy Mode
+1. **Enable sideloading support**: On iOS 16 or newer, open Settings → Privacy & Security → Developer Mode, enable it,
+   then restart and confirm when prompted. iOS 15 does not have this switch, so skip this step.
+2. **Download the IPA**: Open this project's [Releases](https://github.com/xweiba/location-spoofer/releases) and download
+   the latest `PaopaoLocationSpoofer-unsigned.ipa`.
+3. **Prepare signing software**: Download the appropriate Impactor build from
+   [Impactor Releases](https://github.com/claration/Impactor/releases). Other tools that support self-signing and installing
+   IPA files, such as Aisi Assistant, may also be used.
+4. **Connect and install**: Connect the iPhone to the computer with a USB cable, choose “Trust This Computer” on the
+   phone, select the downloaded IPA in the signing software, and follow that tool's instructions to sign and install it.

-The App handles map selection, favorites, and WGS-84 coordinate delivery. A third-party proxy client handles WLOC interception, MITM, and persistence over Wi-Fi, 4G, or 5G. This mode skips the App's local proxy and CA checks.
+Impactor supports Windows, macOS, and Linux. If Windows cannot detect the device, install the Apple device drivers supplied
+with iTunes first. Aisi Assistant is third-party software; obtain it from its official channel and evaluate its account,
+certificate, and privacy risks yourself.

-Shadowrocket is the only client currently available for device testing. Surge, Quantumult X, Loon, Stash, and Egern configurations are provided but unverified. The App lets the user copy the official subscription URL and open the selected client; the URL is then pasted into that client's module, rewrite, or override subscription UI. Configuration snapshots remain bundled for release provenance and offline inspection, but the setup UI does not export files. Egern uses the Surge module, and Stash imports `.stoverride` directly without Script Hub conversion. The third-party client—not this App—owns MITM, certificate, and proxy/VPN setup. Snapshot provenance is recorded in [the module snapshot document](docs/THIRD_PARTY_MODULES.md).
+After installation, if iOS blocks the app from opening, go to Settings → General → VPN & Device Management and trust the
+corresponding developer app. A free Apple ID signature normally expires after seven days and must then be renewed.

-### 3. Local-mode CA Setup
+### 2. First Launch

-Follow the first-setup wizard to download the profile, then:
+1. Choose App Mode or Third-party Proxy Mode;
+2. Complete the corresponding in-app setup;
+3. Run the environment check;
+4. Search, tap, or drag on the map to select a test location;
+5. Enable the test location and verify the result in the authorized test environment.
+
+### 3. Restore the Real Location
+
+App Mode:
+
+1. Stop the test location;
+2. Disable the manual HTTP proxy on the current Wi-Fi network;
+3. Follow the in-app instructions to refresh the location environment.
+
+Third-party Proxy Mode:
+
+1. Clear the WLOC coordinates from the app;
+2. Disable the corresponding module or proxy in the third-party client;
+3. Restore HTTPS decryption and proxy settings according to the client documentation.
+
+Location caches may take time to refresh. Restart the device if the system or target app continues to show an old
+location.
+
+## Coordinate Handling
+
+The project stores two coordinate representations:
+
+- WGS-84: the international standard used for WLOC writes;
+- GCJ-02: the domestic map representation used where required.
+
+MapKit does not expose a public API that reports whether its current runtime output uses GCJ-02 or WGS-84. The project
+uses a fixed-anchor query to resolve the active representation and performs controlled refreshes after blue-dot changes
+and explicit user actions.
+
+Each write boundary stores a complete WGS-84/GCJ-02 pair. Rendering selects the field matching the confirmed map
+representation instead of repeatedly converting an already typed value.
+
+## Project Structure

 ```text
-Settings → General → VPN & Device Management → install WLOC CA
-Settings → General → About → Certificate Trust Settings → enable full trust
+App/        SwiftUI interface, MapKit, location, and runtime flow
+Core/       Go proxy, certificate server, and location-response handling
+Shared/     Coordinates, favorites, logs, configuration, and shared models
+Resources/  Info.plist, Entitlements, and resources
+Config/     Build configuration
+Scripts/    Build, packaging, and validation scripts
+Tests/      XCTest and Shell contract tests
+docs/       Build, module, and release documentation
 ```

-Configure the current Wi-Fi proxy before installing the CA:
+## Building the Project

-On the current Wi‑Fi's proxy settings, choose "Manual":
+Source builds require:

-```text
-Server: 127.0.0.1
-Port: 8888
-Authentication: off
-```
+- macOS;
+- Xcode;
+- Xcode Command Line Tools;
+- XcodeGen;
+- Go 1.23 or newer.

-### 4. Select a Location & Enable
-
-1. Search, tap, or drag the map to pick a location; tap the real-time location button to jump to the MapKit blue dot.
-2. In App Mode, tap “Start Spoofing” and wait for verification. In Third-party Proxy Mode, tap “Sync to Third-party Proxy.”
-3. Follow the in‑app activation instructions to refresh airplane mode, Wi‑Fi, and location services.
-4. Open Apple Maps or your target app to verify.
-
-### 5. Restore Your Real Location
-
-Stop spoofing, remove the manual proxy from the current Wi‑Fi, and follow the in‑app deactivation instructions to refresh the system location cache. If stale cache persists, restart your device.
-
-## Why No VPN?
-
-```text
-iPhone location request
-        │ Wi‑Fi HTTP proxy: 127.0.0.1:8888
-        ▼
-Local wloccore Go proxy
-        │ Handles only the targeted Apple location-service traffic
-        ▼
-Apple location service response
-        │ The selected coordinate is written into the response
-        ▼
-The system and applications receive the modified result
-```
-
-App Mode does not use Network Extension, so it does not occupy the VPN slot. **App Mode still requires the current Wi-Fi HTTP proxy and the locally generated CA.** Third-party Proxy Mode delegates proxy/VPN and MITM handling to the selected proxy client and may cover cellular networks. Do not enable both interception paths at once.
-
-## Compatibility
-
-| Item | Requirement |
-|---|---|
-| iOS | 15.0+ |
-| Build | macOS, Xcode, XcodeGen |
-| Swift | 5.9 |
-| Go | 1.23+ |
-| Network | Local mode: Wi-Fi with manual HTTP proxy support; third-party test mode: client-dependent Wi-Fi/4G/5G |
-| Installation | Self-sign or use release builds |
-
-Actual behavior may vary with iOS version, network conditions, system location cache, device model, and the target app's own location strategy. Compatibility with every iOS version or third-party app is not guaranteed.
-
-## Build & Project Structure
+Building the iOS app directly on Windows is not supported.

 ```bash
+git clone https://github.com/xweiba/location-spoofer.git
+cd location-spoofer
+
 ./build.sh
 ```

-The unsigned IPA is at:
+Build and run Simulator tests:
+
+```bash
+./build.sh --test
+```
+
+The build script generates an unsigned IPA:

 ```text
 dist/PaopaoLocationSpoofer-unsigned.ipa
 ```

-```text
-App/        SwiftUI, MapKit, location and setup flow
-Core/       Go local proxy and location response rewriting
-Shared/     Favorites, settings, logs, and shared models
-Resources/  Info.plist, Entitlements, and icons
-Scripts/    Build, signing, and verification scripts
-Tests/      XCTest and Bash contract tests
-docs/       Build, self-signing, and changelog documentation
-```
+Deploy it to a test device using your own signing and installation process.

-## Documentation & Feedback
+## Privacy and Security Boundaries
+
+- The project contains no telemetry or remote-control service;
+- The project does not automatically upload location data;
+- Runtime logs remain in the device App Group container and retain only the latest three days;
+- Issue reports are copied by the user before being submitted to GitHub;
+- App Mode accesses the local proxy and the environment-verification URL;
+- Third-party Proxy Mode may access the upstream module URL and the WLOC configuration endpoint;
+- The CA private key generated by the app is stored in the device Keychain;
+- Third-party MITM, certificates, and proxy behavior are owned by the selected client.
+
+Do not post real locations, authentication information, CA private keys, or complete sensitive logs in public issues.
+
+## Limitations
+
+- iOS updates may change location-service behavior;
+- MapKit coordinate output can vary with the system, region, and location environment;
+- System location caches may delay visible changes;
+- Each third-party proxy client requires separate compatibility testing;
+- Not every app uses the same location API;
+- Not every app or service accepts test coordinates;
+- Behavior is not guaranteed across every network, device model, or iOS version.
+
+## Contributing
+
+Contributions are welcome for:
+
+- Bug reports;
+- Feature requests;
+- Compatibility results;
+- Performance improvements;
+- Documentation improvements;
+- Additional tests.
+
+When filing an issue, include:
+
+- iOS version;
+- Device model;
+- Runtime mode;
+- Reproduction steps;
+- Sanitized runtime logs;
+- Whether a third-party proxy client was used.
+
+## Documentation

 - [Build guide](docs/BUILD.md)
+- [Third-party module documentation](docs/THIRD_PARTY_MODULES.md)
 - [Changelog](docs/CHANGELOG.md)
 - [中文文档](README.md)
 - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)

-When reporting issues, please include reproduction steps, iOS version, device model, and sanitized runtime logs.
+## Feature Preview

-## Links
+These screenshots show the main interface and selected on-device test scenarios. Actual results depend on the iOS
+version, network environment, system caches, and the target app's location strategy; they are not a compatibility
+guarantee for every app or release.

-**LinuxDo** — [https://linux.do](https://linux.do/)
+<table>
+  <tr>
+    <th>Main interface</th>
+    <th>Apple Maps test</th>
+    <th>Amap test</th>
+  </tr>
+  <tr>
+    <td><img src="images/主界面.jpg" alt="Location Spoofer map selection interface" width="220"></td>
+    <td><img src="images/Apple%20Map.jpg" alt="Apple Maps location test scenario" width="220"></td>
+    <td><img src="images/高德地图.jpg" alt="Amap location test scenario" width="220"></td>
+  </tr>
+  <tr>
+    <th>WeChat test</th>
+    <th>DingTalk test</th>
+    <th>Apple Watch scenario test</th>
+  </tr>
+  <tr>
+    <td><img src="images/微信.jpg" alt="WeChat location test scenario" width="220"></td>
+    <td><img src="images/钉钉.jpg" alt="DingTalk location test scenario" width="220"></td>
+    <td><img src="images/高血压.jpg" alt="Apple Watch region-feature test scenario" width="220"></td>
+  </tr>
+</table>
+
+## Acknowledgements and Links
+
+The core location-response handling approach, Go implementation, and third-party modules are based on:
+
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
+
+Community link:
+
+- [LINUX DO](https://linux.do/)
+
+Thanks to the open-source contributors working on iOS location-service research, network proxies, and mobile testing
+tools.
@@ -2,227 +2,384 @@

 # 📍 Location Spoofer

-### iOS 虚拟定位 · 钉钉定位 · 微信定位 · Apple Watch 国区功能解锁 · Fake GPS
+### iOS Location Service Research & Testing Framework

-**无需越狱；可使用 APP模式的本机 Wi‑Fi HTTP 代理，或第三方代理模式（支持 Wi‑Fi/4G/5G）改写 Apple 定位响应。**<br>
-可修改钉钉、微信及任意依赖系统定位的 App 的位置。地图选点、实时位置、环境检测、证书配置与运行日志集中在一个 App 中。
+一个用于 **iOS 定位服务研究、软件开发测试和 QA 验证** 的开源项目。
+
+项目通过本机代理或第三方代理客户端，对 Apple 定位服务的指定响应进行测试环境模拟，帮助开发者验证应用在
+不同地理位置和定位场景下的行为。

 [![iOS 15+](https://img.shields.io/badge/iOS-15%2B-111111?logo=apple)](project.yml)
-[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138?logo=swift&logoColor=white)](project.yml)
-[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go&logoColor=white)](Core/go.mod)
-[![Version](https://img.shields.io/badge/version-v1.0.1-2563EB)](docs/CHANGELOG.md)
-[![App Mode](https://img.shields.io/badge/APP模式-无需VPN-16A34A)](#为什么不需要-vpn)
+[![Swift 5.9](https://img.shields.io/badge/Swift-5.9-F05138)](project.yml)
+[![Go 1.23+](https://img.shields.io/badge/Go-1.23%2B-00ADD8?logo=go)](Core/go.mod)
+[![Version](https://img.shields.io/badge/version-v1.0.2-2563EB)](docs/CHANGELOG.md)

-[功能介绍](#核心功能) · [安装使用](#快速开始) · [English](README.en.md) · [更新日志](docs/CHANGELOG.md)
-
-<img src="images/主界面.jpg" alt="Location Spoofer iOS 虚拟定位 Fake GPS 主界面" width="380">
+[功能概览](#功能概览) ·
+[工作原理](#工作原理) ·
+[快速开始](#快速开始) ·
+[构建项目](#构建项目) ·
+[English](README.en.md)

 </div>

 > [!IMPORTANT]
-> 本项目用于学习、安全研究与自有设备测试。APP模式需要安装自签 CA，并在当前 Wi‑Fi 上配置本机 HTTP 代理；第三方代理模式的证书、MITM 和代理/VPN 连接由所选客户端处理。请先阅读工作原理和风险说明，并遵守当地法律、网络管理规则及相关服务条款。
+> 本项目用于学习研究、自有设备测试、软件开发和 QA 验证。
+>
+> 请仅在你拥有或获得授权的设备、网络和软件环境中使用，并遵守当地法律法规、网络管理规定以及相关服务条
+> 款。
+>
+> 本项目不保证兼容所有 iOS 版本或第三方应用，也不承诺绕过第三方应用的安全策略、业务限制或服务规则。

-## 致谢
+## 项目定位

-核心定位响应改写思路与 Go 实现来源于 [Yu9191/wloc](https://github.com/Yu9191/wloc)。本项目在此基础上增加 SwiftUI 界面、MapKit 选点、证书与代理引导、环境验证、收藏和诊断能力。
+Location Spoofer 是一个面向 iOS 定位服务行为研究和开发测试的工具。

-## 为什么选择 Location Spoofer？
+它提供：

-很多 iOS 虚拟定位工具依赖电脑常驻、开发者调试、VPN 或越狱。本项目采用不同路线：在 iPhone 本机运行 Go 代理，仅对 Apple 定位服务目标请求进行处理。
+- 原生地图选点和位置场景切换；
+- Apple 定位服务响应的测试环境模拟；
+- 本地代理和第三方代理两种运行模式；
+- 坐标标准识别与 WGS-84 / GCJ-02 双坐标管理；
+- 环境检测、运行日志和问题诊断；
+- 收藏位置和上次地图状态恢复。

-| 特性 | 说明 |
+项目不修改目标 App 的源代码，也不提供远程控制或数据采集服务。
+
+## 功能概览
+
+- **原生地图交互**
+    - 使用 MapKit 显示地图和系统蓝点；
+    - 支持搜索、点击选点、拖动地图中心和缩放；
+    - 支持收藏位置和恢复上次选点；
+    - 当前选点同时显示国内坐标和国际坐标，可分别复制。
+
+- **定位服务响应模拟**
+    - 通过代理层处理指定的 Apple 定位服务请求；
+    - 在测试环境中返回选定的坐标数据；
+    - 不需要修改目标 App 代码。
+
+- **双运行模式**
+    - APP 模式：在设备内运行 Go 代理，仅支持当前 Wi-Fi 网络；
+    - 第三方代理模式：通过支持的代理客户端覆盖 Wi-Fi、4G 或 5G，具体能力取决于客户端。
+
+- **环境检测**
+    - APP 模式检测本地代理、证书信任和请求链路；
+    - 第三方代理模式检测 WLOC 配置接口和模块响应；
+    - 失败时提供对应的配置或诊断入口。
+
+- **开发调试**
+    - 运行日志；
+    - 日志复制和清理；
+    - 坐标标准变化记录；
+    - 脱敏问题报告生成。
+
+## 工作原理
+
+### APP 模式
+
+APP 模式在设备内运行本地 Go 代理，并通过当前 Wi-Fi 的手动 HTTP 代理让指定请求经过本地代理。
+
+```text
+iOS 定位请求
+      │
+      │ 当前 Wi-Fi 手动 HTTP 代理
+      ▼
+设备内 wloccore Go 代理
+      │
+      │ 处理指定 Apple 定位服务请求
+      ▼
+Apple 定位服务响应
+      │
+      │ 测试坐标响应
+      ▼
+系统和应用读取定位结果
+```
+
+APP 模式：
+
+- 不创建 Network Extension；
+- 不显示或占用系统 VPN；
+- 只覆盖当前 Wi-Fi 网络；
+- 需要配置当前 Wi-Fi 的手动 HTTP 代理；
+- 需要安装并信任 App 生成的本机 CA；
+- 代理只处理项目定义的 Apple 定位服务和环境验证请求，不是通用网络抓包工具。
+
+### 第三方代理模式
+
+第三方代理模式不启动 App 内置 Go 代理，也不使用 App 生成的 CA。
+
+```text
+地图选点
+  │
+  │ WGS-84 坐标
+  ▼
+WLOC 配置接口
+  │
+  ▼
+第三方代理客户端保存配置
+  │
+  ▼
+第三方代理客户端处理定位服务请求
+```
+
+在该模式下：
+
+- App 负责地图选点、收藏、坐标同步和清除；
+- 第三方客户端负责代理/VPN、MITM、证书和规则执行；
+- 坐标持久化由第三方客户端负责；
+- 是否支持 Wi-Fi、4G 或 5G 取决于客户端；
+- App 关闭后，第三方客户端中的配置可能继续生效。
+
+不要同时启用 APP 模式代理和第三方代理模式，避免两个代理链路互相干扰。
+
+## 运行模式
+
+### APP 模式
+
+适用于：
+
+- 只使用 Wi-Fi 的设备测试；
+- 不依赖第三方代理客户端的本地验证；
+- 需要在 App 内完成代理、证书和环境检测的场景。
+
+使用条件：
+
+- iOS 设备；
+- 当前 Wi-Fi 支持手动 HTTP 代理；
+- 安装并信任本机 CA；
+- 在 App 内完成代理配置和环境检测。
+
+### 第三方代理模式
+
+适用于：
+
+- 需要 Wi-Fi、4G 或 5G 网络覆盖的测试；
+- 已经使用支持模块或脚本的代理客户端；
+- 希望由第三方客户端继续保持代理配置的场景。
+
+当前客户端状态：
+
+| 客户端 | 状态 |
 |---|---|
-| 🔀 **双运行模式** | APP模式无需第三方客户端、支持 Wi‑Fi；第三方代理模式可覆盖 Wi‑Fi、4G 和 5G |
-| 📱 **无需越狱** | 支持自行签名安装，最低部署目标为 iOS 15 |
-| 🗺️ **原生地图体验** | 使用 Apple 地图同款蓝点，搜索、点击、拖动选点体验与 Apple 地图一致 |
-| 📍 **系统级虚拟定位** | 支持钉钉、微信、Apple 地图、高德等 App 的虚拟实时定位 |
-| 🔍 **可见缩放范围** | 左侧缩放控件显示当前可视范围，地点名称随级别自动适配 |
-| 🧪 **环境检测** | 检查本地代理、CA 证书信任与 Wi‑Fi 代理链路 |
-| 🧾 **诊断日志** | 每条日志独立可复制，方便整理和反馈问题 |
+| Shadowrocket | 当前用于真机测试 |
+| Surge | 已提供配置，尚未完整验证 |
+| Quantumult X | 已提供配置，尚未完整验证 |
+| Loon | 已提供配置，尚未完整验证 |
+| Stash | 已提供配置，尚未完整验证 |
+| Egern | 使用 Surge 模块，尚未完整验证 |

-## 效果预览
+相关模块快照和来源记录：

-<table>
-  <tr>
-    <th>应用主界面</th>
-    <th>钉钉</th>
-    <th>微信</th>
-  </tr>
-  <tr>
-    <td><img src="images/主界面.jpg" alt="iOS 虚拟定位应用主界面" width="180"></td>
-    <td><img src="images/钉钉.jpg" alt="钉钉虚拟定位打卡" width="180"></td>
-    <td><img src="images/微信.jpg" alt="微信虚拟定位" width="180"></td>
-  </tr>
-  <tr>
-    <th>Apple 地图</th>
-    <th>高德地图</th>
-    <th>Apple Watch</th>
-  </tr>
-  <tr>
-    <td><img src="images/Apple%20Map.jpg" alt="Apple Maps 定位效果" width="180"></td>
-    <td><img src="images/高德地图.jpg" alt="高德地图定位效果" width="180"></td>
-    <td><img src="images/高血压.jpg" alt="Apple Watch 地区功能验证" width="180"></td>
-  </tr>
-</table>
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)

-## 核心功能
-
- **iOS 虚拟定位 / Fake GPS**：将当前地图选点应用到本机定位响应改写代理，适配钉钉打卡、微信位置共享等场景。
- **原生实时位置**：地图显示 MapKit 自带蓝点，不再由 App 额外绘制实时位置标记。
- **并发安全选点**：拖动、点击、搜索、收藏和异步定位按用户最新意图处理，旧结果不会覆盖新选点。
- **地点名称分级**：近距离显示 POI、门牌或道路；拉远后显示社区、区县、城市或省份。
- **地图范围显示**：缩放控件中显示 `180 m`、`2.5 km`、`126 km` 等当前可视范围。
- **收藏与快速切换**：保存常用坐标，并明确显示当前准备应用的位置。
- **分流配置引导**：首次启动先选择模式；APP模式引导本机代理和 CA，第三方代理模式引导客户端、配置导入和接口检测。
- **问题诊断**：内置验证流程和结构化运行日志。
- **第三方代理模式（测试）**：内置各客户端模块配置，把收藏或当前选点的 WGS-84 坐标发送到第三方代理模块；代理客户端持久化坐标，关闭本 App 后仍可继续生效。
+第三方客户端、证书、MITM 和代理开关由客户端自身负责。导入任何第三方模块前，请先审查其配置和脚本内容。

 ## 快速开始

-### 1. 安装 App
+### 1. 安装应用

- 从 [Releases](https://github.com/xweiba/location-spoofer/releases) 获取构建产物并自行签名；或
- 在 macOS + Xcode 环境按[构建说明](docs/BUILD.md)编译。
+你可以使用：

-#### 自签安装
+- 自己的 Apple Developer 签名环境；
+- 适合个人测试的自签工具；
+- 项目 Releases 中的未签名 IPA；
+- 在 macOS 上按[构建说明](docs/BUILD.md)自行构建。

-免费 Apple ID 即可侧载，无需付费开发者账号。本项目不使用 VPN、Network Extension 或 Packet Tunnel Provider，但签名工具仍需保留 App 的能力与标识。
+免费自签环境可能无法使用 Network Extension，因此 APP 模式采用设备内本地代理和 Wi-Fi 手动代理，不依赖
+VPN 组件。

-需要自行构建时执行：
+#### 自签安装说明
+
+Release 附件是未签名 IPA，需要使用自签工具安装到 iPhone：
+
+1. **开启自签支持**：iOS 16 及以上版本前往“设置 → 隐私与安全性 → 开发者模式”，开启后按系统提示重启并
+   确认；iOS 15 没有此开关，可跳过本步。
+2. **下载 IPA**：前往本项目的 [Releases](https://github.com/xweiba/location-spoofer/releases)，下载最新的
+   `PaopaoLocationSpoofer-unsigned.ipa`。
+3. **准备自签软件**：前往 [Impactor Releases](https://github.com/claration/Impactor/releases) 下载对应系统
+   版本的 Impactor；也可以使用爱思助手等支持 IPA 自签安装的软件。
+4. **连接并安装**：使用 USB 数据线连接 iPhone 与电脑，在手机上选择“信任此电脑”，然后在自签软件中选择
+   刚下载的 IPA，根据软件提示完成签名与安装。
+
+Impactor 支持 Windows、macOS 和 Linux；Windows 若无法识别设备，请先安装 iTunes 提供的 Apple 设备驱动。
+爱思助手属于第三方软件，请从其官方渠道获取，并自行评估账号、证书和隐私风险。
+
+安装完成后，若 iOS 阻止打开 App，请前往“设置 → 通用 → VPN 与设备管理”信任对应的开发者 App。免费
+Apple ID 自签通常只有 7 天有效期，到期后需要重新签名安装。
+
+### 2. 首次启动
+
+首次启动时：
+
+1. 选择 APP 模式或第三方代理模式；
+2. 按照 App 内引导完成对应配置；
+3. 执行环境检测；
+4. 在地图中搜索、点击或拖动选择测试位置；
+5. 启用测试位置并在目标测试环境中验证结果。
+
+### 3. 恢复真实位置
+
+APP 模式：
+
+1. 停止测试位置；
+2. 关闭当前 Wi-Fi 的手动 HTTP 代理；
+3. 按 App 内提示刷新定位环境。
+
+第三方代理模式：
+
+1. 使用 App 清除 WLOC 坐标；
+2. 在第三方客户端中关闭对应模块或代理；
+3. 按客户端要求恢复 HTTPS 解密和代理设置。
+
+如果系统或目标应用仍显示旧位置，可能需要等待定位缓存刷新，必要时重启设备后再次验证。
+
+## 坐标处理
+
+项目内部保存两种坐标表示：
+
+- WGS-84：国际标准，WLOC 写入使用此坐标；
+- GCJ-02：国内地图标准，用于需要国内地图坐标的场景。
+
+MapKit 不提供公开 API 直接返回当前是否使用 GCJ-02 或 WGS-84。项目通过固定锚点查询判断 MapKit 当前返回
+标准，并在运行期间根据蓝点变化和用户操作进行受控刷新。
+
+坐标写入边界会保存完整的 WGS-84 / GCJ-02 坐标对，使用时根据当前地图标准选择对应字段，避免重复转换造成
+位置偏移。
+
+## 项目结构
+
+```text
+App/        SwiftUI 界面、MapKit、定位和运行流程
+Core/       Go 代理、证书服务和定位响应处理
+Shared/     坐标、收藏、日志、配置和共享模型
+Resources/  Info.plist、Entitlements 和资源文件
+Config/     构建配置
+Scripts/    构建、打包和验证脚本
+Tests/      XCTest 和 Shell contract tests
+docs/       构建、模块和版本文档
+```
+
+## 构建项目
+
+源码构建需要 macOS 环境：
+
+- macOS；
+- Xcode；
+- Xcode Command Line Tools；
+- XcodeGen；
+- Go 1.23 或更高版本。
+
+当前项目不支持在 Windows 上直接构建 iOS 应用。

 ```bash
+git clone https://github.com/xweiba/location-spoofer.git
+cd location-spoofer
+
 ./build.sh
 ```

-输出文件为 `dist/PaopaoLocationSpoofer-unsigned.ipa`。也可以直接下载 Release 附带的未签名 IPA，然后使用 [Impact](https://github.com/claration/Impactor) 签名并安装到设备。
-
-签名时不要修改以下标识，也不要移除 App Group 和 Wi-Fi 信息能力：
-
-| 组件 | 标识 |
-|---|---|
-| 主 App Bundle ID | `com.paopaolabs.location-spoofer` |
-| App Group | `group.com.paopaolabs.location-spoofer` |
-
-免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装；这是 Apple 的侧载限制，不是 App 的证书失效。App 生成的 WLOC CA 私钥保存在 iOS 钥匙串中：使用相同 Bundle ID 和钥匙串访问范围重装时通常可继续复用，但卸载、系统清理或签名能力变化后不保证保留。
-
-### 2. 选择运行模式
-
-#### APP模式
-
-首次打开后选择 APP模式，再按 App 内引导配置代理和 CA。APP模式没有第三方代理客户端依赖，但只支持 Wi‑Fi。免费自签应用无法使用此功能所需的 VPN/Network Extension 能力，因此使用当前 Wi‑Fi 的手动 HTTP 代理实现流量接入。
-
-##### 配置当前 Wi‑Fi 代理
-
-首次打开后，先在当前 Wi‑Fi 的“配置代理”中选择“手动”：
-
-```text
-服务器：127.0.0.1
-端口：8888
-鉴定：关闭
-```
-
-返回 App 后运行环境检测；如果设备尚未信任 CA，App 会自动进入证书初始化。
-
-##### 安装并信任 CA
-
-按首次引导下载描述文件，然后完成：
-
-```text
-设置 → 通用 → VPN 与设备管理 → 安装 WLOC CA
-设置 → 通用 → 关于本机 → 证书信任设置 → 完全信任
-```
-
-#### 第三方代理模式
-
-此模式由 App 负责地图选点、收藏和发送 WGS-84 坐标；WLOC 拦截、MITM 与坐标持久化由第三方代理客户端负责。它不会启动本机 Go 代理，不检查或使用 App 的 CA，也不要求配置 `127.0.0.1:8888`，可用于 Wi‑Fi、4G 和 5G。
-
-首次引导或“设置 → 运行模式”切换后，选择客户端。App 提供官方订阅地址复制和客户端跳转按钮；在对应客户端的模块、重写或覆写订阅入口粘贴地址并导入。仓库和 App 包内仍保留以下模块配置快照，用于版本归档和离线核对：
-
-| 客户端 | 状态 | 模块 |
-|---|---|---|
-| Shadowrocket（小火箭） | **当前可测试** | [wloc.module](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.module) |
-| Surge | 配置已提供，尚未验证 | [wloc.sgmodule](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.sgmodule) |
-| Quantumult X | 配置已提供，尚未验证 | [wloc.conf](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.conf) |
-| Loon | 配置已提供，尚未验证 | [wloc.lpx](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.lpx) |
-| Stash | 配置已提供，尚未验证 | [wloc.stoverride](https://raw.githubusercontent.com/Yu9191/wloc/refs/heads/main/modules/wloc.stoverride) |
-| Egern | 配置已提供，尚未验证 | 直接使用 Surge 模块 |
-
-Stash 应直接订阅 `.stoverride`，无需通过 Script Hub 转换。Egern 复用 Surge 配置。导入后还需要按对应客户端自己的流程启用模块、MITM、证书和代理/VPN 连接；这些状态不由本 App 管理。App 只调用 WLOC 配置接口查询和同步坐标，“检测连接”仅在查询返回模块 JSON 时判定成功，不会把普通 HTTP 200 当作成功。
-
-> 第三方代理模式目前是测试模式。内置模块快照来源及版本记录见 [第三方模块说明](docs/THIRD_PARTY_MODULES.md)；模块引用的运行脚本仍由第三方客户端按配置访问。上游更新可能改变行为；当前仅计划使用 Shadowrocket 做真机验证。
-
-### 3. 选点并启用
-
-1. 搜索、点击或拖动地图选择位置；点击实时位置按钮可回到 MapKit 蓝点。
-2. APP 模式点击“开始虚拟定位”并等待环境检测；第三方代理模式点击“同步到第三方代理”。
-3. 按 App 内"生效说明"刷新飞行模式、Wi‑Fi 和定位服务状态。
-4. 打开 Apple 地图或目标 App 验证结果。
-
-### 4. 恢复真实位置
-
-停止虚拟定位，关闭当前 Wi‑Fi 的手动代理，并按 App 内"失效说明"刷新系统定位缓存。若系统仍保留旧缓存，请重启设备后再检查。
-
-## 为什么不需要 VPN？
-
-```text
-iPhone 定位请求
-      │ 当前 Wi‑Fi HTTP 代理：127.0.0.1:8888
-      ▼
-本机 wloccore（Go）
-      │ 仅处理目标 Apple 定位服务请求
-      ├──────────────► Apple 定位服务
-      ◄──────────────┘
-      │ 改写目标响应中的坐标
-      ▼
-系统与应用读取定位结果
-```
-
-APP 模式不使用 Network Extension 创建 VPN 隧道，因此不会显示 VPN 连接，也不会占用系统 VPN。**APP 模式仍需要为当前 Wi‑Fi 配置 HTTP 代理，并安装、信任本机生成的 CA。** 第三方代理模式则由所选代理客户端管理代理/VPN 和 MITM，可覆盖蜂窝网络；两种模式不得同时拦截 WLOC 请求。
-
-## 兼容性
-
-| 项目 | 要求 |
-|---|---|
-| iOS | 15.0+ |
-| 构建 | macOS、Xcode、XcodeGen |
-| Swift | 5.9 |
-| Go | 1.23+ |
-| 网络 | APP 模式：可手动配置 HTTP 代理的 Wi‑Fi；第三方代理模式（测试）：取决于代理客户端，可覆盖 Wi‑Fi/4G/5G |
-| 安装 | 自行签名或使用 Releases 构建产物 |
-
-效果会受到 iOS 版本、网络、系统定位缓存和目标 App 自身策略影响，不承诺兼容所有系统或第三方 App。
-
-## 构建与项目结构
+运行构建并执行 Simulator 测试：

 ```bash
-./build.sh
+./build.sh --test
 ```

-构建产物默认位于：
+构建脚本会生成未签名 IPA：

 ```text
 dist/PaopaoLocationSpoofer-unsigned.ipa
 ```

-```text
-App/        SwiftUI、MapKit、定位和配置流程
-Core/       Go 本机代理与定位响应改写
-Shared/     收藏、设置、日志和共享模型
-Resources/  Info.plist、Entitlements 与图标
-Scripts/    构建、签名和检查脚本
-Tests/      XCTest 与 Bash 契约测试
-docs/       构建和版本发布归档
-```
+之后需要使用你自己的签名和安装流程部署到测试设备。

-## 文档与反馈
+## 隐私与安全边界
+
+- 项目不包含遥测或远程控制服务；
+- 项目不会自动上传用户位置数据；
+- 运行日志保存在设备 App Group 容器中，并自动保留近三天；
+- 问题报告需要用户主动复制后提交到 GitHub；
+- APP 模式会访问本机代理和环境验证地址；
+- 第三方代理模式可能访问上游模块地址和 WLOC 配置接口；
+- App 生成的 CA 私钥保存在设备 Keychain 中；
+- 第三方客户端模块、MITM 和证书链路由用户选择的客户端负责。
+
+请不要把真实位置、认证信息、证书私钥或完整敏感日志提交到公开 Issue。
+
+## 限制
+
+- iOS 系统版本变化可能影响定位服务行为；
+- MapKit 的坐标返回标准可能随系统、地区和定位环境变化；
+- 系统定位存在缓存，切换位置后不一定立即生效；
+- 第三方代理客户端的兼容性和规则行为需要分别验证；
+- 不保证所有应用都使用同一种定位 API；
+- 不保证所有应用或服务都接受测试坐标；
+- 不保证在所有网络环境、设备型号和 iOS 版本上表现一致。
+
+## 贡献
+
+欢迎提交：
+
+- Bug Report；
+- Feature Request；
+- 兼容性测试结果；
+- 性能改进；
+- 文档改进；
+- 测试补充。
+
+提交 Issue 时建议包含：
+
+- iOS 版本；
+- 设备型号；
+- 使用的运行模式；
+- 复现步骤；
+- 脱敏后的运行日志；
+- 是否使用第三方代理客户端。
+
+## 文档

 - [构建说明](docs/BUILD.md)
+- [第三方模块说明](docs/THIRD_PARTY_MODULES.md)
 - [更新日志](docs/CHANGELOG.md)
- [English README](README.en.md)
+- [英文文档](README.en.md)
 - [GitHub Issues](https://github.com/xweiba/location-spoofer/issues)

-反馈问题时，请附上复现步骤、iOS 版本、设备型号及已脱敏的运行日志。
+## 功能预览

-## 友链
+以下截图用于展示主界面和部分真机测试场景。实际结果会受到 iOS 版本、网络环境、系统缓存和目标应用定位策略
+影响，不代表对所有应用或版本作出兼容性保证。

-**LinuxDo** — [https://linux.do](https://linux.do/)
+<table>
+  <tr>
+    <th>应用主界面</th>
+    <th>Apple 地图测试</th>
+    <th>高德地图测试</th>
+  </tr>
+  <tr>
+    <td><img src="images/主界面.jpg" alt="Location Spoofer 地图选点主界面" width="220"></td>
+    <td><img src="images/Apple%20Map.jpg" alt="Apple 地图定位测试场景" width="220"></td>
+    <td><img src="images/高德地图.jpg" alt="高德地图定位测试场景" width="220"></td>
+  </tr>
+  <tr>
+    <th>微信测试</th>
+    <th>钉钉测试</th>
+    <th>Apple Watch 场景测试</th>
+  </tr>
+  <tr>
+    <td><img src="images/微信.jpg" alt="微信定位测试场景" width="220"></td>
+    <td><img src="images/钉钉.jpg" alt="钉钉定位测试场景" width="220"></td>
+    <td><img src="images/高血压.jpg" alt="Apple Watch 地区功能测试场景" width="220"></td>
+  </tr>
+</table>
+
+## 致谢与友链
+
+核心定位响应处理思路、Go 实现和第三方模块参考自：
+
+- [Yu9191/wloc](https://github.com/Yu9191/wloc)
+
+友链：
+
+- [LINUX DO](https://linux.do/)
+
+感谢开源社区中参与 iOS 定位服务研究、网络代理和移动端测试工具建设的贡献者。
@@ -41,7 +41,7 @@ ${COMMITS}
 ## 自签安装

 - Release 附件为未签名 IPA，安装前需要自行签名。
- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。
+- 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
 - 签名时请保留 Bundle ID \`com.paopaolabs.location-spoofer\`、App Group \`group.com.paopaolabs.location-spoofer\` 及原有 entitlements。
 - 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。

@@ -85,6 +85,13 @@ enum CoordinateConverter {
        let current: MapCoordinateSystem
    }

+    enum RuntimeMapCoordinateSystemRefreshResult: Equatable {
+        case unchanged(MapCoordinateSystem)
+        case changed(MapCoordinateSystemChange)
+        case unavailable(reason: String)
+        case cancelled
+    }
+
    /// 当前 Apple 地图坐标标准。检测不可用时使用国内 GCJ-02 作为兜底。
    @MainActor static var currentMapCoordinateSystem = MapCoordinateSystem.gcj02
    @MainActor private static var mapCoordinateSystemCheckPending = false
@@ -110,7 +117,7 @@ enum CoordinateConverter {
        let nextType: MapCoordinateSystem
        switch await fixedAnchorCoordinateSystemProbe() {
        case let .response(name, count):
-            nextType = name == "林士街" ? .gcj02 : .wgs84
+            nextType = mapCoordinateSystem(forFixedAnchorFirstResultName: name)
            initialMapCoordinateSystemUsedFallback = false
            RuntimeLogger.info("APP", "坐标转换", "地图坐标标准检测获得明确结果", details: [
                "首条名称": name,
@@ -155,6 +162,79 @@ enum CoordinateConverter {
        return nextType
    }

+    /// Re-runs the fixed-anchor MapKit behavior probe while the map is alive.
+    /// Runtime failures preserve the last confirmed type: a potentially spoofed
+    /// Core Location sample is not authoritative for MapKit's representation.
+    @MainActor
+    static func refreshRuntimeMapCoordinateSystem(reason: String) async -> RuntimeMapCoordinateSystemRefreshResult {
+        guard !mapCoordinateSystemCheckPending else {
+            RuntimeLogger.info("APP", "坐标转换", "地图坐标标准运行期检测合并到进行中请求", details: [
+                "触发原因": reason,
+                "当前标准": currentMapCoordinateSystem.rawValue
+            ])
+            return .unchanged(currentMapCoordinateSystem)
+        }
+        mapCoordinateSystemCheckPending = true
+        defer { mapCoordinateSystemCheckPending = false }
+
+        let previous = currentMapCoordinateSystem
+        RuntimeLogger.info("APP", "坐标转换", "地图坐标标准运行期检测开始", details: [
+            "触发原因": reason,
+            "检测前标准": previous.rawValue,
+            "锚点": "22.283819,114.158439",
+            "缓存": "false"
+        ])
+
+        switch await fixedAnchorCoordinateSystemProbe() {
+        case let .response(name, count):
+            guard !Task.isCancelled else {
+                RuntimeLogger.info("APP", "坐标转换", "地图坐标标准运行期检测结果已过期，取消写入", details: [
+                    "触发原因": reason,
+                    "保留标准": previous.rawValue
+                ])
+                return .cancelled
+            }
+            let detected = mapCoordinateSystem(forFixedAnchorFirstResultName: name)
+            initialMapCoordinateSystemUsedFallback = false
+            guard detected != previous else {
+                RuntimeLogger.info("APP", "坐标转换", "地图坐标标准运行期检测完成，标准未变化", details: [
+                    "触发原因": reason,
+                    "首条名称": name,
+                    "结果数": String(count),
+                    "确认标准": detected.rawValue
+                ])
+                return .unchanged(detected)
+            }
+            let change = MapCoordinateSystemChange(previous: previous, current: detected)
+            currentMapCoordinateSystem = detected
+            RuntimeLogger.warning("APP", "坐标转换", "地图坐标标准运行期检测发现切换", details: [
+                "触发原因": reason,
+                "首条名称": name,
+                "结果数": String(count),
+                "from": previous.rawValue,
+                "to": detected.rawValue
+            ])
+            return .changed(change)
+        case .unavailable(let failureReason), .timedOut(let failureReason):
+            RuntimeLogger.warning("APP", "坐标转换", "地图坐标标准运行期检测失败，保留当前标准", details: [
+                "触发原因": reason,
+                "原因": failureReason,
+                "保留标准": previous.rawValue
+            ])
+            return .unavailable(reason: failureReason)
+        case .cancelled:
+            RuntimeLogger.info("APP", "坐标转换", "地图坐标标准运行期检测已取消", details: [
+                "触发原因": reason,
+                "保留标准": previous.rawValue
+            ])
+            return .cancelled
+        }
+    }
+
+    static func mapCoordinateSystem(forFixedAnchorFirstResultName name: String) -> MapCoordinateSystem {
+        name == "林士街" ? .gcj02 : .wgs84
+    }
+
    /// A user-requested realtime sample is WGS-84 and can correct a provisional
    /// startup map coordinate system without altering persisted coordinate pairs.
    @MainActor
@@ -116,11 +116,24 @@ final class FavoriteLocationStore: ObservableObject {
        mapCoordinateSystem: CoordinateConverter.MapCoordinateSystem,
        accuracy: Int
    ) -> FavoriteLocation {
-        let favorite = FavoriteLocation(
-            name: name,
-            coordinatePair: .init(mapCoordinate: mapCoordinate, mapCoordinateSystem: mapCoordinateSystem),
-            accuracy: accuracy
+        save(
+            FavoriteLocation(
+                name: name,
+                coordinatePair: .init(mapCoordinate: mapCoordinate, mapCoordinateSystem: mapCoordinateSystem),
+                accuracy: accuracy
+            )
        )
+    }
+
+    /// Saves a coordinate pair whose source representation was already typed
+    /// before an asynchronous map-coordinate-system refresh.
+    @discardableResult
+    func save(name: String, coordinatePair: CoordinatePair, accuracy: Int) -> FavoriteLocation {
+        save(FavoriteLocation(name: name, coordinatePair: coordinatePair, accuracy: accuracy))
+    }
+
+    @discardableResult
+    private func save(_ favorite: FavoriteLocation) -> FavoriteLocation {
        favorites.removeAll {
            abs($0.coordinatePair.wgs84.latitude - favorite.coordinatePair.wgs84.latitude) < 0.000001
                && abs($0.coordinatePair.wgs84.longitude - favorite.coordinatePair.wgs84.longitude) < 0.000001
@@ -147,6 +160,18 @@ final class FavoriteLocationStore: ObservableObject {
        defaults.set(id?.uuidString, forKey: Keys.selectedID)
    }

+    @discardableResult
+    func selectMatching(coordinatePair: CoordinatePair) -> FavoriteLocation? {
+        let matchingFavorite = favorites.first {
+            $0.coordinatePair.matchesWGS84(
+                latitude: coordinatePair.wgs84.latitude,
+                longitude: coordinatePair.wgs84.longitude
+            )
+        }
+        select(matchingFavorite?.id)
+        return matchingFavorite
+    }
+
    func rename(_ id: UUID, to name: String) {
        guard let idx = favorites.firstIndex(where: { $0.id == id }) else { return }
        favorites[idx].name = name
@@ -19,6 +19,39 @@ final class FavoriteLocationStoreTests: XCTestCase {
        XCTAssertEqual(FavoriteLocationStore(defaults: defaults).selectedFavorite?.name, "深圳湾")
    }

+    func testSelectingMatchingCoordinatePairRestoresFavoriteSelection() {
+        let suite = "FavoriteLocationStoreTests.\(UUID().uuidString)"
+        let defaults = UserDefaults(suiteName: suite)!
+        defer { defaults.removePersistentDomain(forName: suite) }
+        let store = FavoriteLocationStore(defaults: defaults)
+        let favorite = store.save(
+            name: "深圳湾",
+            coordinatePair: CoordinateConverter.coordinatePair(
+                lat: 22.491_438,
+                lon: 113.945_702,
+                mapCoordinateSystem: .wgs84
+            ),
+            accuracy: 20
+        )
+        store.select(nil)
+
+        let nearbyRealtimePair = CoordinateConverter.coordinatePair(
+            lat: 22.491_488,
+            lon: 113.945_752,
+            mapCoordinateSystem: .wgs84
+        )
+        XCTAssertEqual(store.selectMatching(coordinatePair: nearbyRealtimePair)?.id, favorite.id)
+        XCTAssertEqual(store.selectedFavoriteID, favorite.id)
+
+        let unrelatedPair = CoordinateConverter.coordinatePair(
+            lat: 31.2304,
+            lon: 121.4737,
+            mapCoordinateSystem: .wgs84
+        )
+        XCTAssertNil(store.selectMatching(coordinatePair: unrelatedPair))
+        XCTAssertNil(store.selectedFavoriteID)
+    }
+
    func testFavoriteStoresBothFormsAndSelectsMatchingPairWithoutReadConversion() {
        let suite = "FavoriteLocationStoreTests.\(UUID().uuidString)"
        let defaults = UserDefaults(suiteName: suite)!
@@ -36,6 +69,25 @@ final class FavoriteLocationStoreTests: XCTestCase {
        XCTAssertNotEqual(favorite.coordinatePair.gcj02.longitude, wgs.longitude)
    }

+    func testSavingPrecomputedPairDoesNotReinterpretItAfterMapTypeRefresh() {
+        let suite = "FavoriteLocationStoreTests.\(UUID().uuidString)"
+        let defaults = UserDefaults(suiteName: suite)!
+        defer { defaults.removePersistentDomain(forName: suite) }
+        let pair = CoordinateConverter.coordinatePair(
+            lat: 22.296_642,
+            lon: 114.172_175,
+            mapCoordinateSystem: .wgs84
+        )
+
+        let favorite = FavoriteLocationStore(defaults: defaults).save(
+            name: "香港天文台",
+            coordinatePair: pair,
+            accuracy: 25
+        )
+
+        XCTAssertEqual(favorite.coordinatePair, pair)
+    }
+
    func testLegacyFavoriteIsUpgradedAsDomesticGCJAndRewritten() throws {
        let suite = "FavoriteLocationStoreTests.\(UUID().uuidString)"
        let defaults = UserDefaults(suiteName: suite)!
@@ -122,6 +174,17 @@ final class FavoriteLocationStoreTests: XCTestCase {
        XCTAssertNil(CoordinateConverter.diagnoseRepresentation(sample: unrelated, pair: pair).inferredSystem)
    }

+    func testFixedAnchorResultNameUsesOneSharedMapTypeRule() {
+        XCTAssertEqual(
+            CoordinateConverter.mapCoordinateSystem(forFixedAnchorFirstResultName: "林士街"),
+            .gcj02
+        )
+        XCTAssertEqual(
+            CoordinateConverter.mapCoordinateSystem(forFixedAnchorFirstResultName: "Connaught Road West"),
+            .wgs84
+        )
+    }
+
    func testMapConfigurationNeverRequestsRealUserLocation() {
        XCTAssertFalse(MapConfiguration.default.showsUserLocation)
        XCTAssertFalse(MapConfiguration.default.allowsCurrentLocationRequest)
@@ -173,6 +173,19 @@ final class MapLocationStateTests: XCTestCase {
        XCTAssertEqual(state.selection.source, .search)
    }

+    func testMapCoordinateSystemChangeClearsSupersededRealtimeSampleWithoutMovingSelection() {
+        let state = MapLocationState(initialCoordinate: initial)
+        state.selectSearchResult(.init(latitude: 31.23, longitude: 121.47), name: "外滩")
+        let selection = state.selection
+        state.updateRealtimeLocation(CLLocation(latitude: 30.42, longitude: 114.25))
+
+        state.clearRealtimeLocationForMapCoordinateSystemChange()
+
+        XCTAssertNil(state.realtimeLocation)
+        XCTAssertNil(state.realtimeCoordinate)
+        XCTAssertEqual(state.selection, selection)
+    }
+
    func testRealtimeIntentCanImmediatelyAcceptNativeLocation() {
        let state = MapLocationState(initialCoordinate: initial)
        let nativeLocation = CLLocation(latitude: 30.42, longitude: 114.25)
@@ -65,6 +65,22 @@ if grep -q 'logEvent("CONNECT " + host + " -> passthrough")' "$ROOT/Core/proxy.g
 fi
 grep -q 'enum SystemSettingsNavigator' "$SETTINGS_NAVIGATOR" || fail "shared settings navigator is missing"
 grep -q 'await CoordinateConverter.resolveInitialMapCoordinateSystem()' "$CONTENT" || fail "map type must resolve before MapHomeView construction"
+grep -q 'refreshRuntimeMapCoordinateSystem(reason:' "$CONVERTER" || fail "fixed-anchor map type must support runtime refresh"
+grep -q 'scheduleBluePointMapCoordinateSystemRefresh()' "$MAP_HOME" || fail "native blue-point samples must trigger runtime map-type refresh while spoofing"
+! grep -A3 'private func scheduleBluePointMapCoordinateSystemRefresh' "$MAP_HOME" | grep -q 'spoofState == .active' || fail "blue-point map-type refresh must also detect the return to physical location"
+grep -q 'awaitCoordinatedMapCoordinateSystemRefresh(reason: "点击实时定位")' "$MAP_HOME" || fail "realtime button must await the coordinated map-type refresh"
+grep -q 'favorites.selectMatching(coordinatePair: pair)' "$MAP_HOME" || fail "realtime selection must restore a matching favorite selection"
+grep -q 'awaitCoordinatedMapCoordinateSystemRefresh(reason: "保存收藏")' "$MAP_HOME" || fail "favorite save must await the coordinated map-type refresh"
+grep -q 'awaitCoordinatedMapCoordinateSystemRefresh(reason: "App回到前台")' "$MAP_HOME" || fail "foreground recovery must reuse the coordinated map-type refresh"
+grep -q '地图坐标标准运行期检测结果已过期，取消写入' "$CONVERTER" || fail "cancelled runtime probes must not mutate the global map type"
+! grep -q 'source == .coreLocation.*correctMapCoordinateSystemUsingRealtime' "$MAP_HOME" || fail "runtime Core Location samples must not infer MapKit type"
+grep -q 'clearRealtimeLocationForMapCoordinateSystemChange' "$MAP_HOME" || fail "map-type changes must discard superseded blue-point samples"
+grep -q '地图坐标类型已变化' "$MAP_HOME" || fail "map-type changes must emit an explicit searchable business log"
+grep -q '图钉已按新类型重设' "$MAP_HOME" || fail "map-type change log must report pin reprojection"
+grep -q 'coordinateRow(label: "GCJ-02(国内)", system: .gcj02)' "$MAP_HOME" || fail "current selection panel must label the domestic coordinate as GCJ-02"
+grep -q 'coordinateRow(label: "WGS-84(国际)", system: .wgs84)' "$MAP_HOME" || fail "current selection panel must label the international coordinate as WGS-84"
+grep -q 'fixedSize(horizontal: true, vertical: false)' "$MAP_HOME" || fail "coordinate labels must keep their natural single-line width"
+grep -q 'minimumScaleFactor(0.72)' "$MAP_HOME" || fail "coordinate values must shrink to remain on one line"
 grep -q 'phase = .map' "$CONTENT" || fail "ContentView must explicitly gate MapHomeView construction"
 ! grep -q 'startTileProbe' "$MAP_HOME" || fail "MapHomeView must not start a second fixed-anchor coordinate-system probe"
 ! grep -q 'initializeMap()' "$MAP_HOME" || fail "MapHomeView must not replay a second map initialization from onAppear"
@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ZH="$ROOT/README.md"
+EN="$ROOT/README.en.md"
+fail() { echo "FAIL: $*" >&2; exit 1; }
+
+grep -q 'iOS Location Service Research & Testing Framework' "$ZH" || fail "Chinese README positioning is missing"
+grep -q 'iOS Location Service Research & Testing Framework' "$EN" || fail "English README positioning is missing"
+
+grep -q '#### 自签安装说明' "$ZH" || fail "Chinese self-signing instructions are missing"
+grep -q '#### Self-Signing Instructions' "$EN" || fail "English self-signing instructions are missing"
+grep -q 'Impactor Releases' "$ZH" || fail "Chinese README must link the requested Impactor releases"
+grep -q 'Impactor Releases' "$EN" || fail "English README must link the requested Impactor releases"
+grep -q '开发者模式' "$ZH" || fail "Chinese README must explain iOS 16 Developer Mode"
+grep -q 'Developer Mode' "$EN" || fail "English README must explain iOS 16 Developer Mode"
+grep -q '7 天有效期' "$ZH" || fail "Chinese README must disclose free-signing expiry"
+grep -q 'seven days' "$EN" || fail "English README must disclose free-signing expiry"
+
+grep -q '^## 功能预览$' "$ZH" || fail "Chinese feature preview is missing"
+grep -q '^## Feature Preview$' "$EN" || fail "English feature preview is missing"
+
+images=(
+  '主界面.jpg'
+  'Apple%20Map.jpg'
+  '高德地图.jpg'
+  '微信.jpg'
+  '钉钉.jpg'
+  '高血压.jpg'
+)
+for image in "${images[@]}"; do
+  grep -q "images/$image" "$ZH" || fail "Chinese README is missing image: $image"
+  grep -q "images/$image" "$EN" || fail "English README is missing image: $image"
+done
+
+image_files=(
+  '主界面.jpg'
+  'Apple Map.jpg'
+  '高德地图.jpg'
+  '微信.jpg'
+  '钉钉.jpg'
+  '高血压.jpg'
+)
+for image in "${image_files[@]}"; do
+  test -f "$ROOT/images/$image" || fail "referenced preview image is missing: $image"
+done
+
+test "$(grep -c '^## ' "$ZH")" -eq "$(grep -c '^## ' "$EN")" \
+  || fail "Chinese and English README section counts must stay aligned"
+
+! grep -Eq '^## (许可证|License)$' "$ZH" "$EN" || fail "README must not claim a repository license"
+grep -q '当前项目不支持在 Windows 上直接构建 iOS 应用' "$ZH" || fail "Chinese README must reject Windows source builds"
+grep -q 'Building the iOS app directly on Windows is not supported' "$EN" || fail "English README must reject Windows source builds"
+
+if grep -Rnw --include='*.md' --include='*.sh' \
+  "$ROOT/build.sh" "$ROOT/README.md" "$ROOT/README.en.md" "$ROOT/docs" "$ROOT/Scripts" \
+  -e 'Impact'; then
+  fail "documentation and build output must use the correct Impactor name"
+fi
+
+echo "PASS: README contract"
@@ -43,7 +43,7 @@ grep -q 'HTTPS 解密' "$SETUP" || fail "Shadowrocket HTTPS decryption guidance
 grep -q 'presentSuccessfulOperationTip(.activation)' "$ROOT/App/MapHomeView.swift" || fail "third-party save must present the activation tip"
 grep -q 'presentSuccessfulOperationTip(.deactivation)' "$ROOT/App/MapHomeView.swift" || fail "third-party clear must present the deactivation tip"
 grep -q 'if spoofState == .active' "$ROOT/App/MapHomeView.swift" || fail "manual help must follow the shared spoof state"
-grep -q 'MARKETING_VERSION: "1.0.1"' "$ROOT/project.yml" || fail "marketing version must be 1.0.1"
-grep -q 'CURRENT_PROJECT_VERSION: "2"' "$ROOT/project.yml" || fail "build version must be 2"
+grep -q 'MARKETING_VERSION: "1.0.2"' "$ROOT/project.yml" || fail "marketing version must be 1.0.2"
+grep -q 'CURRENT_PROJECT_VERSION: "3"' "$ROOT/project.yml" || fail "build version must be 3"

 echo "PASS: third-party proxy mode contract"
@@ -73,4 +73,4 @@ if [ "$run_tests" -eq 1 ]; then
  run_simulator_tests
 fi

-echo "Next: sign with Impact (https://github.com/claration/Impactor) and install on device."
+echo "Next: sign with Impactor (https://github.com/claration/Impactor) and install on device."
@@ -32,12 +32,12 @@ Output:
 dist/PaopaoLocationSpoofer-unsigned.ipa
 ```

-IPA 始终保持未签名。用 [Impact](https://github.com/claration/Impactor) 签名安装即可。
+IPA 始终保持未签名。用 [Impactor](https://github.com/claration/Impactor) 签名安装即可。

 ## 发布验收

 1. `./build.sh` 通过并输出未签名 IPA
-2. 用 Impact 签名后安装到设备
+2. 用 Impactor 签名后安装到设备
 3. 真机安装后，先配置 WiFi HTTP 代理 `127.0.0.1:8888`，再按检测结果完成 CA 下载、安装和信任
 4. 环境检测通过后，选点开启虚拟定位
 5. 打开 Apple 地图验证定位是否变为虚拟位置
@@ -4,4 +4,6 @@

 ## 已发布

+- [v1.0.2](https://github.com/xweiba/location-spoofer/releases/tag/v1.0.2) — 2026-08-07
+- [v1.0.1](https://github.com/xweiba/location-spoofer/releases/tag/v1.0.1) — 2026-08-06
 - [v1.0.0](https://github.com/xweiba/location-spoofer/releases/tag/v1.0.0) — 2026-08-05
@@ -16,13 +16,13 @@
 | 项目 | 要求 |
 |---|---|
 | iOS | 15.0+ |
-| 安装 | 自行签名（推荐 [Impact](https://github.com/claration/Impactor)） |
+| 安装 | 自行签名（推荐 [Impactor](https://github.com/claration/Impactor)） |
 | 网络 | 可手动配置 HTTP 代理的 WiFi |

 ### 自签安装

 1. 从 [Releases](https://github.com/xweiba/location-spoofer/releases) 下载 `PaopaoLocationSpoofer-unsigned.ipa`
-2. 使用 [Impact](https://github.com/claration/Impactor) 签名安装
+2. 使用 [Impactor](https://github.com/claration/Impactor) 签名安装
 3. 签名时保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements

 ### 致谢
@@ -13,7 +13,7 @@
 ## 自签安装

 - Release 附件为未签名 IPA，安装前需要自行签名。
- 可使用免费 Apple ID 和 Impact 完成签名安装，无需付费开发者账号。
+- 可使用免费 Apple ID 和 Impactor 完成签名安装，无需付费开发者账号。
 - 签名时请保留 Bundle ID `com.paopaolabs.location-spoofer`、App Group `group.com.paopaolabs.location-spoofer` 及原有 entitlements。
 - 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。

@@ -0,0 +1,32 @@
+# v1.0.2
+
+发布日期：2026-08-07
+
+## 主要更新
+
+- 修复虚拟定位跨越中国大陆与境外后，MapKit 坐标标准变化可能导致的地图选点、蓝点和收藏位置偏移。
+- 增加运行期固定锚点刷新与状态清理，坐标标准切换后会按已保存的 WGS-84 / GCJ-02 坐标对重新显示图钉。
+- 点击实时定位时，如果当前位置与已保存收藏匹配，会恢复对应收藏的选中状态。
+- 当前选点面板同时显示 `GCJ-02(国内)` 与 `WGS-84(国际)` 坐标，两行可独立复制，并在窄屏自动调整宽度。
+
+## 文档与安装
+
+- 重写中英文 README，统一项目定位、双运行模式、构建要求、隐私边界和限制说明。
+- 补充 iOS 开发者模式、Impactor/第三方自签工具、USB 安装、设备驱动和 7 天免费签名有效期说明。
+- 增加完整功能预览，包含主界面和现有真机测试截图。
+
+## 兼容性说明
+
+- APP 模式仍使用设备内 Go 代理和当前 Wi-Fi 的手动 HTTP 代理，不创建 Network Extension 或系统 VPN。
+- 第三方代理模式仍由所选客户端负责代理/VPN、MITM、证书和坐标持久化。
+- MapKit 和系统定位存在运行时差异与缓存，本版本改进了坐标一致性，但不保证兼容所有 iOS 版本或第三方应用。
+
+## 自签安装
+
+- Release 附件为未签名 IPA，安装前需要自行签名。
+- 可使用免费 Apple ID 和 [Impactor](https://github.com/claration/Impactor/releases) 完成签名安装，无需付费开发者账号。
+- iOS 16 及以上版本需要在“设置 → 隐私与安全性 → 开发者模式”中开启开发者模式；iOS 15 可跳过。
+- 免费 Apple ID 签名通常只有 7 天有效期，到期后需要重新签名安装。
+- 第三方自签软件请从官方渠道获取，并自行评估账号、证书和隐私风险。
+
+<!-- commit-range: v1.0.1..v1.0.2 -->
@@ -8,8 +8,8 @@ options:
 settings:
  base:
    SWIFT_VERSION: "5.9"
-    MARKETING_VERSION: "1.0.1"
-    CURRENT_PROJECT_VERSION: "2"
+    MARKETING_VERSION: "1.0.2"
+    CURRENT_PROJECT_VERSION: "3"
    CODE_SIGN_STYLE: Manual
    CODE_SIGNING_ALLOWED: "NO"
    CODE_SIGNING_REQUIRED: "NO"
Author	SHA1	Message	Date
xweiba	3499f080d7	chore: prepare v1.0.2 release	2026-08-07 17:01:54 +08:00
xweiba	c7ae14d4b2	docs: refresh installation and feature previews	2026-08-07 16:45:02 +08:00
xweiba	a3f39a93e7	fix: improve coordinate selection feedback	2026-08-07 16:43:34 +08:00
weiba	811f9c9343	Merge pull request #5 from lixiaobaivv/agent/upstream-impact-install-guide docs: 完善自签安装步骤	2026-08-07 15:01:17 +08:00
weiba	8bd15eb13c	Merge pull request #4 from lixiaobaivv/agent/fix-mapkit-coordinate-drift fix: 修复跨境定位后的 MapKit 坐标偏移	2026-08-07 14:54:03 +08:00
xweiba	b0c60673af	merge: integrate complete MapKit runtime refresh # Conflicts: # App/MapHomeView.swift # Shared/CoordinateConverter.swift # Tests/PaopaoLocationSpooferTests/FavoriteLocationStoreTests.swift # Tests/map_refactor_contract_test.sh	2026-08-07 14:51:30 +08:00
Yzzz	111080ad1a	docs: 完善自签安装步骤	2026-08-07 14:33:15 +08:00
xweiba	8acc33186c	fix: refresh MapKit coordinate type at runtime	2026-08-07 14:13:25 +08:00
Yzzz	7721443484	fix: 修复跨境定位后的 MapKit 坐标偏移	2026-08-07 13:59:50 +08:00
weiba	7e362e6b6c	Merge pull request #3 from lixiaobaivv/agent/update-changelog-v1-0-1	2026-08-07 12:38:32 +08:00
Yzzz	d11550228c	docs: 补充 v1.0.1 更新日志	2026-08-07 11:58:34 +08:00
weiba	104df4e4a2	Merge pull request #2 from lixiaobaivv/agent/upstream-readme-copy docs: 更新中英文 README	2026-08-07 11:19:07 +08:00
xweiba	f38a4ebff1	docs: refresh bilingual README	2026-08-07 11:13:06 +08:00
xweiba	bae701d4c6	docs: 移除 README 中的 App Group 标识行	2026-08-07 11:05:51 +08:00