GeoFenceTrackingService

功能概述

GeoFenceTrackingService 是一项混合（前台启动 + 绑定）服务，用于高精度地理围栏监控与低功耗路径跟踪。服务使用 FusedLocationProviderClient 获取位置、利用 GeofencingClient 管理进入/退出事件，按时间与距离阈值采样并聚合步行里程。服务提供绑定接口订阅实时轨迹与围栏状态，通过前台通知展示定位状态，并在设备重启或进程被系统回收后自动恢复关键能力。弱网条件下，服务通过 WorkManager 延迟与重试数据上传，遵循最小化存储与隐私脱敏原则。

主要特性

• 地理围栏管理
  • 基于 GeofencingClient 添加/移除围栏，支持 ENTER/EXIT（可选 DWELL）事件
  • 通过 PendingIntent + BroadcastReceiver 接收围栏回调
• 低功耗路径跟踪
  • 使用 FusedLocationProviderClient 按时间间隔与最小距离采样
  • 路径去噪与距离聚合（里程统计）
• 前台服务与通知
  • 前台服务（前台类型：location），持续展示定位状态与控制操作
• 绑定接口
  • 提供客户端绑定订阅实时轨迹与围栏状态、查询当前统计数据
• 生命周期健壮性
  • onStartCommand 处理添加/移除围栏与开始/停止跟踪指令
  • START_STICKY 提高被系统回收后的恢复概率；设备重启后自动初始化
• 权限与隐私
  • 动态申请 ACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATION/ACCESS_BACKGROUND_LOCATION（视场景）与 POST_NOTIFICATIONS
  • 隐私脱敏与最小化存储策略
• 弱网与后台任务
  • WorkManager 约束上传（网络可用/回退策略），弱网延迟与重试

技术实现

1. 组件形态与进程模型

• 服务形态：混合服务
  • Started Service：承载持续定位与围栏管理
  • Bound Service：向应用内组件暴露订阅与查询接口
• 前台服务
  • Manifest 声明前台服务类型：location
  • 启动后 5 秒内调用 startForeground() 展示持久通知
• 线程模型
  • 定位与围栏回调在单一后台线程或协程作用域中顺序处理，避免竞态（例如使用 HandlerThread 或协程 + Mutex）

2. 定位采样（FusedLocationProviderClient）

• 位置请求
  • 使用 LocationRequest.Builder 配置：
    • setIntervalMillis(...)：常规采样周期（例如 5–15s，依据业务与功耗调优）
    • setMinUpdateDistanceMeters(...)：最小距离阈值（例如 10–25m，防抖与降噪）
    • setPriority(...)：活动跟踪时使用 PRIORITY_HIGH_ACCURACY；仅围栏守候或低功耗场景可降为 PRIORITY_BALANCED_POWER_ACCURACY
    • 可按前台/后台状态动态调整间隔与优先级
• 回调处理
  • 使用 LocationCallback 接收更新；进行基础去噪（水平精度阈值/速度阈值）与距离累计（球面距离）
• 前台限制
  • 在 Android 8.0+ 持续后台定位需以前台服务运行；否则会受后台执行限制影响而中断

3. 地理围栏（GeofencingClient）

• 注册与回调
  • 使用 GeofencingRequest 配置 INITIAL_TRIGGER（根据需要设置 ENTER/EXIT/DWELL）
  • Geofence 使用唯一 requestId、圆形区域（经纬度+半径）与过期时间
  • PendingIntent 指向显式 BroadcastReceiver（使用 FLAG_UPDATE_CURRENT | FLAG_IMMUTABLE）
• 能力边界
  • 每个应用可同时注册的围栏数量存在上限（常见为 100）
  • 半径过小将显著影响稳定性与功耗；建议合理设置半径（例如 ≥100m 以获取更稳定的触发表现）
• 持久化与恢复
  • 持久化围栏定义用于设备重启或服务重建后重新注册
  • addGeofences/removeGeofences 由 onStartCommand 的显式指令驱动，保证可控幂等

