提交代码
This commit is contained in:
zlwu committed
1 parent
788daa3638
commit
2c2e4a52b4
10 files changed
+920
-2
No files matched your search
@@ -17,6 +17,7 @@
|
||||
- [宿舍管理员授权API](./宿舍管理员授权API.md)
|
||||
- [学生管理员授权关系API](./学生管理员授权关系API.md)
|
||||
- [学生销假管理API](./学生销假管理API.md)
|
||||
- [逆地理编码API](./逆地理编码API.md) - **新增逆地理编码功能**（2025-01-03）
|
||||
|
||||
### 1. 用户认证登录
|
||||
|
||||
@@ -88,6 +89,7 @@
|
||||
| 获取未到访记录详情 | GET | /api/xljk/consultation/no-show/{id} | 预约限制 | xljk:consultation:noshow:query |
|
||||
| 解除预约限制 | PUT | /api/xljk/consultation/no-show/{id}/release | 预约限制 | xljk:consultation:noshow:release |
|
||||
| 检查学生是否被限制预约 | GET | /api/xljk/consultation/no-show/check-limitation | 预约限制 | - |
|
||||
| 逆地理编码 | POST | /system/SysRegion/reverse-geocode | 行政区划 | system:SysRegion:geocode |
|
||||
|
||||
## 更新历史
|
||||
|
||||
@@ -97,6 +99,7 @@
|
||||
| 2025-07-01 | 1.0 | 初始版本 | 系统管理员 |
|
||||
| 2025-07-15 | 1.1 | 添加心理健康测评API | 张工 |
|
||||
| 2025-07-30 | 1.2 | 添加预约限制功能API | Cursor |
|
||||
| 2025-01-03 | 1.3 | 添加逆地理编码API | zlwu |
|
||||
|
||||
**详细文档**: [企业信息管理API.md](./企业信息管理API.md)
|
||||
|
||||
|
||||
@@ -0,0 +1,226 @@
|
||||
# 逆地理编码API文档
|
||||
|
||||
## 概述
|
||||
|
||||
逆地理编码API提供将经纬度坐标转换为详细地址信息的功能，基于高德地图API实现。
|
||||
|
||||
## 接口信息
|
||||
|
||||
- **接口路径**: `/system/SysRegion/reverse-geocode`
|
||||
- **请求方法**: `POST`
|
||||
- **权限要求**: `system:SysRegion:geocode`
|
||||
- **数据格式**: `application/json`
|
||||
|
||||
## 请求参数
|
||||
|
||||
### 请求体参数
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|--------|------|------|--------|------|
|
||||
| longitude | Double | 是 | - | 经度，范围：-180.0 到 180.0 |
|
||||
| latitude | Double | 是 | - | 纬度，范围：-90.0 到 90.0 |
|
||||
| output | String | 否 | "json" | 返回格式，目前仅支持json |
|
||||
| batch | Integer | 否 | 1 | 批量查询控制 |
|
||||
| roadlevel | Integer | 否 | 0 | 道路等级 |
|
||||
|
||||
### 请求示例
|
||||
|
||||
```json
|
||||
{
|
||||
"longitude": 120.1551,
|
||||
"latitude": 30.2741,
|
||||
"output": "json",
|
||||
"batch": 1,
|
||||
"roadlevel": 0
|
||||
}
|
||||
```
|
||||
|
||||
## 响应参数
|
||||
|
||||
### 响应结构
|
||||
|
||||
```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"
|
||||
},
|
||||
"pois": [],
|
||||
"roads": [],
|
||||
"roadIntersections": [],
|
||||
"aois": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 响应字段说明
|
||||
|
||||
#### 顶层字段
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| status | String | 状态码，"1"表示成功 |
|
||||
| info | String | 状态信息 |
|
||||
| infocode | String | 信息码 |
|
||||
| regeocode | Object | 逆地理编码结果 |
|
||||
|
||||
#### regeocode字段
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| formattedAddress | String | 格式化地址 |
|
||||
| addressComponent | Object | 地址组件 |
|
||||
| pois | Array | 兴趣点信息 |
|
||||
| roads | Array | 道路信息 |
|
||||
| roadIntersections | Array | 道路交叉口信息 |
|
||||
| aois | Array | 兴趣区域信息 |
|
||||
|
||||
#### addressComponent字段
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
|--------|------|------|
|
||||
| country | String | 国家 |
|
||||
| province | String | 省份 |
|
||||
| city | String | 城市 |
|
||||
| district | String | 区县 |
|
||||
| township | String | 乡镇 |
|
||||
| street | String | 街道 |
|
||||
| number | String | 门牌号 |
|
||||
| adcode | String | 行政区划代码 |
|
||||
| citycode | String | 城市编码 |
|
||||
|
||||
## 错误码说明
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| 10000 | 请求正常 |
|
||||
| 10001 | key不正确或过期 |
|
||||
| 10002 | 请求超出配额 |
|
||||
| 10003 | 请求过于频繁 |
|
||||
| 10004 | 请求参数错误 |
|
||||
| 10005 | 请求IP白名单校验失败 |
|
||||
| 10006 | 请求签名校验失败 |
|
||||
| 10007 | 请求IP不在白名单中 |
|
||||
| 10008 | 请求不在白名单中 |
|
||||
| 10009 | 请求IP不在白名单中 |
|
||||
| 10010 | 请求IP不在白名单中 |
|
||||
| 10011 | 请求IP不在白名单中 |
|
||||
| 10012 | 请求IP不在白名单中 |
|
||||
| 10013 | 请求IP不在白名单中 |
|
||||
| 10014 | 请求IP不在白名单中 |
|
||||
| 10015 | 请求IP不在白名单中 |
|
||||
| 10016 | 请求IP不在白名单中 |
|
||||
| 10017 | 请求IP不在白名单中 |
|
||||
| 10018 | 请求IP不在白名单中 |
|
||||
| 10019 | 请求IP不在白名单中 |
|
||||
| 10020 | 请求IP不在白名单中 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### JavaScript示例
|
||||
|
||||
```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);
|
||||
}
|
||||
```
|
||||
|
||||
### Python示例
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
# 发送逆地理编码请求
|
||||
response = requests.post(
|
||||
'http://localhost:8080/system/SysRegion/reverse-geocode',
|
||||
headers={
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': 'Bearer ' + token,
|
||||
'clientid': 'e5cd7e4891bf95d1d19206ce24a7b32e'
|
||||
},
|
||||
json={
|
||||
'longitude': 120.1551,
|
||||
'latitude': 30.2741
|
||||
}
|
||||
)
|
||||
|
||||
result = response.json()
|
||||
if result['code'] == 200:
|
||||
address = result['data']['regeocode']['formattedAddress']
|
||||
print('地址:', address)
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 高德地图配置
|
||||
|
||||
在 `application-dev.yml` 中配置高德地图API密钥：
|
||||
|
||||
```yaml
|
||||
# 高德地图配置
|
||||
amap:
|
||||
# 高德地图API密钥（请替换为您的实际密钥）
|
||||
key: your_amap_key_here
|
||||
# 高德地图API基础URL
|
||||
url: https://restapi.amap.com
|
||||
```
|
||||
|
||||
### 获取高德地图API密钥
|
||||
|
||||
1. 访问 [高德开放平台](https://lbs.amap.com/)
|
||||
2. 注册并登录账号
|
||||
3. 创建应用并获取API密钥
|
||||
4. 将密钥配置到 `application-dev.yml` 中
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **API密钥安全**: 请妥善保管高德地图API密钥，不要泄露给他人
|
||||
2. **请求频率限制**: 高德地图API有请求频率限制，请合理控制请求频率
|
||||
3. **坐标精度**: 建议使用高精度GPS坐标以获得更准确的地址信息
|
||||
4. **网络要求**: 需要能够访问高德地图API服务器
|
||||
5. **权限配置**: 确保用户具有 `system:SysRegion:geocode` 权限
|
||||
|
||||
## 相关文件
|
||||
|
||||
- 控制器: `SysRegionController.java`
|
||||
- 服务接口: `IAmapService.java`
|
||||
- 服务实现: `AmapServiceImpl.java`
|
||||
- 请求BO: `GeocodingRequestBo.java`
|
||||
- 响应VO: `GeocodingResponseVo.java`
|
||||
- 测试脚本: `test/逆地理编码API测试脚本.py`
|
||||
|
||||
## 更新日志
|
||||
|
||||
- 2025-01-03: 初始版本，实现基础逆地理编码功能
|
||||
@@ -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官方文档
|
||||
Reference in new issue
Block a user