From a3855b437578c05aa2d91ecab957bfb38ab1a8b1 Mon Sep 17 00:00:00 2001 From: LaizyBoy Date: Thu, 7 May 2026 16:25:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=20gpsrelaysentinel/R?= =?UTF-8?q?EADME.md=20=E4=B8=AD=E8=8B=B1=E6=96=87=E5=8F=8C=E8=AF=AD?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 中文文档新增核心功能清单（双模式运行、前台服务、订阅者管理、模拟面板、日志输出、崩溃处理、关于页面） - 技术栈改用表格展示，模块说明更新为实际编译模块（:gpsrelaysentinel 与 :libgpsrelaysentinel） - 核心依赖库分类更清晰（网络、终端模拟、功能组件、UI 组件） - 项目结构树精确到具体 Java 源文件及其功能说明 - 权限说明改为具体 Android 权限声明 - 新增完整英文版本文档（Project Introduction、Core Features、Tech Stack、Module Structure、Core Dependencies、Build Instructions、Permissions、Project Structure、Contributing、License） - 删除失效的参考文档链接 --- gpsrelaysentinel/README.md | 266 ++++++++++++++++++++++++++----------- 1 file changed, 189 insertions(+), 77 deletions(-) diff --git a/gpsrelaysentinel/README.md b/gpsrelaysentinel/README.md index 7d91612..5d77c94 100644 --- 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 ） +3. 提交代码（作者: ZhanGSKen ） 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 ) +4. Create a Pull Request + +#### License + +[License information to be added]