4. 指令协议（onStartCommand）

• 建议的显式 Action
  • ACTION_START_TRACKING / ACTION_STOP_TRACKING：开始/停止路径跟踪
  • ACTION_ADD_GEOFENCES / ACTION_REMOVE_GEOFENCES：添加/移除围栏（通过 Intent extras 传入围栏参数集合）
• 返回值
  • onStartCommand 返回 START_STICKY，提高系统回收后的自动重启概率（需注意不保证一定重启）
• 可靠性
  • 对重复指令进行去重；对失败操作（如权限缺失、Play 服务不可用）进行可观察的错误回报

5. 绑定接口（订阅与查询）

• 本地绑定（同进程）
  • LocalBinder 暴露只读状态与订阅能力：
    • subscribeLocationUpdates(callback)
    • subscribeGeofenceEvents(callback)
    • getCurrentSummary()（里程、采样点数、最近定位时间等）
• 跨进程（可选）
  • 通过 AIDL 定义回调接口（onLocationUpdate/onGeofenceEvent），在需要多进程访问时启用
• 连接管理
  • 订阅与回调在主线程安全派发或通过单线程执行器/协程通道派发，避免阻塞服务主线程

6. 前台通知

• 通知渠道
  • 独立 Channel（最小干扰，且确保可见）
• 通知内容
  • 定位状态（运行/暂停）、活跃围栏数量、上次定位时间
  • 快捷操作：停止跟踪/暂停定位/打开应用
• 安全与合规
  • 不在通知文案中展示经纬度等敏感细节

7. 权限与合规

• 运行时权限
  • 定位：ACCESS_FINE_LOCATION（精确）与 ACCESS_COARSE_LOCATION（近似）
    • 地理围栏与高精度跟踪需精确定位；仅授予近似定位时，不执行围栏注册与高精度采样
  • 后台定位：ACCESS_BACKGROUND_LOCATION
    • Android 10+ 若需在前台界面不在前台时仍接收围栏事件或持续采样，需单独获取后台定位权限（遵循分步引导至设置页的流程）
  • 通知：POST_NOTIFICATIONS（Android 13+）
    • 在首次启动前台服务前请求，以确保通知可见并提供交互
• 申请流程
  • 优先请求“使用期间”精确定位；在功能需要时再引导至设置页授予后台定位（Android 11+ 需分步）
• 失败与降级
  • 权限被拒绝：停止相关能力并向绑定客户端/通知提示受限原因与引导路径
  • 仅近似定位：维持低功耗模式并禁用地理围栏注册
• 隐私与数据最小化
  • 仅存储聚合指标与必要元数据；原始轨迹按最短必要周期缓存或不持久化
  • 对标识进行去标识化处理；遵守最小可见性原则与最短保留期
  • 提供用户可控的清除与导出能力（如适用）

8. 设备重启与系统回收后的恢复

• 系统回收
  • START_STICKY：服务被回收后由系统尝试重建，重建后重新初始化定位与围栏（需重放持久化配置）
• 设备重启
  • 接收 BOOT_COMPLETED 广播，重建必要状态（如需要持续围栏/跟踪时启动前台服务并重新注册）
• 注意
  • 后台执行限制因系统版本与厂商定制有所差异；通过前台服务与持久化重放保证关键能力尽可能恢复

9. 弱网与延迟上传（WorkManager）

• 任务调度
  • 使用 WorkManager 托管上传任务，设置网络约束（如 CONNECTED/UNMETERED 视业务选择）
  • 指数回退策略与持久队列保证在弱网下延迟与重试
• 电量与系统模式
  • WorkManager 在 Doze/App Standby 下具备系统协调执行能力，避免主动唤醒造成额外耗电

10. 存储与安全

• 存储介质
  • 轻量指标与配置使用 EncryptedSharedPreferences 或数据库（最小化结构）
