787 lines
16 KiB
Markdown
787 lines
16 KiB
Markdown
# 电动扳手系统 API 接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **基础URL**: `http://localhost:5000`
|
||
- **API前缀**: `/api`
|
||
- **数据格式**: JSON
|
||
- **字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [工单管理](#工单管理)
|
||
2. [扳手设备管理](#扳手设备管理)
|
||
3. [执行结果查询](#执行结果查询)
|
||
4. [系统健康检查](#系统健康检查)
|
||
|
||
---
|
||
|
||
## 工单管理
|
||
|
||
### 1. 查询工单列表
|
||
|
||
**接口地址**: `GET /api/work-orders`
|
||
|
||
**接口描述**: 查询可用工单列表
|
||
|
||
**请求参数** (Query Parameters):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 否 | 追溯号 |
|
||
| process_id | string | 否 | 工序号 |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/work-orders
|
||
GET /api/work-orders?trace_id=TR20260119001&process_id=P001
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"product_name": "产品A",
|
||
"operator": "操作员1",
|
||
"bolt_count": 4,
|
||
"status": "pending"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**说明**:
|
||
- 如果不传参数，返回所有可用工单
|
||
- 如果同时传入 `trace_id` 和 `process_id`，返回符合条件的工单
|
||
|
||
---
|
||
|
||
### 2. 认领工单
|
||
|
||
**接口地址**: `POST /api/work-orders/claim`
|
||
|
||
**接口描述**: 认领一个工单，使其进入工作状态
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号 |
|
||
| process_id | string | 是 | 工序号 |
|
||
| operator | string | 否 | 操作员名称，默认为"未知操作员" |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"operator": "张三"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "认领成功",
|
||
"data": {
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"product_name": "产品A",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"mode": 1
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 追溯号和工序号不能为空
|
||
- `400`: 该工单已被认领
|
||
- `404`: 未找到符合条件的工单
|
||
- `500`: 认领失败
|
||
|
||
---
|
||
|
||
### 3. 提交工单数据
|
||
|
||
**接口地址**: `POST /api/work-orders/submit`
|
||
|
||
**接口描述**: 提交工单执行结果
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号 |
|
||
| process_id | string | 是 | 工序号 |
|
||
| bolts | array | 是 | 螺栓数据列表 |
|
||
| device_sn | string | 否 | 设备SN号 |
|
||
| device_name | string | 否 | 设备名称 |
|
||
|
||
**螺栓数据格式** (bolts数组中的每个对象):
|
||
```json
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"actual_torque": 50.2,
|
||
"success": true,
|
||
"timestamp": "2026-01-19 10:30:00"
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `target_torque` (float): **目标扭矩**，工单中设定的目标扭矩值，单位：牛米(Nm)
|
||
- `actual_torque` (float): **实际扭矩**，扳手实际拧紧时达到的扭矩值，单位：牛米(Nm)
|
||
- `success` (boolean): 拧紧是否成功，根据实际扭矩是否在目标扭矩的容差范围内判断
|
||
- `timestamp` (string): 拧紧完成的时间戳，格式：`YYYY-MM-DD HH:MM:SS`
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"actual_torque": 50.2,
|
||
"success": true,
|
||
"timestamp": "2026-01-19 10:30:00"
|
||
}
|
||
],
|
||
"device_sn": "1234567890",
|
||
"device_name": "扳手设备1"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "数据提交成功",
|
||
"data": {
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"submitted_at": "2026-01-19 10:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 追溯号和工序号不能为空
|
||
- `400`: 该工单未被认领，无法提交
|
||
- `500`: 提交失败
|
||
|
||
---
|
||
|
||
### 4. 释放工单
|
||
|
||
**接口地址**: `POST /api/work-orders/release`
|
||
|
||
**接口描述**: 释放已认领的工单（取消认领）
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号 |
|
||
| process_id | string | 是 | 工序号 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "释放成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 追溯号和工序号不能为空
|
||
- `400`: 该工单未被认领
|
||
|
||
---
|
||
|
||
### 5. 创建工单
|
||
|
||
**接口地址**: `POST /api/work-orders/create`
|
||
|
||
**接口描述**: 创建新的工单
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号 |
|
||
| process_id | string | 是 | 工序号 |
|
||
| process_name | string | 否 | 工序名称 |
|
||
| product_name | string | 否 | 产品名称 |
|
||
| operator | string | 否 | 操作员 |
|
||
| status | string | 否 | 状态，默认为"pending" |
|
||
| bolts | array | 是 | 螺栓数据列表 |
|
||
|
||
**螺栓数据格式** (bolts数组中的每个对象):
|
||
```json
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"mode": 1,
|
||
"torque_tolerance": 0.10,
|
||
"angle_min": 1,
|
||
"angle_max": 360
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `bolt_id` (string): 螺栓编号
|
||
- `name` (string): 螺栓名称
|
||
- `target_torque` (float): **目标扭矩**，需要达到的目标扭矩值，单位：牛米(Nm)
|
||
- `mode` (integer): 拧紧模式，通常为1
|
||
- `torque_tolerance` (float): 扭矩容差，允许的扭矩偏差范围（相对值，如0.10表示±10%）
|
||
- `angle_min` (integer): 最小角度，单位：度(°)
|
||
- `angle_max` (integer): 最大角度，单位：度(°)
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"product_name": "产品A",
|
||
"operator": "张三",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"mode": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "工单创建成功",
|
||
"data": {
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 必填字段不能为空
|
||
- `500`: 工单创建失败
|
||
|
||
---
|
||
|
||
## 扳手设备管理
|
||
|
||
### 1. 获取设备列表
|
||
|
||
**接口地址**: `GET /api/wrench-devices`
|
||
|
||
**接口描述**: 获取所有扳手设备列表
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"device_name": "扳手设备1",
|
||
"device_sn": "1234567890",
|
||
"ip_address": "192.168.1.100",
|
||
"port": 7888,
|
||
"address_code": 1,
|
||
"status": "online",
|
||
"last_heartbeat": "2026-01-19 10:30:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 创建设备
|
||
|
||
**接口地址**: `POST /api/wrench-devices`
|
||
|
||
**接口描述**: 创建新的扳手设备
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| device_name | string | 是 | 设备名称 |
|
||
| device_sn | string | 否 | 设备SN号 |
|
||
| ip_address | string | 是 | IP地址 |
|
||
| port | integer | 否 | 端口，默认为7888 |
|
||
| address_code | integer | 否 | 地址码，默认为1 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
{
|
||
"device_name": "扳手设备1",
|
||
"device_sn": "1234567890",
|
||
"ip_address": "192.168.1.100",
|
||
"port": 7888,
|
||
"address_code": 1
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备创建成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `400`: 必填字段不能为空
|
||
- `500`: 设备创建失败
|
||
|
||
---
|
||
|
||
### 3. 更新设备
|
||
|
||
**接口地址**: `PUT /api/wrench-devices/<device_id>`
|
||
|
||
**接口描述**: 更新扳手设备信息
|
||
|
||
**路径参数**:
|
||
- `device_id`: 设备ID (integer)
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| device_name | string | 否 | 设备名称 |
|
||
| device_sn | string | 否 | 设备SN号 |
|
||
| ip_address | string | 否 | IP地址 |
|
||
| port | integer | 否 | 端口 |
|
||
| address_code | integer | 否 | 地址码 |
|
||
|
||
**请求示例**:
|
||
```json
|
||
PUT /api/wrench-devices/1
|
||
{
|
||
"device_name": "扳手设备1-更新",
|
||
"ip_address": "192.168.1.101"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `500`: 设备更新失败
|
||
|
||
---
|
||
|
||
### 4. 删除设备
|
||
|
||
**接口地址**: `DELETE /api/wrench-devices/<device_id>`
|
||
|
||
**接口描述**: 删除扳手设备
|
||
|
||
**路径参数**:
|
||
- `device_id`: 设备ID (integer)
|
||
|
||
**请求示例**:
|
||
```
|
||
DELETE /api/wrench-devices/1
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备删除成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `500`: 设备删除失败
|
||
|
||
---
|
||
|
||
### 5. 更新设备状态
|
||
|
||
**接口地址**: `POST /api/wrench-devices/<device_id>/status`
|
||
|
||
**接口描述**: 更新设备状态（用于心跳检测）
|
||
|
||
**路径参数**:
|
||
- `device_id`: 设备ID (integer)
|
||
|
||
**请求参数** (JSON Body):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| status | string | 否 | 状态，默认为"offline"，可选值: "online", "offline" |
|
||
|
||
**请求示例**:
|
||
```json
|
||
POST /api/wrench-devices/1/status
|
||
{
|
||
"status": "online"
|
||
}
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "状态更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `500`: 状态更新失败
|
||
|
||
---
|
||
|
||
### 6. 检测设备在线状态
|
||
|
||
**接口地址**: `POST /api/wrench-devices/<device_id>/check-status`
|
||
|
||
**接口描述**: 主动检测设备是否在线（尝试连接设备）
|
||
|
||
**路径参数**:
|
||
- `device_id`: 设备ID (integer)
|
||
|
||
**请求参数**: 无
|
||
|
||
**请求示例**:
|
||
```
|
||
POST /api/wrench-devices/1/check-status
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备在线",
|
||
"data": {
|
||
"status": "online"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `404`: 设备不存在
|
||
- `500`: 检测失败
|
||
|
||
**说明**:
|
||
- 此接口会主动尝试连接设备，根据连接结果更新设备状态
|
||
- 如果设备在线，状态会被更新为"online"
|
||
- 如果设备离线或连接失败，状态会被更新为"offline"
|
||
|
||
---
|
||
|
||
### 7. 查询设备SN码
|
||
|
||
**接口地址**: `POST /api/wrench-devices/<device_id>/query-sn`
|
||
|
||
**接口描述**: 查询设备SN码（通过设备协议查询）
|
||
|
||
**路径参数**:
|
||
- `device_id`: 设备ID (integer)
|
||
|
||
**请求参数**: 无
|
||
|
||
**请求示例**:
|
||
```
|
||
POST /api/wrench-devices/1/query-sn
|
||
```
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"device_sn": "1234567890",
|
||
"status": "online"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应**:
|
||
- `404`: 设备不存在
|
||
- `500`: 查询失败或无法连接到设备
|
||
|
||
**说明**:
|
||
- 此接口会主动连接设备并查询SN码
|
||
- 如果查询成功，设备SN码会被更新到数据库
|
||
- 设备状态会被更新为"online"
|
||
|
||
---
|
||
|
||
## 执行结果查询
|
||
|
||
### 查询执行结果
|
||
|
||
**接口地址**: `GET /api/work-results`
|
||
|
||
**接口描述**: 查询工单执行结果
|
||
|
||
**请求参数** (Query Parameters):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 否 | 追溯号 |
|
||
| process_id | string | 否 | 工序号 |
|
||
|
||
**请求示例**:
|
||
```
|
||
GET /api/work-results?trace_id=TR20260119001&process_id=P001
|
||
GET /api/work-results?trace_id=TR20260119001
|
||
GET /api/work-results?process_id=P001
|
||
GET /api/work-results
|
||
```
|
||
|
||
**响应示例** (单个结果):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": {
|
||
"id": 1,
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"actual_torque": 50.2,
|
||
"success": true,
|
||
"timestamp": "2026-01-19 10:30:00"
|
||
}
|
||
],
|
||
"device_sn": "1234567890",
|
||
"device_name": "扳手设备1",
|
||
"submitted_at": "2026-01-19 10:35:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应示例** (结果列表):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "查询成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"bolts": [...],
|
||
"device_sn": "1234567890",
|
||
"device_name": "扳手设备1",
|
||
"submitted_at": "2026-01-19 10:35:00"
|
||
}
|
||
],
|
||
"count": 1
|
||
}
|
||
```
|
||
|
||
**说明**:
|
||
- 如果同时提供 `trace_id` 和 `process_id`，返回指定工单的单个结果（如果不存在返回404）
|
||
- 如果只提供 `trace_id`，返回该追溯号下的所有结果列表
|
||
- 如果只提供 `process_id`，返回该工序号下的所有结果列表
|
||
- 如果都不提供，返回所有执行结果列表
|
||
|
||
**结果数据中的扭矩字段说明**:
|
||
- `target_torque` (float): **目标扭矩**，工单中设定的目标扭矩值（单位：牛米/Nm）
|
||
- `actual_torque` (float): **实际扭矩**，扳手实际拧紧时达到的扭矩值（单位：牛米/Nm）
|
||
- 拧紧成功的判断标准：`actual_torque` 在 `target_torque ± (target_torque × torque_tolerance)` 范围内
|
||
|
||
**错误响应**:
|
||
- `404`: 未找到执行结果（仅当同时提供trace_id和process_id时）
|
||
- `500`: 查询失败
|
||
|
||
---
|
||
|
||
## 系统健康检查
|
||
|
||
### 健康检查
|
||
|
||
**接口地址**: `GET /api/health`
|
||
|
||
**接口描述**: 检查系统运行状态
|
||
|
||
**请求参数**: 无
|
||
|
||
**响应示例**:
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "服务运行正常",
|
||
"timestamp": "2026-01-19 10:30:00"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## HTTP状态码
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 数据模型
|
||
|
||
### 工单对象 (WorkOrder)
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"product_name": "产品A",
|
||
"operator": "操作员1",
|
||
"status": "pending",
|
||
"bolt_count": 4,
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"mode": 1,
|
||
"torque_tolerance": 0.10,
|
||
"angle_min": 1,
|
||
"angle_max": 360
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 设备对象 (WrenchDevice)
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"device_name": "扳手设备1",
|
||
"device_sn": "1234567890",
|
||
"ip_address": "192.168.1.100",
|
||
"port": 7888,
|
||
"address_code": 1,
|
||
"status": "online",
|
||
"last_heartbeat": "2026-01-19 10:30:00"
|
||
}
|
||
```
|
||
|
||
### 执行结果对象 (WorkResult)
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "拧紧工序",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0,
|
||
"actual_torque": 50.2,
|
||
"success": true,
|
||
"timestamp": "2026-01-19 10:30:00"
|
||
}
|
||
],
|
||
"device_sn": "1234567890",
|
||
"device_name": "扳手设备1",
|
||
"submitted_at": "2026-01-19 10:35:00"
|
||
}
|
||
```
|
||
|
||
**螺栓结果字段说明**:
|
||
- `target_torque` (float): **目标扭矩**，工单中设定的目标扭矩值，单位：牛米(Nm)
|
||
- `actual_torque` (float): **实际扭矩**，扳手实际拧紧时达到的扭矩值，单位：牛米(Nm)
|
||
- `success` (boolean): 拧紧是否成功，根据实际扭矩是否在目标扭矩的容差范围内判断
|
||
- `timestamp` (string): 拧紧完成的时间戳
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. 所有时间格式为: `YYYY-MM-DD HH:MM:SS`
|
||
2. 所有接口都支持CORS跨域请求
|
||
3. 请求和响应数据均为JSON格式
|
||
4. 设备状态可选值: `online`, `offline`
|
||
5. 工单状态可选值: `pending`, `claimed`, `completed`
|
||
6. 扭矩单位: 牛米 (Nm)
|
||
7. 角度单位: 度 (°)
|
||
|
||
---
|
||
|
||
## 更新日志
|
||
|
||
- 2026-01-19: 初始版本，包含工单管理、设备管理和结果查询功能
|
||
|