TorqueWrench/backend/README.md

# 后端API服务器使用说明

## 功能特性

1. **SQLite数据库存储** - 使用SQLite数据库存储工单数据
2. **工单管理** - 创建、查询、认领、提交工单
3. **自动数据导入** - 首次启动时自动从JSON文件导入数据

## API接口

### 1. 创建工单
**POST** `/api/work-orders/create`

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

### 2. 查询工单列表
**GET** `/api/work-orders?trace_id=TR20260119001&process_id=P001`

返回：符合条件的未认领工单列表

### 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"
}
```

### 6. 健康检查
**GET** `/api/health`

## 数据库结构

### work_orders 表
- `id` - 主键
- `trace_id` - 追溯号
- `process_id` - 工序号
- `process_name` - 工序名称
- `product_name` - 产品名称
- `station` - 工位
- `operator` - 操作员
- `status` - 状态
- `bolts_data` - 螺栓数据（JSON格式）
- `created_at` - 创建时间
- `updated_at` - 更新时间

### claimed_orders 表
- `id` - 主键
- `trace_id` - 追溯号
- `process_id` - 工序号
- `process_name` - 工序名称
- `operator` - 操作员
- `claimed_at` - 认领时间
- `completed_at` - 完成时间
- `status` - 状态（claimed/completed）
- `bolts_result` - 螺栓结果数据（JSON格式）

## 使用步骤

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 启动服务器
```bash
python app.py
```

服务器将在 `http://localhost:5000` 启动

### 3. 首次启动
- 如果数据库为空，会自动从 `work_orders.json` 导入数据
- 数据库文件 `wrench.db` 会自动创建

### 4. 创建工单
可以使用 `create_order_example.py` 作为示例：
```bash
python create_order_example.py
```

或使用curl：
```bash
curl -X POST http://localhost:5000/api/work-orders/create \
  -H "Content-Type: application/json" \
  -d @work_order_data.json
```

## 注意事项

1. **追溯号和工序号必须同时匹配**才能查询到工单
2. **工单只能被认领一次**，认领后其他客户端无法再认领
3. **数据库文件** `wrench.db` 会保存在 `backend/` 目录下
4. 如果修改了 `work_orders.json`，可以删除 `wrench.db` 重新启动服务器来重新导入

## 故障排除

### 查询不到数据
1. 检查数据库是否已初始化（查看是否存在 `wrench.db` 文件）
2. 如果数据库为空，确保 `work_orders.json` 文件存在
3. 检查追溯号和工序号是否完全匹配（区分大小写）

### 数据库初始化
如果需要手动初始化数据库：
```bash
python init_database.py
```