# 透析机IoT数据服务 - 快速入门指南

**目标受众**: 第三方开发者  
**预计时间**: 5-10分钟

---

## 🎯 30秒快速开始

### 1. 验证服务可用

```bash
curl http://localhost:8080/api/health
```

**预期输出**:
```json
{"code":200,"message":"success","data":{"status":"ok"}}
```

### 2. 获取设备列表

```bash
curl "http://localhost:8080/api/device/list"
```

### 3. 查询设备数据

```bash
curl "http://localhost:8080/api/device/data?deviceNumber=D001&mapped=true"
```

---

## 📦 完整集成示例

### 场景：监控透析机实时数据

#### 方案A：JavaScript/Node.js（推荐）

```javascript
const http = require('http');

class DeviceMonitor {
  constructor(serverUrl = 'http://localhost:8080') {
    this.serverUrl = serverUrl;
  }

  // 获取设备数据
  async getDeviceData(deviceNumber) {
    return this.request(
      `/api/device/data?deviceNumber=${deviceNumber}&mapped=true`
    );
  }

  // 获取所有设备
  async getAllDevices() {
    return this.request('/api/device/all?mapped=true');
  }

  // 获取设备列表
  async getDeviceList() {
    return this.request('/api/device/list');
  }

  // 发起HTTP请求
  request(path) {
    return new Promise((resolve, reject) => {
      const url = new URL(path, this.serverUrl);
      const http = require('http');

      http.get(url, (res) => {
        let data = '';
        res.on('data', chunk => data += chunk);
        res.on('end', () => {
          try {
            resolve(JSON.parse(data));
          } catch (e) {
            reject(e);
          }
        });
      }).on('error', reject);
    });
  }
}

// 使用示例
async function main() {
  const monitor = new DeviceMonitor();

  try {
    // 获取设备列表
    console.log('正在获取设备列表...');
    const devices = await monitor.getDeviceList();
    console.log(`找到 ${devices.data.count} 个设备`);

    // 查询每个设备
    for (const device of devices.data.devices) {
      console.log(`\n正在查询设备: ${device.deviceNumber}`);
      const data = await monitor.getDeviceData(device.deviceNumber);
      
      if (data.code === 200) {
        const props = data.data.properties;
        props.forEach(prop => {
          console.log(`  ${prop.name}: ${prop.value}`);
        });
      } else if (data.code === 429) {
        console.log(`  [限流] ${data.message}`);
      }
    }
  } catch (error) {
    console.error('错误:', error);
  }
}

main();
```

#### 方案B：Python（适合数据分析）

```python
import requests
import json
import time
from datetime import datetime

class DeviceMonitor:
    def __init__(self, server_url='http://localhost:8080'):
        self.server_url = server_url
        self.session = requests.Session()
        self.session.headers.update({'Accept': 'application/json'})

    def get_device_data(self, device_number):
        """获取单个设备数据"""
        url = f'{self.server_url}/api/device/data'
        params = {
            'deviceNumber': device_number,
            'mapped': 'true'
        }
        return self._request(url, params)

    def get_all_devices(self):
        """获取所有设备数据"""
        url = f'{self.server_url}/api/device/all'
        params = {'mapped': 'true'}
        return self._request(url, params)

    def get_device_list(self):
        """获取设备列表"""
        url = f'{self.server_url}/api/device/list'
        return self._request(url)

    def _request(self, url, params=None):
        """发起HTTP请求"""
        try:
            response = self.session.get(url, params=params, timeout=5)
            return response.json()
        except requests.RequestException as e:
            print(f'请求失败: {e}')
            return None

# 使用示例
if __name__ == '__main__':
    monitor = DeviceMonitor()

    # 获取设备列表
    print('获取设备列表...')
    result = monitor.get_device_list()
    
    if result and result['code'] == 200:
        print(f"找到 {result['data']['count']} 个设备\n")
        
        # 查询每个设备的数据
        for device in result['data']['devices']:
            device_number = device['deviceNumber']
            print(f"设备: {device_number}")
            
            data = monitor.get_device_data(device_number)
            if data and data['code'] == 200:
                for prop in data['data']['properties']:
                    print(f"  {prop['name']}: {prop['value']}")
            elif data and data['code'] == 429:
                print(f"  [限流] {data['message']}")
            print()
```

