docs: 重构 gpsrelaysentinel/README.md 中英文双语文档

- 中文文档新增核心功能清单（双模式运行、前台服务、订阅者管理、模拟面板、日志输出、崩溃处理、关于页面） - 技术栈改用表格展示，模块说明更新为实际编译模块（:gpsrelaysentinel 与 :libgpsrelaysentinel） - 核心依赖库分类更清晰（网络、终端模拟、功能组件、UI 组件） - 项目结构树精确到具体 Java 源文件及其功能说明 - 权限说明改为具体 Android 权限声明 - 新增完整英文版本文档（Project Introduction、Core Features、Tech Stack、Module Structure、Core Dependencies、Build Instructions、Permissions、Project Structure、Contributing、License） - 删除失效的参考文档链接
2026-05-07 16:25:40 +08:00
parent d5100a8aa4
commit a3855b4375
1 changed files with 189 additions and 77 deletions
--- a/gpsrelaysentinel/README.md
+++ b/gpsrelaysentinel/README.md
@@ -1,127 +1,239 @@
 # GPSRelaySentinel

-## 介绍
+---

-### GPSRelaySentinel 应用描述
+## 中文文档

-#### 中文描述 ：
-GPSRelaySentinel 是一款专业的 GPS 定位中继守护工具，支持真实系统 GPS 定位监听与模拟 GPS 坐标仿真双模式运行。应用后台常驻前台服务，实时接收系统 GPS 位置数据，内置订阅者步长阈值判断机制，可对多个 GPS 订阅视图进行定点推送管理。
-提供可视化模拟控制面板，支持选择八大方位、自定义模拟移动距离，自动计算偏移目标经纬度；配备模拟模式勾选开关，可一键切换真实 GPS 工作模式与虚拟仿真模式。模拟状态下系统会接管自定义模拟坐标，忽略原生真实定位数据；普通模式则正常使用设备 GPS 原始位置。
-界面采用深色极简风格，全控件灰色文字与灰色边框统一视觉设计，集成日志实时输出面板，方便调试定位轨迹与订阅推送状态，适合定位开发测试、虚拟位置仿真、GPS 中继转发等场景使用。
+### 项目介绍

-#### English Description :
-GPSRelaySentinel is a professional GPS relay and guardian tool, supporting dual modes of real system GPS location monitoring and simulated GPS coordinate simulation. It runs as a foreground persistent background service, receives real-time system GPS location data, and builds-in subscriber step threshold judgment mechanism to manage fixed-point push for multiple GPS subscription views.
-It provides a visual simulation control panel, supports eight direction selections and custom simulated moving distance, and automatically calculates offset target latitude and longitude. With a simulation mode checkbox, you can one-click switch between real GPS working mode and virtual simulation mode.
-In simulation mode, the app takes over custom simulated coordinates and ignores original real location data; in normal mode, it uses the device’s native GPS position normally. The UI adopts a dark minimalist design with unified gray text and gray borders for all controls, and integrates a real-time log output panel for debugging location tracks and subscription push status. It is suitable for location development testing, virtual position simulation, GPS relay forwarding and other scenarios.
+GPSRelaySentinel 是一款专业的 **GPS 定位中继守护工具**，支持真实系统 GPS 定位监听与模拟 GPS 坐标仿真双模式运行。应用后台常驻前台服务，实时接收系统 GPS 位置数据，内置订阅者步长阈值判断机制，可对多个 GPS 订阅视图进行定点推送管理。

-## 技术栈
+#### 核心功能

- **编程语言**: Java 7（源码）
- **编译环境**: Java 11（Gradle 编译）
- **Gradle 插件**: 7.2.1
- **安卓 API**:
-  - 最低支持: API 26 (Android 8.0)
-  - 目标版本: API 30 (Android 11)
-  - 编译版本: API 30
+- **双模式运行**：支持真实 GPS 工作模式与虚拟仿真模式一键切换
+- **前台常驻服务**：`MainService` 作为前台 Service 持续监听 GPS 定位变化
+- **订阅者管理**：内置 `GpsSubscribeManager` 与 `SubscribeLocationManager`，支持多订阅者步长阈值推送
+- **模拟控制面板**：支持八大方位选择、自定义移动距离，自动计算偏移目标经纬度
+- **实时日志输出**：集成 `LogView` 面板，方便调试定位轨迹与订阅推送状态
+- **崩溃处理**：`App` 类提供全局 CrashHandler 与 CrashActivity 展示崩溃日志
+- **关于页面**：工具栏提供 About 按钮，可查看应用版本与项目信息

-## 软件架构
+#### 技术栈

-适配以下安卓开发环境的 Gradle 编译结构：
- AIDE Pro
- AndroidIDE
+| 项目 | 版本/说明 |
+|------|-----------|
+| 编程语言 | Java 7（源码） |
+| 编译环境 | Java 11（Gradle 编译） |
+| Gradle 插件 | 7.2.1 |
+| 最低 API | API 26 (Android 8.0) |
+| 目标 API | API 30 (Android 11) |
+| 编译 API | API 30 |

