# AI服务API设计文档

## 1. 概述

本文档详细描述了AI服务(ai-service)提供的API接口，包括智能问答、图像识别、数据分析等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/ai`
- 版本: 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 /qa/ask`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| question | string | 是 | 用户问题 |
| context | object | 否 | 上下文信息 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 问答记录ID |
| question | string | 用户问题 |
| answer | string | AI回答 |
| model_version | string | 使用的模型版本 |
| processing_time | integer | 处理耗时(毫秒) |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "question": "如何防治小麦赤霉病？",
  "context": {
    "crop": "小麦",
    "region": "华北地区"
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "question": "如何防治小麦赤霉病？",
    "answer": "小麦赤霉病防治方法：1.选用抗病品种；2.合理施肥，避免氮肥过量；3.及时排水，降低田间湿度；4.药剂防治，在抽穗扬花期喷施多菌灵等杀菌剂。",
    "model_version": "v1.2.0",
    "processing_time": 1200,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.2 获取问答历史

**接口地址**: `GET /qa/history`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

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

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "question": "如何防治小麦赤霉病？",
        "answer": "小麦赤霉病防治方法：1.选用抗病品种；2.合理施肥，避免氮肥过量；3.及时排水，降低田间湿度；4.药剂防治，在抽穗扬花期喷施多菌灵等杀菌剂。",
        "model_version": "v1.2.0",
        "processing_time": 1200,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 6. 图像识别接口

### 6.1 上传图片进行识别

**接口地址**: `POST /image/recognize`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| image_url | string | 是 | 图片URL |
| recognition_type | string | 是 | 识别类型(PestAndDisease/Plant/Crop等) |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 识别记录ID |
| image_url | string | 图片URL |
| recognition_type | string | 识别类型 |
| result | object | 识别结果 |
| confidence | number | 置信度 |
| processing_time | integer | 处理耗时(毫秒) |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "image_url": "https://example.com/image1.jpg",
  "recognition_type": "PestAndDisease"
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "image_url": "https://example.com/image1.jpg",
    "recognition_type": "PestAndDisease",
    "result": {
      "name": "小麦赤霉病",
      "description": "一种常见的小麦病害，主要危害小麦的穗部",
      "prevention": "1.选用抗病品种；2.合理施肥；3.及时排水；4.药剂防治"
    },
    "confidence": 0.9567,
    "processing_time": 2500,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.2 获取识别历史

**接口地址**: `GET /image/history`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| recognition_type | string | 否 | 识别类型筛选 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

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

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "image_url": "https://example.com/image1.jpg",
        "recognition_type": "PestAndDisease",
        "result": {
          "name": "小麦赤霉病",
          "description": "一种常见的小麦病害，主要危害小麦的穗部"
        },
        "confidence": 0.9567,
        "processing_time": 2500,
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 7. 数据分析接口

### 7.1 创建分析任务

**接口地址**: `POST /analysis/tasks`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| task_name | string | 是 | 任务名称 |
| task_type | string | 是 | 任务类型(YieldPrediction/PriceAnalysis等) |
| input_data | object | 是 | 输入数据 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| task_name | string | 任务名称 |
| task_type | string | 任务类型 |
| status | string | 任务状态 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "task_name": "2024年小麦产量预测",
  "task_type": "YieldPrediction",
  "input_data": {
    "crop": "小麦",
    "region": "华北地区",
    "planting_area": 10000,
    "historical_data": [
      {"year": 2021, "yield": 500},
      {"year": 2022, "yield": 520},
      {"year": 2023, "yield": 510}
    ]
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "task_name": "2024年小麦产量预测",
    "task_type": "YieldPrediction",
    "status": "PENDING",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 7.2 查询任务状态

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 任务ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 任务ID |
| task_name | string | 任务名称 |
| task_type | string | 任务类型 |
| input_data | object | 输入数据 |
| result | object | 分析结果 |
| status | string | 任务状态 |
| processing_time | integer | 处理耗时(毫秒) |
| error_message | string | 错误信息 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "task_name": "2024年小麦产量预测",
    "task_type": "YieldPrediction",
    "input_data": {
      "crop": "小麦",
      "region": "华北地区",
      "planting_area": 10000,
      "historical_data": [
        {"year": 2021, "yield": 500},
        {"year": 2022, "yield": 520},
        {"year": 2023, "yield": 510}
      ]
    },
    "result": {
      "predicted_yield": 515,
      "confidence": 0.85,
      "factors": ["气候条件", "土壤质量", "种植技术"]
    },
    "status": "COMPLETED",
    "processing_time": 5000,
    "error_message": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:05Z"
  }
}
```

### 7.3 获取任务列表

**接口地址**: `GET /analysis/tasks`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| task_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": 3001,
        "task_name": "2024年小麦产量预测",
        "task_type": "YieldPrediction",
        "status": "COMPLETED",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

## 8. 用户反馈接口

### 8.1 提交反馈

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

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| service_type | string | 是 | 服务类型(QA/IMAGE_RECOGNITION/ANALYSIS) |
| record_id | integer | 是 | 相关记录ID |
| rating | integer | 是 | 评分(1-5星) |
| feedback | string | 否 | 反馈内容 |
| is_helpful | boolean | 是 | 是否有帮助 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 反馈ID |
| service_type | string | 服务类型 |
| record_id | integer | 相关记录ID |
| rating | integer | 评分 |
| feedback | string | 反馈内容 |
| is_helpful | boolean | 是否有帮助 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "service_type": "QA",
  "record_id": 1001,
  "rating": 5,
  "feedback": "回答很详细，很有帮助",
  "is_helpful": true
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 4001,
    "service_type": "QA",
    "record_id": 1001,
    "rating": 5,
    "feedback": "回答很详细，很有帮助",
    "is_helpful": true,
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## 9. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 40001 | 参数错误 | 请求参数不合法 |
| 40002 | 问答记录不存在 | 指定的问答记录不存在 |
| 40003 | 图像识别记录不存在 | 指定的图像识别记录不存在 |
| 40004 | 分析任务不存在 | 指定的分析任务不存在 |
| 40005 | 不支持的识别类型 | 指定的识别类型不被支持 |
| 40006 | 不支持的任务类型 | 指定的任务类型不被支持 |
| 40007 | 任务状态不允许此操作 | 当前任务状态不允许执行该操作 |
| 50001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 50002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |