02 API接口设计 - Ei-Ayw/smart-tea-garden GitHub Wiki

环境监测（硬件通信模块）

（1）气象数据采集接口

获取实时气象数据

  • 请求方式：GET
  • 请求方法：Server-Sent Events (SSE)
  • 接口路径：/weather/realtime/{plantationId}
  • 请求参数：无额外参数，使用公共请求参数即可。
  • 请求示例
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {
  "code":200,
  "message":"success",
  "timestamp":"2025-07-03 14:30:00",
  "data":
  {
      "weather": {
      "temperature": {
        "value": 25.3,
        "unit": "°C",
        "range": "-30°C to 60°C"
      },
      "humidity": {
        "value": 60.5,
        "unit": "%RH",
        "range": "0% to 100%"
      },
      "light": {
        "value": 1500,
        "unit": "lux",
        "range": "0 to 100000 lux"
      },
      "wind": {
        "speed": {
          "value": 3.2,
          "unit": "m/s",
          "range": "0 to 30 m/s"
        },
        "direction": {
          "value": 90,
          "unit": "degrees",
          "description": "East"
        }
      },
      "rainfall": {
        "value": 0,
        "unit": "mm",
        "range": "0 to 500 mm",
        "duration": "last 24 hours"
      }
    },
    "device": {
      "id": "SENSOR-2025-07-03-001",
      "type": "气象综合监测仪",
      "location": {
        "name": "户外监测点A",
        "coordinates": {
          "latitude": 31.2304,
          "longitude": 121.4737
        },
        "altitude": 12.5
      },
      "status": "active",
      "last_calibration": "2025-06-15"
    },
    "metadata": {
      "accuracy": {
        "temperature": "±0.5°C",
        "humidity": "±3%RH",
        "light": "±5% of reading",
        "wind_speed": "±0.3 m/s",
        "wind_direction": "±5 degrees",
        "rainfall": "±0.2 mm"
      },
      "update_interval": "5 minutes",
      "data_quality": "high",
      "environment": "outdoor"
    }
  }
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示请求成功。
  • message: 响应消息，描述请求的结果，"success" 表示成功处理了请求。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • historical_soil_data: 一个数组，包含多个时间点的历史土壤数据记录。
    • 每个对象代表特定时间点的土壤数据，字段包括：
      • timestamp: 数据记录的时间点，格式为 "YYYY-MM-DD HH:MM:SS"。
      • soil_moisture: 土壤湿度信息对象。
        • value: 土壤湿度的数值。
        • unit: 土壤湿度的单位，% 表示百分比。
      • soil_temperature: 土壤温度信息对象。
        • value: 土壤温度的数值。
        • unit: 土壤温度的单位，°C 表示摄氏度。
      • soil_ph: 土壤酸碱度（pH值）信息对象。
        • value: 土壤的 pH 值。
        • unit: pH 值的单位，pH。
      • soil_nutrients: 土壤养分信息对象，包括：
        • nitrogen: 氮含量信息对象。
          • value: 氮含量的数值。
          • unit: 氮含量的单位，mg/kg 表示毫克每千克。
        • phosphorus: 磷含量信息对象。
          • value: 磷含量的数值。
          • unit: 磷含量的单位，mg/kg。
        • potassium: 钾含量信息对象。
          • value: 钾含量的数值。
          • unit: 钾含量的单位，mg/kg。
      • soil_electrical_conductivity: 土壤电导率信息对象。
        • value: 土壤电导率的数值。
        • unit: 电导率的单位，dS/m 表示分西门子每米。
  • device: 监测设备的详细信息对象，字段包括：
    • id: 设备的唯一标识符。
    • type: 设备类型。
    • location: 设备位置信息对象，包括：
      • name: 位置名称。
      • coordinates: 坐标信息对象，包括：
        • latitude: 纬度。
        • longitude: 经度。
      • depth: 监测深度。
    • status: 设备状态，active 表示设备运行正常。
    • last_calibration: 设备最后校准的时间。
  • time_range: 字符串，表示数据覆盖的时间范围，格式为 "YYYY-MM-DD HH:MM:SS to YYYY-MM-DD HH:MM:SS"。
#### **获取历史气象数据** + **请求方式**：GET + **请求方法**：传统http请求 + **接口路径**：/weather/history/plantationId? + **请求参数**：无额外参数，使用公共请求参数即可。 
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "historical_weather": [
        {
            "timestamp": "2025-07-03 12:00:00",
            "temperature": {
                "value": 24.8,
                "unit": "°C"
            },
            "humidity": {
                "value": 62.1,
                "unit": "%RH"
            },
            "light": {
                "value": 1400,
                "unit": "lux"
            },
            "wind": {
                "speed": {
                    "value": 2.8,
                    "unit": "m/s"
                },
                "direction": {
                    "value": 85,
                    "unit": "degrees",
                    "description": "East"
                }
            },
            "rainfall": {
                "value": 0,
                "unit": "mm",
                "duration": "last 24 hours"
            }
        },
        {
            "timestamp": "2025-07-03 10:00:00",
            "temperature": {
                "value": 23.5,
                "unit": "°C"
            },
            "humidity": {
                "value": 65.3,
                "unit": "%RH"
            },
            "light": {
                "value": 1100,
                "unit": "lux"
            },
            "wind": {
                "speed": {
                    "value": 2.5,
                    "unit": "m/s"
                },
                "direction": {
                    "value": 95,
                    "unit": "degrees",
                    "description": "East"
                }
            },
            "rainfall": {
                "value": 0,
                "unit": "mm",
                "duration": "last 24 hours"
            }
        },
        {
            "timestamp": "2025-07-03 08:00:00",
            "temperature": {
                "value": 22.0,
                "unit": "°C"
            },
            "humidity": {
                "value": 68.7,
                "unit": "%RH"
            },
            "light": {
                "value": 800,
                "unit": "lux"
            },
            "wind": {
                "speed": {
                    "value": 2.2,
                    "unit": "m/s"
                },
                "direction": {
                    "value": 100,
                    "unit": "degrees",
                    "description": "East"
                }
            },
            "rainfall": {
                "value": 0,
                "unit": "mm",
                "duration": "last 24 hours"
            }
        }
    ],
    "device": {
        "id": "SENSOR-2025-07-03-001",
        "type": "气象综合监测仪",
        "location": {
            "name": "户外监测点A",
            "coordinates": {
                "latitude": 31.2304,
                "longitude": 121.4737
            },
            "altitude": 12.5
        },
        "status": "active",
        "last_calibration": "2025-06-15"
    },
    "time_range": "2025-07-03 08:00:00 to 2025-07-03 14:30:00"
  }
}
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示请求成功。
  • message: 响应消息，描述请求的结果，"success" 表示成功处理了请求。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • historical_soil_data: 一个数组，包含多个时间点的历史土壤数据记录。
    • 每个对象代表特定时间点的土壤数据，字段包括：
      • timestamp: 数据记录的时间点，格式为 "YYYY-MM-DD HH:MM:SS"。
      • soil_moisture: 土壤湿度信息对象。
        • value: 土壤湿度的数值。
        • unit: 土壤湿度的单位，% 表示百分比。
      • soil_temperature: 土壤温度信息对象。
        • value: 土壤温度的数值。
        • unit: 土壤温度的单位，°C 表示摄氏度。
      • soil_ph: 土壤酸碱度（pH值）信息对象。
        • value: 土壤的 pH 值。
        • unit: pH 值的单位，pH。
      • soil_nutrients: 土壤养分信息对象，包括：
        • nitrogen: 氮含量信息对象。
          • value: 氮含量的数值。
          • unit: 氮含量的单位，mg/kg 表示毫克每千克。
        • phosphorus: 磷含量信息对象。
          • value: 磷含量的数值。
          • unit: 磷含量的单位，mg/kg。
        • potassium: 钾含量信息对象。
          • value: 钾含量的数值。
          • unit: 钾含量的单位，mg/kg。
      • soil_electrical_conductivity: 土壤电导率信息对象。
        • value: 土壤电导率的数值。
        • unit: 电导率的单位，dS/m 表示分西门子每米。
  • device: 监测设备的详细信息对象，字段包括：
    • id: 设备的唯一标识符。
    • type: 设备类型。
    • location: 设备位置信息对象，包括：
      • name: 位置名称。
      • coordinates: 坐标信息对象，包括：
        • latitude: 纬度。
        • longitude: 经度。
      • depth: 监测深度。
    • status: 设备状态，active 表示设备运行正常。
    • last_calibration: 设备最后校准的时间。
  • time_range: 字符串，表示数据覆盖的时间范围，格式为 "YYYY-MM-DD HH:MM:SS to YYYY-MM-DD HH:MM:SS"。
  • code: 响应状态码，值为200表示成功。
  • message: 响应消息，描述响应结果，这里是“success”表示成功。
  • timestamp: 响应生成的时间戳，格式为“年-月-日 时:分:秒”。
  • data: 包含实际数据的对象。
    • historical_weather: 包含历史气象数据的数组，每个元素代表一个时间点的气象数据。
      • timestamp: 记录时间点，格式为“年-月-日 时:分:秒”。
      • temperature: 温度信息对象。
        • value: 温度的当前值，单位为摄氏度（°C）。
        • unit: 温度的单位，这里是摄氏度（°C）。
      • humidity: 相对湿度信息对象。
        • value: 相对湿度的当前值，单位为%RH。
        • unit: 相对湿度的单位，这里是%RH。
      • light: 光照强度信息对象。
        • value: 光照强度的当前值，单位为lux。
        • unit: 光照强度的单位，这里是lux。
      • wind: 风速和风向信息对象。
        • speed: 风速信息对象。
          • value: 风速的当前值，单位为米每秒（m/s）。
          • unit: 风速的单位，这里是米每秒（m/s）。
        • direction: 风向信息对象。
          • value: 风向的角度值，单位为度（degrees）。
          • unit: 风向的单位，这里是度（degrees）。
          • description: 风向的文字描述，例如“East”表示东风。
      • rainfall: 降雨量信息对象。
        • value: 降雨量的当前值，单位为毫米（mm）。
        • unit: 降雨量的单位，这里是毫米（mm）。
        • duration: 降雨量的测量时长，例如“last 24 hours”表示过去24小时。
    • device: 包含气象监测设备信息的对象。
      • id: 设备的唯一标识符，例如“SENSOR-2025-07-03-001”。
      • type: 设备类型，这里是“气象综合监测仪”。
      • location: 设备位置信息对象。
        • name: 位置名称，例如“户外监测点A”。
        • coordinates: 坐标信息对象。
          • latitude: 纬度坐标。
          • longitude: 经度坐标。
        • altitude: 海拔高度，单位为米。
      • status: 设备状态，例如“active”表示设备处于活动状态。
      • last_calibration: 设备最后校准的时间，格式为“年-月-日”。
    • time_range: 表示数据覆盖的时间范围，格式为“起始时间 to 结束时间”。