-## 模块说明
+#### 模块结构

-本项目采用多模块结构：
- `gpsrelaysentinel` - 主应用模块
- `libappbase` - 基础库模块（提供 OkHttp、Gson、JSch 等基础能力）
- `libaes` - AES 加密库模块（提供权限请求、二维码、拼音搜索等扩展功能）
+本项目采用多模块 Gradle 结构：

-## 核心依赖库
+| 模块 | 类型 | 说明 |
+|------|------|------|
+| `:gpsrelaysentinel` | application | 主应用模块（MainActivity、MainService、AboutActivity 等） |
+| `:libgpsrelaysentinel` | library | GPS 中继核心类库（GpsSubscribeManager、SubscribeLocationManager 等） |

-### 网络相关
- OkHttp 4.4.1 / 3.14.9 - HTTP 客户端
- Gson 2.10.1 - JSON 解析
+#### 核心依赖库

-### 终端模拟
+**网络相关**
+- OkHttp 4.4.1 / 3.14.9 — HTTP 客户端
+- Gson 2.10.1 — JSON 解析
+
+**终端模拟**
 - Termux: terminal-emulator 0.118.0
 - Termux: terminal-view 0.118.0
 - Termux: termux-shared 0.118.0

-### 功能组件
- ZXing 3.4.1 - 二维码生成与扫描
- JSch 0.1.55 - SSH/SFTP 客户端
- Jsoup 1.13.1 - HTML 解析
- FastJSON 1.2.76 - JSON 处理
+**功能组件**
+- ZXing 3.4.1 — 二维码生成与扫描
+- JSch 0.1.55 — SSH/SFTP 客户端
+- Jsoup 1.13.1 — HTML 解析
+- FastJSON 1.2.76 — JSON 处理

-### UI 组件
+**UI 组件**
 - Material Design 1.4.0
 - AndroidX 组件库
- PullRefreshLayout 1.2.0 - 下拉刷新
+- PullRefreshLayout 1.2.0 — 下拉刷新

-## Gradle 编译说明
+#### 编译说明

-### 调试版编译
+**调试版编译**
 ```bash
-gradle assembleDebug
+./gradlew assembleBetaDebug
 ```

-### 阶段版编译（发布）
+**阶段版编译（发布）**
 ```bash
 bash .winboll/bashPublishAPKAddTag.sh gpsrelaysentinel
 ```

-### 版本管理
+**版本管理**
 版本信息由 `gpsrelaysentinel/build.properties` 管理：
- `baseVersion` - 基础版本号
- `stageCount` - 阶段构建次数
- `publishVersion` - 发布版本号
- `buildCount` - 构建次数
+- `baseVersion` — 基础版本号
+- `stageCount` — 阶段构建次数
+- `publishVersion` — 发布版本号
+- `buildCount` — 构建次数

-## 使用说明
-
-### Termux 应用配置
-
-1. 安装 Termux 应用（包名: `com.termux`）
-2. 配置允许外部应用访问：
-   ```bash
-   echo "allow-external-apps = true" > ~/.termux/termux.properties
-   ```
-
-### 权限说明
+#### 权限说明

 应用需要以下权限：
- 网络访问权限
- 存储读写权限
- 相机权限（二维码扫描）
- 位置权限（GPS 相关功能）
+- `ACCESS_FINE_LOCATION` — 精确定位
+- `ACCESS_COARSE_LOCATION` — 大致定位
+- `ACCESS_BACKGROUND_LOCATION` — 后台定位
+- `FOREGROUND_SERVICE` — 前台服务

-## 项目结构
+#### 项目结构

 ```
 gpsrelaysentinel/
 ├── src/main/
-│   ├── java/          # Java 源码（Java 7 语法）
-│   ├── res/           # 资源文件
-│   ├── libs/          # 本地库文件（含 JNI 库）
-│   └── AndroidManifest.xml
-├── build.gradle       # 模块构建配置
-└── build.properties   # 版本配置文件
+│   ├── java/cc/winboll/studio/gpsrelaysentinel/
+│   │   ├── App.java              # Application 类，初始化与崩溃处理
+│   │   ├── MainActivity.java     # 主控制页面（GPS服务开关、模拟面板、订阅视图）
+│   │   ├── MainService.java      # GPS 定位核心前台服务
+│   │   ├── AboutActivity.java    # 关于页面
+│   │   └── GpsReceiverChildService[1-3].java  # GPS 接收子服务
+│   ├── res/
+│   │   ├── layout/               # 布局文件
+│   │   ├── menu/                 # 菜单文件
+│   │   └── values/               # 资源值文件
+│   ├── libs/                     # 本地库文件
+│   └── AndroidManifest.xml       # 应用清单
+├── build.gradle                  # 模块构建配置
+└── build.properties              # 版本配置文件
 ```

-## 参与贡献
+#### 参与贡献

 1. Fork 本仓库
 2. 新建功能分支 (`git checkout -b feat_xxx`)
