# 电动扳手系统 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: 初始版本，包含工单管理、设备管理和结果查询功能