254 lines
5.3 KiB
Markdown
254 lines
5.3 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可能返回的错误信息：
|
||
|
||
- `区域名称已存在`: 当尝试创建或更新区域名称与现有名称重复时
|
||
- `区域不存在`: 当尝试更新或删除不存在的区域时
|
||
- `权限错误`: 当请求缺少有效的授权令牌时 |