# 快速开始指南

## 项目已准备好！

新项目位置：`/Users/pythagodzilla/Projects/Kotlin/refactored-likeRunner/`

## 文件清单

### 📌 必读文档（3份）
1. **README.md** - 项目完整说明
2. **DATA_FLOW_GUIDE.md** - 数据流快速参考（**最重要**）
3. **BEFORE_AFTER.md** - 改进前后对比

### 📌 项目代码（9个文件）

**数据模型层**
- `model/Coordinate.kt` - 4种坐标类型
- `model/MotionState.kt` - 2种状态类型

**核心模拟层**
- `core/TrajectorySimulator.kt` - 主协调器（**从这里开始理解**）
- `core/physics/RunnerPhysics.kt` - 物理计算
- `core/trajectory/PathInterpolator.kt` - 路径插值（Haversine完全保留）

**噪声处理层**
- `noise/NoiseProcessor.kt` - 噪声协调器
- `noise/GpsNoiseEngine.kt` - GPS噪声 + 预留其他引擎

**程序入口**
- `Main.kt` - 使用示例

**数据资源**
- `resources/data/SampleRoute.kt` - 样本轨迹

## 5分钟快速理解

### 问题1：程序是干什么的？
✅ 模拟真实的跑步轨迹，包含：
- 物理计算（距离、速度、加速度）
- 路径插值（根据距离找坐标）
- GPS噪声模拟（白噪声 + 漂移）

### 问题2：怎么用？
✅ 看 `Main.kt` 就行：
```kotlin
val simulator = TrajectorySimulator(sampleRoute)
for (time in 0.0..duration step 0.1) {
    val motionState = simulator.simulate(time)
    println(motionState)
}
```

### 问题3：数据流是什么？
✅ 4步简单流程：
```
时间 → [物理] → 距离 → [路径] → 坐标 → [噪声] → 最终坐标 → [组装] → 输出
```

详见 `DATA_FLOW_GUIDE.md`

### 问题4：我想加新功能怎么办？
✅ 取决于是什么功能：
- 改物理：改 `RunnerPhysics.kt`
- 加噪声：改 `GpsNoiseEngine.kt`
- 改坐标：改 `Coordinate.kt`
- 改路径：改 `PathInterpolator.kt`（只改命名，算法完全保留）

详见 `DATA_FLOW_GUIDE.md` 的"在哪里插入新功能"

### 问题5：原有代码呢？
✅ 完全保留在 `/Users/pythagodzilla/Projects/Kotlin/likeRunner/`

新项目不会影响原项目。

## 文件阅读顺序

**第一次接触项目（推荐）**
```
1. 本文件（QUICK_START.md）      ← 你在这里
2. README.md                     ← 了解项目概况
3. Main.kt                       ← 看代码怎么用
4. DATA_FLOW_GUIDE.md           ← 深入理解数据流
5. core/TrajectorySimulator.kt  ← 看主协调器
```

**要修改代码时**
```
1. DATA_FLOW_GUIDE.md            ← 找到目标步骤
2. 对应的代码文件                ← 修改代码
3. BEFORE_AFTER.md              ← 参考改进示例
```

**要添加新功能时**
```
1. DATA_FLOW_GUIDE.md            ← "在哪里插入新功能"部分
2. GpsNoiseEngine.kt             ← 参考预留位置的代码
3. 创建新文件或修改现有文件
```

## 核心概念速查

### 4步数据流
```
步骤1 [物理]    : time → PhysicsState
步骤2 [路径]    : distance → RawCoordinate
步骤3 [噪声]    : RawCoordinate → NoisyCoordinate
步骤4 [组装]    : 所有 → MotionState
```

### 关键类
```
TrajectorySimulator  ← 主协调器，管理4步
RunnerPhysics        ← 步骤1
PathInterpolator     ← 步骤2
NoiseProcessor       ← 步骤3
GpsNoiseEngine       ← 步骤3的实现
```

### 关键方法
```
TrajectorySimulator.simulate(time)     ← 主入口
RunnerPhysics.calculate(time)          ← 物理计算
PathInterpolator.interpolate(distance) ← 路径查询
NoiseProcessor.applyNoise(...)         ← 添加噪声
```

## 代码规范

✅ **保留原样**
- Haversine算法逻辑
- GPS噪声模型逻辑
- 所有数学计算

✅ **改进**
- 方法命名（`haversine` → `calculateHaversineDistance`）
- 类名规范（`PathLinearize` → `PathInterpolator`）
- 数据类型清晰（每步都有明确的输出类型）
- 充分注释（伪代码、说明、预留标记）

✅ **新增**
- NoiseProcessor 协调器
- 中间数据类型（RawCoordinate, PhysicsState等）
- 详细注释和文档

## 常见问题

**Q: Haversine算法被改了吗？**
A: 没有。只改了方法名（`haversine` → `calculateHaversineDistance`），逻辑完全一样。

**Q: GPS噪声算法被改了吗？**
A: 没有。白噪声和漂移的计算逻辑完全保留，返回值改为Triple以包含噪声大小。

**Q: 我能直接跑这个代码吗？**
A: 大部分可以（Main.kt展示了完整流程），但物理计算部分还需要实现（已标记TODO）。

**Q: 怎么才能在项目中看到数据流？**
A: 打开 `core/TrajectorySimulator.kt`，`simulate()` 方法就是完整的4步流程。

**Q: 预留位置在哪里？**
A: 在 `GpsNoiseEngine.kt` 和 `NoiseProcessor.kt` 中，都用注释清晰标记了。

**Q: 能同时运行原项目和新项目吗？**
A: 可以，它们完全独立。新项目在 `refactored-likeRunner/` 文件夹里。

## 下一步

- [ ] 阅读 README.md 了解完整项目
- [ ] 在 Main.kt 中看程序怎么用
- [ ] 阅读 DATA_FLOW_GUIDE.md 深入理解数据流
- [ ] 根据需要修改或添加功能

祝你使用愉快！有问题随时查看相关文档。