更新记录

1.0.3（2026-08-31）

Changelog

1.0.3 (2026-08-27)

• 移除 package.json 的 uni_modules.dependencies 中对 keepalive-location 的声明，修复 Android 云打包 Project :uni_modules:keepalive-location could not be found（两插件为 JS 层配套，无原生 Gradle 依赖）

1.0.2 (2026-08-27)

• Android 云打包修复：Kotlin 顶层类型替代 object 嵌套类；queryTracks 参数 status 与字段 shadow 修复
• Android UTS 对齐 iOS：禁用 any 桥接、geofenceToNative 改用 GeofenceConfigNative 实例赋值
• makePoint / initDb / TTS 参数统一 .toDouble() / (0).toLong()

1.0.1 (2026-08-27)

• 围栏改为消费 keepalive-location 点位，移除三端第二路 LocationManager / geoLocationManager
• 新增 feedGeofenceLocation()：仅围栏判定、无需 startTrack
• 新增根目录 index.vue 联调 Demo 与 examples/README.md
• 文档强调 uni_modules 目录须用 ASCII -，不可用 Unicode ‑（U+2011）
• GPX 时间统一为 UTC ISO8601（含毫秒）
• Android 多边形 JSON 改 Kotlin 解析；本插件 manifest 不再重复定位权限

1.0.0 (2026-08-27)

• 初始版本：三端 UTS 插件 keepalive-track-tool
• 原生 SQLite 轨迹会话：start/stop、批量落库、重启恢复 active 会话
• GPS 降噪过滤（精度 / 速度阈值）
• 历史轨迹分页查询、删轨迹、过期清理
• GPX / CSV 导出至沙盒缓存目录
• 圆形 / 多边形电子围栏，原生后台 enter / leave / stay
• 系统 TTS 语音播报（语速 / 音量 / 停止）
• 依赖 keepalive-location 输出点位，对接 ebook-select-files 上传导出文件

平台兼容性

uni-app(3.8.3)

keepalive-track-tool

UTS 轨迹 SQLite 存储 / GPX·CSV 导出 / 电子围栏 / 系统 TTS

配套 keepalive-location 使用：定位与权限由前者负责，本插件负责轨迹持久化、导出、围栏几何判定与语音播报。导出文件路径可直接交给 ebook-select-files 预览上传。

功能

1. 原生 SQLite 轨迹存储

   • startTrack() / stopTrack()：会话管理，自动统计里程、点数、起止时间
   • appendTrackPoint()：接收 keepalive-location 的 GpsPoint，原生批量写入
   • 进程重启恢复未完成（active）轨迹会话
   • GPS 降噪：速度 / 精度阈值过滤
   • 历史分页查询、删轨迹、过期自动清理

2. 轨迹导出

   • 原生生成 GPX / CSV（UTC ISO8601 时间），写入应用沙盒 cache/track_exports/
   • 返回 filePath，对接文件选择器上传

3. 三端电子围栏

   • 圆形（中心 + 半径）、多边形（经纬度数组）
   • 不重复起第二路定位：消费 keepalive-location 出点，原生层做几何判定；息屏后台依赖 keepalive-location 前台服务/Background Modes
   • SQLite 持久化，enter / leave / stay 事件 + 可选 TTS
   • 地图展示不在本插件内：Demo（background-location/pages/fence-map）用 listGeofences() + uni-app <map> 绘制，业务 App 自行接入地图 SDK

4. 系统 TTS

   • 围栏 / 业务层调用 speak()，无需第三方 SDK
   • setTtsRate / setTtsVolume / stopSpeak

安装

目录名必须与 package.json 的 id 完全一致，且使用 ASCII 连字符 -。 禁止使用 Unicode 连字符 ‑（U+2011），否则 Android 云打包会报： Namespace 'uts.sdk.modules.keepalive‑track‑tool' is not a valid Java package name。

将本目录以 keepalive-track-tool（普通减号）放入 uni_modules/keepalive-track-tool，并手动确保已安装 uni_modules/keepalive-location（业务层配套，无原生 Gradle 依赖）。

试用页：根目录 index.vue 为完整联调 Demo（轨迹 + 围栏 + 导出），用法见 examples/README.md。

import {
  initTrack,
  startLocation,
  onLocationUpdate,
  requestPermissions
} from '@/uni_modules/keepalive-location'
import {
  initTrackTool,
  startTrack,
  stopTrack,
  appendTrackPoint,
  feedGeofenceLocation,
  exportTrackGpx,
  addGeofence,
  onGeofenceEvent,
  speak
} from '@/uni_modules/keepalive-track-tool'

快速接入（推荐）

await initTrackTool({ filter: { maxAccuracy: 60 }, expireDays: 90 })
await initTrack({ enableForegroundService: true })
await requestPermissions()

await addGeofence({
  name: '仓库',
  shape: { type: 'circle', latitude: 31.2, longitude: 121.5, radiusMeters: 200 },
  ttsOnEnter: '已进入仓库区域'
})

onGeofenceEvent((ev) => console.log(ev.event, ev.geofenceId))

const trackId = await startTrack({ name: '外勤巡检' })
await startLocation({ intervalMs: 3000 })

// 录轨迹 + 判围栏（一点两用）
onLocationUpdate((point) => appendTrackPoint(point))

// 仅围栏、不录轨迹时：
// onLocationUpdate((point) => feedGeofenceLocation(point))

const summary = await stopTrack()
const gpx = await exportTrackGpx(summary.trackId)

与 keepalive-location 的分工

围栏要能息屏触发，必须同时运行 keepalive-location 的 startLocation()；本插件不再单独申请定位或起第二路 LocationManager。

与 ebook-select-files 对接

import { selectFiles } from '@/uni_modules/ebook-select-files'

const gpx = await exportTrackGpx(trackId)
selectFiles({
  count: 1,
  extensions: ['gpx', 'csv'],
  success(res) {
    // uni.uploadFile({ url, filePath: gpx.filePath })
  }
})

API 摘要

权限说明

• 定位：全部由 keepalive-location 申请；本插件 manifest 不再重复声明
• TTS：系统语音合成，无网络依赖
• 数据仅存本地 SQLite 与沙盒导出目录

平台实现

联调清单

1. 制作含两插件的自定义基座
2. initTrackTool → initTrack → requestPermissions → startLocation
3. 验证 appendTrackPoint 后 queryTrackPoints 有点
4. 验证 addGeofence 后进出区域触发 onGeofenceEvent（需 keepalive 后台仍在出点）
5. exportTrackGpx 后用 ebook-select-files 或 uni.uploadFile 上传