368 lines
8.5 KiB
Markdown
368 lines
8.5 KiB
Markdown
# 第三方接口文档
|
||
|
||
## 概述
|
||
|
||
本文档提供第三方系统集成所需的简化API接口，包含工单创建和结果查询功能。
|
||
|
||
**基础URL**: `http://localhost:5000/api`
|
||
|
||
**数据格式**: JSON
|
||
|
||
**字符编码**: UTF-8
|
||
|
||
---
|
||
|
||
## 1. 创建工单
|
||
|
||
### 接口信息
|
||
|
||
- **URL**: `/api/work-orders/create`
|
||
- **方法**: `POST`
|
||
- **描述**: 创建新的工单
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号（唯一标识） |
|
||
| process_id | string | 是 | 工序号 |
|
||
| process_name | string | 否 | 工序名称 |
|
||
| product_name | string | 否 | 产品名称 |
|
||
| operator | string | 否 | 操作员 |
|
||
| bolts | array | 是 | 螺栓数据列表 |
|
||
|
||
**螺栓数据格式** (bolts数组中的每个对象):
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| bolt_id | string/integer | 是 | 螺栓编号 |
|
||
| name | string | 否 | 螺栓名称 |
|
||
| target_torque | float | 是 | 目标扭矩（单位：牛米/Nm） |
|
||
| mode | integer | 否 | 拧紧模式，默认为1 |
|
||
| torque_tolerance | float | 否 | 扭矩容差（相对值，如0.10表示±10%），默认0.10 |
|
||
| angle_min | integer | 否 | 最小角度（度），默认1 |
|
||
| angle_max | integer | 否 | 最大角度（度），默认360 |
|
||
|
||
### 请求示例
|
||
|
||
```json
|
||
{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "前轮装配",
|
||
"product_name": "汽车底盘组件",
|
||
"operator": "张三",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "前轮螺栓1",
|
||
"target_torque": 50.0,
|
||
"mode": 1,
|
||
"torque_tolerance": 0.10,
|
||
"angle_min": 1,
|
||
"angle_max": 360
|
||
},
|
||
{
|
||
"bolt_id": "B002",
|
||
"name": "前轮螺栓2",
|
||
"target_torque": 50.0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
**成功响应** (HTTP 200):
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "工单创建成功",
|
||
"data": {
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001"
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应** (HTTP 400):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "字段 trace_id 不能为空"
|
||
}
|
||
```
|
||
|
||
### 注意事项
|
||
|
||
1. `trace_id` 和 `process_id` 的组合必须唯一
|
||
2. 如果已存在相同的 `trace_id` 和 `process_id` 组合，创建会失败
|
||
3. 工单创建后状态默认为 `pending`（待处理）
|
||
4. 螺栓数据中，`target_torque` 是必填项，其他参数有默认值
|
||
|
||
---
|
||
|
||
## 2. 查询工单结果
|
||
|
||
### 接口信息
|
||
|
||
- **URL**: `/api/work-results`
|
||
- **方法**: `GET`
|
||
- **描述**: 查询工单执行结果
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| trace_id | string | 是 | 追溯号 |
|
||
| process_id | string | 是 | 工序号 |
|
||
|
||
### 请求示例
|
||
|
||
```
|
||
GET /api/work-results?trace_id=TR20260119001&process_id=P001
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
**成功响应 - 有结果** (HTTP 200):
|
||
```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"
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功响应 - 无结果** (HTTP 404):
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "未找到执行结果",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
|
||
**结果对象字段**:
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | integer | 结果记录ID |
|
||
| trace_id | string | 追溯号 |
|
||
| process_id | string | 工序号 |
|
||
| process_name | string | 工序名称 |
|
||
| bolts | array | 螺栓执行结果列表 |
|
||
| device_sn | string | 使用的设备SN号 |
|
||
| device_name | string | 使用的设备名称 |
|
||
| submitted_at | string | 提交时间 |
|
||
|
||
**螺栓结果字段** (bolts数组中的每个对象):
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| bolt_id | string/integer | 螺栓编号 |
|
||
| name | string | 螺栓名称 |
|
||
| target_torque | float | **目标扭矩**（单位：牛米/Nm） |
|
||
| actual_torque | float | **实际扭矩**（单位：牛米/Nm） |
|
||
| success | boolean | 拧紧是否成功 |
|
||
| timestamp | string | 拧紧完成时间 |
|
||
|
||
### 注意事项
|
||
|
||
1. 必须同时提供 `trace_id` 和 `process_id` 才能查询到结果
|
||
2. 如果工单还未执行完成，查询会返回404
|
||
3. `actual_torque` 是扳手实际达到的扭矩值
|
||
4. `success` 字段表示拧紧是否在容差范围内成功
|
||
5. 时间格式为：`YYYY-MM-DD HH:MM:SS`
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### Python示例
|
||
|
||
```python
|
||
import requests
|
||
|
||
BASE_URL = "http://localhost:5000/api"
|
||
|
||
# 1. 创建工单
|
||
def create_work_order(trace_id, process_id, bolts):
|
||
url = f"{BASE_URL}/work-orders/create"
|
||
data = {
|
||
"trace_id": trace_id,
|
||
"process_id": process_id,
|
||
"process_name": "前轮装配",
|
||
"bolts": bolts
|
||
}
|
||
response = requests.post(url, json=data)
|
||
return response.json()
|
||
|
||
# 2. 查询工单结果
|
||
def get_work_result(trace_id, process_id):
|
||
url = f"{BASE_URL}/work-results"
|
||
params = {
|
||
"trace_id": trace_id,
|
||
"process_id": process_id
|
||
}
|
||
response = requests.get(url, params=params)
|
||
return response.json()
|
||
|
||
# 使用示例
|
||
if __name__ == "__main__":
|
||
# 创建工单
|
||
bolts = [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0
|
||
}
|
||
]
|
||
result = create_work_order("TR20260119001", "P001", bolts)
|
||
print("创建工单:", result)
|
||
|
||
# 查询结果（等待执行完成后）
|
||
import time
|
||
time.sleep(60) # 等待执行完成
|
||
|
||
result = get_work_result("TR20260119001", "P001")
|
||
print("查询结果:", result)
|
||
```
|
||
|
||
### cURL示例
|
||
|
||
```bash
|
||
# 1. 创建工单
|
||
curl -X POST http://localhost:5000/api/work-orders/create \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"trace_id": "TR20260119001",
|
||
"process_id": "P001",
|
||
"process_name": "前轮装配",
|
||
"bolts": [
|
||
{
|
||
"bolt_id": "B001",
|
||
"name": "螺栓1",
|
||
"target_torque": 50.0
|
||
}
|
||
]
|
||
}'
|
||
|
||
# 2. 查询工单结果
|
||
curl "http://localhost:5000/api/work-results?trace_id=TR20260119001&process_id=P001"
|
||
```
|
||
|
||
### JavaScript示例
|
||
|
||
```javascript
|
||
const BASE_URL = "http://localhost:5000/api";
|
||
|
||
// 1. 创建工单
|
||
async function createWorkOrder(traceId, processId, bolts) {
|
||
const response = await fetch(`${BASE_URL}/work-orders/create`, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
trace_id: traceId,
|
||
process_id: processId,
|
||
bolts: bolts
|
||
})
|
||
});
|
||
return await response.json();
|
||
}
|
||
|
||
// 2. 查询工单结果
|
||
async function getWorkResult(traceId, processId) {
|
||
const url = `${BASE_URL}/work-results?trace_id=${traceId}&process_id=${processId}`;
|
||
const response = await fetch(url);
|
||
return await response.json();
|
||
}
|
||
|
||
// 使用示例
|
||
createWorkOrder("TR20260119001", "P001", [
|
||
{
|
||
bolt_id: "B001",
|
||
name: "螺栓1",
|
||
target_torque: 50.0
|
||
}
|
||
]).then(result => {
|
||
console.log("创建工单:", result);
|
||
|
||
// 等待执行完成后查询结果
|
||
setTimeout(() => {
|
||
getWorkResult("TR20260119001", "P001").then(result => {
|
||
console.log("查询结果:", result);
|
||
});
|
||
}, 60000);
|
||
});
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| HTTP状态码 | 说明 |
|
||
|-----------|------|
|
||
| 200 | 请求成功 |
|
||
| 400 | 请求参数错误（如必填字段缺失） |
|
||
| 404 | 资源不存在（查询结果时，工单未执行完成） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q1: 如何判断工单是否执行完成？
|
||
|
||
**A**: 定期调用查询接口，如果返回404表示还未执行完成，返回200表示已执行完成。
|
||
|
||
### Q2: 创建工单后多久可以查询到结果？
|
||
|
||
**A**: 这取决于操作员何时认领和执行工单。建议采用轮询方式，每隔一段时间查询一次。
|
||
|
||
### Q3: 如果工单执行失败怎么办？
|
||
|
||
**A**: 即使部分螺栓失败，结果也会被提交。可以通过 `bolts` 数组中每个螺栓的 `success` 字段判断是否成功。
|
||
|
||
### Q4: `trace_id` 和 `process_id` 的格式要求？
|
||
|
||
**A**: 没有特殊格式要求，但建议使用有意义的标识符，如 `TR20260119001` 和 `P001`。
|
||
|
||
### Q5: 可以批量创建工单吗？
|
||
|
||
**A**: 目前接口只支持单个工单创建，如需批量创建，请循环调用创建接口。
|
||
|
||
---
|
||
|
||
## 联系支持
|
||
|
||
如有问题，请联系技术支持团队。
|
||
|
||
---
|
||
|
||
**版本**: v1.0
|
||
**更新日期**: 2026-01-19
|
||
|