• 安全策略
  • 严禁在日志或明文存储中记录经纬度与用户可识别信息
  • 对必要的本地缓存实施加密与到期清理

11. 依赖与前置条件

• 依赖 Google Play 服务
  • FusedLocationProviderClient 与 GeofencingClient 依赖 Google Play services；在不可用设备上需回退策略或禁用相关能力
• 运行环境
  • Android 8.0+ 建议以符合前台限制的方式运行持续定位；Manifest 正确声明前台服务类型

使用场景

• 到店打卡：在商圈或店铺范围内触发进入事件，结合前台服务保障稳定性
• 跑步记录：前台跟踪低功耗采样与里程统计，应用内订阅实时轨迹
• 位置提醒：在特定地点附近进入/退出时提醒用户，弱网时延迟同步云端

注意事项

• 围栏配置
  • 合理设置半径与过期时间；避免大量、小半径围栏导致的不稳定与高功耗
• 权限体验
  • 遵循“先使用期间，后后台”的分步授权；在 Android 11+ 通过设置页引导获取后台定位
• 前台服务合规
  • 启动后 5 秒内调用 startForeground()；Manifest 声明 foregroundServiceType="location"
• PendingIntent 安全
  • 使用显式接收者与 FLAG_IMMUTABLE；避免可被第三方篡改
• 版本与厂商差异
  • 背景限制与电源管理因版本/厂商不同而异；应在目标设备上充分测试
• 误差与延迟
  • 在 Doze/省电模式下，定位与围栏回调可能存在延迟；通过前台服务与合理阈值减轻影响
• Play 服务可用性
  • 在 Play 服务不可用时，禁用依赖能力或提供明示提示，避免产生不可预期行为
• 错误处理
  • 对权限、传感器、Play 服务、定位关闭等情况提供可观察状态与用户可理解的恢复路径

服务名称

OfflineDataSyncService

功能概述

面向离线优先场景的数据同步服务。通过增量队列同步与分页拉取，结合Room事务批处理与可配置冲突合并策略，实现端侧与服务器的数据一致性。服务在满足约束条件时以后台任务执行，必要时切换为前台服务以保障时效，并提供Binder接口用于进度/速率查询与取消。支持网络恢复自动重试（指数退避）、Token自动续期以及数据在存储与传输过程中的安全保护。

主要特性

• 增量同步队列：支持本地变更排队上传与服务端变更分页拉取，保障离线可用与在线一致性收敛。
• 事务化批处理：基于Room的事务提交，支持批量读写、原子性与一致性保证。
• 冲突合并策略可配置：
  • 客户端时间戳优先（Last-Write-Wins，客户端为主）
  • 服务器回滚策略（以服务器状态为准，回滚本地冲突变更）
• 网络自动恢复与指数退避：断网暂停，恢复后按指数退避与上限重试，避免过度消耗。
• 调度融合（WorkManager + 前台服务）：默认受约束后台执行；需要持续与及时性时，切换前台服务（dataSync类型）并展示通知。
• 分页API：支持基于页码或游标/续传令牌的分页拉取；上传端变更按批分片提交与确认。
• 认证与续期：自动处理鉴权令牌过期与续期，401后有限重试。
• 失败上限与告警广播：达到重试上限后发出显式应用内广播，便于UI或监控捕获。
• Binder能力：进度、吞吐速率查询，取消指定/全部任务；支持回调订阅。
• 数据安全：传输层TLS；敏感数据与凭据安全存储，密钥托管于Android Keystore；遵循平台加密与权限管控。

技术实现

1) 组件与职责

• WorkManager任务（核心执行单元）
  • 使用OneTimeWorkRequest组成的同步链（上传→下载→对账），根据网络、电量等约束调度。
  • 在需要及时性或长时任务时，通过setForeground(…)切换至前台执行（前台服务类型：dataSync）。
