16 KiB

Raw Permalink Blame History

电动扳手系统 API 接口文档

基础信息

基础URL: http://localhost:5000
API前缀: /api
数据格式: JSON
字符编码: UTF-8

工单管理

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

响应示例:

{
  "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	否	操作员名称，默认为"未知操作员"

请求示例:

{
  "trace_id": "TR20260119001",
  "process_id": "P001",
  "operator": "张三"
}

响应示例:

{
  "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数组中的每个对象):

{
  "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

请求示例:

{
  "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"
}

响应示例:

{
  "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	是	工序号

请求示例:

{
  "trace_id": "TR20260119001",
  "process_id": "P001"
}

响应示例:

{
  "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数组中的每个对象):

{
  "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): 最大角度，单位：度(°)

请求示例:

{
  "trace_id": "TR20260119001",
  "process_id": "P001",
  "process_name": "拧紧工序",
  "product_name": "产品A",
  "operator": "张三",
  "bolts": [
    {
      "bolt_id": "B001",
      "name": "螺栓1",
      "target_torque": 50.0,
      "mode": 1
    }
  ]
}

响应示例:

{
  "success": true,
  "message": "工单创建成功",
  "data": {
    "trace_id": "TR20260119001",
    "process_id": "P001"
  }
}

错误响应:

400: 必填字段不能为空
500: 工单创建失败

扳手设备管理

1. 获取设备列表

接口地址: GET /api/wrench-devices

接口描述: 获取所有扳手设备列表

请求参数: 无

响应示例:

{
  "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

请求示例:

{
  "device_name": "扳手设备1",
  "device_sn": "1234567890",
  "ip_address": "192.168.1.100",
  "port": 7888,
  "address_code": 1
}

响应示例:

{
  "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	否	地址码

请求示例:

PUT /api/wrench-devices/1
{
  "device_name": "扳手设备1-更新",
  "ip_address": "192.168.1.101"
}

响应示例:

{
  "success": true,
  "message": "设备更新成功"
}

错误响应:

500: 设备更新失败

4. 删除设备

接口地址: DELETE /api/wrench-devices/<device_id>

接口描述: 删除扳手设备

路径参数:

device_id: 设备ID (integer)

请求示例:

DELETE /api/wrench-devices/1

响应示例:

{
  "success": true,
  "message": "设备删除成功"
}

错误响应:

500: 设备删除失败

5. 更新设备状态

接口地址: POST /api/wrench-devices/<device_id>/status

接口描述: 更新设备状态（用于心跳检测）

路径参数:

device_id: 设备ID (integer)

请求参数 (JSON Body):

参数名	类型	必填	说明
status	string	否	状态，默认为"offline"，可选值: "online", "offline"

请求示例:

POST /api/wrench-devices/1/status
{
  "status": "online"
}

响应示例:

{
  "success": true,
  "message": "状态更新成功"
}

错误响应:

500: 状态更新失败

6. 检测设备在线状态

接口地址: POST /api/wrench-devices/<device_id>/check-status

接口描述: 主动检测设备是否在线（尝试连接设备）

路径参数:

device_id: 设备ID (integer)

请求参数: 无

请求示例:

POST /api/wrench-devices/1/check-status

响应示例:

{
  "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

响应示例:

{
  "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

响应示例 (单个结果):

{
  "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"
  }
}

响应示例 (结果列表):

{
  "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

接口描述: 检查系统运行状态

请求参数: 无

响应示例:

{
  "success": true,
  "message": "服务运行正常",
  "timestamp": "2026-01-19 10:30:00"
}

通用响应格式

成功响应

{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}

错误响应

{
  "success": false,
  "message": "错误信息",
  "data": null
}

HTTP状态码

状态码	说明
200	请求成功
400	请求参数错误
404	资源不存在
500	服务器内部错误

数据模型

工单对象 (WorkOrder)

{
  "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)

{
  "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)

{
  "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): 拧紧完成的时间戳

注意事项

所有时间格式为: YYYY-MM-DD HH:MM:SS
所有接口都支持CORS跨域请求
请求和响应数据均为JSON格式
设备状态可选值: online, offline
工单状态可选值: pending, claimed, completed
扭矩单位: 牛米 (Nm)
角度单位: 度 (°)

更新日志

2026-01-19: 初始版本，包含工单管理、设备管理和结果查询功能

16 KiB Raw Permalink Blame History Unescape Escape

电动扳手系统 API 接口文档

基础信息

目录

工单管理

1. 查询工单列表

2. 认领工单

3. 提交工单数据

4. 释放工单

5. 创建工单

扳手设备管理

1. 获取设备列表

2. 创建设备

3. 更新设备

4. 删除设备

5. 更新设备状态

6. 检测设备在线状态

7. 查询设备SN码

执行结果查询

查询执行结果

系统健康检查

健康检查

通用响应格式

成功响应

错误响应

HTTP状态码

数据模型

工单对象 (WorkOrder)

设备对象 (WrenchDevice)

执行结果对象 (WorkResult)

注意事项

更新日志

16 KiB

Raw Permalink Blame History