### Project Setup and Execution Commands

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Provides step-by-step instructions for setting up the project, including downloading releases, placing data files, optional configuration, and running the executable on different operating systems.

```bash
# 1. 下载并解压最新 Release
# https://github.com/hygao1024/steplife-universal-importer/releases

# 2. 将轨迹文件放入 source_data/ 目录（支持 .kml / .gpx / .ovjsn）
cp my_route.gpx ./source_data/

# 3. （可选）编辑 config.ini 调整参数
echo "enableInsertPointStrategy = 1" > config.ini
echo "insertPointDistance = 100"     >> config.ini
echo "pathStartTime = 2024-04-21 08:00:00" >> config.ini

# 4. macOS / Linux 运行
./main

# 4. Windows 运行
./main.exe

# 5. 将生成的 output.csv 导入手机 → 打开「一生足迹」App 选择该文件即可
```

--------------------------------

### Set Custom Path Start Time

Source: https://github.com/hygao1024/steplife-universal-importer/blob/main/README.md

Customize the start time for a trajectory path by setting the 'pathStartTime' parameter. The default is the current system time. Ensure the format is 'yyyy-MM-dd HH:mm:ss'.

```INI
# Custom path start time. Format: yyyy-MM-dd HH:mm:ss. Default value is the current system time
pathStartTime = 2024-04-21 08:00:00
```

--------------------------------

### 解析器工厂: CreateAdaptor 函数

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

根据文件扩展名创建相应的轨迹文件解析器适配器。不支持的格式将返回 nil。

```go
// 工厂函数：按文件扩展名路由
adaptor := parser.CreateAdaptor(".kml")   // => *KML
adaptor  = parser.CreateAdaptor(".gpx")   // => *GpxAdaptor
adaptor  = parser.CreateAdaptor(".ovjsn") // => *Ovjsn
adaptor  = parser.CreateAdaptor(".xyz")   // => nil（不支持）

// 完整调用流程
content, _ := utils.ReadFile("./source_data/track.gpx")
points, err := adaptor.Parse(content)
if err != nil {
    log.Fatal(err)
}
// points => []model.Point{ {DataTime:1713657600, Lat:39.90, Lng:116.40, Alt:50.0}, ... }

sl, err := adaptor.Convert2StepLife(config, points)
// sl.CSVData => 经过插点处理后的所有坐标行
```

--------------------------------

### 核心数据模型: model.Config 结构体

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Go 语言结构体，用于存储运行时配置信息。PathStartTimestamp 在运行时计算，无需手动设置。

```go
// internal/model/config.go
type Config struct {
    EnableInsertPointStrategy int    `ini:"enableInsertPointStrategy"` // 0=禁用, 1=启用
    InsertPointDistance       int    `ini:"insertPointDistance"`        // 插点间距（米）
    PathStartTime             string `ini:"pathStartTime"`              // 原始时间字符串
    PathStartTimestamp        int64  // 运行时计算的 Unix 时间戳（秒）
}

// main.go 中的初始化逻辑示例
cfg, _ := ini.Load("config.ini")
var config model.Config
cfg.MapTo(&config)

if config.PathStartTime != "" {
    config.PathStartTimestamp, _ = timeUtils.ToTimestamp(config.PathStartTime)
    // config.PathStartTimestamp => 1713657600
} else {
    config.PathStartTimestamp = time.Now().Unix()
}

// 最小插点距离保护
if config.InsertPointDistance < consts.MinInsertPointDistance { // MinInsertPointDistance = 30
    config.InsertPointDistance = consts.DefaultInsertPointDistance // DefaultInsertPointDistance = 100
}
```

--------------------------------

### 配置系统: config.ini 示例

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

运行时配置文件，用于控制轨迹补点策略、插点距离阈值和自定义路径起始时间。程序启动时自动加载。

```ini
# config.ini 完整配置示例

# 是否启用插点策略。0: 不启用；1: 启用。缺省值 1
enableInsertPointStrategy = 1

# 插点间距（米）。两点距离超过此值时自动插入中间点。缺省值 100，最小值 30
insertPointDistance = 100

# 自定义路径起始时间（可选）。格式：yyyy-MM-dd HH:mm:ss
# 若注释掉此行，则默认使用程序运行时的系统时间
pathStartTime = 2024-04-21 08:00:00
```

--------------------------------

### 解析器接口: FileAdaptor 接口定义

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

定义了所有轨迹文件解析器的统一接口，包括解析原始数据和转换为 StepLife 格式的方法。

```go
// internal/parser/interface.go

type FileAdaptor interface {
    Parse(content []byte) ([]model.Point, error)
    Convert2StepLife(config model.Config, points []model.Point) (*model.StepLife, error)
}
```

--------------------------------

### Run Importer on Windows

Source: https://github.com/hygao1024/steplife-universal-importer/blob/main/README.md

