# 重量 OCR 接入说明

## 功能位置

重量 OCR 已作为功能模块并入 `integration-service`，不再作为独立微服务部署，不新增端口、数据库或注册服务名。

主要代码：

- `controller/WeightOcrController.java`：内部批量识别接口。
- `service/ocr/WeightOcrBatchService.java`：批次编排、结果汇总和文件落盘。
- `service/ocr/ImageCropper.java`：图片下方中央区域裁剪。
- `service/ocr/WeightCandidateSelector.java`：重量候选筛选。
- `service/ocr/WeightOcrStoragePolicy.java`：输入、输出目录边界保护。
- `provider/ocr/BaiduMeterClient.java`：百度令牌缓存、识别、限速和重试。

## 接口

```text
POST /internal/integrations/weight-ocr/batches
X-Internal-Service-Token: 内部服务令牌
Content-Type: application/json
```

请求示例：

```json
{
  "inputDirectory": "batch-001",
  "outputDirectory": null,
  "cropStartRatio": 0.5,
  "horizontalTrimRatio": 0.25,
  "recursive": false
}
```

`inputDirectory` 默认相对于 `WEIGHT_OCR_INPUT_ROOT`，`outputDirectory` 默认在 `WEIGHT_OCR_OUTPUT_ROOT` 下按批次 ID 自动创建。接口拒绝访问两个受控根目录之外的路径。

## 必需配置

```text
BAIDU_OCR_ENABLED=true
BAIDU_OCR_API_KEY=百度应用的API Key
BAIDU_OCR_SECRET_KEY=百度应用的Secret Key
INTERNAL_SERVICE_TOKEN=至少32字节的内部令牌
```

本地默认目录：

```text
${java.io.tmpdir}/baiyue-weight-ocr/input
${java.io.tmpdir}/baiyue-weight-ocr/output
```

国内服务器默认目录：

```text
/data/baiyue/weight-ocr/input
/data/baiyue/weight-ocr/output
```

可选配置：

| 环境变量 | 默认值 | 说明 |
| --- | ---: | --- |
| `WEIGHT_OCR_MAX_IMAGE_SIZE` | `3MB` | 单张原图及裁剪图上限 |
| `WEIGHT_OCR_MAX_IMAGE_PIXELS` | `40000000` | 解码后最大像素数 |
| `WEIGHT_OCR_MAX_BATCH_SIZE` | `50` | 单批图片上限 |
| `BAIDU_OCR_CONNECT_TIMEOUT` | `10s` | 建连超时 |
| `BAIDU_OCR_REQUEST_TIMEOUT` | `60s` | 单次请求超时 |
| `BAIDU_OCR_MIN_REQUEST_INTERVAL` | `600ms` | 百度请求最小间隔 |
| `BAIDU_OCR_MAX_QPS_RETRIES` | `3` | 百度 QPS 限制重试次数 |

## 输出文件

```text
批次输出目录/
├─ batch-results.json
├─ cropped/
└─ raw/
```

接口和结果文件仅返回相对于受控根目录的路径，不返回服务器绝对路径。真实百度响应不写入日志，只保存在批次的 `raw` 目录。

## 安全边界

- 接口仅供内部服务调用，必须校验 `X-Internal-Service-Token`。
- 百度能力默认关闭，密钥只从环境变量或配置中心密文注入。
- 同一实例一次只执行一个 OCR 批次，避免并发压垮第三方接口。
- 单批顺序调用百度接口，并对 QPS 错误执行有上限的退避重试。
- 支持 `jpg`、`jpeg`、`png`、`bmp`，同时限制文件大小和解码像素数。
- 当前不访问业务数据库，识别结果由调用方按自己的业务边界处理。