#### 方案C：cURL（快速测试）

```bash
#!/bin/bash

# 服务器地址
SERVER="http://localhost:8080"

echo "=== 健康检查 ==="
curl -s "$SERVER/api/health" | jq .

echo -e "\n=== 设备列表 ==="
curl -s "$SERVER/api/device/list" | jq '.data.devices'

echo -e "\n=== 第一个设备的详细数据 ==="
DEVICE_NUMBER=$(curl -s "$SERVER/api/device/list" | jq -r '.data.devices[0].deviceNumber')
echo "查询设备: $DEVICE_NUMBER"
curl -s "$SERVER/api/device/data?deviceNumber=$DEVICE_NUMBER&mapped=true" | jq '.data.properties'

echo -e "\n=== 所有设备摘要 ==="
curl -s "$SERVER/api/device/all?mapped=true" | jq '.data | keys'
```

运行脚本:
```bash
chmod +x monitor.sh
./monitor.sh
```

---

## ⚠️ 常见陷阱

### 陷阱1：触发限流

❌ **错误做法** - 连续快速请求：
```bash
for i in {1..5}; do
  curl "http://localhost:8080/api/device/data?deviceNumber=D001&mapped=true"
done
# 后4个请求会返回 429 Too Many Requests
```

✅ **正确做法** - 使用批量查询：
```bash
# 一次获取所有设备，而不是逐个查询
curl "http://localhost:8080/api/device/all?mapped=true"
```

或添加延迟：
```bash
for i in {1..5}; do
  curl "http://localhost:8080/api/device/data?deviceNumber=D001&mapped=true"
  sleep 6  # 等待6秒
done
```

### 陷阱2：忘记映射设备号

❌ **容易困惑**：
```json
{"A": "50", "B": "25", "C": "10"}  // 原始格式，看不懂
```

✅ **清晰易懂**：
```json
[
  {"name": "脱水目标量", "value": "50"},
  {"name": "脱水量", "value": "25"},
  {"name": "脱水速率", "value": "10"}
]
```

**永远使用**: `?mapped=true`

### 陷阱3：处理中文编码

❌ **可能乱码**：
```python
response = requests.get(url)
data = response.text  # 如果没有正确设置编码
```

✅ **正确方式**：
```python
response = requests.get(url)
response.encoding = 'utf-8'  # 明确指定编码
data = response.json()  # JSON自动处理编码
```

### 陷阱4：没有错误处理

❌ **容易崩溃**：
```javascript
const data = await fetch(url).then(r => r.json());
console.log(data.data.properties[0].name);  // 如果请求失败，直接崩溃
```

✅ **健壮的代码**：
```javascript
try {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }
  const data = await response.json();
  if (data.code !== 200) {
    throw new Error(data.message);
  }
  return data.data;
} catch (error) {
  console.error('获取数据失败:', error);
  return null;
}
```

---

## 📊 属性参考表

系统支持68个设备属性，以下是常用属性示例：

| 标识符 | 中文名称 | 说明 | 数据类型 |
|--------|---------|------|---------|
| A | 脱水目标量 | 目标脱水量 | float |
| B | 脱水量 | 当前已脱水量 | float |
| C | 脱水速率 | 脱水速率 | float |
| D | 置换液输入速度 | mL/min | float |
| E | 置换液输出速度 | mL/min | float |
| R | 收缩压下限 | mmHg | int |
| S | 收缩压上限 | mmHg | int |
| mb | 脉搏-德朗 | 心率 | int |
| deviceName | 设备名称 | 设备标识 | string |
| IPAddress | IP地址 | 设备IP | string |

更多属性请查看完整API文档。

---

## 🔍 调试技巧

### 1. 使用Postman或Insomnia

