173 lines
5.0 KiB
Markdown
173 lines
5.0 KiB
Markdown
# 快速开始指南
|
||
|
||
## 项目已准备好！
|
||
|
||
新项目位置：`/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 深入理解数据流
|
||
- [ ] 根据需要修改或添加功能
|
||
|
||
祝你使用愉快！有问题随时查看相关文档。
|