# 数据流快速参考指南

## 一句话理解：4步处理流程

```
时间 → 物理 → 路径 → 噪声 → 结果
```

## 详细数据流

### 第1步：物理计算 (Physics)

```
输入：double time（秒）

过程：
  RunnerPhysics.calculate(time)
    ↓
  计算距离、速度、加速度

输出：PhysicsState
  {
    time: Double,           // 时间
    distance: Double,       // 行进距离（米）
    velocity: Double,       // 速度（m/s）
    acceleration: Double    // 加速度（m/s²）
  }

文件位置：src/main/kotlin/core/physics/RunnerPhysics.kt
```

### 第2步：路径插值 (Trajectory)

```
输入：double distance（米）来自第1步

过程：
  PathInterpolator.interpolate(distance)
    ↓
  在轨迹上查找对应坐标
  （使用Haversine算法计算路段距离）
  （线性插值得到准确坐标）

输出：RawCoordinate（无噪声）
  {
    lon: Double,  // 经度
    lat: Double   // 纬度
  }

文件位置：src/main/kotlin/core/trajectory/PathInterpolator.kt
```

### 第3步：噪声处理 (Noise)

```
输入：
  - RawCoordinate（第2步的输出）
  - PhysicsState（第1步的输出）

过程：
  NoiseProcessor.applyNoise()
    ↓
  ├─ GpsNoiseEngine.applyNoise(lon, lat)
  │   - 白噪声：每个时刻的随机偏差
  │   - 漂移：GPS偏向某侧的持续特性
  │   - 返回：(lon±noise, lat±noise, error_magnitude)
  │
  ├─ [预留] VelocityNoiseEngine.applyNoise(velocity)
  │   - 速度波动噪声
  │
  └─ [预留] AccelerationNoiseEngine.applyNoise(acceleration)
      - 加速度波动噪声

输出：NoisyCoordinate
  {
    lon: Double,           // 经度（带噪声）
    lat: Double,           // 纬度（带噪声）
    gpsError: Double       // 噪声大小（米）
  }

文件位置：
  - 协调器：src/main/kotlin/noise/NoiseProcessor.kt
  - GPS噪声：src/main/kotlin/noise/GpsNoiseEngine.kt
```

### 第4步：结果组装 (Assembly)

```
输入：
  - PhysicsState（第1步）
  - NoisyCoordinate（第3步）

过程：
  组装所有数据到单一对象

输出：MotionState（最终结果）
  {
    time: Double,                // 时间（秒）
    distance: Double,            // 距离（米）
    velocity: Double,            // 速度（m/s）
    acceleration: Double,        // 加速度（m/s²）
    latitude: Double,            // 纬度（带噪声）
    longitude: Double,           // 经度（带噪声）
    gpsError: Double,            // GPS噪声（米）
    velocityNoise: Double,       // 速度噪声（预留）
    accelNoise: Double           // 加速度噪声（预留）
  }

文件位置：src/main/kotlin/model/MotionState.kt
```

## 在哪里插入新功能？

### 想添加速度噪声？
```
位置：第3步 - NoiseProcessor.applyNoise()
方法：
  1. 在 GpsNoiseEngine.kt 中实现 VelocityNoiseEngine
  2. 在 NoiseProcessor 中调用：
     val velNoise = velocityNoiseEngine.applyNoise(physicsState.velocity)
  3. 在 MotionState 中记录结果：velocityNoise = velNoise
```

### 想添加高程信息？
```
位置：第2步和第3步之间
方法：
  1. 创建 src/main/kotlin/core/trajectory/ElevationInterpolator.kt
  2. 在 TrajectorySimulator.simulate() 中：
     步骤2.5: val elevation = elevationInterpolator.interpolate(distance)
  3. 扩展 MotionState 添加 elevation 字段
```

### 想改变运动模式（跑步/散步）？
```
位置：第1步 - RunnerPhysics.calculate()
方法：
  1. 在 RunnerPhysics 中添加运动模式参数
  2. 根据速度判断当前模式
  3. 不同模式使用不同的速度曲线
```

### 想添加传感器噪声（加速度计）？
```
位置：第3步 - NoiseProcessor.applyNoise()
方法：
  1. 在 GpsNoiseEngine.kt 中实现 AccelerationNoiseEngine
  2. 在 NoiseProcessor 中调用
  3. 在 MotionState 中记录结果
```

## 重要的类和文件

| 类名 | 文件位置 | 职责 |
|------|---------|------|
| TrajectorySimulator | core/TrajectorySimulator.kt | 主协调器，管理4步流程 |
| RunnerPhysics | core/physics/RunnerPhysics.kt | 第1步：物理计算 |
| PathInterpolator | core/trajectory/PathInterpolator.kt | 第2步：路径插值 |
| NoiseProcessor | noise/NoiseProcessor.kt | 第3步：噪声处理 |
| GpsNoiseEngine | noise/GpsNoiseEngine.kt | GPS噪声实现 |
| MotionState | model/MotionState.kt | 最终输出数据结构 |

## 调用顺序（不要改）

```
main()
  ↓
TrajectorySimulator(route)  // 初始化
  ↓
for (time in 0..duration)
  ↓
  simulator.simulate(time)
    ↓
    [第1步] physicsEngine.calculate(time) → PhysicsState
    ↓
    [第2步] pathInterpolator.interpolate(distance) → RawCoordinate
    ↓
    [第3步] noiseProcessor.applyNoise(rawCoord, physicsState) → NoisyCoordinate
    ↓
    [第4步] 组装 MotionState
    ↓
    return MotionState
```

## 核心算法（逻辑保持原样）

### Haversine 公式（计算球面距离）
位置：PathInterpolator.calculateHaversineDistance()
- 输入：两个坐标点
- 输出：球面距离（米）
- **逻辑完全保留**

### GPS 噪声模型
位置：GpsNoiseEngine.applyNoise()
- 白噪声：高斯分布
- 漂移：0.8 衰减 + 随机累积
- **逻辑完全保留**

## 常见问题

**Q: 我该改哪个文件？**
A: 看你要做什么：
- 改物理计算 → RunnerPhysics.kt
- 改路径算法 → PathInterpolator.kt（但不要改Haversine）
- 加新噪声 → GpsNoiseEngine.kt 或新建文件
- 改输出格式 → MotionState.kt

**Q: 怎么知道在哪一步插入新功能？**
A: 问自己"我的新功能需要什么输入"：
- 需要时间 → 第1步前
- 需要距离 → 第2步前
- 需要坐标 → 第3步前
- 需要物理参数 → 第3步中

**Q: 原有代码会不会被破坏？**
A: 不会。原始项目（likeRunner）完全保留，新项目（refactored-likeRunner）独立放置。