# 拍照接口文档

## 接口概述

在拍照机客户端本机触发一次拍摄。调用效果与拍摄页操作一致：先填入货号，再按左脚或右脚启动对应拍摄程序。

接口会等待这只脚的程序执行结束再返回。成功只表示程序已跑完，响应里不包含图片文件或 base64。照片仍按客户端原有流程落盘。

**运行环境**: 拍照机客户端（Electron）已启动。接口跑在客户端内部，调用方访问本机 `localhost`。

---

## 接口信息

### 基本信息

- **接口地址**: `http://localhost:3001/take_photo`
- **请求方法**: `POST`
- **Content-Type**: `application/json`
- **超时建议**: 客户端超时请大于单次拍摄时长。接口最长等待 10 分钟，超时返回失败。

### 接口路径

```
POST /take_photo
```

同一端口上的 `POST /generate` 仍是图片生成接口，互不影响。同一时间只能有一个拍照请求在执行。

---

## 请求参数

### 请求体结构

```json
{
  "goods_art_no": "A596351",
  "foot": "left"
}
```

### 参数说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| goods_art_no | string | 是 | 货号。也可用字段名 `货号` 或 `goodsArtNo` |
| foot | string | 是 | 左右脚。也可用字段名 `左右脚`、`side`、`type` |

`foot` 取值：

| 传值 | 实际动作 |
|------|----------|
| `left`、`l`、`0`、`左`、`左脚` | 执行左脚程序 |
| `right`、`r`、`1`、`右`、`右脚` | 执行右脚程序 |

货号前后空格会被去掉。未识别的左右脚会直接失败。

---

## 响应格式

业务结果看 JSON 里的 `code`。`code` 不为 `0` 时，HTTP 状态码为 `500`，响应体仍是 JSON。

### 成功响应

**HTTP 状态码**: `200`

```json
{
  "code": 0,
  "msg": "货号:A596351,执行完成",
  "data": {
    "goods_art_no": "A596351",
    "foot": "left",
    "action": "执行左脚程序"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | number | `0` 表示这只脚的拍摄程序已执行完成 |
| msg | string | 设备返回的完成说明 |
| data.goods_art_no | string | 本次货号 |
| data.foot | string | `left` 或 `right` |
| data.action | string | `执行左脚程序` 或 `执行右脚程序` |

### 失败响应

**HTTP 状态码**: `500`

```json
{
  "code": 1,
  "msg": "货号不能为空"
}
```

参数错误、设备忙、拍摄失败都是这个结构。已经开始拍摄后失败时，可能带上 `data`（货号、左右脚、动作名）。

常见 `msg`：

| msg | 说明 |
|-----|------|
| 货号不能为空 | 未传货号 |
| 左右脚不能为空，请传 left/right 或 左/右 | 未传或无法识别左右脚 |
| 拍摄程序正在运行，请稍候 | 已有拍摄在进行，不要并发调用 |
| 拍照接口仅在客户端内可用 | 客户端未启动，或不是在客户端里访问 |
| 设备服务未连接 | 8 秒内连不上本机拍摄服务 |
| mcu设备未连接,请先连接设备 | 拍摄开始前 MCU 未连接 |
| MCU 连接失败 / MCU串口未连接,请检查 | 拍摄过程中 MCU 断开，接口立即返回失败 |
| 请检查相机是否连接 / 相机未连接 | 拍摄过程中相机断开或相机软件未打开，接口立即返回失败 |
| mcu设备未初始化 | 设备未完成初始化 |
| 当前有未完成的任务，请稍后再试 | 设备上还有未结束的动作 |
| 货号[xxx]已存在,请勿重复拍摄~ | 该货号已有拍摄记录，需先在客户端删除后再拍 |
| 当前没有可用配置 | 对应左脚或右脚没有可用拍摄配置 |
| 拍照超时 | 超过 10 分钟仍未结束 |

`msg` 还可能是设备返回的具体步骤失败原因，以实际返回为准。

### 其他错误

| HTTP 状态码 | 说明 | 响应体 |
|------------|------|--------|
| 404 | 路径或方法不对 | `Not Found`（纯文本） |
| 413 | 请求体过大 | `Payload Too Large`（纯文本） |

---

## 调用示例

### cURL

左脚：

```bash
curl -X POST http://localhost:3001/take_photo \
  -H "Content-Type: application/json" \
  -d "{\"goods_art_no\":\"A596351\",\"foot\":\"left\"}"
```

右脚（中文字段）：

```bash
curl -X POST http://localhost:3001/take_photo \
  -H "Content-Type: application/json" \
  -d "{\"货号\":\"A596351\",\"左右脚\":\"右\"}"
```

请把调用超时调到 10 分钟以上。`curl` 可加 `--max-time 600`。

### Python

```python
import requests

url = "http://localhost:3001/take_photo"
payload = {
    "goods_art_no": "A596351",
    "foot": "left",  # 右脚传 "right"
}

# 失败时 HTTP 状态码是 500，但仍返回 JSON，不要用 raise_for_status() 丢掉响应体
response = requests.post(url, json=payload, timeout=600)
result = response.json()

if result.get("code") == 0:
    print("拍摄完成:", result.get("msg"))
    print(result.get("data"))
else:
    print("拍摄失败:", result.get("msg"))
```

### JavaScript

```javascript
const response = await fetch("http://localhost:3001/take_photo", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    goods_art_no: "A596351",
    foot: "right",
  }),
});

const result = await response.json();
if (result.code === 0) {
  console.log("拍摄完成", result.data);
} else {
  console.error("拍摄失败", result.msg);
}
```

---

## 调用前检查

1. 拍照机客户端已打开，本机可以访问 `http://localhost:3001`。
2. 拍摄设备已连接并完成初始化。
3. 左脚、右脚拍摄配置已在客户端配好。
4. 该货号当前没有未删除的拍摄记录。重复货号会被拒绝。
5. 上一次拍摄已经结束。接口不支持并发，进行中再次调用会返回「拍摄程序正在运行，请稍候」。
6. 调用方与客户端在同一台电脑上。这是本机接口，不对外网开放。

拍摄页处于打开状态时，输入框会显示本次货号，界面进入与点击左右脚相同的拍摄状态。

---

## 注意事项

1. 一次请求只拍一只脚。左脚、右脚需要分两次调用。
2. 请求在程序结束前不会返回，请勿使用默认的短超时。
3. 以响应 JSON 的 `code` 判断成败。`code === 0` 为成功，其余为失败。
4. 接口不返回照片内容。拍完后的文件位置与客户端拍摄页一致。
5. 中途在客户端点停止，接口会以失败返回，`msg` 为终止说明。