# OCR Platform

新一代 OCR 中台，从 0 开始建设，不继承原型项目代码结构。

## 项目定位

OCR Platform 面向业务系统提供统一的文档智能识别能力：

- 全文 OCR 识别
- 文档版面与表格结构化
- 图片区域识别与裁切
- 键值对抽取
- 表单回填数据输出
- 人工校验
- OCR 引擎治理
- 算法评估
- 运行监控与审计

OCR Platform 不依赖任何历史 OCR 项目。PaddleOCR / PP-ChatOCR 只是当前已经验证过的一批外部算法服务适配器，不是平台本体；后续可以继续接入 RapidOCR、云 OCR、自研 OCR 或多模态文档模型。

## 技术栈

- 后端：Java 25、Spring Boot 4、Maven
- 前端：Vue 3、TypeScript、Vite 8
- 数据库：MySQL 8.4 LTS
- 缓存 / 队列：第一阶段使用 MySQL 任务表，后续按吞吐需要接 Redis / MQ
- 文件存储：第一阶段使用本地文件目录，后续可替换为 MinIO / S3
- 观测：OpenTelemetry、Micrometer、Prometheus、Grafana

后端软件包统一以 `com.zhengmeng` 开头，当前根包为 `com.zhengmeng.ocrplatform`。

## 目录

```text
backend/      Spring Boot 后端
frontend/     Vue 管理端
deploy/       本地和生产部署配置
docs/         架构、API、数据库、运维文档
samples/      样张、表单、标准答案、评估集
scripts/      辅助脚本
```

## 本地启动

先启动基础设施：

```bash
docker compose -f deploy/docker-compose.dev.yml up -d
```

后端默认使用已经部署好的 PaddleOCR Layout Parsing。需要联调其他 OCR provider 时，可以通过环境变量显式切换 PaddleOCR / PP-ChatOCR 外部容器：

```bash
OCR_ENGINE_DEFAULT_CODE=paddle-layout
```

例如切换到已部署的 PaddleOCR 结构识别服务：

```bash
OCR_ENGINE_DEFAULT_CODE=paddle-layout
PADDLE_LAYOUT_ENABLED=true
PADDLE_LAYOUT_ENDPOINT=http://192.168.1.13:18080/layout-parsing
```

如需验证 PP-ChatOCR 语义抽取，再显式启用：

```bash
PP_CHAT_OCR_ENABLED=true
PP_CHAT_OCR_VISUAL_ENDPOINT=http://192.168.1.13:18083/chatocr-visual
PP_CHAT_OCR_CHAT_ENDPOINT=http://192.168.1.13:18083/chatocr-chat
```

后端：

```bash
cd backend
mvn spring-boot:run
```

前端：

```bash
cd frontend
npm install
npm run dev
```

当前已经接入 MySQL/Flyway/JPA 的基础任务表，第一阶段目标是跑通“上传文件 -> 创建 OCR 任务 -> Worker 调用引擎 -> 保存原始结果 -> 展示任务详情”。

目前 Worker 已能消费 `QUEUED` 任务，并把引擎原始结果、文本块和键值对写入数据库。PaddleOCR `/layout-parsing` 和 PP-ChatOCR 视觉/语义接口都是可选外部 OCR provider，平台通过统一适配器接入，不把任何算法服务代码内置到中台。

## 文档入口

- 架构设计：[docs/architecture/ocr-platform-design.md](docs/architecture/ocr-platform-design.md)
- API 草案：[docs/api/api-v1.md](docs/api/api-v1.md)
- OCR 引擎适配契约：[docs/api/engine-adapter-contract.md](docs/api/engine-adapter-contract.md)
- OCR Provider 接入指南：[docs/api/ocr-provider-onboarding.md](docs/api/ocr-provider-onboarding.md)
- 开发清单：[docs/todolist.md](docs/todolist.md)

## 生产部署

生产环境建议使用：

```bash
cp .env.example .env
# 补齐数据库与服务参数后：
docker compose -f deploy/docker-compose.prod.yml up -d --build
```

部署前可先执行 smoke check，确认 compose 配置和已部署算法容器连通：

```bash
scripts/prod-smoke-check.sh
```

如需显式开启已部署 PaddleOCR provider 并跑一条端到端验证任务：

```bash
scripts/verify-paddle-layout.sh
```

该脚本使用 `.env.paddleocr.verify`，只用于验证 `paddle-layout` 外部 provider，不改变平台默认配置。
脚本会先直接调用外部 PaddleOCR `/layout-parsing` 做 provider 验证；如果后端和数据库可用，再继续上传样张跑平台端到端任务。需要强制要求平台端到端通过时，可设置 `BACKEND_REQUIRED=true`。

如需验证 PP-ChatOCR + MiniMax 语义抽取链路：

```bash
cp .env.pp-chatocr.verify.example .env.pp-chatocr.verify
scripts/verify-pp-chatocr.sh
```

该脚本会分别验证 `/chatocr-visual` 服务可达、`/chatocr-chat` 服务可达，并单独输出字段抽取是否命中。默认从本机毛豆配置读取 `MiniMax-M2.7` 参数，真实 key 不写入仓库。

当前验证库为 `ocrplatform`。该库按 MySQL 5.7 兼容的 `utf8mb4_unicode_ci` 建库，表结构由 Flyway 迁移生成。
数据库 `root` 账号只用于建库和授权管理，不用于运行本项目。应用运行账号使用 `ocrplatform_app`，只授予 `ocrplatform.*` 下的项目所需权限。

生产配置默认不绑定具体 OCR provider。当前已验证可接入的外部算法容器包括：

- PaddleOCR 结构识别：`http://192.168.1.13:18080/layout-parsing`
- PP-ChatOCR 视觉和语义接口：`http://192.168.1.13:18083/chatocr-visual`、`/chatocr-chat`

LLM 模型由后台 `LLM 模型管理` 页面维护，当前内置候选包括 DeepSeek V4 Pro、DeepSeek V4 Flash 与 MiniMax M2.7。后台可以选择当前模型，也可以独立开关每个模型的思考模式。API Key 只保存在运行数据库中，不写入仓库示例配置。
如需从本机毛豆配置导入 DeepSeek / MiniMax 参数，可执行：

```bash
scripts/import-maodou-llm-settings.py
```

PP-ChatOCR `/chatocr-chat` 调用时会读取后台选中的 LLM，并把 `chatBotConfig` 注入给外部算法容器。

服务暴露端口：

- 前端 + API 统一入口（Nginx）：`18091`
- 后端服务端口：`18090`
- Prometheus：`19090`
- Grafana：`13000`

默认生产数据库主机可通过 `.env` 中配置：

- `MYSQL_HOST=192.168.1.222`
- `MYSQL_PORT=3306`

日志目录建议：

- 后端日志：`/var/log/ocr-platform/backend.log*`
- Nginx 日志：`deploy/nginx/logs/*.log`