• Service（绑定服务，同进程或跨进程）
  • 暴露Binder/AIDL接口：查询任务状态/速率、注册进度回调、取消任务。
  • 作为UI与同步引擎的控制/遥测面板，不直接持久阻塞或执行长耗时I/O。
• 持久化层（Room）
  • 本地变更队列表（pending_ops）、同步锚点表（sync_anchor）、领域数据表（entities…）。
  • 使用@Transaction与WAL模式，保障批处理一致性与吞吐。
• 网络层
  • 统一客户端封装：分页拉取、批量上传、重试与令牌续期；对HTTP 401触发续期流程与幂等重试。

2) 生命周期与调度

• 任务入队
  • 本地写操作完成后将变更写入pending_ops，触发唯一命名的OneTimeWork（避免并发重复执行）。
  • 可配置周期性拉取（PeriodicWork）用于服务端主导的变更同步，或由推送/用户操作触发一次性同步。
• 约束条件
  • 网络：根据业务场景选择RequiredNetworkType（如 CONNECTED/METERED/UNMETERED）。
  • 电量与充电：可配置BatteryNotLow/RequiresCharging，平衡时效与能耗。
• 前台切换
  • 长时间或用户期望快速完成时，在Worker中调用setForeground(…)附带持续通知，前台服务类型声明为dataSync。
  • 执行完成或被取消后，及时结束前台状态并移除通知。
• 退避与重试
  • 使用指数退避策略（BackoffPolicy.EXPONENTIAL）与最大重试次数上限；超过上限发送应用内显式广播（包含失败原因与任务ID）。
• 取消与并发控制
  • 通过WorkManager的唯一任务名与tags控制并发；Binder取消调用映射至cancelUniqueWork/cancelAllWorkByTag。
  • 确保同一账户/数据域同步互斥，避免交叉写冲突。

3) 同步协议与数据流

• 拉取（下行）
  • 依据服务端分页（page/limit或cursor/nextPageToken）与本地同步锚点（如last_server_version或变更令牌）。
  • 对每页数据在单个Room事务中批处理写入，成功后推进锚点并持久化。
• 上传（上行）
  • 从pending_ops按批读取（可配置批大小与最大负载字节数），发送变更列表；依据服务端返回逐条确认并标记完成。
  • 建议携带幂等键（如本地操作ID）以支持服务端幂等处理，避免重放。
• 对账与补偿
  • 同步结束后进行校验（如计数或校验哈希）；异常时进入补偿流程（限次重试或标记为人工干预）。

4) 冲突合并

• 客户端时间戳优先（LWW）
  • 以本地记录的updated_at为准；当服务端记录较旧时覆盖写入。
  • 要求端侧时间来源稳定（推荐使用单一时钟源），并在写入前统一标准化时区与精度。
• 服务器回滚策略
  • 以服务端状态为权威；本地冲突项回退并记录差异（用于UI提示或后续重试）。
• 策略选择
  • 通过服务配置或账户级策略下发；在同一同步会话中保持一致性，避免混用导致非确定性。

5) Room事务批处理

• 读写合并至受控批次，使用@Transaction包裹：
  • 批大小与超时可配置，依据设备性能与I/O情况调整。
  • 优先使用主键/索引，减少UPSERT的扫描成本。
• 数据一致性
  • 先写关联表/字典表，后写业务表，保证外键完整性。
  • DOA层提供幂等写接口（如基于版本号/时间戳的条件更新）。

6) 网络与自动重试

• 连接管理
  • WorkManager网络约束保证仅在可用网络下执行；断网时暂停，网络恢复系统自动重试。
• 指数退避
  • 初始退避窗口与最大退避窗口可配置；达到上限后停止并广播告警。
• HTTP语义
  • 遵循标准缓存/条件请求（如ETag/If-None-Match或服务端变更令牌）；避免无谓全量拉取。

7) 认证与Token自动续期

