# 条形码识别 API 对接文档

本文档说明与 Java 后端对接的上传识别接口，返回 EAN‑13 结果；若无法识别返回明确错误提示。

## 基本信息
- 接口地址：`/api/barcode/scan`
- 请求方式：`POST multipart/form-data`
- 参数：
  - `file`：图片文件（二进制）。
- 成功响应（HTTP 200）：
  ```json
  { "success": true, "barcodeType": "EAN13", "barcode": "6901234567892" }
  ```
- 失败响应（HTTP 400）：
  ```json
  { "success": false, "message": "无法识别，请重新上传" }
  ```

## 请求示例（PowerShell）
```powershell
Invoke-RestMethod -Uri http://127.0.0.1:8000/api/barcode/scan -Method Post -Form @{ file = Get-Item .\sample.jpg }
```

## 请求示例（curl）
```bash
curl -F "file=@sample.jpg" http://127.0.0.1:8000/api/barcode/scan
```

## Java 示例（Spring WebClient）
```java
WebClient client = WebClient.create("http://127.0.0.1:8000");
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("file", new FileSystemResource(new File("sample.jpg")));

Map res = client.post()
    .uri("/api/barcode/scan")
    .contentType(MediaType.MULTIPART_FORM_DATA)
    .body(BodyInserters.fromMultipartData(body))
    .retrieve()
    .onStatus(s -> s.value() == 400, r -> r.bodyToMono(String.class).map(RuntimeException::new))
    .bodyToMono(Map.class)
    .block();

System.out.println(res);
```

## Java 示例（Spring RestTemplate）
```java
RestTemplate rest = new RestTemplate();
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
MultiValueMap<String, Object> body = new LinkedMultiValueMap<>();
body.add("file", new FileSystemResource("sample.jpg"));
HttpEntity<MultiValueMap<String, Object>> req = new HttpEntity<>(body, headers);

ResponseEntity<String> resp = rest.postForEntity("http://127.0.0.1:8000/api/barcode/scan", req, String.class);
System.out.println(resp.getStatusCode());
System.out.println(resp.getBody());
```

## 返回字段说明
- `success`：是否识别成功。
- `barcodeType`：条码类型（当前为 `EAN13`）。
- `barcode`：条码数字串。
- `message`：失败时的人类可读说明。

## 错误码
- 400：文件为空、图片解析失败、或未识别；返回 `{ success:false, message:"无法识别，请重新上传" }`。
- 413：文件过大（受 `config/config.yaml` 中 `app.server.max_upload_mb` 限制）。