### （2）土壤数据采集接口 #### 获取**实时土壤数据** + **请求方式**：GET + **请求方法**：Server-Sent Events (SSE) + **接口路径**：/ground/realtime/plantationId? + **请求参数**：无额外参数，使用公共请求参数即可。 + **请求示例** 
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data:{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "soil_moisture": {
      "value": 28.7,
      "unit": "%",
      "range": "0% to 100%"
    },
    "soil_temperature": {
      "value": 22.4,
      "unit": "°C",
      "range": "-20°C to 60°C"
    },
    "soil_ph": {
      "value": 6.8,
      "unit": "pH",
      "range": "0 to 14 pH"
    },
    "soil_nutrients": {
      "nitrogen": {
        "value": 120,
        "unit": "mg/kg",
        "range": "0 to 500 mg/kg"
      },
      "phosphorus": {
        "value": 45,
        "unit": "mg/kg",
        "range": "0 to 300 mg/kg"
      },
      "potassium": {
        "value": 180,
        "unit": "mg/kg",
        "range": "0 to 400 mg/kg"
      }
    },
    "soil_electrical_conductivity": {
      "value": 0.25,
      "unit": "dS/m",
      "range": "0 to 10 dS/m"
    }
  },
  "device": {
    "id": "SOIL_SENSOR_2025_07_03_001",
    "type": "土壤综合监测仪",
    "location": {
      "name": "试验田A-4",
      "coordinates": {
        "latitude": 31.2304,
        "longitude": 121.4737
      },
      "depth": 15
    },
    "status": "active",
    "last_calibration": "2025-06-20"
  },
  "metadata": {
    "accuracy": {
      "soil_moisture": "±2%",
      "soil_temperature": "±0.3°C",
      "soil_ph": "±0.1 pH",
      "soil_nutrients": "±5%",
      "soil_electrical_conductivity": "±0.02 dS/m"
    },
    "update_interval": "10 minutes",
    "data_quality": "high",
    "environment": "soil"
  }
}
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示请求成功。
  • message: 响应消息，描述请求的结果，"success" 表示成功处理了请求。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • historical_soil_data: 一个数组，包含多个时间点的历史土壤数据记录。
    • 每个对象代表特定时间点的土壤数据，字段包括：
      • timestamp: 数据记录的时间点，格式为 "YYYY-MM-DD HH:MM:SS"。
      • soil_moisture: 土壤湿度信息对象。
        • value: 土壤湿度的数值。
        • unit: 土壤湿度的单位，% 表示百分比。
      • soil_temperature: 土壤温度信息对象。
        • value: 土壤温度的数值。
        • unit: 土壤温度的单位，°C 表示摄氏度。
      • soil_ph: 土壤酸碱度（pH值）信息对象。
        • value: 土壤的 pH 值。
        • unit: pH 值的单位，pH。
      • soil_nutrients: 土壤养分信息对象，包括：
        • nitrogen: 氮含量信息对象。
          • value: 氮含量的数值。
          • unit: 氮含量的单位，mg/kg 表示毫克每千克。
        • phosphorus: 磷含量信息对象。
          • value: 磷含量的数值。
          • unit: 磷含量的单位，mg/kg。
        • potassium: 钾含量信息对象。
          • value: 钾含量的数值。
          • unit: 钾含量的单位，mg/kg。
      • soil_electrical_conductivity: 土壤电导率信息对象。
        • value: 土壤电导率的数值。
        • unit: 电导率的单位，dS/m 表示分西门子每米。
  • device: 监测设备的详细信息对象，字段包括：
    • id: 设备的唯一标识符。
    • type: 设备类型。
    • location: 设备位置信息对象，包括：
      • name: 位置名称。
      • coordinates: 坐标信息对象，包括：
        • latitude: 纬度。
        • longitude: 经度。
      • depth: 监测深度。
    • status: 设备状态，active 表示设备运行正常。
    • last_calibration: 设备最后校准的时间。
  • time_range: 字符串，表示数据覆盖的时间范围，格式为 "YYYY-MM-DD HH:MM:SS to YYYY-MM-DD HH:MM:SS"。
  • code：状态码，值为200表示成功。
  • message：状态消息，此处为"success"表示操作成功。
  • timestamp：服务器生成响应的时间戳，格式为"年-月-日 时:分:秒"。
  • data：包含实际数据的对象。
    • soil_moisture：土壤湿度信息。
      • value：当前土壤湿度值，单位为百分比（%）。
      • unit：土壤湿度的单位，此处为百分比（%）。
      • range：土壤湿度的测量范围，从0%到100%。
    • soil_temperature：土壤温度信息。
      • value：当前土壤温度值，单位为摄氏度（°C）。
      • unit：土壤温度的单位，此处为摄氏度（°C）。
      • range：土壤温度的测量范围，从-20°C到60°C。
    • soil_ph：土壤pH值信息。
      • value：当前土壤pH值。
      • unit：土壤pH值的单位，此处为pH。
      • range：土壤pH值的测量范围，从0到14 pH。
    • soil_nutrients：土壤养分信息。
      • nitrogen：氮含量。
        • value：当前氮含量值，单位为mg/kg。
        • unit：氮含量的单位，此处为mg/kg。
        • range：氮含量的测量范围，从0到500 mg/kg。
      • phosphorus：磷含量。
        • value：当前磷含量值，单位为mg/kg。
        • unit：磷含量的单位，此处为mg/kg。
        • range：磷含量的测量范围，从0到300 mg/kg。
      • potassium：钾含量。
        • value：当前钾含量值，单位为mg/kg。
        • unit：钾含量的单位，此处为mg/kg。
        • range：钾含量的测量范围，从0到400 mg/kg。
    • soil_electrical_conductivity：土壤电导率信息。
      • value：当前土壤电导率值，单位为dS/m。
      • unit：土壤电导率的单位，此处为dS/m。
      • range：土壤电导率的测量范围，从0到10 dS/m。
  • device：包含土壤监测设备信息的对象。
    • id：设备唯一标识符。
    • type：设备类型描述。
    • location：设备位置信息。
      • name：位置名称。
      • coordinates：坐标信息。
        • latitude：纬度。
        • longitude：经度。
      • depth：土壤监测的深度。
    • status：设备状态，如"active"表示设备处于活动状态。
    • last_calibration：设备最后校准日期。
  • metadata：包含数据的元信息。
    • accuracy：各测量值的精度。
      • soil_moisture：土壤湿度测量精度。
      • soil_temperature：土壤温度测量精度。
      • soil_ph：土壤pH值测量精度。
      • soil_nutrients：土壤养分测量精度。
      • soil_electrical_conductivity：土壤电导率测量精度。
    • update_interval：数据更新的时间间隔。
    • data_quality：数据质量的描述。
    • environment：数据采集的环境类型。
#### **获取历史气象数据** + **请求方式**：GET + **请求方法**：传统http请求 + **接口路径**：/ground/history/{plantationId} + **请求参数**：无额外参数，使用公共请求参数即可。 + **请求响应** 
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "historical_soil_data": [
      {
        "timestamp": "2025-07-03 12:00:00",
        "soil_moisture": {
          "value": 27.5,
          "unit": "%"
        },
        "soil_temperature": {
          "value": 22.2,
          "unit": "°C"
        },
        "soil_ph": {
          "value": 6.9,
          "unit": "pH"
        },
        "soil_nutrients": {
          "nitrogen": {
            "value": 118,
            "unit": "mg/kg"
          },
          "phosphorus": {
            "value": 44,
            "unit": "mg/kg"
          },
          "potassium": {
            "value": 178,
            "unit": "mg/kg"
          }
        },
        "soil_electrical_conductivity": {
          "value": 0.24,
          "unit": "dS/m"
        }
      },
      {
        "timestamp": "2025-07-03 10:00:00",
        "soil_moisture": {
          "value": 26.3,
          "unit": "%"
        },
        "soil_temperature": {
          "value": 21.9,
          "unit": "°C"
        },
        "soil_ph": {
          "value": 6.8,
          "unit": "pH"
        },
        "soil_nutrients": {
          "nitrogen": {
            "value": 115,
            "unit": "mg/kg"
          },
          "phosphorus": {
            "value": 43,
            "unit": "mg/kg"
          },
          "potassium": {
            "value": 175,
            "unit": "mg/kg"
          }
        },
        "soil_electrical_conductivity": {
          "value": 0.23,
          "unit": "dS/m"
        }
      },
      {
        "timestamp": "2025-07-03 08:00:00",
        "soil_moisture": {
          "value": 25.0,
          "unit": "%"
        },
        "soil_temperature": {
          "value": 21.5,
          "unit": "°C"
        },
        "soil_ph": {
          "value": 6.7,
          "unit": "pH"
        },
        "soil_nutrients": {
          "nitrogen": {
            "value": 112,
            "unit": "mg/kg"
          },
          "phosphorus": {
            "value": 42,
            "unit": "mg/kg"
          },
          "potassium": {
            "value": 172,
            "unit": "mg/kg"
          }
        },
        "soil_electrical_conductivity": {
          "value": 0.22,
          "unit": "dS/m"
        }
      }
    ],
    "device": {
      "id": "SOIL_SENSOR_2025_07_03_001",
      "type": "土壤综合监测仪",
      "location": {
        "name": "试验田A-4",
        "coordinates": {
          "latitude": 31.2304,
          "longitude": 121.4737
        },
        "depth": 15
      },
      "status": "active",
      "last_calibration": "2025-06-20"
    },
    "time_range": "2025-07-03 08:00:00 to 2025-07-03 14:30:00"
  }
}
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示请求成功。
  • message: 响应消息，描述请求的结果，"success" 表示成功处理了请求。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • historical_soil_data: 一个数组，包含多个时间点的历史土壤数据记录。
    • 每个对象代表特定时间点的土壤数据，字段包括：
      • timestamp: 数据记录的时间点，格式为 "YYYY-MM-DD HH:MM:SS"。
      • soil_moisture: 土壤湿度信息对象。
        • value: 土壤湿度的数值。
        • unit: 土壤湿度的单位，% 表示百分比。
      • soil_temperature: 土壤温度信息对象。
        • value: 土壤温度的数值。
        • unit: 土壤温度的单位，°C 表示摄氏度。
      • soil_ph: 土壤酸碱度（pH值）信息对象。
        • value: 土壤的 pH 值。
        • unit: pH 值的单位，pH。
      • soil_nutrients: 土壤养分信息对象，包括：
        • nitrogen: 氮含量信息对象。
          • value: 氮含量的数值。
          • unit: 氮含量的单位，mg/kg 表示毫克每千克。
        • phosphorus: 磷含量信息对象。
          • value: 磷含量的数值。
          • unit: 磷含量的单位，mg/kg。
        • potassium: 钾含量信息对象。
          • value: 钾含量的数值。
          • unit: 钾含量的单位，mg/kg。
      • soil_electrical_conductivity: 土壤电导率信息对象。
        • value: 土壤电导率的数值。
        • unit: 电导率的单位，dS/m 表示分西门子每米。
  • device: 监测设备的详细信息对象，字段包括：
    • id: 设备的唯一标识符。
    • type: 设备类型。
    • location: 设备位置信息对象，包括：
      • name: 位置名称。
      • coordinates: 坐标信息对象，包括：
        • latitude: 纬度。
        • longitude: 经度。
      • depth: 监测深度。
    • status: 设备状态，active 表示设备运行正常。
    • last_calibration: 设备最后校准的时间。
  • time_range: 字符串，表示数据覆盖的时间范围，格式为 "YYYY-MM-DD HH:MM:SS to YYYY-MM-DD HH:MM:SS"。
### （3）无人机画面传输接口 #### 获取**实时画面（指定单无人机、图像）** + **请求方式**：GET + **请求方法**：Server-Sent Events (SSE) + **接口路径**：/drone-images/teaplanation/picture/single/{droneId} + **请求参数**：无额外参数，使用公共请求参数即可。 + **请求示例** 
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantationId": "TP-2025-07-03-001",
    "drone_images": [
      {
        "type": "visible_light",
        "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_visible_image_20250703143000.jpg",
        "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_visible_thumbnail_20250703143000.jpg",
        "capture_time": "2025-07-03 14:30:00",
        "resolution": "1920x1080",
        "format": "JPEG"
      },
      {
        "type": "multispectral",
        "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_multispectral_image_20250703143000.tif",
        "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_multispectral_thumbnail_20250703143000.jpg",
        "capture_time": "2025-07-03 14:30:00",
        "resolution": "1280x720",
        "format": "TIFF",
        "spectral_bands": [
          "red",
          "green",
          "blue",
          "near_infrared"
        ]
      },
      {
        "type": "hyperspectral",
        "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_hyperspectral_image_20250703143000.hdr",
        "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001_hyperspectral_thumbnail_20250703143000.jpg",
        "capture_time": "2025-07-03 14:30:00",
        "resolution": "640x480",
        "format": "ENVI HDR",
        "spectral_bands_range": "400-1000 nm",
        "spectral_resolution": "2.5 nm"
      }
    ],
    "drone_info": {
      "drone_id": "DRN-2025-07-03-005",
      "location": {
        "latitude": 31.2304,
        "longitude": 121.4737,
        "altitude": 85.2,
        "accuracy": {
          "horizontal": "±3 meters",
          "vertical": "±5 meters"
        }
      },
      "status": {
        "battery_level": 72,
        "flight_mode": "manual",
        "connection_status": "connected",
        "health": "good"
      },
      "mission": {
        "id": "M-2025-07-03-TEA-MONITORING-001",
        "type": "tea_plantation_monitoring",
        "start_time": "2025-07-03 13:00:00",
        "planned_end_time": "2025-07-03 16:00:00",
        "current_waypoint": 12,
        "total_waypoints": 25
      }
    },
    "metadata": {
      "plantation": {
        "name": "西湖龙井茶园A",
        "area": "45.2 hectares",
        "elevation": "120-250 meters"
      },
      "image_capture_interval": "2 seconds",
      "data_transfer_rate": "12 Mbps",
      "signal_strength": "82%",
      "environmental_conditions": {
        "weather": "clear",
        "wind_speed": 4.1,
        "wind_direction": 120,
        "temperature": 25.5
      },
      "image_processing": {
        "visible_light": "raw",
        "multispectral": "radiometric_calibration_applied",
        "hyperspectral": "radiometric_calibration_and_atmospheric_correction_applied"
      }
    }
  }
}
  • 响应字段说明