**安装**: 下载 [Postman](https://www.postman.com/downloads/) 或 [Insomnia](https://insomnia.rest/download)

**步骤**:
1. 创建新请求
2. URL: `http://localhost:8080/api/device/list`
3. 点击 Send
4. 查看响应

### 2. 使用在线工具测试

访问 [ReqBin](https://reqbin.com/) 或 [REST Client](https://www.restclient.com/):

```
GET http://localhost:8080/api/device/list HTTP/1.1
Host: localhost:8080
Accept: application/json
```

### 3. 浏览器控制台测试

在浏览器console执行：
```javascript
fetch('http://localhost:8080/api/device/list')
  .then(r => r.json())
  .then(d => console.table(d.data.devices))
```

### 4. 性能测试

```bash
# 使用 ab (Apache Bench)
ab -n 100 -c 10 http://localhost:8080/api/health

# 使用 wrk
wrk -t12 -c400 -d30s http://localhost:8080/api/health
```

---

## 🚀 进阶用法

### 定期监控和告警

```javascript
class DeviceAlertSystem {
  constructor(serverUrl, checkInterval = 30000) {
    this.serverUrl = serverUrl;
    this.checkInterval = checkInterval;
    this.thresholds = {
      maxDehydrationRate: 50,  // 最大脱水速率
      minBloodPressure: 80,    // 最小血压
    };
  }

  async start() {
    console.log('监控系统已启动');
    setInterval(() => this.check(), this.checkInterval);
  }

  async check() {
    try {
      const response = await fetch(`${this.serverUrl}/api/device/all?mapped=true`);
      const data = await response.json();

      if (data.code === 200) {
        Object.entries(data.data.data).forEach(([deviceId, deviceData]) => {
          this.checkThresholds(deviceId, deviceData.properties);
        });
      }
    } catch (error) {
      console.error('检查失败:', error);
    }
  }

  checkThresholds(deviceId, properties) {
    properties.forEach(prop => {
      // 检查脱水速率是否过高
      if (prop.name === '脱水速率' && parseFloat(prop.value) > this.thresholds.maxDehydrationRate) {
        this.alert(`设备 ${deviceId} 脱水速率过高: ${prop.value}`);
      }
      
      // 检查血压是否过低
      if (prop.name === '收缩压' && parseFloat(prop.value) < this.thresholds.minBloodPressure) {
        this.alert(`设备 ${deviceId} 血压过低: ${prop.value}`);
      }
    });
  }

  alert(message) {
    console.warn(`⚠️  告警: ${message}`);
    // 这里可以发送邮件、短信等
  }
}

// 启动监控
const system = new DeviceAlertSystem('http://localhost:8080', 30000);
system.start();
```

### 数据导出到CSV

```python
import requests
import csv
from datetime import datetime

def export_device_data_to_csv(server_url, filename):
    """导出所有设备数据到CSV文件"""
    
    response = requests.get(f'{server_url}/api/device/all?mapped=true')
    data = response.json()
    
    with open(filename, 'w', newline='', encoding='utf-8') as f:
        writer = csv.writer(f)
        
        # 写表头
        writer.writerow(['设备号', '时间戳', '属性名', '值'])
        
        # 写数据
        for device_id, device_data in data['data']['data'].items():
            timestamp = device_data['timestamp']
            for prop in device_data['properties']:
                writer.writerow([
                    device_id,
                    timestamp,
                    prop['name'],
                    prop['value']
                ])
    
    print(f'数据已导出到: {filename}')

# 使用
export_device_data_to_csv('http://localhost:8080', 'devices.csv')
```

---

## 📞 需要帮助？

### 检查清单

- [ ] 服务器地址和端口正确
- [ ] 防火墙允许访问8080端口
- [ ] 网络连接正常（ping测试）
- [ ] 已调用 `/api/health` 验证服务
- [ ] 请求格式正确（参数名和类型）
- [ ] 没有触发限流（检查 `/api/ratelimit/stats`）

### 获取支持

1. 查看完整文档: `HTTP_API_INTEGRATION_GUIDE.md`
2. 查看OpenAPI规范: `openapi.json`
3. 检查服务日志
4. 联系技术支持团队

---

**版本**: v1.1.0  
**最后更新**: 2025-12-08