TorqueWrench/backend/接口文档.md

# 第三方接口文档

## 概述

本文档提供第三方系统集成所需的简化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