字段解释

  • code: 状态码，200表示接口调用成功。
  • message: 状态消息，"success"表示成功获取数据。
  • timestamp: 表示数据生成的时间戳，格式为"YYYY-MM-DD HH:MM:SS"。
  • data: 包含实际业务数据的对象，字段包括：
    • plantationId: 茶园的唯一标识符。
    • drone_images: 无人机拍摄的图像列表，每个对象包含：
      • type: 图像类型（如可见光、多光谱、高光谱）。
      • url: 图像文件的完整URL地址。
      • thumbnail_url: 图像缩略图的完整URL地址。
      • capture_time: 图像拍摄的时间。
      • resolution: 图像分辨率。
      • format: 图像格式。
      • spectral_bands: 对于多光谱和高光谱图像，列出包含的光谱带。
      • spectral_bands_range: 高光谱图像的光谱范围。
      • spectral_resolution: 高光谱图像的光谱分辨率。
    • drone_info: 无人机信息，包含：
      • drone_id: 无人机的唯一标识符。
      • location: 无人机的位置信息，包括：
        • latitude: 纬度。
        • longitude: 经度。
        • altitude: 高度。
        • accuracy: 位置精度，包括水平和垂直精度。
      • status: 无人机的当前状态信息，包括：
        • battery_level: 电池电量百分比。
        • flight_mode: 飞行模式（手动或自动）。
        • connection_status: 连接状态（已连接或断开）。
        • health: 无人机的健康状况（良好）。
      • mission: 无人机当前执行的任务信息，包括：
        • id: 任务ID。
        • type: 任务类型。
        • start_time: 任务开始时间。
        • planned_end_time: 计划结束时间。
        • current_waypoint: 当前航点。
        • total_waypoints: 总航点数。
    • metadata: 与数据相关的元数据，包含：
      • plantation: 茶园信息，包括：
        • name: 茶园名称。
        • area: 茶园面积。
        • elevation: 海拔高度范围。
      • image_capture_interval: 图像捕获的时间间隔。
      • data_transfer_rate: 数据传输速率。
      • signal_strength: 信号强度。
      • environmental_conditions: 当前环境条件，包括：
        • weather: 天气状况。
        • wind_speed: 风速。
        • wind_direction: 风向。
        • temperature: 温度。
      • image_processing: 图像处理信息，指明是否进行了辐射校准或大气校正。
#### 获取**实时画面（**指定茶园所有无人机**、图像）** + **请求方式**：GET + **请求方法**：Server-Sent Events (SSE) + **接口路径**：/drone-images/teaplanation/picture/mutil/{plantationId} + **请求参数**：无额外参数，使用公共请求参数即可。 + **请求示例** 
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantationId": "TP-2025-07-03-001",
    "drones": [
      {
        "drone_id": "DRN-2025-07-03-005",
        "images": [
          {
            "type": "visible_light",
            "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-005_visible_image_20250703143000.jpg",
            "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-005_visible_thumbnail_20250703143000.jpg",
            "capture_time": "2025-07-03 14:30:00",
            "resolution": "1920x1080",
            "format": "JPEG"
          },
          {
            "type": "multispectral",
            "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-005_multispectral_image_20250703143000.tif",
            "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-005_multispectral_thumbnail_20250703143000.jpg",
            "capture_time": "2025-07-03 14:30:00",
            "resolution": "1280x720",
            "format": "TIFF",
            "spectral_bands": [
              "red",
              "green",
              "blue",
              "near_infrared"
            ]
          }
        ],
        "location": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2,
          "accuracy": {
            "horizontal": "±3 meters",
            "vertical": "±5 meters"
          }
        },
        "status": {
          "battery_level": 72,
          "flight_mode": "manual",
          "connection_status": "connected",
          "health": "good"
        }
      },
      {
        "drone_id": "DRN-2025-07-03-006",
        "images": [
          {
            "type": "visible_light",
            "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-006_visible_image_20250703143000.jpg",
            "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-006_visible_thumbnail_20250703143000.jpg",
            "capture_time": "2025-07-03 14:30:00",
            "resolution": "1920x1080",
            "format": "JPEG"
          },
          {
            "type": "hyperspectral",
            "url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-006_hyperspectral_image_20250703143000.hdr",
            "thumbnail_url": "https://drone-storage.example.com/2025/07/03/TP-2025-07-03-001/DRN-2025-07-03-006_hyperspectral_thumbnail_20250703143000.jpg",
            "capture_time": "2025-07-03 14:30:00",
            "resolution": "640x480",
            "format": "ENVI HDR",
            "spectral_bands_range": "400-1000 nm",
            "spectral_resolution": "2.5 nm"
          }
        ],
        "location": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 90.5,
          "accuracy": {
            "horizontal": "±3 meters",
            "vertical": "±5 meters"
          }
        },
        "status": {
          "battery_level": 68,
          "flight_mode": "automatic",
          "connection_status": "connected",
          "health": "good"
        }
      }
    ],
    "metadata": {
      "plantation": {
        "name": "西湖龙井茶园A",
        "area": "45.2 hectares",
        "elevation": "120-250 meters"
      },
      "data_transfer_rate": "12 Mbps",
      "signal_strength": "85%",
      "environmental_conditions": {
        "weather": "clear",
        "wind_speed": 4.1,
        "wind_direction": 120,
        "temperature": 25.5
      }
    }
  }
}
  • 响应字段说明

字段解释

  • code：响应状态码，200 表示成功。
  • message：响应消息，"success" 表示请求成功。
  • timestamp：响应生成的时间戳，格式为 ISO 8601。
  • data：包含具体业务数据的对象。
    • plantationId：茶园的唯一标识符。
    • drones：无人机信息数组，每个元素包含以下信息：
      • drone_id：无人机的唯一标识符。
      • images：无人机拍摄的不同类型图像列表，每个图像包含以下字段：
        • type：图像类型，如 "visible_light" 表示可见光图像，"multispectral" 表示多光谱图像。
        • url：图像文件的完整 URL 路径。
        • thumbnail_url：图像缩略图的完整 URL 路径。
        • capture_time：图像捕获时间，格式为 ISO 8601。
        • resolution：图像分辨率，如 "1920x1080"。
        • format：图像格式，如 "JPEG" 或 "TIFF"。
        • spectral_bands：图像中包含的光谱带，仅适用于多光谱图像。
      • location：无人机的地理位置，包含：
        • latitude：纬度。
        • longitude：经度。
        • altitude：海拔高度。
        • accuracy：位置精度，包括水平和垂直精度。
      • status：无人机当前状态，包含：
        • battery_level：电池电量百分比。
        • flight_mode：飞行模式，手动或自动。
        • connection_status：连接状态，如 "connected"。
        • health：无人机的健康状况，如 "good"。
    • metadata：与数据相关的元信息，包括：
      • plantation：茶园信息，包含：
        • name：茶园名称。
        • area：茶园面积。
        • elevation：海拔高度范围。
      • data_transfer_rate：数据传输速率。
      • signal_strength：信号强度。
      • environmental_conditions：环境条件，包含：
        • weather：天气状况。
        • wind_speed：风速。
        • wind_direction：风向。
        • temperature：温度。
#### 获取**实时画面（**指定无人机**、实时视频流）** 参考：[https://zhuanlan.zhihu.com/p/334809](https://zhuanlan.zhihu.com/p/334809573)

获取无人机状态信息（可指定茶园）

无人机调度

（1）获取无人机编队实时位置

  • 请求方式：GET
  • 请求方法：Server-Sent Events (SSE)
  • 接口路径：/drone-formation/realtime-location/{plantationId}
  • 请求参数：无额外参数，使用公共请求参数即可。
  • 请求示例
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantationId": "TP-2025-07-03-001",
    "formation_id": "F-2025-07-03-001",
    "drones": [
      {
        "drone_id": "DRN-2025-07-03-005",
        "location": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2,
          "timestamp": "2025-07-03 14:30:00"
        },
        "status": {
          "battery_level": 72,
          "flight_mode": "manual",
          "connection_status": "connected",
          "health": "good"
        }
      },
      {
        "drone_id": "DRN-2025-07-03-006",
        "location": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 90.5,
          "timestamp": "2025-07-03 14:30:00"
        },
        "status": {
          "battery_level": 68,
          "flight_mode": "automatic",
          "connection_status": "connected",
          "health": "good"
        }
      }
    ],
    "metadata": {
      "data_transfer_rate": "12 Mbps",
      "signal_strength": "85%",
      "environmental_conditions": {
        "weather": "clear",
        "wind_speed": 4.1,
        "wind_direction": 120,
        "temperature": 25.5
      }
    }
  }
}
  • 响应字段说明

字段解释

  • code：状态码，200 表示请求成功。
  • message：状态消息，"success" 表示成功处理了请求。
  • timestamp：生成响应的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • data：包含实际业务数据的对象。
    • plantationId：茶园的唯一标识符。
    • formation_id：无人机编队的唯一标识符。
    • drones：一个数组，包含编队中各个无人机的信息。
      • drone_id：无人机的唯一标识符。
      • location：无人机的地理位置信息，包括：
        • latitude：纬度。
        • longitude：经度。
        • altitude：海拔高度。
        • timestamp：记录位置的时间戳。
      • status：无人机的状态信息，包括：
        • battery_level：电池电量百分比。
        • flight_mode：飞行模式，如手动（manual）或自动（automatic）。
        • connection_status：连接状态，如已连接（connected）。
        • health：无人机的健康状况，如良好（good）。
    • metadata：元数据信息，包括：
      • data_transfer_rate：数据传输速率。
      • signal_strength：信号强度。
      • environmental_conditions：环境条件，包括：
        • weather：天气状况，如晴朗（clear）。
        • wind_speed：风速。
        • wind_direction：风向。
        • temperature：温度。
### （2）无人机编队路线规划 + **请求方式**：POST + **请求方法**：传统http请求 + **接口路径**：/drone-formation/route-planning + **请求参数**： 
{
    "plantationId": "F-2025-07-03-001",
    "route": [
      {
        "waypoint_id": "W1",
        "coordinates": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2
        },
        "estimated_arrival": "2025-07-03 14:35:00"
      },
      {
        "waypoint_id": "W2",
        "coordinates": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 85.2
        },
        "estimated_arrival": "2025-07-03 14:40:00"
      }
    ],
    "droneFormationPositions": [
      {
        "drone_id": "DRN-2025-07-03-005",
        "relative_position": {
          "x": 0,
          "y": 0,
          "z": 0
        }
      },
      {
        "drone_id": "DRN-2025-07-03-006",
        "relative_position": {
          "x": 10,
          "y": 5,
          "z": 0
        }
      }
    ]
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "formationId": "F-2025-07-03-001",
    "route": [
      {
        "waypoint_id": "W1",
        "coordinates": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2
        },
        "estimated_arrival": "2025-07-03 14:35:00"
      },
      {
        "waypoint_id": "W2",
        "coordinates": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 85.2
        },
        "estimated_arrival": "2025-07-03 14:40:00"
      }
    ],
    "status": "planned",
    "execution_start_time": "2025-07-03 14:30:00",
    "planned_end_time": "2025-07-03 14:40:00"
  }
}
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示请求成功。
  • message: 响应消息，"success" 表示请求成功处理。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • formationId: 无人机编队的唯一标识符。
  • route: 无人机编队的飞行路线，是一个包含多个航点的对象数组。
    • waypoint_id: 当前航点的唯一标识符。
    • coordinates: 航点的坐标信息，包括：
      • latitude: 纬度值。
      • longitude: 经度值。
      • altitude: 高度值。
    • estimated_arrival: 预计到达当前航点的时间，格式为 "YYYY-MM-DD HH:MM:SS"。
  • status: 编队飞行任务的当前状态，"planned" 表示计划中。
  • execution_start_time: 编队飞行任务计划开始执行的时间，格式为 "YYYY-MM-DD HH:MM:SS"。
