2

backend/txm/doc/API.md

@@ -0,0 +1,71 @@
+# 条形码识别 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` 限制）。
+
+