# 农业服务API设计文档

## 1. 概述

本文档详细描述了农业服务(farming-service)提供的API接口，包括农田管理、农事活动记录、作物生长监测、病虫害防治、环境数据监测、收获管理等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/farming`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 40001,
  "message": "错误描述",
  "data": null
}
```

## 5. 农田管理接口

### 5.1 创建农田

**接口地址**: `POST /farmlands`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| name | string | 是 | 农田名称 |
| location | string | 是 | 地理位置 |
| area | number | 是 | 面积(亩) |
| crop_type | string | 是 | 作物类型 |
| planting_date | string | 否 | 种植日期(YYYY-MM-DD) |
| description | string | 否 | 描述 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "name": "一号小麦田",
  "location": "北京市朝阳区某农场",
  "area": 100.5,
  "crop_type": "小麦",
  "planting_date": "2024-01-15",
  "description": "春季小麦种植"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "name": "一号小麦田",
    "location": "北京市朝阳区某农场",
    "area": 100.5,
    "crop_type": "小麦",
    "planting_date": "2024-01-15",
    "status": "ACTIVE",
    "description": "春季小麦种植",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.2 获取农田列表

**接口地址**: `GET /farmlands`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| crop_type | string | 否 | 作物类型筛选 |
| status | string | 否 | 状态筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 农田列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "name": "一号小麦田",
        "location": "北京市朝阳区某农场",
        "area": 100.5,
        "crop_type": "小麦",
        "planting_date": "2024-01-15",
        "status": "ACTIVE",
        "description": "春季小麦种植",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 5.3 获取农田详情

**接口地址**: `GET /farmlands/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 农田ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "name": "一号小麦田",
    "location": "北京市朝阳区某农场",
    "area": 100.5,
    "crop_type": "小麦",
    "planting_date": "2024-01-15",
    "status": "ACTIVE",
    "description": "春季小麦种植",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.4 更新农田信息

**接口地址**: `PUT /farmlands/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 农田ID |
| name | string | 否 | 农田名称 |
| location | string | 否 | 地理位置 |
| area | number | 否 | 面积(亩) |
| crop_type | string | 否 | 作物类型 |
| planting_date | string | 否 | 种植日期(YYYY-MM-DD) |
| status | string | 否 | 状态 |
| description | string | 否 | 描述 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 农田ID |
| user_id | integer | 用户ID |
| name | string | 农田名称 |
| location | string | 地理位置 |
| area | number | 面积(亩) |
| crop_type | string | 作物类型 |
| planting_date | string | 种植日期 |
| status | string | 状态 |
| description | string | 描述 |
| updated_at | string | 更新时间 |

**示例请求**:
```json
{
  "name": "一号小麦田",
  "location": "北京市朝阳区某农场",
  "area": 100.5,
  "crop_type": "小麦",
  "planting_date": "2024-01-15",
  "status": "ACTIVE",
  "description": "春季小麦种植，已施肥"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "name": "一号小麦田",
    "location": "北京市朝阳区某农场",
    "area": 100.5,
    "crop_type": "小麦",
    "planting_date": "2024-01-15",
    "status": "ACTIVE",
    "description": "春季小麦种植，已施肥",
    "updated_at": "2024-01-15T11:00:00Z"
  }
}
```

## 6. 农事活动接口

### 6.1 记录农事活动

**接口地址**: `POST /activities`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| activity_type | string | 是 | 活动类型(播种/施肥/除草/收割等) |
| activity_date | string | 是 | 活动日期(YYYY-MM-DD) |
| description | string | 否 | 活动描述 |
| cost | number | 否 | 费用 |
| operator | string | 否 | 操作人员 |
| images | array | 否 | 活动图片URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 活动记录ID |
| farmland_id | integer | 农田ID |
| activity_type | string | 活动类型 |
| activity_date | string | 活动日期 |
| description | string | 活动描述 |
| cost | number | 费用 |
| operator | string | 操作人员 |
| images | array | 活动图片URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "farmland_id": 1001,
  "activity_type": "施肥",
  "activity_date": "2024-01-20",
  "description": "施用氮肥",
  "cost": 500.00,
  "operator": "张三",
  "images": ["https://example.com/image1.jpg"]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "farmland_id": 1001,
    "activity_type": "施肥",
    "activity_date": "2024-01-20",
    "description": "施用氮肥",
    "cost": 500.00,
    "operator": "张三",
    "images": ["https://example.com/image1.jpg"],
    "created_at": "2024-01-20T10:30:00Z"
  }
}
```

### 6.2 获取农事活动列表

**接口地址**: `GET /activities`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| activity_type | string | 否 | 活动类型筛选 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 活动记录列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "farmland_id": 1001,
        "activity_type": "施肥",
        "activity_date": "2024-01-20",
        "description": "施用氮肥",
        "cost": 500.00,
        "operator": "张三",
        "images": ["https://example.com/image1.jpg"],
        "created_at": "2024-01-20T10:30:00Z"
      }
    ]
  }
}
```