Execute the main importer program on Windows by double-clicking 'main.exe' or running it from the terminal. Ensure source data files are in the 'source_data' directory. An 'output.csv' file will be generated.

```bash
./main.exe
```

--------------------------------

### Scan Source Data Directory for File Paths

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Scans the 'source_data/' directory and categorizes files. Files directly in the root are 'common', while files in subfolders are typed by their folder name. Ignores '.DS_Store' files.

```go
filePathMap, err := utils.GetAllFilePath("./source_data")
// filePathMap => map[string][]string{
//   "common":     ["./source_data/beijing.kml", "./source_data/shanghai.gpx"],
//   "variflight": ["./source_data/variflight/flight.json"],
// }
```

--------------------------------

### Run Complete Conversion Pipeline

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Orchestrates the full data processing pipeline: CSV creation/header check, source file scanning, file parsing, point insertion, and CSV writing. Ensures timestamp continuity between merged tracks.

```go
config := model.Config{
    EnableInsertPointStrategy: 1,
    InsertPointDistance:       100,
    PathStartTimestamp:        1713686400,
}

err := server.Run(config)
// 执行日志输出示例：
// [INFO] 处理第0个文件（./source_data/beijing.kml）
// [INFO] 处理经纬度
// [INFO] 处理经纬度完成，原始坐标52个，插点后坐标438个
// [INFO] 处理第1个文件（./source_data/shanghai.gpx）
// ...
// output.csv 生成在当前工作目录

// 错误场景：不支持的文件类型
// => error: "不支持的结构解析（common）" （当扩展名非 .kml/.gpx/.ovjsn 时）
```

--------------------------------

### 核心数据模型: CSV 输出结构

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

定义了 CSV 输出的表头和数据行结构。Row 结构体继承自 Point 并添加了 App 特定的字段。

```go
// internal/model/steplife.go  internal/model/row.go

// CSV 列顺序（固定）：
// dataTime, locType, longitude, latitude, heading, accuracy,
// speed, distance, isBackForeground, stepType, altitude

sl := model.NewStepLife()
// sl.CSVHeader => [["dataTime","locType","longitude","latitude","heading","accuracy","speed","distance","isBackForeground","stepType","altitude"]]

row := model.NewRow()
// NewRow 默认值：LocType=1, Accuracy=14, Altitude=316，其余为 0
row.Point = model.Point{
    DataTime:  1713657600,
    Latitude:  39.90403,
    Longitude: 116.40753,
    Altitude:  1200.5,
}

sl.AddCSVRow(*row)
// sl.CSVData[0] => ["1713657600","1","116.40753000","39.90403000","0","14","0.00","0","0","0","1200.50"]
```

--------------------------------

### 核心数据模型: model.Point 结构体

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

表示地理坐标点的数据结构，包含时间戳、海拔、速度、纬度和经度。是格式转换的中间表示。

```go
// internal/model/point.go
type Point struct {
    DataTime  int64   // Unix 时间戳（秒），KML/ovjsn 格式来源无时间时为 0
    Altitude  float64 // 海拔（米）
    Speed     float64 // 速度（米/秒），GPX 有值，其他格式为 0
    Latitude  float64 // 纬度（WGS84）
    Longitude float64 // 经度（WGS84）
}

// 构造示例
p := model.Point{
    DataTime:  1713657600,
    Altitude:  1200.5,
    Speed:     0.0,
    Latitude:  39.90403,
    Longitude: 116.40753,
}
```

--------------------------------

### Run Importer on macOS

Source: https://github.com/hygao1024/steplife-universal-importer/blob/main/README.md

Execute the main importer program from the terminal on macOS after placing your source data files in the 'source_data' directory. The program will generate an 'output.csv' file.

```bash
./main
```

--------------------------------

### Parse GPX File Content

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Uses GpxAdaptor to parse standard GPX XML files. Converts <time> tags to Unix timestamps and extracts <ele> and <speed>.

```go
adaptor := parser.NewGpxAdaptor()
content, _ := os.ReadFile("track.gpx")
points, err := adaptor.Parse(content)
// points[0] => {DataTime:1713686400, Latitude:39.90403, Longitude:116.40753, Altitude:50.0, Speed:5.2}
// points[1] => {DataTime:1713686460, Latitude:39.90500, Longitude:116.41000, Altitude:52.0, Speed:4.8}
```

--------------------------------

### Parse KML File Content

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Uses KMLAdaptor to parse KML XML files, extracting coordinates from <coordinates> tags. Initializes DataTime to 0 as KML lacks time information.

```go
adaptor := parser.NewKMLAdaptor()
content, _ := os.ReadFile("track.kml")
points, err := adaptor.Parse(content)
// points[0] => {DataTime:0, Latitude:39.90403, Longitude:116.40753, Altitude:50.0}
// points[1] => {DataTime:0, Latitude:39.90500, Longitude:116.41000, Altitude:52.0}
// DataTime=0 将在 Convert2StepLife 中被 PathStartTimestamp 替换
```

