API/area-api-doc.md

# 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可能返回的错误信息:

- `区域名称已存在`: 当尝试创建或更新区域名称与现有名称重复时
- `区域不存在`: 当尝试更新或删除不存在的区域时
- `权限错误`: 当请求缺少有效的授权令牌时