first commit

This commit is contained in:
WIN-20230613SRA\Administrator
2026-07-02 16:07:26 +08:00
commit c4a347b287
17 changed files with 2924 additions and 0 deletions
+328
View File
@@ -0,0 +1,328 @@
# Python Gateway HTTP API 接口文档
## 概述
Python Gateway HTTP Server 提供RESTful API接口,用于文件上传、计算处理、设备管理和状态查询。
**服务器地址**: `http://<host>:<port>`
**默认端口**: `5000`
**当前版本**: `1.0.0` (在version.py中管理)
**Content-Type**: `application/json` 或 `multipart/form-data`
---
## API 接口列表
### 1. 上传数据并计算
**接口地址**: `/api/data`
**请求方法**: `POST`
**Content-Type**: `multipart/form-data`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | File | 是 | 要上传的文件(CSV格式) |
| dev_id | String | 否 | 设备ID,默认为'default' |
| init | Integer | 否 | 初始化标志(0或1),默认为0 |
| device_name | String | 否 | 设备名称,用于设置文件根目录 |
| file_type | String | 否 | 文件类型,默认为'raw' |
| compress | String | 否 | 压缩类型('none'或'gz'),默认为'none' |
| scale | Float | 否 | 数据缩放因子,默认为1.0 |
| offset | Float | 否 | 数据偏移量,默认为0.0 |
| row_count | Integer | 否 | 行数限制,默认为0(不限制) |
#### 请求示例
```bash
curl -X POST http://localhost:5000/api/data \
-F "file=@data.csv" \
-F "dev_id=device1" \
-F "init=0" \
-F "device_name=TGX-08-0005"
```
#### 响应格式
成功响应(200 OK):
```json
{
"WtOSC": [1.234, 2.345, 3.456, 4.567, 5.678, 6.789, 7.890, 8.901],
"WtINS": [2.345, 3.456, 4.567, 5.678, 6.789, 7.890, 8.901, 9.012],
"WtISC": [3.456, 4.567, 5.678, 6.789, 7.890, 8.901, 9.012, 10.123],
"WtALL": [4.567, 5.678, 6.789, 7.890, 8.901, 9.012, 10.123, 11.234],
"AngOSC": [95.5, 185.3, 275.1],
"AngINS": [105.2, 195.0, 284.8],
"AngISC": [115.1, 204.9, 294.7],
"AngALL": [125.0, 214.8, 304.6],
"DmCORE": [100.5, 101.2, 102.3],
"DmALL": [120.5, 121.2, 122.3],
"EccentricityINS": 2.5,
"EccentricityOSC": 3.2,
"EccentricityISC": 1.8,
"Volatility": [0.05, 0.08, 0.12],
"EdgesA": [10.5, 20.3, 30.1, 40.9, 50.7, 60.5, 70.3, 80.1],
"EdgesB": [15.5, 25.3, 35.1, 45.9, 55.7, 65.5, 75.3, 85.1]
}
```
错误响应(400 Bad Request):
```json
{
"error": "No file provided"
}
```
或
```json
{
"error": "Failed to process file"
}
```
或
```json
{
"error": "ComputeService not initialized for dev_id device1"
}
```
#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| WtOSC | Array[Float] | 外屏层壁厚(8个测量点) |
| WtINS | Array[Float] | 绝缘层壁厚(8个测量点) |
| WtISC | Array[Float] | 内屏层壁厚(8个测量点) |
| WtALL | Array[Float] | 总壁厚(8个测量点) |
| AngOSC | Array[Float] | 外屏层角度(3个角度值) |
| AngINS | Array[Float] | 绝缘层角度(3个角度值) |
| AngISC | Array[Float] | 内屏层角度(3个角度值) |
| AngALL | Array[Float] | 总壁厚角度(3个角度值) |
| DmCORE | Array[Float] | 核心直径(3个测量值) |
| DmALL | Array[Float] | 总直径(3个测量值) |
| EccentricityINS | Float | 绝缘层偏心率(百分比) |
| EccentricityOSC | Float | 外屏层偏心率(百分比) |
| EccentricityISC | Float | 内屏层偏心率(百分比) |
| Volatility | Array[Float] | 波动性[设备1标准差, 设备2标准差, 总体标准差] |
| EdgesA | Array[Float] | A边边缘位置(8个点) |
| EdgesB | Array[Float] | B边边缘位置(8个点) |
---
### 2. 获取服务器状态
**接口地址**: `/api/status`
**请求方法**: `GET`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| dev_id | String | 否 | 设备ID,如果不提供则返回服务器基本状态 |
#### 请求示例
示例1:获取服务器基本状态
```bash
curl -X GET http://localhost:5000/api/status
```
示例2:获取特定设备状态
```bash
curl -X GET "http://localhost:5000/api/status?dev_id=device1"
```
#### 响应格式
成功响应 - 基本状态(200 OK):
```json
{
"running": "true",
"mqtt_connected": true,
"version": "1.0.0"
}
```
或
```json
{
"running": "false",
"mqtt_connected": false,
"version": "1.0.0"
}
```
成功响应 - 设备状态(200 OK):
```json
{
"running": true,
"mqtt_connected": true,
"compute_status": true,
"version": "1.0.0"
}
```
或
```json
{
"running": true,
"mqtt_connected": true,
"compute_status": false,
"version": "1.0.0"
}
```
#### 响应字段说明
| 字段名 | 类型 | 说明 |
|--------|------|------|
| running | String/Boolean | 服务器运行状态(不带dev_id时为字符串"true"/"false",带dev_id时为布尔值) |
| mqtt_connected | Boolean | MQTT连接状态 |
| compute_status | Boolean | 计算服务可用状态(仅当提供dev_id时返回) |
| version | String | 软件版本号 |
---
### 3. 注册设备
**接口地址**: `/api/register`
**请求方法**: `POST`
**Content-Type**: `application/json`
#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| dev_id | String | 是 | 设备ID |
#### 请求示例
```bash
curl -X POST http://localhost:5000/api/register \
-H "Content-Type: application/json" \
-d '{"dev_id": "device1"}'
```
#### 响应格式
成功响应(200 OK):
```json
{
"message": "Device registered successfully"
}
```
错误响应(400 Bad Request):
```json
{
"error": "dev_id is required"
}
```
或
```json
{
"error": "Failed to initialize ComputeService: ..."
}
```
---
## 错误码说明
| HTTP状态码 | 说明 |
|-----------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |
---
## 使用场景示例
### 场景1:首次上传数据并计算
```bash
# 上传CSV文件并计算
curl -X POST http://localhost:5000/api/data \
-F "file=@measurement_data.csv" \
-F "dev_id=device1" \
-F "init=1" \
-F "device_name=TGX-08-0005"
```
### 场景2:连续上传数据
```bash
# 后续上传,init=0
curl -X POST http://localhost:5000/api/data \
-F "file=@measurement_data_002.csv" \
-F "dev_id=device1" \
-F "init=0"
```
### 场景3:检查服务器状态
```bash
# 查询服务器状态
curl -X GET http://localhost:5000/api/status
```
### 场景4:注册新设备
```bash
# 注册新设备
curl -X POST http://localhost:5000/api/register \
-H "Content-Type: application/json" \
-d '{"dev_id": "device2"}'
```
---
## 注意事项
1. **文件格式**: 上传的文件应为CSV格式,包含CH1和CH2两列数据
2. **设备ID**: 每个设备需要先通过`/api/register`接口注册,才能进行计算
3. **初始化**: 首次上传数据时建议设置`init=1`,后续上传设置`init=0`
4. **文件大小**: 建议单次上传文件不超过10MB
5. **并发处理**: 服务器支持多线程并发处理请求
6. **MQTT发布**: 计算结果会自动发布到MQTT主题(如果MQTT已启用)
---
## 配置说明
服务器配置存储在`config.json`文件中,主要配置项:
```json
{
"http": {
"host": "0.0.0.0",
"port": 5000
},
"mqtt": {
"enable": true,
"broker": "123.57.81.127",
"port": 1883,
"username": "test",
"password": "test"
},
"file_root": "D:\\CPY_DTAT",
"template_path": "D:\\Python\\CPY_Server\\InStructTemplate.mat"
}
```
---
## 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| 1.0.0 | 2026-01-05 | 初始版本,支持数据上传、计算和设备管理 |