# 逆地理编码功能使用说明

## 功能概述

逆地理编码功能提供将经纬度坐标转换为详细地址信息的能力，基于高德地图API实现。该功能可以用于：

- 获取用户当前位置的详细地址信息
- 将GPS坐标转换为可读的地址描述
- 支持地址组件的详细解析（省、市、区、街道等）

## 快速开始

### 1. 配置高德地图API密钥

在 `backend/ruoyi-admin/src/main/resources/application-dev.yml` 中配置您的高德地图API密钥：

```yaml
# 高德地图配置
amap:
  # 高德地图API密钥（请替换为您的实际密钥）
  key: your_amap_key_here
  # 高德地图API基础URL
  url: https://restapi.amap.com
```

### 2. 获取高德地图API密钥

1. 访问 [高德开放平台](https://lbs.amap.com/)
2. 注册并登录账号
3. 创建应用并获取API密钥
4. 将密钥配置到配置文件中

### 3. 调用API接口

#### 接口信息
- **路径**: `/system/SysRegion/reverse-geocode`
- **方法**: `POST`
- **权限**: `system:SysRegion:geocode`

#### 请求示例

```javascript
// 前端调用示例
const response = await fetch('/system/SysRegion/reverse-geocode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token,
    'clientid': 'e5cd7e4891bf95d1d19206ce24a7b32e'
  },
  body: JSON.stringify({
    longitude: 120.1551,
    latitude: 30.2741
  })
});

const result = await response.json();
if (result.code === 200) {
  const address = result.data.regeocode.formattedAddress;
  console.log('地址:', address);
}
```

#### 响应示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "status": "1",
    "info": "OK",
    "infocode": "10000",
    "regeocode": {
      "formattedAddress": "浙江省杭州市西湖区文三路",
      "addressComponent": {
        "country": "中国",
        "province": "浙江省",
        "city": "杭州市",
        "district": "西湖区",
        "township": "文三街道",
        "street": "文三路",
        "number": "123号",
        "adcode": "330106",
        "citycode": "0571"
      }
    }
  }
}
```

## 功能特性

### 1. 参数验证
- 经度范围：-180.0 到 180.0
- 纬度范围：-90.0 到 90.0
- 自动参数校验和错误提示

### 2. 详细地址解析
- 格式化地址：完整的地址字符串
- 地址组件：省、市、区、街道等详细信息
- 行政区划代码：标准的行政区划编码
- 城市编码：城市电话区号

### 3. 错误处理
- 完善的错误码说明
- 详细的错误信息返回
- 异常情况的友好提示

## 使用场景

### 1. 移动端定位
```javascript
// 获取用户当前位置并转换为地址
navigator.geolocation.getCurrentPosition(async (position) => {
  const { longitude, latitude } = position.coords;
  
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const address = result.data.regeocode.formattedAddress;
    // 显示用户当前位置
    showUserLocation(address);
  }
});
```

### 2. 地图标记点信息
```javascript
// 为地图标记点获取详细地址信息
async function getMarkerAddress(longitude, latitude) {
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const addressComponent = result.data.regeocode.addressComponent;
    return {
      province: addressComponent.province,
      city: addressComponent.city,
      district: addressComponent.district,
      street: addressComponent.street
    };
  }
  return null;
}
```

### 3. 地址选择器
```javascript
// 根据坐标获取地址供用户选择
async function getAddressOptions(longitude, latitude) {
  const response = await fetch('/system/SysRegion/reverse-geocode', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({ longitude, latitude })
  });
  
  const result = await response.json();
  if (result.code === 200) {
    const regeocode = result.data.regeocode;
    return [
      regeocode.formattedAddress,
      `${regeocode.addressComponent.province}${regeocode.addressComponent.city}`,
      `${regeocode.addressComponent.city}${regeocode.addressComponent.district}`,
      regeocode.addressComponent.street
    ];
  }
  return [];
}
```

## 测试验证

### 运行测试脚本

项目提供了完整的测试脚本，可以验证功能是否正常工作：

```bash
cd test
python 逆地理编码API测试脚本.py
```

### 测试坐标点

测试脚本包含以下坐标点：
- 杭州第一技师学院 (120.1551, 30.2741)
- 西湖 (120.1551, 30.2741)
- 杭州东站 (120.2099, 30.2936)

## 注意事项

### 1. API密钥安全
- 请妥善保管高德地图API密钥
- 不要将密钥提交到版本控制系统
- 生产环境使用环境变量管理密钥

### 2. 请求频率限制
- 高德地图API有请求频率限制
- 建议实现本地缓存机制
- 避免频繁重复请求相同坐标

### 3. 坐标精度
- 建议使用高精度GPS坐标
- 室内定位可能精度较低
- 考虑坐标漂移问题

### 4. 网络要求
- 需要能够访问高德地图API服务器
- 建议配置网络超时处理
- 考虑网络异常情况

## 相关文档

- [逆地理编码API文档](./API/逆地理编码API.md)
- [高德地图开放平台文档](https://lbs.amap.com/api/webservice/guide/api/georegeo)
- [测试脚本](../test/逆地理编码API测试脚本.py)

## 技术支持

如有问题，请参考：
1. 检查API密钥配置是否正确
2. 确认网络连接是否正常
3. 查看服务器日志获取详细错误信息
4. 参考高德地图API官方文档