# OCR Provider Onboarding Guide

OCR Platform 是中台，不是某个 OCR 算法项目的子模块。任何 OCR 能力都必须以 provider 的形式接入。

## 边界原则

- 中台不依赖历史 OCR 项目、本地源码目录或算法仓库。
- 中台不内置 PaddleOCR、PP-ChatOCR、RapidOCR、自研模型或云 OCR 的服务实现。
- `paddle-layout`、`pp-chatocr` 只是当前已验证的外部服务适配器。
- 默认配置必须保持 provider-neutral：`OCR_ENGINE_DEFAULT_CODE=local-placeholder`。
- 新 provider 必须默认禁用，由部署环境显式启用。

## 接入步骤

1. 部署外部 OCR provider 服务，并确认健康检查、识别接口和超时策略。
2. 在后端新增 `OcrEngineAdapter` 实现，负责调用外部 provider。
3. 在 `EngineProperties` 增加独立配置段，例如 `rapidOcr`、`cloudOcr`、`customOcr`。
4. 在 `application.yml` 和 `deploy/docker-compose.prod.yml` 增加环境变量，默认 `enabled=false`。
5. 在 `OcrEngineController` 增加 provider descriptor，声明能力标签和可用状态。
6. 在 `OcrTaskWorker` 的请求快照中加入该 provider 的开关、endpoint、timeout 和关键参数。
7. 把 provider 原始响应完整保存到 `rawJson`，并尽量转换为标准 `textBlocks`、`keyValues`。
8. 用样张集做多 run 对比，不用 HTTP 200 代替业务成功。

## 适配器输出标准

每个 provider 适配器最终都应返回：

- `engineCode`：稳定 provider 编码，例如 `rapid-ocr`、`cloud-ocr-a`。
- `engineVersion`：provider 版本或接口版本。
- `rawJson`：外部 provider 原始响应或合并后的调用结果。
- `textBlocks`：标准文本块；没有就返回空数组。
- `keyValues`：标准键值对；没有就返回空数组。

## 禁止事项

- 不要在中台仓库新增算法服务源码目录。
- 不要让中台依赖某个本地算法项目路径。
- 不要把 PaddleOCR 或任意单一 provider 写成平台默认能力。
- 不要用 provider 的原始字段直接穿透业务层。
- 不要把 provider 健康等同于识别质量达标。