API/area-api-doc.md

Area 区域管理 API 文档

概述

本文档详细描述了区域管理相关的API接口,包括增删改查操作以及新增的坐标功能.

API 接口列表

1. 创建区域

请求信息

• URL: /api/area
• Method: POST
• Headers: Authorization: Bearer {token}

请求体 (JSON)

{
  "name": "欧洲",
  "latitude": 48.8566,
  "longitude": 2.3522
}

参数说明

• name: 区域名称 (必填)
• latitude: 纬度 (-90 到 90 之间,可选)
• longitude: 经度 (-180 到 180 之间,可选)

响应示例

{
  "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)

{
  "name": "欧洲区域",
  "latitude": 48.8566,
  "longitude": 2.3522
}

参数说明

• name: 区域名称 (可选)
• latitude: 纬度 (-90 到 90 之间,可选)
• longitude: 经度 (-180 到 180 之间,可选)

响应示例

{
  "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}

响应示例

{
  "code": 0,
  "message": "删除成功",
  "data": null
}

4. 获取区域列表(分页)

请求信息

• URL: /api/area
• Method: GET
• Headers: Authorization: Bearer {token}
• Query Parameters:
  • currentPage: 当前页码 (默认 1)
  • pageSize: 每页数量 (默认 10)
  • name: 区域名称(可选,用于搜索)

响应示例

{
  "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}

响应示例

{
  "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}

响应示例

{
  "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. 初始化地图:

   // 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. 添加区域标记:

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

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