### （3）无人机编队实时位置与轨迹同步大屏展示 + **请求方式**：GET + **请求方法**：Server-Sent Events (SSE) + **接口路径**：/drone-formation/realtime-sync/{plantationId} + **请求参数**：无额外参数，使用公共请求参数即可。 + **请求示例** 
GET /weather/realtime/TP-2025-07-03-001 HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer <ACCESS_TOKEN>
  • 请求响应
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantationId": "TP-2025-07-03-001",
    "formation_id": "F-2025-07-03-001",
    "drones": [
      {
        "drone_id": "DRN-2025-07-03-005",
        "location": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2,
          "timestamp": "2025-07-03 14:30:00"
        },
        "trajectory": {
          "current_position": {
            "latitude": 31.2304,
            "longitude": 121.4737,
            "altitude": 85.2,
            "timestamp": "2025-07-03 14:30:00"
          },
          "previous_positions": [
            {
              "latitude": 31.2304,
              "longitude": 121.4737,
              "altitude": 85.2,
              "timestamp": "2025-07-03 14:29:30"
            },
            {
              "latitude": 31.2304,
              "longitude": 121.4737,
              "altitude": 85.2,
              "timestamp": "2025-07-03 14:29:00"
            }
          ],
          "next_waypoint": {
            "latitude": 31.2305,
            "longitude": 121.4738,
            "altitude": 85.2,
            "estimated_arrival": "2025-07-03 14:31:00"
          }
        },
        "status": {
          "battery_level": 72,
          "flight_mode": "manual",
          "connection_status": "connected",
          "health": "good"
        }
      },
      {
        "drone_id": "DRN-2025-07-03-006",
        "location": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 90.5,
          "timestamp": "2025-07-03 14:30:00"
        },
        "trajectory": {
          "current_position": {
            "latitude": 31.2305,
            "longitude": 121.4738,
            "altitude": 90.5,
            "timestamp": "2025-07-03 14:30:00"
          },
          "previous_positions": [
            {
              "latitude": 31.2305,
              "longitude": 121.4738,
              "altitude": 90.5,
              "timestamp": "2025-07-03 14:29:30"
            },
            {
              "latitude": 31.2305,
              "longitude": 121.4738,
              "altitude": 90.5,
              "timestamp": "2025-07-03 14:29:00"
            }
          ],
          "next_waypoint": {
            "latitude": 31.2306,
            "longitude": 121.4739,
            "altitude": 90.5,
            "estimated_arrival": "2025-07-03 14:31:00"
          }
        },
        "status": {
          "battery_level": 68,
          "flight_mode": "automatic",
          "connection_status": "connected",
          "health": "good"
        }
      }
    ],
    "metadata": {
      "plantation": {
        "name": "西湖龙井茶园A",
        "area": "45.2 hectares",
        "elevation": "120-250 meters"
      },
      "data_transfer_rate": "12 Mbps",
      "signal_strength": "85%",
      "environmental_conditions": {
        "weather": "clear",
        "wind_speed": 4.1,
        "wind_direction": 120,
        "temperature": 25.5
      }
    }
  }
}
  • 响应字段说明

字段解释

  • code: 响应状态码，200 表示接口调用成功。
  • message: 状态消息，"success" 表示成功获取数据。
  • timestamp: 响应生成的时间戳，格式为 "YYYY-MM-DD HH:MM:SS"。
  • data: 包含实际业务数据的对象，字段包括：
    • plantationId: 茶园的唯一标识符。
    • formation_id: 无人机编队形的唯一标识符。
    • drones: 无人机列表，每个无人机包含以下信息：
      • drone_id: 无人机的唯一标识符。
      • location: 无人机的当前位置信息，包括：
        • latitude: 纬度。
        • longitude: 经度。
        • altitude: 高度。
        • timestamp: 位置记录的时间戳。
      • trajectory: 无人机的飞行轨迹信息，包括：
        • current_position: 当前位置信息，与 location 类似。
        • previous_positions: 之前的飞行位置列表。
        • next_waypoint: 下一个航点信息，包括：
          • latitude: 纬度。
          • longitude: 经度。
          • altitude: 高度。
          • estimated_arrival: 预计到达时间。
      • status: 无人机的当前状态信息，包括：
        • battery_level: 电池电量百分比。
        • flight_mode: 飞行模式（手动或自动）。
        • connection_status: 连接状态（已连接或断开）。
        • health: 无人机的健康状况（良好）。
    • metadata: 与数据相关的元信息，包含：
      • plantation: 茶园信息，包括：
        • name: 茶园名称。
        • area: 茶园面积。
        • elevation: 海拔高度范围。
      • data_transfer_rate: 数据传输速率。
      • signal_strength: 信号强度。
      • environmental_conditions: 当前环境条件，包括：
        • weather: 天气状况。
        • wind_speed: 风速。
        • wind_direction: 风向。
        • temperature: 温度。
### （4）无人机状态信息（可指定茶园，无人机列表、详情与状态） + **请求方式**：GET + **请求方法**：传统http请求 + **接口路径**：/drone/status{plantationId} + **使用说明**： - 如果指定 `plantationId`，则返回该茶园内所有无人机的状态信息。 - 如果不指定 `plantationId`，则返回所有无人机的状态信息。 + **请求响应** 
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "drones": [
      {
        "drone_id": "DRN-2025-07-03-005",
        "plantation_id": "TP-2025-07-03-001",
        "plantation_name": "西湖龙井茶园A",
        "location": {
          "latitude": 31.2304,
          "longitude": 121.4737,
          "altitude": 85.2,
          "timestamp": "2025-07-03 14:30:00",
          "accuracy": {
            "horizontal": "±3 meters",
            "vertical": "±5 meters"
          }
        },
        "status": {
          "battery_level": 72,
          "flight_mode": "manual",
          "connection_status": "connected",
          "health": "good"
        },
        "mission": {
          "id": "M-2025-07-03-TEA-MONITORING-001",
          "type": "tea_plantation_monitoring",
          "start_time": "2025-07-03 13:00:00",
          "planned_end_time": "2025-07-03 16:00:00",
          "current_waypoint": 12,
          "total_waypoints": 25
        }
      },
      {
        "drone_id": "DRN-2025-07-03-006",
        "plantation_id": "TP-2025-07-03-001",
        "plantation_name": "西湖龙井茶园A",
        "location": {
          "latitude": 31.2305,
          "longitude": 121.4738,
          "altitude": 90.5,
          "timestamp": "2025-07-03 14:30:00",
          "accuracy": {
            "horizontal": "±3 meters",
            "vertical": "±5 meters"
          }
        },
        "status": {
          "battery_level": 68,
          "flight_mode": "automatic",
          "connection_status": "connected",
          "health": "good"
        },
        "mission": {
          "id": "M-2025-07-03-TEA-MONITORING-002",
          "type": "tea_plantation_monitoring",
          "start_time": "2025-07-03 13:00:00",
          "planned_end_time": "2025-07-03 16:00:00",
          "current_waypoint": 10,
          "total_waypoints": 25
        }
      }
    ]
  }
}
  • 响应字段说明

字段解释

  • code：状态码，200 表示成功。
  • message：状态消息，描述响应结果。
  • timestamp：响应生成的时间戳。
  • data.drones：无人机状态信息列表。
    • drone_id：无人机的唯一标识符。
    • plantation_id：无人机所在的茶园的唯一标识符。
    • plantation_name：茶园的名称。
    • location：无人机的当前位置信息。
      • latitude：纬度。
      • longitude：经度。
      • altitude：海拔高度。
      • timestamp：位置信息的时间戳。
      • accuracy：位置精度信息。
    • status：无人机的状态信息。
      • battery_level：电池电量百分比。
      • flight_mode：飞行模式（手动、自动等）。
      • connection_status：连接状态（已连接、断开等）。
      • health：健康状态（良好、警告、故障等）。
    • mission：无人机当前执行的任务信息。
      • id：任务的唯一标识符。
      • type：任务类型。
      • start_time：任务开始时间。
      • planned_end_time：计划结束时间。
      • current_waypoint：当前航点。
      • total_waypoints：总航点数。
## 知识库 AI Agent ### （1）知识库搭建（用户上传资料） #### 单文档上传 + **请求方式**：POST + **请求方法**：传统http请求 + **接口路径**：/knowledge-base/upload/single + **请求参数**： 
"plantationId": "TP-2025-07-03-001",
"description": "茶园管理指南文档",
"file": 。。。。
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "knowledgeBaseId": "KB-2025-07-03-001",
    "status": "processing",
    "file": {
      "fileId": "F-2025-07-03-001",
      "name": "teaplanation_guide.pdf",
      "uploadTime": "2025-07-03 14:30:00",
      "processingStatus": "queued"
    }
  }
}

多文档批量上传

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/knowledge-base/upload/multi
  • 请求参数：
"plantationId": "TP-2025-07-03-001",
"description": "茶园管理指南文档",
"files": 。。。。
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "knowledgeBaseId": "KB-2025-07-03-002",
    "status": "processing",
    "files": [
      {
        "fileId": "F-2025-07-03-002",
        "name": "teaplanation_guide.pdf",
        "uploadTime": "2025-07-03 14:30:00",
        "processingStatus": "queued"
      },
      {
        "fileId": "F-2025-07-03-003",
        "name": "tea_processing.pdf",
        "uploadTime": "2025-07-03 14:30:00",
        "processingStatus": "queued"
      },
      {
        "fileId": "F-2025-07-03-004",
        "name": "disease_management.pdf",
        "uploadTime": "2025-07-03 14:30:00",
        "processingStatus": "queued"
      }
    ]
  }
}

（2）知识库搭建（关键词网络爬虫）

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/knowledge-base/crawl
  • 请求参数：
{
    "plantationId": "TP-2025-07-03-001",
    "keywords": ["茶树种植", "茶叶采摘", "茶园管理"],
    "sources": ["web", "scientific_papers"],
    "maxPages": 10
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "knowledgeBaseId": "KB-2025-07-03-002",
    "crawlJobId": "CJ-2025-07-03-001",
    "status": "started",
    "estimatedCompletion": "2025-07-03 15:00:00",
    "keywords": ["茶树种植", "茶叶采摘", "茶园管理"]
  }
}

（3）AI Agent（知识库 AI 问答【流式】）

（4）AI Agent（指定茶园数据监测分析报告）

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/ai-agent/monitoring-report
  • 请求参数：
{
    "plantationId": "TP-2025-07-03-001",
    "reportType": "detailed",
    "timeRange": {
      "startTime": "2025-07-01T00:00:00Z",
      "endTime": "2025-07-31T23:59:59Z"
    },
    "include": ["meteorological", "soil", "drone_images"]
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "reportId": "R-2025-07-03-001",
    "plantationId": "TP-2025-07-03-001",
    "timeRange": {
      "startTime": "2025-07-01T00:00:00Z",
      "endTime": "2025-07-31T23:59:59Z"
    },
    "status": "generated",
    "downloadUrl": "https://api.example.com/reports/R-2025-07-03-001.pdf"
  }
}