## 7. 作物生长监测接口

### 7.1 记录作物生长情况

**接口地址**: `POST /growth-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_date | string | 是 | 记录日期(YYYY-MM-DD) |
| growth_stage | string | 是 | 生长阶段 |
| height | number | 否 | 株高(cm) |
| leaf_count | integer | 否 | 叶片数 |
| health_status | string | 否 | 健康状况 |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_date | string | 记录日期 |
| growth_stage | string | 生长阶段 |
| height | number | 株高(cm) |
| leaf_count | integer | 叶片数 |
| health_status | string | 健康状况 |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "farmland_id": 1001,
  "record_date": "2024-01-25",
  "growth_stage": "分蘖期",
  "height": 15.5,
  "leaf_count": 6,
  "health_status": "健康",
  "notes": "生长良好",
  "images": ["https://example.com/image2.jpg"]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "farmland_id": 1001,
    "record_date": "2024-01-25",
    "growth_stage": "分蘖期",
    "height": 15.5,
    "leaf_count": 6,
    "health_status": "健康",
    "notes": "生长良好",
    "images": ["https://example.com/image2.jpg"],
    "created_at": "2024-01-25T10:30:00Z"
  }
}
```

### 7.2 获取作物生长记录列表

**接口地址**: `GET /growth-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| growth_stage | string | 否 | 生长阶段筛选 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 生长记录列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 3001,
        "farmland_id": 1001,
        "record_date": "2024-01-25",
        "growth_stage": "分蘖期",
        "height": 15.5,
        "leaf_count": 6,
        "health_status": "健康",
        "notes": "生长良好",
        "images": ["https://example.com/image2.jpg"],
        "created_at": "2024-01-25T10:30:00Z"
      }
    ]
  }
}
```

## 8. 病虫害防治接口

### 8.1 记录病虫害情况

**接口地址**: `POST /pest-disease-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_date | string | 是 | 记录日期(YYYY-MM-DD) |
| type | string | 是 | 类型(病害/虫害) |
| name | string | 是 | 病虫害名称 |
| severity | string | 是 | 严重程度(轻/中/重) |
| affected_area | number | 否 | 受害面积(亩) |
| control_method | string | 否 | 防治方法 |
| control_date | string | 否 | 防治日期(YYYY-MM-DD) |
| control_result | string | 否 | 防治效果 |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_date | string | 记录日期 |
| type | string | 类型 |
| name | string | 病虫害名称 |
| severity | string | 严重程度 |
| affected_area | number | 受害面积(亩) |
| control_method | string | 防治方法 |
| control_date | string | 防治日期 |
| control_result | string | 防治效果 |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "farmland_id": 1001,
  "record_date": "2024-01-30",
  "type": "病害",
  "name": "小麦赤霉病",
  "severity": "中",
  "affected_area": 20.0,
  "control_method": "喷施多菌灵",
  "control_date": "2024-01-31",
  "control_result": "控制良好",
  "notes": "发现较早，及时处理",
  "images": ["https://example.com/image3.jpg"]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4001,
    "farmland_id": 1001,
    "record_date": "2024-01-30",
    "type": "病害",
    "name": "小麦赤霉病",
    "severity": "中",
    "affected_area": 20.0,
    "control_method": "喷施多菌灵",
    "control_date": "2024-01-31",
    "control_result": "控制良好",
    "notes": "发现较早，及时处理",
    "images": ["https://example.com/image3.jpg"],
    "created_at": "2024-01-30T10:30:00Z"
  }
}
```

### 8.2 获取病虫害记录列表

**接口地址**: `GET /pest-disease-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| type | string | 否 | 类型筛选 |
| name | string | 否 | 病虫害名称筛选 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 病虫害记录列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 4001,
        "farmland_id": 1001,
        "record_date": "2024-01-30",
        "type": "病害",
        "name": "小麦赤霉病",
        "severity": "中",
        "affected_area": 20.0,
        "control_method": "喷施多菌灵",
        "control_date": "2024-01-31",
        "control_result": "控制良好",
        "notes": "发现较早，及时处理",
        "images": ["https://example.com/image3.jpg"],
        "created_at": "2024-01-30T10:30:00Z"
      }
    ]
  }
}
```

## 9. 环境数据监测接口

### 9.1 记录环境数据

