254 lines
5.2 KiB
Markdown
254 lines
5.2 KiB
Markdown
# Area 区域管理 API 文档
|
|
|
|
## 概述
|
|
|
|
本文档详细描述了区域管理相关的API接口,包括增删改查操作以及新增的坐标功能.
|
|
|
|
## API 接口列表
|
|
|
|
### 1. 创建区域
|
|
|
|
**请求信息**
|
|
- URL: `/api/area`
|
|
- Method: `POST`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
|
|
**请求体 (JSON)**
|
|
```json
|
|
{
|
|
"name": "欧洲",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522
|
|
}
|
|
```
|
|
|
|
**参数说明**
|
|
- `name`: 区域名称 (必填)
|
|
- `latitude`: 纬度 (-90 到 90 之间,可选)
|
|
- `longitude`: 经度 (-180 到 180 之间,可选)
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "创建成功",
|
|
"data": {
|
|
"id": 1,
|
|
"name": "欧洲",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522,
|
|
"createdAt": "2024-01-01T12:00:00Z",
|
|
"updatedAt": "2024-01-01T12:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. 更新区域
|
|
|
|
**请求信息**
|
|
- URL: `/api/area/{id}`
|
|
- Method: `PUT`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
|
|
**请求体 (JSON)**
|
|
```json
|
|
{
|
|
"name": "欧洲区域",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522
|
|
}
|
|
```
|
|
|
|
**参数说明**
|
|
- `name`: 区域名称 (可选)
|
|
- `latitude`: 纬度 (-90 到 90 之间,可选)
|
|
- `longitude`: 经度 (-180 到 180 之间,可选)
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "更新成功",
|
|
"data": {
|
|
"id": 1,
|
|
"name": "欧洲区域",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522,
|
|
"createdAt": "2024-01-01T12:00:00Z",
|
|
"updatedAt": "2024-01-01T12:30:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 删除区域
|
|
|
|
**请求信息**
|
|
- URL: `/api/area/{id}`
|
|
- Method: `DELETE`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "删除成功",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### 4. 获取区域列表(分页)
|
|
|
|
**请求信息**
|
|
- URL: `/api/area`
|
|
- Method: `GET`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
- Query Parameters:
|
|
- `currentPage`: 当前页码 (默认 1)
|
|
- `pageSize`: 每页数量 (默认 10)
|
|
- `name`: 区域名称(可选,用于搜索)
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "查询成功",
|
|
"data": {
|
|
"list": [
|
|
{
|
|
"id": 1,
|
|
"name": "欧洲",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522,
|
|
"createdAt": "2024-01-01T12:00:00Z",
|
|
"updatedAt": "2024-01-01T12:00:00Z"
|
|
}
|
|
],
|
|
"total": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5. 获取所有区域
|
|
|
|
**请求信息**
|
|
- URL: `/api/area/all`
|
|
- Method: `GET`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "查询成功",
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "欧洲",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522,
|
|
"createdAt": "2024-01-01T12:00:00Z",
|
|
"updatedAt": "2024-01-01T12:00:00Z"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "亚洲",
|
|
"latitude": 35.6762,
|
|
"longitude": 139.6503,
|
|
"createdAt": "2024-01-01T12:10:00Z",
|
|
"updatedAt": "2024-01-01T12:10:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### 6. 根据ID获取区域详情
|
|
|
|
**请求信息**
|
|
- URL: `/api/area/{id}`
|
|
- Method: `GET`
|
|
- Headers: `Authorization: Bearer {token}`
|
|
|
|
**响应示例**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "查询成功",
|
|
"data": {
|
|
"id": 1,
|
|
"name": "欧洲",
|
|
"latitude": 48.8566,
|
|
"longitude": 2.3522,
|
|
"createdAt": "2024-01-01T12:00:00Z",
|
|
"updatedAt": "2024-01-01T12:00:00Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 世界地图实现建议
|
|
|
|
对于前端实现世界地图并显示区域坐标,推荐以下方案:
|
|
|
|
### 1. 使用开源地图库
|
|
|
|
- **Leaflet.js**: 轻量级开源地图库,易于集成
|
|
- **Mapbox**: 提供丰富的地图样式和交互功能
|
|
- **Google Maps API**: 功能强大但需要API密钥
|
|
|
|
### 2. 实现步骤
|
|
|
|
1. **获取区域数据**:
|
|
使用 `/api/area/all` 接口获取所有包含坐标信息的区域
|
|
|
|
2. **初始化地图**:
|
|
```javascript
|
|
// Leaflet示例
|
|
const map = L.map('map').setView([0, 0], 2);
|
|
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
|
|
attribution: '© OpenStreetMap contributors'
|
|
}).addTo(map);
|
|
```
|
|
|
|
3. **添加区域标记**:
|
|
```javascript
|
|
// 假设areas是从API获取的数据
|
|
areas.forEach(area => {
|
|
if (area.latitude && area.longitude) {
|
|
const marker = L.marker([area.latitude, area.longitude]).addTo(map);
|
|
marker.bindPopup(`<b>${area.name}</b>`);
|
|
}
|
|
});
|
|
```
|
|
|
|
4. **添加交互功能**:
|
|
- 点击标记显示区域详情
|
|
- 搜索和筛选功能
|
|
- 编辑坐标功能(调用更新API)
|
|
|
|
### 3. 坐标输入建议
|
|
|
|
在区域管理界面,可以添加以下功能来辅助坐标输入:
|
|
|
|
1. 提供搜索框,根据地点名称自动获取坐标
|
|
2. 集成小型地图,允许用户点击选择位置
|
|
3. 添加验证,确保输入的坐标在有效范围内
|
|
|
|
## 数据模型说明
|
|
|
|
### Area 实体
|
|
|
|
| 字段名 | 类型 | 描述 | 是否必填 |
|
|
|--------|------|------|----------|
|
|
| id | number | 区域ID | 否(自动生成) |
|
|
| name | string | 区域名称 | 是 |
|
|
| latitude | number | 纬度(范围:-90 到 90) | 否 |
|
|
| longitude | number | 经度(范围:-180 到 180) | 否 |
|
|
| createdAt | Date | 创建时间 | 否(自动生成) |
|
|
| updatedAt | Date | 更新时间 | 否(自动生成) |
|
|
|
|
## 错误处理
|
|
|
|
API可能返回的错误信息:
|
|
|
|
- `区域名称已存在`: 当尝试创建或更新区域名称与现有名称重复时
|
|
- `区域不存在`: 当尝试更新或删除不存在的区域时
|
|
- `权限错误`: 当请求缺少有效的授权令牌时 |