（5）AI Agent（指定茶园获取AI管理建议列表或详情）

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/ai-agent/suggestions
  • 请求参数：
{
    "plantationId": "TP-2025-07-03-001",
    "suggestionId":"324232345" // 指定suggestionId时为获取对应建议详情,
    "page": 1,
    "per_page": 20,
    "status": "unread",
    "type": "irrigation",
    "priority": "high",
    "start_date": "2025-07-01T00:00:00Z",
    "end_date": "2025-07-10T23:59:59Z",
    "sort": "created_at",
    "order": "desc"
}
  • 请求响应
{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "total": 123,
    "page": 1,
    "per_page": 20,
    "items": [
      {
        "suggestion_id": "sugg_12345",
        "title": "地块A土壤含水率低于15%，建议今日16:00-18:00开启滴灌系统",
        "content": "根据传感器数据显示，地块A当前土壤含水率为12.5%，低于作物生长适宜范围15%-25%。建议今日16:00-18:00开启滴灌系统，预计灌溉量50立方米。",
        "type": "irrigation",
        "priority": "high",
        "status": "unread",
        "plantation_id": "plant_67890",
        "plantation_name": "南山茶园A区",
        "sensor_data": {
          "sensor_id": "soil_123",
          "data_time": "2025-07-04T10:00:00Z",
          "soil_moisture": 12.5,
          "threshold": 15,
          "normal_range": [15, 25]
        },
        "execution_data": {
          "drone_task_id": null,
          "scheduled_time": null,
          "actual_time": null
        },
        "created_at": "2025-07-04T10:30:00Z",
        "updated_at": "2025-07-04T10:30:00Z",
        "is_new": true
      },
      {
        "suggestion_id": "sugg_12346",
        "title": "地块B土壤含水率低于15%，建议今日16:00-18:00开启滴灌系统",
        "content": "根据传感器数据显示，地块A当前土壤含水率为12.5%，低于作物生长适宜范围15%-25%。建议今日16:00-18:00开启滴灌系统，预计灌溉量50立方米。",
        "type": "irrigation",
        "priority": "high",
        "status": "unread",
        "plantation_id": "plant_67890",
        "plantation_name": "南山茶园A区",
        "sensor_data": {
          "sensor_id": "soil_123",
          "data_time": "2025-07-04T10:00:00Z",
          "soil_moisture": 12.5,
          "threshold": 15,
          "normal_range": [15, 25]
        },
        "execution_data": {
          "drone_task_id": null,
          "scheduled_time": null,
          "actual_time": null
        },
        "created_at": "2025-07-04T10:30:00Z",
        "updated_at": "2025-07-04T10:30:00Z",
        "is_new": true
      },
    ]
  }
}
{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "suggestion_id": "sugg_12345",
    "title": "地块A土壤含水率低于15%，建议今日16:00-18:00开启滴灌系统",
    "content": "根据传感器数据显示，地块A当前土壤含水率为12.5%，低于作物生长适宜范围15%-25%。建议今日16:00-18:00开启滴灌系统，预计灌溉量50立方米。",
    "type": "irrigation",
    "priority": "high",
    "status": "unread",
    "plantation_id": "plant_67890",
    "plantation_name": "南山茶园A区",
    "plot_id": "plot_123",
    "plot_name": "A区1号地块",
    "sensor_data": {
      "sensor_id": "soil_123",
      "data_time": "2025-07-04T10:00:00Z",
      "soil_moisture": 12.5,
      "threshold": 15,
      "normal_range": [15, 25],
      "trend_data": [
        {"time": "2025-07-01", "value": 18.2},
        {"time": "2025-07-02", "value": 16.5},
        {"time": "2025-07-03", "value": 14.3},
        {"time": "2025-07-04", "value": 12.5}
      ],
      "sensor_location": {
        "latitude": 28.5432,
        "longitude": 119.3210,
        "altitude": 85.5
      }
    },
    "recommendation": {
      "action": "开启滴灌系统",
      "time": "2025-07-04T16:00:00Z 至 2025-07-04T18:00:00Z",
      "duration": "2小时",
      "water_volume": "50立方米",
      "equipment": "滴灌系统A区",
      "operator": "系统自动建议"
    },
    "execution_data": {
      "drone_task_id": null,
      "scheduled_time": null,
      "actual_time": null,
      "execution_status": "not_executed",
      "execution_guide": "1. 登录设备管理系统\n2. 找到A区滴灌设备\n3. 设置灌溉时间2小时\n4. 确认启动"
    },
    "supporting_charts": {
      "soil_moisture_trend": {
        "type": "line",
        "data": {
          "labels": ["7/1", "7/2", "7/3", "7/4"],
          "datasets": [{
            "label": "土壤含水率(%)",
            "data": [18.2, 16.5, 14.3, 12.5],
            "borderColor": "#3B82F6",
            "backgroundColor": "rgba(59, 130, 246, 0.1)",
            "fill": true
          }, {
            "label": "适宜范围",
            "data": [15, 15, 15, 15],
            "borderColor": "#10B981",
            "borderDash": [5, 5],
            "backgroundColor": "transparent",
            "yAxisID": "y"
          }]
        },
        "options": {
          "yAxis": {
            "min": 10,
            "max": 30,
            "title": {
              "display": true,
              "text": "土壤含水率(%)"
            }
          },
          "title": {
            "display": true,
            "text": "地块A土壤含水率趋势"
          }
        }
      }
    },
    "created_at": "2025-07-04T10:30:00Z",
    "updated_at": "2025-07-04T10:30:00Z",
    "is_new": true
  }
}

（6）AI Agent（指定茶园批量处理建议并同步农事计划）

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/ai-agent/suggestions/batch
  • 请求参数：
{
  "action": "mark_as_read", // 或 "mark_as_executed", "generate_farm_task"
  "suggestion_ids": ["sugg_12345", "sugg_67890", "sugg_01234"],
  "farm_task_data": {
    "task_type": "irrigation",
    "scheduled_date": "2025-07-05",
    "priority": "high",
    "assigned_to": "drone_001",
    "notes": "批量生成的灌溉任务"
  }
}
  • 请求响应
{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "total": 3,
    "success": 3,
    "failed": 0,
    "farm_task_id": "farm_task_54321" // 当action为generate_farm_task时返回
  }
}

（7）AI Agent（指定茶园导出AI管理建议）

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/ai-agent/suggestions/export
  • 请求参数：
{
    "plantationId": "TP-2025-07-03-001",
    "format": "pdf", // 或 "excel", "csv"
    "filter": {
      "status": "unread",
      "type": "irrigation",
      "timeRange": {
        "startTime": "2025-07-01T00:00:00Z",
        "endTime": "2025-07-31T23:59:59Z"
      },
    },
    "include_details": true,
    "include_charts": true
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "export_id": "export_12345",
    "format": "pdf",
    "plantationId": "TP-2025-07-03-001",
    "timeRange": {
      "startTime": "2025-07-01T00:00:00Z",
      "endTime": "2025-07-31T23:59:59Z"
    },
    "status": "generated",
    "downloadUrl": "https://api.example.com/reports/R-2025-07-03-001.pdf"
  }
}

（8）AI Agent（获取知识分类与热门问题）

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/ai-agent/knowledge/categories_questions
  • 请求响应
{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "categories": [
      {
        "category_id": "cat_123",
        "name": "灌溉知识",
        "description": "关于茶园灌溉系统和方法的知识",
        "teas_count": 12,
        "created_at": "2025-06-01T10:30:00Z",
        "updated_at": "2025-06-01T10:30:00Z"
      },
      {
        "category_id": "cat_124",
        "name": "灌溉知识",
        "description": "关于茶园灌溉系统和方法的知识",
        "teas_count": 12,
        "created_at": "2025-06-01T10:30:00Z",
        "updated_at": "2025-06-01T10:30:00Z"
      },
    ]
    "popular_questions": [
      {
        "question_id": "qst_321",
        "question": "如何判断茶园土壤是否缺水？",
        "answer_count": 3,
        "view_count": 125,
        "created_at": "2025-06-15T14:20:00Z",
        "updated_at": "2025-06-15T14:20:00Z",
        "tags": ["土壤", "灌溉", "茶园管理"],
        "last_answer_at": "2025-06-20T09:15:30Z"
      },
      {
        "question_id": "qst_322",
        "question": "如何判断茶园土壤是否缺水？",
        "answer_count": 3,
        "view_count": 125,
        "created_at": "2025-06-15T14:20:00Z",
        "updated_at": "2025-06-15T14:20:00Z",
        "tags": ["土壤", "灌溉", "茶园管理"],
        "last_answer_at": "2025-06-20T09:15:30Z"
      },
    ]
  }
}

产量预测模型

（1） 获取所有可用预测模型

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/models
● 请求参数：

{
  "active_only": true  // 是否只返回激活的模型，可选，默认true
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": [
    {
      "model_id": "mlp_tea_yield",
      "name": "多层感知机茶叶产量预测模型",
      "description": "基于气象、土壤和管理数据的茶叶产量预测模型",
      "version": "v2.1.0",
      "status": "active",
      "accuracy": 0.85,
      "last_updated": "2025-06-15T09:30:00Z",
      "supported_parameters": [
        "temperature", "humidity", "rainfall", "sunshine_hours", 
        "soil_moisture", "fertilizer_amount", "pest_control"
      ]
    },
    {
      "model_id": "lstm_time_series",
      "name": "LSTM时间序列预测模型",
      "description": "基于历史产量数据的时间序列预测模型",
      "version": "v1.2.0",
      "status": "inactive",
      "accuracy": 0.78,
      "last_updated": "2025-05-20T14:15:00Z",
      "supported_parameters": [
        "historical_yield", "temperature", "rainfall", "seasonal_factor"
      ]
    }
  ]
}

（2）执行产量预测

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/predict
● 请求参数：

{
  "model_id": "mlp_tea_yield",
  "plantation_id": "plant_001",
  "prediction_period": "quarterly",  // 预测周期：daily, weekly, monthly, quarterly, yearly
  "start_date": "2025-07-01",
  "end_date": "2025-09-30",
  "parameters": {
    "temperature": [25.5, 26.3, 27.1],  // 预测周期内每日温度
    "humidity": [70.2, 68.5, 67.8],    // 预测周期内每日湿度
    "rainfall": [12.5, 8.3, 15.6],     // 预测周期内每日降雨量
    "sunshine_hours": [6.2, 7.5, 6.8], // 预测周期内每日日照时长
    "soil_moisture": [20.5, 19.8, 21.2], // 预测周期内每日土壤湿度
    "fertilizer_amount": [150, 0, 150],   // 预测周期内施肥量
    "pest_control": [0, 1, 0]            // 预测周期内病虫害防治措施
  }
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "prediction_id": "pred_001",
    "model_id": "mlp_tea_yield",
    "plantation_id": "plant_001",
    "prediction_period": "quarterly",
    "start_date": "2025-07-01",
    "end_date": "2025-09-30",
    "status": "processing",
    "estimated_completion": "2025-07-04T11:15:00Z",
    "created_at": 2025-07-04T11:00:00Z"
  }
}

（3）获取预测结果详情

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/api/yield-prediction/results/{predictionId}
● 请求参数：无
● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "prediction_id": "pred_001",
    "model_id": "mlp_tea_yield",
    "plantation_id": "plant_001",
    "prediction_period": "quarterly",
    "start_date": "2025-07-01",
    "end_date": "2025-09-30",
    "status": "completed",
    "prediction_time": "2025-07-04T11:12:00Z",
    "results": {
      "total_yield": 1250.5,      // 总产量(kg)
      "yield_per_mu": 125.05,     // 亩产量(kg)
      "yield_trend": [
        {"date": "2025-07-31", "yield": 420.3},
        {"date": "2025-08-31", "yield": 435.2},
        {"date": "2025-09-30", "yield": 395.0}
      ],
      "confidence_interval": [1205.3, 1295.7], // 置信区间
      "comparison": {
        "last_year": {
          "change_percentage": 8.3,
          "change_amount": 96.2
        },
        "average": {
          "change_percentage": 5.1,
          "change_amount": 60.8
        }
      },
      "contributing_factors": {
        "temperature": 0.35,
        "rainfall": 0.25,
        "soil_moisture": 0.20,
        "fertilizer_amount": 0.15,
        "pest_control": 0.05
      }
    },
    "recommendations": [
      "7月中旬适当增加灌溉，保持土壤湿度在22%-25%",
      "8月初追加氮肥，建议每亩30kg",
      "密切关注9月天气变化，提前做好防旱准备"
    ]
  }
}

（4）获取预测结果可视化数据

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/visualize/{predictionId}
● 请求参数：