**接口地址**: `POST /environmental-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| record_time | string | 否 | 记录时间(ISO8601格式)，默认为当前时间 |
| temperature | number | 否 | 温度(℃) |
| humidity | number | 否 | 湿度(%) |
| soil_moisture | number | 否 | 土壤湿度(%) |
| ph_value | number | 否 | 土壤pH值 |
| nitrogen | number | 否 | 氮含量(mg/kg) |
| phosphorus | number | 否 | 磷含量(mg/kg) |
| potassium | number | 否 | 钾含量(mg/kg) |
| notes | string | 否 | 备注 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| record_time | string | 记录时间 |
| temperature | number | 温度(℃) |
| humidity | number | 湿度(%) |
| soil_moisture | number | 土壤湿度(%) |
| ph_value | number | 土壤pH值 |
| nitrogen | number | 氮含量(mg/kg) |
| phosphorus | number | 磷含量(mg/kg) |
| potassium | number | 钾含量(mg/kg) |
| notes | string | 备注 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "farmland_id": 1001,
  "record_time": "2024-02-01T10:00:00Z",
  "temperature": 15.5,
  "humidity": 65.0,
  "soil_moisture": 45.0,
  "ph_value": 6.8,
  "nitrogen": 120.5,
  "phosphorus": 45.2,
  "potassium": 180.3,
  "notes": "环境适宜作物生长"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 5001,
    "farmland_id": 1001,
    "record_time": "2024-02-01T10:00:00Z",
    "temperature": 15.5,
    "humidity": 65.0,
    "soil_moisture": 45.0,
    "ph_value": 6.8,
    "nitrogen": 120.5,
    "phosphorus": 45.2,
    "potassium": 180.3,
    "notes": "环境适宜作物生长",
    "created_at": "2024-02-01T10:00:00Z"
  }
}
```

### 9.2 获取环境数据列表

**接口地址**: `GET /environmental-data`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| start_time | string | 否 | 开始时间(ISO8601格式) |
| end_time | string | 否 | 结束时间(ISO8601格式) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 环境数据列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 5001,
        "farmland_id": 1001,
        "record_time": "2024-02-01T10:00:00Z",
        "temperature": 15.5,
        "humidity": 65.0,
        "soil_moisture": 45.0,
        "ph_value": 6.8,
        "nitrogen": 120.5,
        "phosphorus": 45.2,
        "potassium": 180.3,
        "notes": "环境适宜作物生长",
        "created_at": "2024-02-01T10:00:00Z"
      }
    ]
  }
}
```

## 10. 收获管理接口

### 10.1 记录收获信息

**接口地址**: `POST /harvest-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 是 | 农田ID |
| harvest_date | string | 是 | 收获日期(YYYY-MM-DD) |
| yield | number | 是 | 产量(公斤) |
| quality | string | 否 | 质量等级 |
| storage_location | string | 否 | 存储位置 |
| selling_price | number | 否 | 销售价格(元/公斤) |
| sold_quantity | number | 否 | 已售数量(公斤) |
| notes | string | 否 | 备注 |
| images | array | 否 | 图片URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 记录ID |
| farmland_id | integer | 农田ID |
| harvest_date | string | 收获日期 |
| yield | number | 产量(公斤) |
| quality | string | 质量等级 |
| storage_location | string | 存储位置 |
| selling_price | number | 销售价格(元/公斤) |
| sold_quantity | number | 已售数量(公斤) |
| notes | string | 备注 |
| images | array | 图片URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "farmland_id": 1001,
  "harvest_date": "2024-06-15",
  "yield": 52000.0,
  "quality": "一级",
  "storage_location": "一号仓库",
  "selling_price": 2.5,
  "sold_quantity": 30000.0,
  "notes": "丰收年，质量上乘",
  "images": ["https://example.com/image4.jpg"]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 6001,
    "farmland_id": 1001,
    "harvest_date": "2024-06-15",
    "yield": 52000.0,
    "quality": "一级",
    "storage_location": "一号仓库",
    "selling_price": 2.5,
    "sold_quantity": 30000.0,
    "notes": "丰收年，质量上乘",
    "images": ["https://example.com/image4.jpg"],
    "created_at": "2024-06-15T10:30:00Z"
  }
}
```

### 10.2 获取收获记录列表

**接口地址**: `GET /harvest-records`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| farmland_id | integer | 否 | 农田ID筛选 |
| start_date | string | 否 | 开始日期(YYYY-MM-DD) |
| end_date | string | 否 | 结束日期(YYYY-MM-DD) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 收获记录列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 6001,
        "farmland_id": 1001,
        "harvest_date": "2024-06-15",
        "yield": 52000.0,
        "quality": "一级",
        "storage_location": "一号仓库",
        "selling_price": 2.5,
        "sold_quantity": 30000.0,
        "notes": "丰收年，质量上乘",
        "images": ["https://example.com/image4.jpg"],
        "created_at": "2024-06-15T10:30:00Z"
      }
    ]
  }
}
```

## 11. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 农田不存在 | 指定的农田不存在 |
| 40003 | 农田状态不允许此操作 | 当前农田状态不允许执行该操作 |
| 40004 | 农事活动记录不存在 | 指定的农事活动记录不存在 |
| 40005 | 作物生长记录不存在 | 指定的作物生长记录不存在 |
| 40006 | 病虫害记录不存在 | 指定的病虫害记录不存在 |
| 40007 | 环境数据记录不存在 | 指定的环境数据记录不存在 |
| 40008 | 收获记录不存在 | 指定的收获记录不存在 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |