更新记录

1.2.1（2026-10-19）

无

1.2.0（2026-10-19）

• 【单调时钟免疫】 原生与算法层全面引入硬件单调递增时钟（elapsedRealtime）及时间回拨自愈机制，彻底根除系统时钟回拨导致的滤波死锁与工时作弊；
• 【硬件脉冲保底】 原生层集成 11s 硬件脉冲防丢机制，在室内盲区断流时精准保底唤醒，并自动剥离历史残存速度航向，数据源标准规范化；
• 【拐点突变捕捉】 新增基于上一个已推流点的 2s 航向角突变捕捉（偏航 $\ge 30^\circ$ 破锁推流），解决拐角切角与漏抓难题；
• 【算法层协同加固】 优化自适应运动档位距离门槛（步行 5m / 骑行 6m / 驾车 10m），并在第 8 步增加高速防误杀保护，彻底避免拐弯采样点因短时位移未满门槛导致速度窗口清空及工位误锁。

平台兼容性

uni-app(3.8.6)

uni-app x(3.8.6)

其他

keepalive-tracker - 企业级 Android 前台常驻保活与自适应高精轨迹引擎

专为 uni-app 打造的高性能、低功耗、商业级移动端高精度轨迹追踪与防杀保活套件。

🌟 核心特性与技术亮点

1. Android 14+ 原生常驻前台保活服务 (Foreground Service + Partial WakeLock)：
   • 原生常驻通知栏，向左滑动无法清除，杜绝 Android 系统在灭屏锁屏后因省电策略挂起网络与 CPU；
   • 采用系统内核级广播与硬件唤醒锁，实现锁屏熄屏下长时间稳定连续定位采样。
2. 4 档速度阶梯自适应智能调频：
   • 根据巡检/作业人员的移动速度自动在 静止驻留 (30s/60s心跳) ➔ 步行巡检 (10s) ➔ 骑行慢车 (4.5s) ➔ 车载高速 (2.5s) 之间毫秒级平滑自适应切换；
   • 既保证了快速转弯时的轨迹平滑不丢点，又在低速驻留时大幅降低设备发热与电量消耗。
3. 专业级坐标去噪与工位驻留绝对锚定算法：
   • 原地抖动去噪：过滤室内与原地微动漂移（15m 驻留吸附），杜绝现场画出“毛线团”乱轨迹；
   • 飞溅瞬移拦截：120km/h 物理大圆测距过滤，精准剔除由基站跳变产生的瞬移野点；
   • 工时冻结续接：支持作业暂停与断点续跑，驻留工时统计精确到毫秒。
4. 离线防丢点存储队列与网络恢复自动回传：
   • 采用内存镜像 + 1秒异步节流刷盘双层存储架构；
   • 即使穿越地下室、隧道等完全断网区域，点位也能在本地可靠缓存；网络恢复瞬间 0 秒唤醒，智能批量清仓上报。
5. 国产主流手机厂商系统白名单防杀深度跳转：
   • 深度封装华为鸿蒙、小米澎湃/MIUI、OPPO ColorOS、vivo OriginOS 的“自启动”与“电池无限制”设置页直达跳转与用户指引弹窗。

📦 三分钟快速接入指引 (Quick Start)

步骤 1：导入插件并配置系统权限

1. 在 DCloud 插件市场点击【使用 HBuilderX 导入插件】，插件将自动安装到您项目的 uni_modules/keepalive-tracker/ 目录下；
2. 打开项目的 manifest.json，在“源码视图”的 app-plus -> distribute -> android -> permissions 数组中添加以下系统权限：

"permissions": [
    "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
    "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
    "<uses-permission android:name=\"android.permission.ACCESS_BACKGROUND_LOCATION\"/>",
    "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/>",
    "<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE_LOCATION\"/>",
    "<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>",
    "<uses-permission android:name=\"android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS\"/>",
    "<uses-permission android:name=\"android.permission.WAKE_LOCK\"/>"
]

注意：FOREGROUND_SERVICE_LOCATION 为 Android 14 (API 34) 官方强制要求的前台定位服务类型，插件已内置声明。

步骤 2：制作自定义调试基座（⚠️ 运行必备）

为什么必须使用自定义基座？ 本套件包含 Android 原生 Kotlin 代码 (InspectionLocationService.kt)，HBuilderX 官方标准运行基座不包含自定义原生源码，直接标准运行将无法激活原生前台保活服务。

1. 打开 HBuilderX 菜单：【运行】 ➔ 【运行到手机或模拟器】 ➔ 【制作自定义调试基座】；
2. 打包成功后，点击菜单：【运行】 ➔ 【运行到手机或模拟器】 ➔ 【运行时电脑环境】 ➔ 勾选【使用自定义基座运行】；
3. 连接 Android 真机点击运行。