{
  "chart_types": ["line", "bar", "comparison"]  // 图表类型，可选，默认全部
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "prediction_id": "pred_001",
    "visualizations": {
      "yield_trend": {
        "type": "line",
        "data": {
          "labels": ["7月", "8月", "9月"],
          "datasets": [{
            "label": "预测产量(kg)",
            "data": [420.3, 435.2, 395.0],
            "borderColor": "#3B82F6",
            "backgroundColor": "rgba(59, 130, 246, 0.1)",
            "fill": true
          }]
        },
        "options": {
          "yAxis": {
            "title": {
              "display": true,
              "text": "产量(kg)"
            }
          },
          "title": {
            "display": true,
            "text": "本季度产量预测趋势"
          }
        }
      },
      "factor_importance": {
        "type": "bar",
        "data": {
          "labels": ["温度", "降雨量", "土壤湿度", "施肥量", "病虫害防治"],
          "datasets": [{
            "label": "因素重要性",
            "data": [0.35, 0.25, 0.20, 0.15, 0.05],
            "backgroundColor": [
              "#3B82F6", "#10B981", "#F59E0B", "#EF4444", "#8B5CF6"
            ]
          }]
        },
        "options": {
          "yAxis": {
            "title": {
              "display": true,
              "text": "重要性权重"
            },
            "min": 0,
            "max": 0.4
          },
          "title": {
            "display": true,
            "text": "产量影响因素重要性分析"
          }
        }
      },
      "comparison": {
        "type": "comparison",
        "data": {
          "labels": ["本季度预测", "去年同期", "三年平均"],
          "datasets": [{
            "label": "产量(kg)",
            "data": [1250.5, 1154.3, 1189.7],
            "backgroundColor": [
              "#3B82F6", "#6366F1", "#8B5CF6"
            ]
          }]
        },
        "options": {
          "title": {
            "display": true,
            "text": "产量对比分析"
          }
        }
      }
    }
  }
}

（5）生成预测报告 PDF

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/report/{predictionId}
● 请求参数：

{
  "format": "pdf",          // 报告格式，可选，默认pdf
  "include_visualizations": true,  // 是否包含可视化图表，可选，默认true
  "include_recommendations": true  // 是否包含建议，可选，默认true
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "report_id": "report_001",
    "prediction_id": "pred_001",
    "format": "pdf",
    "status": "generating",
    "estimated_completion": "2025-07-04T11:20:00Z",
    "created_at": "2025-07-04T11:15:00Z"
  }
}

（6）获取历史预测记录

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/history
● 请求参数：

{
  "page": 1,                // 页码，可选，默认1
  "per_page": 10,           // 每页数量，可选，默认10
  "plantation_id": "plant_001", // 茶园ID，可选
  "model_id": "mlp_tea_yield",  // 模型ID，可选
  "start_date": "2025-01-01",   // 开始日期，可选
  "end_date": "2025-07-04",     // 结束日期，可选
  "sort": "created_at",         // 排序字段，可选
  "order": "desc"               // 排序方向，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "total": 8,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "prediction_id": "pred_001",
        "model_id": "mlp_tea_yield",
        "plantation_id": "plant_001",
        "prediction_period": "quarterly",
        "start_date": "2025-07-01",
        "end_date": "2025-09-30",
        "status": "completed",
        "prediction_time": "2025-07-04T11:12:00Z",
        "results": {
          "total_yield": 1250.5,
          "yield_per_mu": 125.05
        },
        "accuracy": 0.85,
        "created_at": "2025-07-04T11:00:00Z"
      },
      // 其他历史记录...
    ]
  }
}

（7）更新预测模型参数

● 请求方式：PUT
● 请求方法：传统 http 请求
● 接口路径：/yield-prediction/parameters
● 请求参数：

{
  "model_id": "mlp_tea_yield",
  "parameters": {
    "learning_rate": 0.001,
    "hidden_layers": [128, 64, 32],
    "batch_size": 32,
    "epochs": 100,
    "dropout_rate": 0.2
  }
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "model_id": "mlp_tea_yield",
    "updated_at": "2025-07-04T14:30:00Z"
  }
}

病虫害防控

（1）获取病虫害识别历史

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/pests/history
● 请求参数：

{
  "page": 1,                // 页码，可选，默认1
  "per_page": 10,           // 每页数量，可选，默认10
  "plantation_id": "plant_001", // 茶园ID，可选
  "pest_type": "aphid",     // 病虫害类型，可选
  "start_date": "2025-01-01",   // 开始日期，可选
  "end_date": "2025-07-04",     // 结束日期，可选
  "sort": "created_at",         // 排序字段，可选
  "order": "desc"               // 排序方向，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "total": 12,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "identification_id": "id_001",
        "plantation_id": "plant_001",
        "plot_id": "plot_001",
        "pest_type": "aphid",
        "severity_level": "moderate",
        "confidence": 0.92,
        "area_affected": 50, // 受影响面积(m²)
        "status": "completed",
        "identification_time": "2025-07-04T11:25:00Z",
        "created_at": "2025-07-04T11:00:00Z"
      },
      // 其他历史记录...
    ]
  }
}

（2）获取病虫害预警地图

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/pests/ warning /map
● 请求参数：

{
  "plantation_id": "plant_001", // 茶园ID，可选
  "severity_level": "moderate", // 严重程度过滤，可选
  "pest_types": ["aphid", "tea_moth"] // 病虫害类型过滤，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantation_id": "plant_001",
    "center": {
      "latitude": 30.2435,
      "longitude": 120.1546
    },
    "zoom_level": 15,
    "warning_areas": [
      {
        "area_id": "area_001",
        "plot_id": "plot_001",
        "location": {
          "latitude": 30.2435,
          "longitude": 120.1546
        },
        "radius": 50, // 半径(m)
        "pest_type": "aphid",
        "severity_level": "moderate",
        "affected_area": 50, // 受影响面积(m²)
        "predicted_spread": 10, // 预测扩散速度(m/周)
        "last_updated": "2025-07-04T11:25:00Z"
      },
      // 其他预警区域...
    ]
  }
}

（3）获取病虫害趋势

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/pests/ warning /trends
● 请求参数：

{
  "plantation_id": "plant_001", // 茶园ID，可选
  "time_period": "monthly",     // 时间周期：weekly, monthly, quarterly, yearly
  "start_date": "2025-01-01",   // 开始日期，可选
  "end_date": "2025-07-04",     // 结束日期，可选
  "pest_types": ["aphid", "tea_moth"] // 病虫害类型，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plantation_id": "plant_001",
    "time_period": "monthly",
    "start_date": "2025-01-01",
    "end_date": "2025-07-04",
    "trends": [
      {
        "pest_type": "aphid",
        "data": [
          {"date": "2025-01-31", "count": 5, "severity": "mild"},
          {"date": "2025-02-28", "count": 8, "severity": "mild"},
          {"date": "2025-03-31", "count": 12, "severity": "moderate"},
          {"date": "2025-04-30", "count": 25, "severity": "moderate"},
          {"date": "2025-05-31", "count": 42, "severity": "severe"},
          {"date": "2025-06-30", "count": 35, "severity": "severe"},
          {"date": "2025-07-04", "count": 30, "severity": "moderate"}
        ]
      },
      {
        "pest_type": "tea_moth",
        "data": [
          {"date": "2025-01-31", "count": 0, "severity": "none"},
          {"date": "2025-02-28", "count": 2, "severity": "mild"},
          {"date": "2025-03-31", "count": 5, "severity": "mild"},
          {"date": "2025-04-30", "count": 10, "severity": "mild"},
          {"date": "2025-05-31", "count": 15, "severity": "moderate"},
          {"date": "2025-06-30", "count": 20, "severity": "moderate"},
          {"date": "2025-07-04", "count": 18, "severity": "moderate"}
        ]
      }
    ]
  }
}

（4）创建防治方案

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/pests/control
● 请求参数：

{
  "plantation_id": "plant_001",
  "plot_id": "plot_001",
  "pest_type": "aphid",
  "severity_level": "moderate",
  "identification_id": "id_001",
  "control_methods": [
    {
      "method": "biological",
      "agent": "ladybug",
      "quantity": 500,
      "application_time": "2025-07-05T10:00:00Z"
    },
    {
      "method": "chemical",
      "agent": "imidacloprid",
      "concentration": "0.05%",
      "quantity": "20L",
      "application_time": "2025-07-10T15:00:00Z"
    }
  ],
  "estimated_cost": 1200.50,
  "estimated_effect_time": 7, // 预计生效时间(天)
  "estimated_duration": 14,   // 预计持续时间(天)
  "responsible_person": "user_001"
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plan_id": "plan_001",
    "status": "pending",
    "created_at": "2025-07-04T14:30:00Z"
  }
}

（5）获取防治方案详情

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/pests/control/{planId}
● 请求参数：无
● 请求响应：

{
  "code": 200,
  "message": "success",
  "timestamp": "2025-07-03 14:30:00",
  "data": {
    "plan_id": "plan_001",
    "plantation_id": "plant_001",
    "plot_id": "plot_001",
    "pest_type": "aphid",
    "severity_level": "moderate",
    "identification_id": "id_001",
    "control_methods": [
      {
        "method": "biological",
        "agent": "ladybug",
        "quantity": 500,
        "application_time": "2025-07-05T10:00:00Z",
        "status": "pending"
      },
      {
        "method": "chemical",
        "agent": "imidacloprid",
        "concentration": "0.05%",
        "quantity": "20L",
        "application_time": "2025-07-10T15:00:00Z",
        "status": "pending"
      }
    ],
    "estimated_cost": 1200.50,
    "estimated_effect_time": 7,
    "estimated_duration": 14,
    "responsible_person": {
      "user_id": "user_001",
      "username": "植保专家"
    },
    "status": "pending",
    "progress": 0,
    "start_time": null,
    "end_time": null,
    "created_at": "2025-07-04T14:30:00Z",
    "updated_at": "2025-07-04T14:30:00Z"
  }
}

设备运维

（1）提交维修请求

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/maintenance/requests
● 请求参数：

{
  "device_id": "drone_001",        // 设备ID（必选）
  "device_type": "drone",          // 设备类型（必选）
  "fault_description": "飞行异常，偏航严重", // 故障描述（必选）
  "fault_photos": [                // 故障照片URL列表（可选）
    "https://cos.example.com/fault_photo1.jpg",
    "https://cos.example.com/fault_photo2.jpg"
  ],
  "fault_time": "2025-07-04T14:30:00Z", // 故障发生时间（可选）
  "urgency_level": "high",         // 紧急程度（可选，默认normal）
  "suggested_solution": "检查GPS模块", // 建议解决方案（可选）
  "reported_by": "user_001",       // 报修人ID（必选）
  "plantation_id": "plant_001"     // 茶园ID（必选）
}

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "request_id": "maint_001",
    "status": "pending",
    "created_at": "2025-07-04T14:45:00Z"
  }
}

（2）获取维修请求列表

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/maintenance/requests
● 请求参数：

{
  "page": 1,                // 页码（可选，默认1）
  "per_page": 10,           // 每页数量（可选，默认10）
  "status": "pending",      // 状态过滤（可选，pending/in_progress/completed/cancelled）
  "device_type": "drone",   // 设备类型过滤（可选）
  "urgency_level": "high",  // 紧急程度过滤（可选）
  "start_date": "2025-07-01", // 开始日期（可选）
  "end_date": "2025-07-05",   // 结束日期（可选）
  "sort": "created_at",     // 排序字段（可选，默认created_at）
  "order": "desc"           // 排序方向（可选，默认desc）
}

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "total": 15,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "request_id": "maint_001",
        "device_id": "drone_001",
        "device_type": "drone",
        "fault_description": "飞行异常，偏航严重",
        "status": "pending",
        "urgency_level": "high",
        "reported_by": "user_001",
        "assigned_to": null,
        "created_at": "2025-07-04T14:45:00Z",
        "updated_at": "2025-07-04T14:45:00Z"
      },
      // 其他维修请求...
    ]
  }
}

（3）获取维修请求详情

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/maintenance/requests/{requestId}
● 请求参数：

