risingLee
/
TorqueWrench
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
TorqueWrench/backend/接口文档.md

8.5 KiB
Raw Blame History

第三方接口文档

概述

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

请求示例

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

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

错误响应 (HTTP 400):

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

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

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

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示例

# 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示例

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