# 外部系统联动 - 决策API接口重构完成

## 📋 更新概述

将外部系统联动功能重构为**以决策为中心的API接口展示系统**，为每个决策提供标准的RESTful API接口，支持外部系统通过HTTP请求获取决策详情。

## ✅ 核心变更

### 1. **从系统管理转向决策API展示**

**原有架构：** 
- 管理外部系统连接
- 推送记录追踪
- 系统状态监控

**新架构：**
- **决策列表展示**
- **每个决策的API接口**
- **接口文档和调用示例**

### 2. **三大功能模块**

#### 📋 **决策列表**
展示所有可通过API调用的决策，包含完整的接口信息

#### 📖 **接口文档**
提供标准的RESTful API文档，包括认证方式、请求格式、响应格式等

#### 💻 **调用示例**
提供多种编程语言的API调用代码示例

## 🎯 功能详情

### **决策列表模块**

#### 决策信息展示
- ✅ 决策编号（如：DEC-20241023-001）
- ✅ 决策标题
- ✅ 决策类型（灌溉、施肥、病虫害、播种、收获、气象预警）
- ✅ 地块信息
- ✅ 作物类型
- ✅ 执行状态
- ✅ 优先级
- ✅ 创建时间

#### API接口信息
每个决策都显示完整的API信息：

```
GET https://api.smart-farm.com/api/v1/decisions/irrigation/dec_001
```

**接口特性：**
- 🔑 **需要认证**：Bearer Token认证
- 📝 **请求方法**：GET
- 🔗 **完整URL**：包含decisionId参数
- 📄 **接口描述**：说明接口功能

#### 快捷操作
每个决策提供以下快捷操作：

1. **复制URL** - 复制API接口地址
2. **cURL示例** - 生成cURL命令
3. **请求示例** - 复制完整的请求参数
4. **响应示例** - 复制响应数据示例
5. **测试API** - 一键测试接口连通性

### **接口文档模块**

#### 基本信息
```
接口域名: https://api.smart-farm.com
API版本: v1
数据格式: JSON
字符编码: UTF-8
```

#### 认证方式
```http
Authorization: Bearer YOUR_ACCESS_TOKEN
```
所有接口都需要在请求头中包含访问令牌

#### 请求示例
```http
GET /api/v1/decisions/irrigation/dec_001 HTTP/1.1
Host: api.smart-farm.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json
```

#### 响应格式
```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 决策数据
  }
}
```

#### 错误码说明
- `200` - 请求成功
- `400` - 请求参数错误
- `401` - 未授权，令牌无效或过期
- `404` - 资源不存在
- `429` - 请求过于频繁
- `500` - 服务器内部错误

#### 频率限制
- 每个令牌：**100次/分钟**
- 超出限制返回429错误

### **调用示例模块**

提供4种主流编程语言的调用示例：

