数据持久化API

Tracelet 通过使用离线优先的架构来保证数据交付。每个位置坐标、活动变化和地理围栏事件都会立即写入加密的本地 SQLite 数据库。

虽然 Tracelet 的同步引擎自动从此数据库读取和删除数据，但您可以完全手动控制持久存储。

1. 查询位置

您可以提取当前位于 SQLite 数据库中的原始、未同步位置。


// Get ALL locations currently stored in the database
final locations = await tl.Tracelet.getLocations();
 
for (final loc in locations) {
  print('Location: \${loc.coords.latitude}, \${loc.coords.longitude}');
}

高级 SQL 查询

您不必获取所有内容。 Tracelet 公开了一个 SQLQuery 对象，该对象允许您像标准 SQL 一样过滤数据库。


// Get only the locations recorded on a specific date
final query = tl.SQLQuery(
  where: "timestamp >= ? AND timestamp <= ?",
  whereArgs: ["2024-01-01T00:00:00Z", "2024-01-01T23:59:59Z"],
  limit: 100,
  order: "timestamp DESC"
);
 
final specificLocations = await tl.Tracelet.getLocations(query);

2. 统计记录

如果您只需要知道有多少位置积压（例如，要在 UI 中显示“离线同步队列”徽章），请使用 getCount()。它经过高度优化，不会将记录加载到内存中。


// Count total un-synced locations
final count = await tl.Tracelet.getCount();
print('Pending locations to sync: \$count');
 
// You can also use SQL queries here
final highAccuracyCount = await tl.Tracelet.getCount(
  tl.SQLQuery(where: "accuracy <= 20")
);

3. 检查离线队列

由于 Tracelet 会在确认同步后修剪每条记录，因此根据定义，数据库中仍然存在的每个位置都处于待定上传状态。待处理队列帮助程序使这一点变得明确，这非常适合显示“等待同步”徽章、构建审核视图或诊断连接。


// The locations still waiting to be delivered to your backend.
final pending = await tl.Tracelet.getPendingLocations();
 
// Just the queue depth (optimized — no records are loaded into memory).
final pendingCount = await tl.Tracelet.getPendingLocationCount();
print('Offline queue: \$pendingCount location(s) waiting to sync');

两者都接受可选的 SQLQuery 进行时间范围过滤，与 getLocations() / getCount() 完全相同。

4. 销毁数据

如果用户注销或明确删除其帐户，您必须销毁其位置历史记录以符合 GDPR/HIPAA。

摧毁全部

这会将位置数据库彻底清除。


await tl.Tracelet.destroyLocations();

摧毁特定地点

如果您知道某个特定位置的 UUID，则可以销毁该位置。

从哪里获得 UUID？ Tracelet 生成的每个位置都会自动分配一个唯一的 uuid。您可以通过调用 getLocations() 并读取 Location 对象上的 uuid 属性来获取此 ID。


final locations = await tl.Tracelet.getLocations();
 
if (locations.isNotEmpty) {
  final firstLocationId = locations.first.uuid;
  
  // Destroy just this specific location from the database
  await tl.Tracelet.destroyLocation(firstLocationId);
}

销毁同步

通常，Tracelet 在从服务器收到 HTTP 200 OK 后会自动删除位置。但是，如果您正在进行手动同步，则可以手动触发此清理。


await tl.Tracelet.destroySyncedLocations();