{
  "include_comments": true,  // 是否包含评论（可选，默认false）
  "include_history": true    // 是否包含历史记录（可选，默认false）
}

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "request_id": "maint_001",
    "device_id": "drone_001",
    "device_type": "drone",
    "fault_description": "飞行异常，偏航严重",
    "fault_photos": [
      "https://cos.example.com/fault_photo1.jpg",
      "https://cos.example.com/fault_photo2.jpg"
    ],
    "fault_time": "2025-07-04T14:30:00Z",
    "urgency_level": "high",
    "status": "pending",
    "diagnosis": null,
    "repair_solution": null,
    "repair_parts": null,
    "repair_cost": null,
    "reported_by": {
      "user_id": "user_001",
      "username": "茶园管理员",
      "phone": "13800138001"
    },
    "assigned_to": null,
    "completed_at": null,
    "created_at": "2025-07-04T14:45:00Z",
    "updated_at": "2025-07-04T14:45:00Z",
    
    "comments": [
      {
        "comment_id": "comm_001",
        "user_id": "tech_001",
        "content": "初步判断可能是GPS模块故障，需要进一步检查",
        "created_at": "2025-07-04T15:00:00Z"
      }
    ],
    
    "history": [
      {
        "status": "pending",
        "change_time": "2025-07-04T14:45:00Z",
        "changed_by": "user_001"
      }
    ]
  }
}

（4）更新维修请求状态

● 请求方式：PUT
● 请求方法：传统 http 请求
● 接口路径：/maintenance/requests/{requestId}/status
● 请求参数：

{
  "status": "in_progress",    // 新状态（必选，pending/in_progress/completed/cancelled）
  "assigned_to": "tech_001",  // 分配给（可选）
  "diagnosis": "GPS模块故障", // 诊断结果（可选）
  "repair_solution": "更换GPS模块", // 维修方案（可选）
  "repair_parts": ["GPS模块-A型"], // 维修部件（可选）
  "repair_cost": 850.0,       // 维修费用（可选）
  "completed_at": "2025-07-05T10:30:00Z", // 完成时间（可选）
  "comments": "已更换GPS模块，测试飞行正常" // 备注（可选）
}

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "request_id": "maint_001",
    "status": "in_progress",
    "updated_at": "2025-07-04T16:15:00Z"
  }
}

（5）设备固件升级

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/firmware/upgrade
● 请求参数：

{
  "device_ids": ["drone_001", "drone_002"], // 设备ID列表（必选）
  "firmware_version": "v2.3.5",             // 固件版本（必选）
  "upgrade_time": "2025-07-05T02:00:00Z",  // 升级时间（可选，默认立即）
  "upgrade_type": "auto",                   // 升级类型（可选，auto/manual）
  "force": false                            // 是否强制升级（可选，默认false）
}

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "upgrade_id": "fw_upg_001",
    "status": "scheduled",
    "scheduled_time": "2025-07-05T02:00:00Z",
    "created_at": "2025-07-04T17:30:00Z"
  }
}

（6）获取固件升级历史

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/firmware/history

● 请求响应：

{
  "code": 200, // 返回码、错误码
  "timestamp": "2025-07-03 14:30:00", // 时间戳
  "message": "success", // 状态描述
  "data": {
    "total": 8,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "upgrade_id": "fw_upg_001",
        "device_id": "drone_001",
        "device_type": "drone",
        "firmware_version": "v2.3.5",
        "status": "scheduled",
        "start_time": "2025-07-05T02:00:00Z",
        "end_time": null,
        "duration": null,
        "result": null,
        "logs": null,
        "created_at": "2025-07-04T17:30:00Z",
        "updated_at": "2025-07-04T17:30:00Z"
      },
      {
        "upgrade_id": "fw_upg_002",
        "device_id": "sensor_001",
        "device_type": "soil_sensor",
        "firmware_version": "v1.2.3",
        "status": "completed",
        "start_time": "2025-07-03T03:00:00Z",
        "end_time": "2025-07-03T03:15:00Z",
        "duration": "15分钟",
        "result": "升级成功",
        "logs": "升级过程正常，设备重启后运行稳定",
        "created_at": "2025-07-03T02:45:00Z",
        "updated_at": "2025-07-03T03:15:00Z"
      },
      // 其他升级记录...
    ]
  }
}

茶园信息

（1）获取茶园列表

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/plantations/info
  • 请求参数：
{
  "page": 1,                // 页码，可选，默认1
  "per_page": 10,           // 每页数量，可选，默认10
  "status": "deployed",     // 部署状态，可选，默认全部
  "country": "China",       // 国家，可选
  "province": "浙江",        // 省份，可选
  "city": "杭州",           // 城市，可选
  "sort": "created_at",     // 排序字段，可选，默认创建时间
  "order": "desc"           // 排序方向，可选，默认降序
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 25,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "plantation_id": "plant_001",
        "user_id": "user_001",
        "photo_url": "https://cos.example.com/plantation_001.jpg",
        "plantation_name": "龙井茶园示范基地",
        "country": "China",
        "province": "浙江",
        "city": "杭州",
        "district": "西湖区",
        "detail_address": "龙井村123号",
        "latitude": 30.2435,
        "longitude": 120.1546,
        "altitude": 85.5,
        "drone_count": 3,
        "drone_running": 1,
        "soil_sensors_count": 10,
        "soil_sensors_running": 8,
        "insect_pests_status": 1,
        "deployment_status": 2,
        "created_at": "2025-01-15T08:30:00Z",
        "updated_at": "2025-07-04T10:15:00Z"
      },
      // 其他茶园...
    ]
  }
}

（2）获取茶园详情

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/plantations/info/{plantationId}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "plantation_id": "plant_001",
    "user_id": "user_001",
    "photo_url": "https://cos.example.com/plantation_001.jpg",
    "plantation_name": "龙井茶园示范基地",
    "country": "China",
    "province": "浙江",
    "city": "杭州",
    "district": "西湖区",
    "detail_address": "龙井村123号",
    "latitude": 30.2435,
    "longitude": 120.1546,
    "altitude": 85.5,
    "drone_count": 3,
    "drone_running": 1,
    "soil_sensors_count": 10,
    "soil_sensors_running": 8,
    "insect_pests_status": 1,
    "deployment_status": 2,
    "created_at": "2025-01-15T08:30:00Z",
    "updated_at": "2025-07-04T10:15:00Z",
    
    "sensors": [
      {
        "sensor_id": "soil_001",
        "sensor_name": "A区土壤湿度仪",
        "sensor_type": "moisture",
        "location_name": "A区东北角",
        "latitude": 30.2445,
        "longitude": 120.1556,
        "depth": 15.0,
        "status": "ready",
        "last_calibration": "2025-06-30"
      },
      // 其他传感器...
    ],
    
    "drones": [
      {
        "drone_id": "drone_001",
        "plantation_name": "龙井茶园示范基地",
        "latitude": 30.2438,
        "longitude": 120.1542,
        "altitude": 30.0,
        "battery_level": 75,
        "flight_mode": "auto",
        "connection_status": "connected",
        "health_check": "health",
        "status": "ready",
        "timestamp": "2025-07-04T10:15:00Z"
      },
      // 其他无人机...
    ],
    
    "weather": {
      "station_id": "weather_001",
      "station_name": "西湖气象站",
      "temperature": 28.5,
      "humidity": 65.2,
      "light": 85000.0,
      "wind_speed": 2.3,
      "wind_direction": 120.5,
      "rainfall": 0.0,
      "timestamp": "2025-07-04T10:00:00Z"
    }
  }
}

（3）创建新茶园

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/plantations/create
  • 请求参数：
{
  "user_id": "user_001",
  "photo": "", // file 格式
  "plantation_name": "新茶园基地",
  "country": "China",
  "province": "福建",
  "city": "武夷山",
  "district": "武夷山区",
  "detail_address": "星村镇123号",
  "latitude": 27.7534,
  "longitude": 118.0245,
  "altitude": 350.5,
  "drone_count": 0,
  "soil_sensors_count": 0
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "plantation_id": "plant_002",
    "created_at": "2025-07-04T11:30:00Z"
  }
}

（4）更新茶园信息

  • 请求方式：PUT
  • 请求方法：传统http请求
  • 接口路径：/plantations/update/{plantationId}
  • 请求参数：
{
  "photo": "", // file 格式
  "plantation_name": "龙井茶园示范基地（扩建）",
  "detail_address": "龙井村123号（扩建区域）",
  "drone_count": 5,
  "soil_sensors_count": 15,
  "insect_pests_status": 2,
  "deployment_status": 2
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "plantation_id": "plant_001",
    "updated_at": "2025-07-04T11:45:00Z"
  }
}

（5）删除茶园

  • 请求方式：DELETE
  • 请求方法：传统http请求
  • 接口路径：/plantations/delete/{plantationId}
  • 请求响应
{
  "code": 200,
  "message": "plantation delete success"
}

智能设备管理

（1）获取设备列表

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/devices
● 请求参数：

{
  "page": 1,                // 页码，可选，默认1
  "per_page": 10,           // 每页数量，可选，默认10
  "plantation_id": "plant_001", // 茶园ID，可选
  "device_type": "drone",   // 设备类型，可选
  "status": "active",       // 设备状态，可选
  "sort": "created_at",     // 排序字段，可选
  "order": "desc"           // 排序方向，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 25,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "device_id": "drone_001",
        "device_type": "drone",
        "model": "DJI Mavic 3",
        "firmware_version": "v2.3.5",
        "serial_number": "DR-2025-0001",
        "plantation_id": "plant_001",
        "location_latitude": 30.2435,
        "location_longitude": 120.1546,
        "status": "active",
        "purchase_date": "2025-01-15",
        "warranty_expire_date": "2026-01-14",
        "last_maintenance_date": "2025-06-30",
        "created_at": "2025-01-15T08:30:00Z",
        "updated_at": "2025-07-04T10:15:00Z"
      },
      // 其他设备...
    ]
  }
}

（2）获取设备详情

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/devices/{deviceId}
● 请求参数：

{
  "include_maintenance": true,  // 是否包含维修历史，可选，默认false
  "include_firmware": true      // 是否包含固件升级历史，可选，默认false
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "device_id": "drone_001",
    "device_type": "drone",
    "model": "DJI Mavic 3",
    "firmware_version": "v2.3.5",
    "serial_number": "DR-2025-0001",
    "plantation_id": "plant_001",
    "location_latitude": 30.2435,
    "location_longitude": 120.1546,
    "status": "active",
    "purchase_date": "2025-01-15",
    "warranty_expire_date": "2026-01-14",
    "last_maintenance_date": "2025-06-30",
    "created_at": "2025-01-15T08:30:00Z",
    "updated_at": "2025-07-04T10:15:00Z",
    
    "maintenance_requests": [
      {
        "request_id": "maint_001",
        "fault_description": "飞行异常，偏航严重",
        "status": "completed",
        "diagnosis": "GPS模块故障",
        "repair_solution": "更换GPS模块",
        "completed_at": "2025-07-05T10:30:00Z",
        "created_at": "2025-07-04T14:45:00Z"
      }
    ],
    
    "firmware_upgrades": [
      {
        "upgrade_id": "fw_upg_001",
        "firmware_version": "v2.3.5",
        "status": "completed",
        "start_time": "2025-07-05T02:00:00Z",
        "end_time": "2025-07-05T02:15:00Z",
        "result": "升级成功",
        "created_at": "2025-07-04T17:30:00Z"
      }
    ]
  }
}

（3）添加新设备

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/devices
● 请求参数：

{
  "device_id": "drone_002",
  "device_type": "drone",
  "model": "DJI Mavic 3",
  "firmware_version": "v2.3.0",
  "serial_number": "DR-2025-0002",
  "plantation_id": "plant_001",
  "location_latitude": 30.2438,
  "location_longitude": 120.1542,
  "status": "active",
  "purchase_date": "2025-03-20",
  "warranty_expire_date": "2026-03-19"
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "device_id": "drone_002",
    "created_at": "2025-07-04T14:30:00Z"
  }
}

（4）更新设备信息

● 请求方式：PUT
● 请求方法：传统 http 请求
● 接口路径：/devices/{deviceId}
● 请求参数：