--------------------------------

### Convert Time Strings to Unix Timestamp

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Converts various time string formats to Unix timestamps. Parses UTC if 'T' or 'Z' is present, otherwise uses local time. Supports RFC3339, 'yyyy-MM-dd HH:mm:ss', and 'yyyy/MM/dd HH:mm:ss'.

```go
ts, err := timeUtils.ToTimestamp("2024-04-21T08:00:00Z")
// ts => 1713686400, err => nil  （UTC 解析）

ts, err = timeUtils.ToTimestamp("2024-04-21 08:00:00")
// ts => 本地时区对应的 Unix 时间戳, err => nil

ts, err = timeUtils.ToTimestamp("2024/04/21")
// ts => 当天零点时间戳, err => nil

ts, err = timeUtils.ToTimestamp("invalid-date")
// ts => 0, err => "无法解析时间字符串: invalid-date"
```

--------------------------------

### Parse Ovjsn File Content

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Uses OvjsnAdaptor to parse Omap JSON (.ovjsn) files. Recursively extracts latitude and longitude pairs from nested 'Latlng' fields.

```go
adaptor := parser.NewOvjsnAdaptor()
content, _ := os.ReadFile("route.ovjsn")
points, err := adaptor.Parse(content)
// 递归解析所有层级，共返回 4 个点：
// points[0] => {Latitude:39.90403, Longitude:116.40753}
// points[1] => {Latitude:39.90500, Longitude:116.41000}
// points[2] => {Latitude:39.91000, Longitude:116.41500}
// points[3] => {Latitude:39.92000, Longitude:116.42000}
// ...
```

--------------------------------

### Calculate Interpolated Track Points

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Uses pointcalc.Calculate to insert intermediate points between two track points based on distance and spacing. Linearly interpolates latitude, longitude, altitude, speed, and timestamp. Includes a protection against clock rollback.

```go
// internal/utils/pointcalc/calc.go

prev := model.Point{DataTime: 1713686400, Latitude: 39.90000, Longitude: 116.40000, Altitude: 50.0}
curr := model.Point{DataTime: 1713686700, Latitude: 39.93000, Longitude: 116.43000, Altitude: 80.0}
// 两点大圆距离约 4.0 km，spacing=100m，应插入约 40 个点

points := pointcalc.Calculate(prev, curr, 100)
// len(points) => 40（39 个插值点 + 1 个终点）
// points[0]  => {DataTime:1713686407, Lat:39.90075, Lng:116.40075, Alt:50.75}  // alpha=1/40
// points[19] => {DataTime:1713686550, Lat:39.91500, Lng:116.41500, Alt:65.0}   // 中间点
// points[39] => {DataTime:1713686700, Lat:39.93000, Lng:116.43000, Alt:80.0}   // 原始终点

// 时钟回拨保护：若 curr.DataTime < prev.DataTime，自动修正为 prev.DataTime+1
backwardCurr := model.Point{DataTime: 1713686000, Latitude: 39.93000, Longitude: 116.43000}
// Calculate 内部: backwardCurr.DataTime = prev.DataTime + 1 = 1713686401
```

--------------------------------

### Configure Trajectory Point Insertion Strategy

Source: https://github.com/hygao1024/steplife-universal-importer/blob/main/README.md

Disable the automatic point insertion strategy by setting 'enableInsertPointStrategy' to 0. This strategy is enabled by default to smooth trajectories, especially in areas with intermittent GPS signals.

```ini
# Is enable insert point strategy. 0: not enable; 1: enable. Default value 1
enableInsertPointStrategy = 0

# Insert point distance. When the distance between two points is greater than this value, it is considered that a point should be inserted between them. Unit: meters. Default value 100. Minimum value 30
insertPointDistance = 100
```

--------------------------------

### Append Data Rows to CSV File

Source: https://context7.com/hygao1024/steplife-universal-importer/llms.txt

Appends data rows to a CSV file in append mode, ensuring correct field escaping. If the file doesn't exist, it's created with a header row first.

```go
// 写入表头
header := [][]string{{"dataTime","locType","longitude","latitude","heading","accuracy","speed","distance","isBackForeground","stepType","altitude"}}
utils.WriteCSV("./output.csv", header)

// 追加数据行
rows := [][]string{
    {"1713686400","1","116.40753000","39.90403000","0","14","5.20","0","0","0","50.00"},
    {"1713686407","1","116.40828000","39.90478000","0","14","5.06","0","0","0","50.75"},
}
err := utils.WriteCSV("./output.csv", rows)
// output.csv:
// dataTime,locType,longitude,latitude,heading,accuracy,speed,distance,isBackForeground,stepType,altitude
// 1713686400,1,116.40753000,39.90403000,0,14,5.20,0,0,0,50.00
// 1713686407,1,116.40828000,39.90478000,0,14,5.06,0,0,0,50.75
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.