-3. 提交代码（作者: ZhanGSKen <zhangsken@188.com>）
+3. 提交代码（作者: ZhanGSKen <ZhanGSKen@QQ.COM>）
 4. 新建 Pull Request

-## 许可证
+#### 许可证

 [待添加许可证信息]

-## 参考文档
+---

- [Android Developer Documentation](https://developer.android.com/)
- [Termux Wiki](https://wiki.termux.com/)
- [Gradle User Manual](https://docs.gradle.org/)
+## English Documentation
+
+### Project Introduction
+
+GPSRelaySentinel is a professional **GPS relay and guardian tool**, supporting dual modes of real system GPS location monitoring and simulated GPS coordinate simulation. It runs as a foreground persistent background service, receives real-time system GPS location data, and builds-in subscriber step threshold judgment mechanism to manage fixed-point push for multiple GPS subscription views.
+
+#### Core Features
+
+- **Dual Mode Operation**: One-click switch between real GPS working mode and virtual simulation mode
+- **Foreground Persistent Service**: `MainService` as a foreground Service continuously monitors GPS location changes
+- **Subscriber Management**: Built-in `GpsSubscribeManager` and `SubscribeLocationManager`, supporting multi-subscriber step threshold push
+- **Simulation Control Panel**: Supports eight direction selections, custom moving distance, and automatic offset target coordinate calculation
+- **Real-time Log Output**: Integrated `LogView` panel for debugging location tracks and subscription push status
+- **Crash Handling**: `App` class provides global CrashHandler and CrashActivity for crash log display
+- **About Page**: Toolbar provides an About button to view app version and project information
+
+#### Tech Stack
+
+| Item | Version/Description |
+|------|---------------------|
+| Programming Language | Java 7 (source code) |
+| Build Environment | Java 11 (Gradle compilation) |
+| Gradle Plugin | 7.2.1 |
+| Minimum API | API 26 (Android 8.0) |
+| Target API | API 30 (Android 11) |
+| Compile API | API 30 |
+
+#### Module Structure
+
+This project uses a multi-module Gradle structure:
+
+| Module | Type | Description |
+|--------|------|-------------|
+| `:gpsrelaysentinel` | application | Main application module (MainActivity, MainService, AboutActivity, etc.) |
+| `:libgpsrelaysentinel` | library | GPS relay core library (GpsSubscribeManager, SubscribeLocationManager, etc.) |
+
+#### Core Dependencies
+
+**Networking**
+- OkHttp 4.4.1 / 3.14.9 — HTTP client
+- Gson 2.10.1 — JSON parsing
+
+**Terminal Emulation**
+- Termux: terminal-emulator 0.118.0
+- Termux: terminal-view 0.118.0
+- Termux: termux-shared 0.118.0
+
+**Functional Components**
+- ZXing 3.4.1 — QR code generation and scanning
+- JSch 0.1.55 — SSH/SFTP client
+- Jsoup 1.13.1 — HTML parsing
+- FastJSON 1.2.76 — JSON processing
+
+**UI Components**
+- Material Design 1.4.0
+- AndroidX libraries
+- PullRefreshLayout 1.2.0 — Pull-to-refresh
+
+#### Build Instructions
+
+**Debug Build**
+```bash
+./gradlew assembleBetaDebug
+```
+
+**Stage Build (Release)**
+```bash
+bash .winboll/bashPublishAPKAddTag.sh gpsrelaysentinel
+```
+
+**Version Management**
+Version info is managed by `gpsrelaysentinel/build.properties`:
+- `baseVersion` — Base version number
+- `stageCount` — Stage build count
+- `publishVersion` — Release version number
+- `buildCount` — Build count
+
+#### Permissions
+
+The app requires the following permissions:
+- `ACCESS_FINE_LOCATION` — Precise location
+- `ACCESS_COARSE_LOCATION` — Approximate location
+- `ACCESS_BACKGROUND_LOCATION` — Background location
+- `FOREGROUND_SERVICE` — Foreground service
+
+#### Project Structure
+
+```
+gpsrelaysentinel/
+├── src/main/
+│   ├── java/cc/winboll/studio/gpsrelaysentinel/
+│   │   ├── App.java              # Application class, initialization and crash handling
+│   │   ├── MainActivity.java     # Main control page (GPS service switch, simulation panel, subscription views)
+│   │   ├── MainService.java      # GPS location core foreground service
+│   │   ├── AboutActivity.java    # About page
+│   │   └── GpsReceiverChildService[1-3].java  # GPS receiver child services
+│   ├── res/
+│   │   ├── layout/               # Layout files
+│   │   ├── menu/                 # Menu files
+│   │   └── values/               # Resource value files
+│   ├── libs/                     # Local library files
+│   └── AndroidManifest.xml       # App manifest
+├── build.gradle                  # Module build configuration
+└── build.properties              # Version configuration file
+```
+
+#### Contributing
+
+1. Fork this repository
+2. Create a feature branch (`git checkout -b feat_xxx`)
+3. Commit your changes (Author: ZhanGSKen <ZhanGSKen@QQ.COM>)
+4. Create a Pull Request
+
+#### License
+
+[License information to be added]