# 百度地图距离计算 - 快速开始

## 🚀 快速配置(3步)

### 1️⃣ 配置百度地图API Key

在 `ruoyi-admin/src/main/resources/application.yml` 中配置:

```yaml
# 百度地图配置
baidu:
  map:
    ak: YOUR_BAIDU_MAP_AK_HERE  # 替换为您的百度地图AK
```

**获取AK**: https://lbsyun.baidu.com/ → 控制台 → 应用管理 → 创建应用

### 2️⃣ 重启后端服务

配置完成后重启 Spring Boot 应用即可。

### 3️⃣ 调用接口

## 📌 两个核心接口

### 接口1: 计算两个坐标之间的距离

**接口**: `GET /system/gps/baidu/route/driving`

**参数**:
- `origin`: 起点坐标 (纬度,经度)
- `destination`: 终点坐标 (纬度,经度)

**示例**:
```
GET /system/gps/baidu/route/driving?origin=40.056878,116.30815&destination=31.222965,121.505821
```

**前端调用**:
```javascript
import { baiduRouteDriving } from '@/api/map'

baiduRouteDriving('40.056878,116.30815', '31.222965,121.505821')
  .then(res => {
    const result = JSON.parse(res.data)
    const distanceKm = (result.result.routes[0].distance / 1000).toFixed(2)
    console.log('距离:', distanceKm + ' 公里')
  })
```

### 接口2: 计算两个地址之间的距离

**两步走**:

**步骤1**: 地址转坐标

```javascript
import { baiduGeocoding } from '@/api/map'

// 起点地址转坐标
baiduGeocoding('广州市天河区天河路', '广州市')
  .then(res => {
    const result = JSON.parse(res.data)
    const lat = result.result.location.lat
    const lng = result.result.location.lng
    console.log('起点坐标:', lat + ',' + lng)
  })
```

**步骤2**: 坐标计算距离 (同接口1)

**或使用组合接口**:

```javascript
import { baiduDistanceByAddress, baiduRouteDriving } from '@/api/map'

async function calcDistance() {
  // 第1步: 获取坐标
  const geocode = await baiduDistanceByAddress(
    '广州市天河区天河路', '广州市',
    '广州市越秀区中山路', '广州市'
  )
  
  const fromGeo = JSON.parse(geocode.data.fromGeocoding)
  const toGeo = JSON.parse(geocode.data.toGeocoding)
  
  const origin = fromGeo.result.location.lat + ',' + fromGeo.result.location.lng
  const dest = toGeo.result.location.lat + ',' + toGeo.result.location.lng
  
  // 第2步: 计算距离
  const route = await baiduRouteDriving(origin, dest)
  const result = JSON.parse(route.data)
  const distanceKm = (result.result.routes[0].distance / 1000).toFixed(2)
  
  console.log('距离:', distanceKm + ' 公里')
  return distanceKm
}
```

## 💡 实战场景

### 场景: 任务创建时自动计算距离

```javascript
// 在任务表单组件中
data() {
  return {
    form: {
      startAddress: '',
      endAddress: '',
      distance: ''
    }
  }
},

watch: {
  // 监听起点和终点变化
  'form.startAddress': 'autoCalculateDistance',
  'form.endAddress': 'autoCalculateDistance'
},

methods: {
  async autoCalculateDistance() {
    if (!this.form.startAddress || !this.form.endAddress) {
      return
    }
    
    try {
      // 1. 起点地址转坐标
      const fromRes = await baiduGeocoding(this.form.startAddress, '广州市')
      const fromGeo = JSON.parse(fromRes.data)
      const fromLat = fromGeo.result.location.lat
      const fromLng = fromGeo.result.location.lng
      
      // 2. 终点地址转坐标
      const toRes = await baiduGeocoding(this.form.endAddress, '广州市')
      const toGeo = JSON.parse(toRes.data)
      const toLat = toGeo.result.location.lat
      const toLng = toGeo.result.location.lng
      
      // 3. 计算距离
      const routeRes = await baiduRouteDriving(
        fromLat + ',' + fromLng,
        toLat + ',' + toLng
      )
      const route = JSON.parse(routeRes.data)
      const distanceKm = (route.result.routes[0].distance / 1000).toFixed(2)
      
      // 4. 自动填充距离字段
      this.form.distance = distanceKm
      this.$message.success('距离自动计算成功: ' + distanceKm + ' 公里')
      
    } catch (error) {
      console.error('距离计算失败:', error)
      this.$message.warning('距离自动计算失败,请手动填写')
    }
  }
}
```

## ⚠️ 注意事项

### 1. 坐标格式

- 百度地图: `纬度,经度` (lat,lng)
- 示例: `40.056878,116.30815`

### 2. 坐标系统

- 百度地图使用 BD-09 坐标系
- 如果您的坐标是 GPS 或高德坐标,需要先转换

### 3. 距离单位

- API 返回的是 **米(m)**
- 转换为公里: `distanceKm = distance / 1000`

### 4. 错误处理

返回状态码说明:
- `status: 0` - 成功
- `status: 1` - 服务器内部错误  
- `status: 2` - 参数非法
- `status: 3` - 权限校验失败 (检查AK配置)
- `status: 4` - 配额不足

## 📝 完整示例代码

见 `prd/百度地图距离计算接口说明.md` 获取详细文档。

## 🔗 相关文件

- **后端配置**: `ruoyi-common/src/main/java/com/ruoyi/common/config/BaiduMapConfig.java`
- **后端接口**: `ruoyi-admin/src/main/java/com/ruoyi/web/controller/system/VehicleGpsController.java`
- **前端API**: `app/api/map.js`
- **配置文件**: `ruoyi-admin/src/main/resources/application.yml`

## ❓ 常见问题

**Q: 返回 status: 3 怎么办?**

A: 检查 application.yml 中的 AK 是否正确配置。

**Q: 计算的距离不准确?**

A: 确认坐标系是 BD-09,如果是其他坐标系需要转换。

**Q: 能支持步行、骑行距离吗?**

A: 可以,修改接口路径为 `/walking` 或 `/riding` 即可。

---

**开发完成时间**: 2025-10-21  
**文档版本**: v1.0