步骤 3：在应用全局入口初始化 (App.vue)

在 App.vue 中配置上报接口与断点续接（保活驱动已在插件内部自动装配完成，无需外部手动介入）：

// App.vue
import LocationTracker from '@/uni_modules/keepalive-tracker/js_sdk/index.js';
// 引入您自己项目的轨迹上报接口 (支持单点或批量)
import { uploadTrackPointApi, uploadTrackBatchApi } from '@/api/track.js';

export default {
  onLaunch() {
    // 1. 初始化定位核心调度器
    LocationTracker.init({
      uploadApi: uploadTrackPointApi,       // 单点上报接口: (pointObj) => Promise
      batchUploadApi: uploadTrackBatchApi,  // 批量上报接口(可选): (pointsArray) => Promise
      interval: 10000,                      // 基础采样周期 10 秒
      usePermissionGuide: true              // 开启厂商自启动与电池优化白名单引导
    });

    // 2. 进程被杀恢复检查 (冷启动断点续接)
    if (!LocationTracker.isTracking()) {
      LocationTracker.checkAndResume((resumedTask) => {
        console.log('[App] 恢复未完成的巡检任务:', resumedTask);
      });
    }
  },
  onShow() {
    // 从后台切回前台时，尝试热升级驱动（应对用户刚在系统权限设置页开启定位权限返回的场景）
    if (typeof LocationTracker.tryUpgradeDriver === 'function') {
      LocationTracker.tryUpgradeDriver();
    }
  }
};

💻 业务页面调用示例

场景 A：现场巡检 / 连续轨迹采集 (pages/task/execute.vue)

<script setup>
import LocationTracker from '@/uni_modules/keepalive-tracker/js_sdk/index.js';

// 1. 开启巡检任务
async function handleStartTask() {
  // 引导开启 Android 后台定位权限与厂商电池白名单
  await LocationTracker.checkPermissionGuide();

  // 启动流式定位与 Android 原生常驻前台通知栏
  await LocationTracker.start({
    taskId: 'TASK_20261019_001',
    taskName: '电力线路巡检',
    userId: '10086'
  }, {
    title: '线路巡检进行中',              // 原生常驻通知栏卡片标题
    content: '正在后台持续高精记录巡检轨迹' // 原生常驻通知栏卡片内容
  });

  // 监听采纳点位（用于在前端地图上画轨迹线或更新图标坐标）
  LocationTracker.onLocation(onNewLocation);
}

// 接收经过 4 档自适应调频、15m 抖动去噪、工位驻留过滤后的优质点
function onNewLocation(point) {
  console.log('采纳点位:', point.lng, point.lat, '速度:', point.speed, '来源:', point.source);
}

// 2. 结束巡检任务
function handleStopTask() {
  LocationTracker.offLocation(onNewLocation); // 移除监听
  LocationTracker.stop();                     // 销毁常驻通知栏、清空 WakeLock、冲刷上传剩余队列
}
</script>

场景 B：打卡签到 / 现场拍照单次高精定位

在拍照打卡、表单填写需要获取当前最新高精坐标时直接调用：

import LocationTracker from '@/uni_modules/keepalive-tracker/js_sdk/index.js';

LocationTracker.getCurrentLocation(
  (lng, lat, accuracy, ext) => {
    console.log('打卡成功:', lng, lat, '精度:', accuracy, '海拔:', ext.altitude);
  },
  (err) => {
    uni.showToast({ title: '定位失败，请检查GPS', icon: 'none' });
  }
);

📋 采纳点位结构说明 (LocationPoint DTO)

通过 onLocation 回调接收或批量上报给后端的坐标对象包含完整的数据维度：

📱 国产主流手机厂商系统级防杀支持

套件内部针对国内主流手机品牌深度集成了底层白名单跳转与适配：

✅ 验收与排查核对清单 (Checklist)

在新项目中集成后，可以通过以下 4 点进行全链路保活验收：

1. 基座识别：运行后查看控制台，必须输出 [UtsKeepAliveDriver] 🚀 UTS Android 原生前台连续流式定位保活服务已成功启动！。若输出“非 Android 环境”或未启动，说明未勾选自定义调试基座；
2. 通知常驻：下拉手机状态栏，必须能看到常驻系统通知卡片（如“线路巡检进行中”），向左滑动无法清除；
3. 熄屏长测：开启任务后将手机熄屏锁屏 15~30 分钟，解锁后查看服务端接收点位记录，点位时间戳应保持连续记录，无丢点；
4. 防杀跳转：在华为/小米/OPPO/vivo 设备上点击权限引导弹窗，应能准确跳转至手机系统的“自启动管理”或“电池无限制”设置页。