#### 1. **cURL**
```bash
curl -X GET "https://api.smart-farm.com/api/v1/decisions/irrigation/dec_001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

#### 2. **JavaScript (Fetch API)**
```javascript
async function getDecisionDetail(decisionId, type) {
  const response = await fetch(
    `https://api.smart-farm.com/api/v1/decisions/${type}/${decisionId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
      }
    }
  );
  
  const data = await response.json();
  return data;
}
```

#### 3. **Python (requests库)**
```python
import requests

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json()
```

#### 4. **Java (HttpURLConnection)**
```java
con.setRequestMethod("GET");
con.setRequestProperty("Authorization", "Bearer " + ACCESS_TOKEN);
con.setRequestProperty("Content-Type", "application/json");
```

## 📊 样例数据

系统包含6个完整的决策样例：

### 1. **灌溉决策** - 1号大棚番茄开花期
```json
{
  "irrigation": {
    "waterAmount": 120,
    "duration": 45,
    "startTime": "17:00",
    "method": "滴灌"
  },
  "conditions": {
    "soilMoisture": 45,
    "temperature": 24.5,
    "humidity": 68
  }
}
```

### 2. **施肥决策** - 3号地块小麦拔节期
```json
{
  "fertilizers": [
    { "type": "尿素", "amount": 50, "unit": "kg/亩" },
    { "type": "磷酸二铵", "amount": 30, "unit": "kg/亩" }
  ],
  "soilAnalysis": {
    "pH": 6.8,
    "nitrogen": "medium",
    "phosphorus": "low"
  }
}
```

### 3. **病虫害防治** - 番茄晚疫病
```json
{
  "pest": {
    "name": "番茄晚疫病",
    "severity": "high",
    "infectionRate": 15
  },
  "control": {
    "pesticides": [{
      "name": "甲霜灵锰锌",
      "concentration": "500倍液"
    }]
  }
}
```

### 4. **播种计划** - 4号地块玉米
```json
{
  "sowing": {
    "variety": "先玉335",
    "sowingDate": "2024-04-15",
    "density": 4500,
    "depth": "3-5cm"
  }
}
```

### 5. **收获计划** - 6号地块水稻
```json
{
  "harvest": {
    "estimatedDate": "2024-10-28",
    "estimatedYield": 550,
    "maturity": {
      "progress": 95,
      "grainMoisture": 22
    }
  }
}
```

### 6. **气象预警** - 强降雨防护
```json
{
  "weather": {
    "alertType": "暴雨预警",
    "alertLevel": "橙色",
    "rainfall": 50
  },
  "protection": {
    "urgentMeasures": [
      "关闭通风口",
      "加固大棚",
      "清理排水沟"
    ]
  }
}
```

## 🎨 UI特性

### 决策卡片设计
- **图标展示**：每种决策类型有专属图标
  - 💧 灌溉决策 - Droplets
  - 🌱 施肥决策 - Sprout
  - 🐛 病虫害防治 - Bug
  - 📦 播种计划 - Package
  - 📊 收获计划 - BarChart3
  - ☁️ 气象预警 - CloudRain

- **状态标签**：
  - 🟡 待执行
  - 🔵 执行中
  - 🟢 已完成
  - ⚪ 已取消

- **优先级标签**：
  - ⚪ 低
  - 🔵 中
  - 🟠 高
  - 🔴 紧急

### API信息展示
- 灰色背景区域突出显示
- 方法标签（GET=绿色, POST=蓝色）
- 认证标识（黄色徽章）
- 单行代码展示，支持复制

### 筛选功能
- 🔍 **搜索框**：按决策编号或标题搜索
- 🏷️ **类型筛选**：按决策类型筛选

## 💡 使用场景

### 1. **第三方系统集成**
外部业务系统可以通过API获取决策信息：
- 农事管理系统获取施肥决策
- 灌溉控制系统获取灌溉计划
- ERP系统获取资源需求

### 2. **移动应用开发**
移动端App可以调用API展示决策：
```javascript
// 在移动端App中获取决策列表
const decisions = await getDecisions('irrigation');
```

### 3. **数据分析平台**
数据分析系统可以批量获取决策数据：
```python
# 批量获取决策进行分析
for decision_id in decision_ids:
    data = get_decision_detail(decision_id, type)
    analyze(data)
```

### 4. **智能硬件设备**
IoT设备可以获取决策并自动执行：
```java
// 获取灌溉决策并下发到设备
Decision decision = getDecisionDetail("dec_001", "irrigation");
irrigationDevice.execute(decision.getData());
```

## 🔒 安全特性

### 1. **访问令牌认证**
- 所有接口都需要Bearer Token
- 令牌需要妥善保管，不可泄露

### 2. **频率限制**
- 100次/分钟，防止滥用
- 超限自动限流保护

### 3. **HTTPS传输**
- 建议使用HTTPS协议
- 确保数据传输安全

## 📈 统计信息

页面顶部展示4个统计卡片：

1. **决策总数** - 可调用API接口数量
2. **待执行** - 等待执行的决策数
3. **执行中** - 正在执行的决策数
4. **已完成** - 已完成的决策数

## 🎯 快速开始

### 步骤1: 获取访问令牌
联系系统管理员获取您的访问令牌

### 步骤2: 选择决策
在决策列表中找到您需要的决策

### 步骤3: 查看API信息
查看决策卡片中的API接口地址

### 步骤4: 复制示例代码
点击"cURL示例"或其他按钮复制代码

### 步骤5: 调用API
使用您熟悉的编程语言调用API

### 步骤6: 测试接口
点击"测试API"按钮验证接口可用性

## 📝 注意事项

1. ✅ 妥善保管访问令牌，不要泄露
2. ✅ 实现请求失败重试机制
3. ✅ 遵守API频率限制
4. ✅ 使用HTTPS协议确保安全
5. ✅ 实现错误处理和日志记录

## 🔄 后续规划

### 短期计划
- [ ] 添加Webhook推送功能
- [ ] 支持批量获取决策接口
- [ ] 添加API调用日志查询
- [ ] 提供Postman Collection下载

### 长期规划
- [ ] 支持GraphQL接口
- [ ] 提供SDK开发包（Python、Java、Node.js）
- [ ] 添加实时数据订阅功能
- [ ] 支持自定义字段筛选

## 🎓 技术细节

### 接口路径规范
```
/api/v1/decisions/{type}/{decisionId}
```

**类型(type)映射：**
- irrigation - 灌溉决策
- fertilization - 施肥决策
- pest_control - 病虫害防治
- sowing - 播种计划
- harvest - 收获计划
- weather_alert - 气象预警

### 响应数据结构
所有决策响应都包含以下标准字段：
- `decisionId` - 决策ID
- `decisionNo` - 决策编号
- `title` - 决策标题
- `type` - 决策类型
- `field` - 地块信息
- `confidence` - 置信度
- `createdAt` - 创建时间
- `status` - 执行状态
- `recommendation` - 建议说明

## 📞 技术支持

如有问题，请联系：
- 📧 Email: api-support@smart-farm.com
- 📱 电话: 400-xxx-xxxx
- 💬 在线客服: 工作日 9:00-18:00

---

**更新时间:** 2024-10-23  
**版本:** v2.0.0  
**状态:** ✅ 已完成并上线
