数据模型

本文档描述 GoWherer 应用的核心数据类型定义，源码位于 types/ 目录。

枚举类型

JourneyKind

旅程类型，区分旅行与通勤两种模式。

export type JourneyKind = 'travel' | 'commute';

值	说明
travel	旅行
commute	通勤

JourneyStatus

旅程状态，标识旅程是否正在进行。

export type JourneyStatus = 'active' | 'completed';

值	说明
active	进行中
completed	已结束

MediaType

媒体附件类型。

export type MediaType = 'photo' | 'video' | 'audio';

值	说明
photo	照片
video	视频
audio	音频

JourneyCostMode

交通费记录的交通方式。

export type JourneyCostMode =
  | 'metro'
  | 'rail'
  | 'bus'
  | 'taxi'
  | 'flight'
  | 'other';

值	说明
metro	地铁
rail	高铁/火车
bus	公交
taxi	打车
flight	航班
other	其他

CoordinateType

坐标系类型，用于区分 WGS84 和 GCJ02。

export type CoordinateType = 'wgs84' | 'gcj02';

值	说明
wgs84	国际标准坐标系（GPS 使用）
gcj02	中国国测局坐标系（高德、腾讯使用）

ReverseGeocodeProvider

反向地理编码服务提供商。

export type ReverseGeocodeProvider = 'system' | 'amap';

值	说明
system	系统原生地理编码
amap	高德地图 Web API

---

核心类型

TimelineLocation

时间线中的位置数据。

export type TimelineLocation = {
  latitude: number;          // 纬度 (-90 ~ 90)
  longitude: number;         // 经度 (-180 ~ 180)
  accuracy?: number | null;  // 定位精度（米），可选
  placeName?: string;        // 地点名称（通过逆地理编码获取），可选
  capturedAt?: string;       // 采集时间（ISO 8601），可选
  source?: 'manual' | 'tracking'; // 来源：手动选点 | 后台追踪，可选
  coordSystem?: 'wgs84' | 'gcj02'; // 坐标系，可选（缺失视为历史数据，加载时迁移归一）
};

TimelineMedia

时间线中的媒体附件。

export type TimelineMedia = {
  id: string;                // 唯一标识符（UUID）
  type: MediaType;            // 媒体类型：photo | video | audio
  uri: string;               // 媒体资源 URI（本地路径或网络 URL）
  thumbnailUri?: string;      // 视频缩略图 URI，可选
};

EntryCost

记录条目上的交通费。

export type EntryCost = {
  mode: JourneyCostMode;      // 交通方式
  amount: number;             // 金额（元），保留两位小数
};

TimelineEntry

时间线条目，即旅程中的一条记录。

export type TimelineEntry = {
  id: string;                // 唯一标识符（UUID）
  createdAt: string;         // 创建时间，ISO 8601 格式字符串
  text: string;               // 文本内容
  location?: TimelineLocation; // 关联的位置信息，可选
  media: TimelineMedia[];     // 媒体附件列表
  tags: string[];             // 标签列表
  cost?: EntryCost;           // 本段交通花费，可选
};

Journey

旅程主体，包含一次完整出行的所有信息。

export type Journey = {
  id: string;                // 唯一标识符（UUID）
  title: string;             // 旅程标题
  kind: JourneyKind;          // 旅程类型：travel | commute
  createdAt: string;          // 创建时间，ISO 8601 格式
  endedAt?: string;           // 结束时间，ISO 8601 格式，可选
  status: JourneyStatus;      // 旅程状态：active | completed
  tags: string[];             // 旅程级标签
  entries: TimelineEntry[];   // 时间线条目列表
  trackLocations: TimelineLocation[]; // 持续 GPS 轨迹点集合
};

EntryTemplate

记录模板（定义于 types/template.ts），用于快速录入预设文本与标签。

export type EntryTemplate = {
  id: string;                // 唯一标识符
  label: string;              // 显示标签
  text: string;               // 模板预置文本内容
  tags: string[];             // 预置标签列表
};

EntryTemplateConfig

按旅程类型分类的模板配置。

export type EntryTemplateConfig = Record<JourneyKind, EntryTemplate[]>;

NearbyPlace

附近地点查询结果。

export type NearbyPlace = {
  id: string;                // 地点唯一标识
  name: string;               // 地点名称
  address?: string;            // 详细地址，可选
  distance?: number;           // 距查询点的距离（米），可选
  latitude: number;            // 纬度
  longitude: number;           // 经度
};

ReportTemplateId

导出报告模板标识（定义于 lib/report-templates.ts）。

export type ReportTemplateId = 'classic' | 'compact';

值	说明
classic	经典：青绿封面 · 时间线卡片 · 交通费表
compact	简约：单页紧凑排版 · 蓝色基调

LocalePreference

语言偏好设置。

export type LocalePreference = Locale | 'system';
export type Locale = 'en' | 'zh';

AppBackupV1

应用备份数据结构，用于数据导出与迁移。

export type AppBackupV1 = {
  version: 1;
  exportedAt: string;
  app: {
    slug: string;
    version: string;
  };
  preferences: {
    locale: LocalePreference;
    theme: ThemePreference;
  };
  journeys: Journey[];
  entryTemplates: Record<Locale, EntryTemplateConfig>;
};

---

数据流向

flowchart TD
    User[用户操作] --> JourneyMgmt[旅程管理]
    User --> TimelineEntry[时间线记录]
    User --> Cost[交通费记录]
    User --> Template[模板记录]
    User --> Map[地图选点]

    JourneyMgmt -->|create| Journey[Journey]
    JourneyMgmt -->|end| Journey
    JourneyMgmt -->|search| JourneyList[旅程列表]

    TimelineEntry -->|text| TimelineEntry
    TimelineEntry -->|location| TimelineLocation
    TimelineEntry -->|media| TimelineMedia
    TimelineEntry -->|tags| TagList[标签列表]
    TimelineEntry -->|cost| EntryCost

    Template -->|travel| TravelTemplate[旅行模板]
    Template -->|commute| CommuteTemplate[通勤模板]

    Map --> ReverseGeocode[逆地理编码]
    Map --> Track[轨迹记录]
    Map --> Nearby[附近地点]

    Journey --> Storage[(AsyncStorage)]
    Storage --> Persistence[数据持久化]

---

存储键

所有数据通过 AsyncStorage 本地持久化，存储键前缀为 gowherer:，集中定义在 lib/storage-keys.ts。

存储键	数据类型	说明
gowherer:journeys:v1	Journey[]	所有旅程数据
gowherer:entry-templates:v1:zh	EntryTemplate[]	中文模板
gowherer:entry-templates:v1:en	EntryTemplate[]	英文模板
gowherer:pending-location:v1	TimelineLocation	待处理位置（地图选点后临时存储）
gowherer:locale-preference:v1	LocalePreference	语言偏好
gowherer:theme-preference:v1	ThemePreference	主题偏好
gowherer:review-filters:v1	回顾页筛选状态	类型/标签筛选与展开状态持久化
gowherer:geocode-cache:v1	GeocodeCachePayload	逆地理编码本地缓存（约 110m 网格键，上限 500 条）