# 地理编码服务使用说明

## 功能说明

地理编码服务可以将地址字符串转换为GPS坐标（经纬度），用于自动计算医院之间的转运距离。

## 后端接口

### 接口地址
```
GET /system/geocode/address
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| address | String | 是 | 地址字符串，例如："北京市朝阳区某某医院" |
| city | String | 否 | 城市名称，用于提高解析准确度，例如："北京市" |

### 响应示例

成功响应：
```json
{
  "code": 200,
  "msg": "地理编码成功",
  "data": {
    "latitude": 39.908722,
    "longitude": 116.397496,
    "address": "北京市东城区东长安街1号",
    "success": true,
    "errorMessage": null
  }
}
```

失败响应：
```json
{
  "code": 500,
  "msg": "地理编码失败: 地址不存在"
}
```

## 前端使用示例

### 1. 导入API
```javascript
import { getCoordinatesByAddress } from '@/api/geocode'
```

### 2. 调用接口获取坐标

```javascript
// 基本用法
async getHospitalCoordinates() {
  try {
    const res = await getCoordinatesByAddress('北京协和医院')
    if (res.code === 200) {
      const { latitude, longitude } = res.data
      console.log('GPS坐标:', latitude, longitude)
      // 保存坐标到表单
      this.taskForm.hospitalOut.latitude = latitude
      this.taskForm.hospitalOut.longitude = longitude
    }
  } catch (error) {
    console.error('获取坐标失败', error)
  }
}

// 指定城市，提高准确度
async getHospitalCoordinates() {
  try {
    const res = await getCoordinatesByAddress('协和医院', '北京市')
    if (res.code === 200) {
      const { latitude, longitude, address } = res.data
      console.log('GPS坐标:', latitude, longitude)
      console.log('标准化地址:', address)
    }
  } catch (error) {
    console.error('获取坐标失败', error)
  }
}
```

### 3. 在急救转运页面中集成

在 `create-emergency.vue` 中，当用户选择医院后自动获取坐标：

```javascript
// 选择转出医院
selectHospitalOut(hospital) {
  this.taskForm.hospitalOut.name = hospital.hospName
  this.taskForm.hospitalOut.address = hospital.hospAddress
  this.hospitalOutSearchKeyword = hospital.hospName
  this.showHospitalOutResults = false
  this.hospitalOutResults = []
  
  // 自动获取GPS坐标
  this.getHospitalOutCoordinates(hospital.hospAddress, hospital.hopsCity)
},

// 获取转出医院坐标
async getHospitalOutCoordinates(address, city) {
  try {
    const res = await getCoordinatesByAddress(address, city)
    if (res.code === 200) {
      this.taskForm.hospitalOut.latitude = res.data.latitude
      this.taskForm.hospitalOut.longitude = res.data.longitude
      // 如果转入医院也已选择，自动计算距离
      if (this.taskForm.hospitalIn.latitude) {
        this.calculateDistance()
      }
    }
  } catch (error) {
    console.error('获取转出医院坐标失败', error)
  }
},

// 获取转入医院坐标
async getHospitalInCoordinates(address, city) {
  try {
    const res = await getCoordinatesByAddress(address, city)
    if (res.code === 200) {
      this.taskForm.hospitalIn.latitude = res.data.latitude
      this.taskForm.hospitalIn.longitude = res.data.longitude
      // 如果转出医院也已选择，自动计算距离
      if (this.taskForm.hospitalOut.latitude) {
        this.calculateDistance()
      }
    }
  } catch (error) {
    console.error('获取转入医院坐标失败', error)
  }
},

// 计算两点之间的距离（使用Haversine公式）
calculateDistance() {
  const lat1 = this.taskForm.hospitalOut.latitude
  const lon1 = this.taskForm.hospitalOut.longitude
  const lat2 = this.taskForm.hospitalIn.latitude
  const lon2 = this.taskForm.hospitalIn.longitude
  
  if (!lat1 || !lon1 || !lat2 || !lon2) {
    return
  }
  
  const R = 6371 // 地球半径（公里）
  const dLat = (lat2 - lat1) * Math.PI / 180
  const dLon = (lon2 - lon1) * Math.PI / 180
  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
            Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
            Math.sin(dLon / 2) * Math.sin(dLon / 2)
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
  const distance = R * c
  
  // 自动填充距离字段（保留2位小数）
  this.taskForm.transferDistance = distance.toFixed(2)
  
  uni.showToast({
    title: `预估距离: ${distance.toFixed(2)}公里`,
    icon: 'none'
  })
}
```

## 配置说明

### 腾讯地图API密钥配置

在 `application.yml` 中配置腾讯地图API密钥：

```yaml
# 腾讯地图配置
tencent:
  map:
    key: YOUR_TENCENT_MAP_API_KEY
```

### 获取腾讯地图API密钥

1. 访问腾讯位置服务：https://lbs.qq.com/
2. 注册并登录开发者账号
3. 进入控制台，创建应用
4. 添加Key，选择WebService API
5. 将生成的Key填入配置文件

## 技术实现

### 后端架构

- **GeocodeResult.java**: 地理编码结果DTO，包含经纬度、地址、成功状态等信息
- **IGeocodeService.java**: 地理编码服务接口
- **GeocodeServiceImpl.java**: 地理编码服务实现类，调用腾讯地图WebService API
- **GeocodeController.java**: 地理编码控制器，提供RESTful接口

### API说明

使用腾讯地图WebService API的地理编码接口：
- API文档：https://lbs.qq.com/service/webService/webServiceGuide/webServiceGcoder
- 免费额配额：10000次/天/Key
- 请求限流：5次/秒/Key

## 注意事项

1. **API密钥安全**：不要将API密钥提交到公开的代码仓库
2. **调用频率**：注意不要超过API的调用限制（5次/秒）
3. **错误处理**：需要处理网络异常、API调用失败等情况
4. **地址准确性**：输入的地址越详细，解析结果越准确
5. **坐标系统**：腾讯地图使用GCJ-02坐标系（火星坐标系）

## 后续优化建议

1. **缓存机制**：对已解析过的地址进行缓存，减少API调用
2. **批量查询**：如果需要查询多个地址，可以考虑批量接口
3. **距离计算**：可以直接调用腾讯地图的路线规划API获取实际导航距离，而不是直线距离
4. **坐标存储**：将解析后的坐标存储到数据库，避免重复解析