{
  "firmware_version": "v2.3.5",
  "location_latitude": 30.2440,
  "location_longitude": 120.1545,
  "status": "maintenance",
  "last_maintenance_date": "2025-07-04"
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "device_id": "drone_001",
    "updated_at": "2025-07-04T15:45:00Z"
  }
}

（5）删除设备

● 请求方式：DELETE
● 请求方法：传统 http 请求
● 接口路径：/devices/{deviceId}
● 请求参数：

{
  "confirm": true           // 确认删除，必须为true
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "message": "设备删除成功"
}

（6）获取设备状态统计

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/devices/status
● 请求参数：

{
  "plantation_id": "plant_001" // 茶园ID，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "active": 42,
    "inactive": 3,
    "maintenance": 5,
    "offline": 0,
    "by_type": {
      "drone": {
        "total": 10,
        "active": 8,
        "inactive": 0,
        "maintenance": 2,
        "offline": 0
      },
      "soil_sensor": {
        "total": 30,
        "active": 26,
        "inactive": 2,
        "maintenance": 2,
        "offline": 0
      },
      "weather_station": {
        "total": 5,
        "active": 5,
        "inactive": 0,
        "maintenance": 0,
        "offline": 0
      },
      "irrigation_controller": {
        "total": 5,
        "active": 3,
        "inactive": 1,
        "maintenance": 1,
        "offline": 0
      }
    },
    "last_updated": "2025-07-04T16:00:00Z"
  }
}

任务调度中心

（1）获取任务列表

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/missions
● 请求参数：

{
  "page": 1,                // 页码，可选，默认1
  "per_page": 10,           // 每页数量，可选，默认10
  "plantation_id": "plant_001", // 茶园ID，可选
  "task_type": "irrigation", // 任务类型，可选
  "status": "in_progress",  // 任务状态，可选
  "start_date": "2025-07-01", // 开始日期，可选
  "end_date": "2025-07-05",   // 结束日期，可选
  "sort": "scheduled_time", // 排序字段，可选
  "order": "asc"            // 排序方向，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 15,
    "page": 1,
    "per_page": 10,
    "items": [
      {
        "task_id": "task_001",
        "task_type": "irrigation",
        "title": "A区滴灌任务",
        "description": "对A区茶园进行灌溉",
        "plantation_id": "plant_001",
        "plot_id": "plot_001",
        "status": "in_progress",
        "priority": "high",
        "scheduled_time": "2025-07-04T16:00:00Z",
        "actual_start_time": "2025-07-04T16:10:00Z",
        "actual_end_time": null,
        "assigned_to": "drone_001",
        "assigned_to_id": "drone_001",
        "suggestion_ids": ["sugg_001"],
        "created_by": "user_001",
        "created_at": "2025-07-04T10:30:00Z",
        "updated_at": "2025-07-04T16:10:00Z"
      },
      // 其他任务...
    ]
  }
}

（2）获取任务详情

● 请求方式：GET
● 请求方法：传统 http 请求
● 接口路径：/missions/{missionId}
● 请求参数：

{
  "include_execution": true  // 是否包含执行详情，可选，默认false
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_001",
    "task_type": "irrigation",
    "title": "A区滴灌任务",
    "description": "对A区茶园进行灌溉",
    "plantation_id": "plant_001",
    "plot_id": "plot_001",
    "status": "in_progress",
    "priority": "high",
    "scheduled_time": "2025-07-04T16:00:00Z",
    "actual_start_time": "2025-07-04T16:10:00Z",
    "actual_end_time": null,
    "assigned_to": "drone_001",
    "assigned_to_id": "drone_001",
    "suggestion_ids": ["sugg_001"],
    "execution_details": {
      "progress": 45,
      "completed_area": 450,
      "total_area": 1000,
      "remaining_time": "45分钟",
      "resources_used": {
        "water": 22.5,
        "battery": 35
      },
      "logs": [
        {
          "time": "2025-07-04T16:10:00Z",
          "message": "任务开始执行"
        },
        {
          "time": "2025-07-04T16:25:00Z",
          "message": "已完成45%灌溉区域"
        }
      ]
    },
    "created_by": "user_001",
    "created_at": "2025-07-04T10:30:00Z",
    "updated_at": "2025-07-04T16:25:00Z"
  }
}

（3）创建新任务

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/missions
● 请求参数：

{
  "task_type": "irrigation",
  "title": "A区滴灌任务",
  "description": "对A区茶园进行灌溉",
  "plantation_id": "plant_001",
  "plot_id": "plot_001",
  "status": "pending",
  "priority": "high",
  "scheduled_time": "2025-07-04T16:00:00Z",
  "assigned_to": "drone_001",
  "assigned_to_id": "drone_001",
  "suggestion_ids": ["sugg_001"],
  "execution_details": {
    "water_volume": 50,
    "area": 1000,
    "estimated_time": "2小时"
  }
}

● 请求响应：

{
  "status": "success",
  "data": {
    "task_id": "task_002",
    "created_at": "2025-07-04T14:30:00Z"
  }
}

（4）更新任务

● 请求方式：PUT
● 请求方法：传统 http 请求
● 接口路径：/missions/{missionId}
● 请求参数：

{
  "title": "A区滴灌任务（更新）",
  "status": "in_progress",
  "priority": "high",
  "scheduled_time": "2025-07-04T16:00:00Z",
  "actual_start_time": "2025-07-04T16:10:00Z"
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_001",
    "updated_at": "2025-07-04T16:10:00Z"
  }
}

（5） 执行任务

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/missions/{missionId}/execute
● 请求参数：

{
  "execute_time": "2025-07-04T16:10:00Z",  // 执行时间，可选，默认立即执行
  "operator": "user_001"                    // 操作人，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_001",
    "status": "in_progress",
    "actual_start_time": "2025-07-04T16:10:00Z",
    "updated_at": "2025-07-04T16:10:00Z"
  }
}

（6）暂停任务

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/missions/{missionId}/pause
● 请求参数：

{
  "reason": "设备需要检查",  // 暂停原因，可选
  "operator": "user_001"    // 操作人，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_001",
    "status": "paused",
    "updated_at": "2025-07-04T16:30:00Z"
  }
}

（7）恢复任务

● 请求方式：POST
● 请求方法：传统 http 请求
● 接口路径：/missions/{missionId}/resume
● 请求参数：

{
  "resume_time": "2025-07-04T16:45:00Z",  // 恢复时间，可选，默认立即恢复
  "operator": "user_001"                   // 操作人，可选
}

● 请求响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_001",
    "status": "in_progress",
    "updated_at": "2025-07-04T16:45:00Z"
  }
}

认证与授权

（1）用户注册

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/users/register
  • 请求参数：
{
  "role": "user",  // 或 "admin"
  "username": "user123",
  "nickname": "茶农小王",
  "password": "secure_password_2025",
  "phone": "13800138000",
  "avatar": "optional_avatar_url", // file格式
  "bio": "茶园管理者",
  "contact_info": "[email protected]",
  "plantations": [
    {
      "plantation_name": "西湖龙井茶园A",
      "plantation_id": "TP-2025-07-03-001"
    },
    {
      "plantation_name": "安吉白茶茶园B",
      "plantation_id": "TP-2025-07-03-002"
    }
  ]
}
  • 请求响应
{
  "code": 200,
  "message": "User created successfully",
  "data": {
    "userId": "U-2025-07-03-001",
    "nickname": "茶农小王",
    "role": "user",
    "phone": "13800138000",
    "avatar": "optional_avatar_url",
    "bio": "茶园管理者",
    "contact_info": "[email protected]",
    "plantations": [
      {
        "plantation_name": "西湖龙井茶园A",
        "plantation_id": "TP-2025-07-03-001"
      },
      {
        "plantation_name": "安吉白茶茶园B",
        "plantation_id": "TP-2025-07-03-002"
      }
    ]
  }
}

（2）用户登录【获取JWT令牌】

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/users/login
  • 请求参数：
{
  "username": "user123",
  "password": "secure_password_2025"
}
  • 请求响应
{
  "code": 200,
  "message": "Login successful",
  "data": {
    "userId": "U-2025-07-03-001",
    "nickname": "茶农小王",
    "role": "user",
    "token": "generated_jwt_token",
    "token_expiration": "2025-07-04T14:30:00Z",
    "plantations": [
      {
        "plantation_name": "西湖龙井茶园A",
        "plantation_id": "TP-2025-07-03-001"
      },
      {
        "plantation_name": "安吉白茶茶园B",
        "plantation_id": "TP-2025-07-03-002"
      }
    ]
  }
}

（3）获取当前登录信息

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/users/auth
  • 请求响应
{
  "code": 200,
  "message": "User login info",
  "data": {
    "userId": "U-2025-07-03-001",
    "nickname": "茶农小王",
    "role": "user",
    "phone": "13800138000",
    "avatar": "optional_avatar_url",
    "bio": "茶园管理者",
    "contact_info": "[email protected]",
    "plantations": [
      {
        "plantation_name": "西湖龙井茶园A",
        "plantation_id": "TP-2025-07-03-001"
      },
      {
        "plantation_name": "安吉白茶茶园B",
        "plantation_id": "TP-2025-07-03-002"
      }
    ]
  }
}

（4）用户登出

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：GET：/users/logout
  • 请求响应
{
  "code": 200,
  "message": "Logout successful"
}

（5）浏览个人信息

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/users/profile
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "userId": "U-2025-07-03-001",
    "role": "user",
    "username": "user123",
    "nickname": "茶农小王",
    "phone": "13800138000",
    "avatar": "optional_avatar_url",
    "bio": "茶园管理者",
    "contact_info": "[email protected]",
    "plantations": [
      {
        "plantation_name": "西湖龙井茶园A",
        "plantation_id": "TP-2025-07-03-001"
      },
      {
        "plantation_name": "安吉白茶茶园B",
        "plantation_id": "TP-2025-07-03-002"
      }
    ]
  }
}

用户管理

（1）浏览所有用户

  • 请求方式：GET
  • 请求方法：传统http请求
  • 接口路径：/admin/users
  • 查询参数:
{
  "page": 1,
  "pageSize": 20,
  "roleFilter": "user"  // 可选，过滤用户角色
}
  • 请求响应
{
  "code": 200,
  "message": "success",
  "data": {
    "totalUsers": 150,
    "users": [
      {
        "userId": "U-2025-07-03-001",
        "role": "user",
        "nickname": "茶农小王",
        "phone": "13800138000",
        "avatar": "optional_avatar_url",
        "bio": "茶园管理者",
        "contact_info": "[email protected]",
        "plantations": [
          {
            "plantation_name": "西湖龙井茶园A",
            "plantation_id": "TP-2025-07-03-001"
          },
          {
            "plantation_name": "安吉白茶茶园B",
            "plantation_id": "TP-2025-07-03-002"
          }
        ]
      },
      // 更多用户...
    ]
  }
}

（2）管理员增加用户

  • 请求方式：POST
  • 请求方法：传统http请求
  • 接口路径：/admin/users
  • 请求参数：
{
  "role": "user",
  "username": "new_user",
  "nickname": "新茶农",
  "password": "secure_password_2025",
  "phone": "13800138001",
  "avatar": "optional_avatar_url",
  "bio": "新茶园管理者",
  "contact_info": "[email protected]",
  "plantations": [
    {
      "plantation_name": "新建茶园C",
      "plantation_id": "TP-2025-07-03-003"
    }
  ]
}
  • 请求响应
{
  "code": 200,
  "message": "User created successfully",
  "data": {
    "userId": "U-2025-07-03-003",
    "nickname": "新茶农",
    "role": "user",
    "phone": "13800138001",
    "avatar": "optional_avatar_url",
    "bio": "新茶园管理者",
    "contact_info": "[email protected]",
    "plantations": [
      {
        "plantation_name": "新建茶园C",
        "plantation_id": "TP-2025-07-03-003"
      }
    ]
  }
}

（3）管理员删除用户

  • 请求方式：DELETE
  • 请求方法：传统http请求
  • 接口路径：/admin/users/{userId}
  • 请求响应
{
  "code": 200,
  "message": "User deleted successfully"
}

苍穹智鉴 · 智慧茶园 - AIoT 全栈架构设计文档

© 2025 Ei-Ayw

⚠️ **GitHub.com Fallback** ⚠️