提交代码

2025-08-16 23:02:25 +08:00
1 parent 788daa3638
commit 2c2e4a52b4
@@ -0,0 +1,242 @@
+# 逆地理编码功能使用说明
+
+## 功能概述
+
+逆地理编码功能提供将经纬度坐标转换为详细地址信息的能力，基于高德地图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官方文档