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