TorqueWrench/backend/API_README.md

# 后端API使用说明

## 数据库

系统使用SQLite数据库存储工单数据，数据库文件为 `wrench.db`。

### 数据库表结构

1. **work_orders** - 工单表
   - id: 主键
   - trace_id: 追溯号
   - process_id: 工序号
   - process_name: 工序名称
   - product_name: 产品名称
   - operator: 操作员
   - status: 状态（系统自动管理，创建时默认为pending）
   - bolts: 螺栓数据（JSON格式）
   - created_at: 创建时间
   - updated_at: 更新时间

2. **claimed_orders** - 认领表
   - id: 主键
   - trace_id: 追溯号
   - process_id: 工序号
   - process_name: 工序名称
   - operator: 操作员
   - status: 状态（claimed/completed）
   - claimed_at: 认领时间
   - completed_at: 完成时间

3. **work_results** - 结果表
   - id: 主键
   - trace_id: 追溯号
   - process_id: 工序号
   - process_name: 工序名称
   - bolts: 螺栓结果数据（JSON格式）
   - device_sn: 设备SN号
   - device_name: 设备名称
   - submitted_at: 提交时间

## API接口

### 1. 创建工单

**POST** `/api/work-orders/create`

**请求体：**
```json
{
  "trace_id": "TR20260119001",
  "process_id": "P001",
  "process_name": "前轮装配",
  "product_name": "汽车底盘组件",
  "operator": "张三",
  "bolts": [
    {
      "bolt_id": 1,
      "name": "前轮螺栓1",
      "target_torque": 280,
      "mode": 1,
      "torque_tolerance": 0.10,
      "angle_min": 1,
      "angle_max": 360
    }
  ]
}
```

**响应：**
```json
{
  "success": true,
  "message": "工单创建成功",
  "data": {
    "trace_id": "TR20260119001",
    "process_id": "P001"
  }
}
```

### 2. 查询工单列表

**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": "汽车底盘组件",
      "operator": "张三",
      "bolt_count": 2,
      "status": "pending"
    }
  ]
}
```

### 3. 认领工单

**POST** `/api/work-orders/claim`

**请求体：**
```json
{
  "trace_id": "TR20260119001",
  "process_id": "P001",
  "operator": "操作员"
}
```

### 4. 提交工单数据

**POST** `/api/work-orders/submit`

**请求体：**
```json
{
  "trace_id": "TR20260119001",
  "process_id": "P001",
  "bolts": [
    {
      "bolt_id": 1,
      "name": "前轮螺栓1",
      "target_torque": 280,
      "actual_torque": 285,
      "actual_angle": 0,
      "status": "success",
      "timestamp": "2026-01-19 10:30:00",
      "result": {...}
    }
  ]
}
```

### 5. 释放工单

**POST** `/api/work-orders/release`

**请求体：**
```json
{
  "trace_id": "TR20260119001",
  "process_id": "P001"
}
```

## 使用示例

### Python示例

```python
import requests

# 创建工单
order_data = {
    "trace_id": "TR20260119001",
    "process_id": "P001",
    "process_name": "前轮装配",
    "bolts": [...]
}

response = requests.post(
    "http://localhost:5000/api/work-orders/create",
    json=order_data
)
print(response.json())
```

### cURL示例

```bash
# 创建工单
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": [...]
  }'

# 查询工单
curl "http://localhost:5000/api/work-orders?trace_id=TR20260119001&process_id=P001"
```

## 注意事项

1. **追溯号和工序号必须同时匹配**才能查询到工单
2. **同一追溯号和工序号的组合是唯一的**（UNIQUE约束）
3. **工单只能被认领一次**，认领后其他客户端无法再认领
4. **数据库启动时自动从work_orders.json导入数据**（如果数据库为空）
5. 所有时间字段使用格式：`YYYY-MM-DD HH:MM:SS`