• 令牌管理
  • 请求前检查令牌有效期；401时触发续期流程，仅限次重试避免循环。
  • 刷新令牌与敏感凭据保存在Android Keystore保护的加密容器中；最小化持久化范围与可见性。
• 线程与重入
  • 续期过程串行化，避免并发多次刷新；失败时短路后续请求并上报。

8) Binder接口（进度/速率/取消）

• 接口建议（AIDL或本地Binder）
  • getStatus(jobId): 返回任务状态（Pending/Running/Retrying/Succeeded/Failed/Cancelled）与阶段（Upload/Download/Reconcile）
  • getProgress(jobId): 返回总量/已完成条目、字节数、当前页/总页
  • getThroughput(jobId): 返回最近时间窗内字节/秒与记录/秒
  • cancel(jobId)、cancelAll()
  • registerCallback(callback)、unregisterCallback(callback)（进度/状态变更回调，建议一次性快照+增量事件）
• 实现要点
  • Binder调用为非阻塞；长耗时操作通过内部队列或协程执行。
  • 跨进程场景使用一方定义的权限保护与包名校验，防止越权调用。
  • 进度来源与WorkManager进度API对齐，保持一致性。

9) 安全与隐私

• 传输安全：使用TLS；如需明文测试，利用Network Security Config显式允许并限制域名范围。
• 本地安全：利用平台文件级加密；密钥由Android Keystore生成与封装；敏感数据最小化存储周期。
• 数据最小化：仅同步必要字段；调试日志脱敏，不记录令牌与个人敏感信息。

10) 日志与可观测性

• 结构化日志：同步阶段、页号、批大小、延迟、失败码、退避次数。
• 指标上报：成功率、平均延迟、吞吐、重试分布、冲突率；用于容量与策略优化。
• 告警广播：达到重试上限或不可恢复错误时，发送显式广播（附带自定义权限）供UI/监控订阅。

11) 平台与权限要求

• 前台服务类型与权限（Android 12+）
  • 声明前台服务类型 dataSync，并在清单中声明对应权限（如需要：android.permission.FOREGROUND_SERVICE_DATA_SYNC）。
  • 前台执行时必须展示常驻通知；Android 13+ 需申请POST_NOTIFICATIONS权限以展示通知。
• 后台限制与Doze
  • 使用WorkManager适配各版本的后台执行限制与电量优化策略；避免自行持有唤醒锁。
• 开机恢复（可选）
  • 若需设备重启后继续同步，声明RECEIVE_BOOT_COMPLETED并在开机完成后恢复未完成任务。

使用场景

• 线下表单/问卷采集：弱网/离线环境下先本地提交，网络可用时批量同步与冲突提示。
• 订单与库存同步：门店或仓库端的增量变更在后台自动汇聚，出现冲突时按配置策略处理。
• 业务数据拉链更新：高频小批量变更，分页拉取降低峰值压力与内存占用。

注意事项

• 任务去重与并发：
  • 采用唯一命名的Work与合理的Tag，防止同一数据域重复同步与资源竞争。
• 前台执行合规：
  • 仅在确需及时性或长时网络I/O时切换前台，结束后及时降级；通知内容清晰可见并可取消。
• 重试与上限：
  • 合理设置指数退避与最大重试次数，避免在网络极差或服务端故障期间造成过载。
• 冲突可解释性：
  • 记录冲突详情与最终决策，便于UI提示与审计；避免在同一次会话中更改策略。
• 数据库演进：
  • 严格进行Room迁移测试；批处理内注意索引与约束，避免大事务导致ANR或存储抖动。
• 令牌与隐私：
  • 刷新令牌最小权限与最小存活；任何日志与崩溃上报中屏蔽敏感字段。
• 接口稳定性：
  • AIDL版本化与向后兼容；变更字段时提供默认值与兼容路径。
• 资源与性能：
  • 根据设备与网络状况动态调整批大小与页大小；监控吞吐与失败分布以持续优化。