mirror of
https://github.com/serty2005/rmser.git
synced 2026-02-05 03:12:34 -06:00
87 lines
6.0 KiB
Markdown
87 lines
6.0 KiB
Markdown
Вот подробный системный промпт (System Definition), который описывает архитектуру, логику и контракт работы твоего OCR-сервиса.
|
||
|
||
Сохрани этот текст как **`SYSTEM_PROMPT.md`** или в документацию проекта (Confluence/Wiki). К нему стоит обращаться при разработке API-клиентов, тестировании или доработке логики.
|
||
|
||
---
|
||
|
||
# System Definition: RMSER OCR Service
|
||
|
||
## 1. Роль и Назначение
|
||
**RMSER OCR Service** — это специализированный микросервис на базе FastAPI, предназначенный для извлечения структурированных данных (товарных позиций) из изображений кассовых чеков РФ.
|
||
|
||
Сервис реализует **Гибридную Стратегию Распознавания**, отдавая приоритет получению верифицированных данных через ФНС, и используя оптическое распознавание (OCR) только как запасной вариант (fallback).
|
||
|
||
## 2. Логика Обработки (Workflow)
|
||
|
||
При получении `POST /recognize` с изображением, сервис выполняет действия в строгой последовательности:
|
||
|
||
### Этап А: Поиск QR-кода (Priority 1)
|
||
1. **Детекция:** Сервис сканирует изображение на наличие QR-кода (библиотека `pyzbar`).
|
||
2. **Декодирование:** Извлекает сырую строку чека (формат: `t=YYYYMMDD...&s=SUM...&fn=...`).
|
||
3. **Запрос к API:** Отправляет сырые данные в API `proverkacheka.com` (или аналог).
|
||
4. **Результат:**
|
||
* Если API возвращает успех: Возвращает идеальный список товаров.
|
||
* **Метаданные ответа:** `source: "qr_api"`.
|
||
|
||
### Этап Б: Оптическое Распознавание (Fallback Strategy)
|
||
*Запускается только если QR-код не найден или API вернул ошибку.*
|
||
|
||
1. **Препроцессинг (OpenCV):**
|
||
* Поиск контуров документа.
|
||
* Выравнивание перспективы (Perspective Warp).
|
||
* Бинаризация (Adaptive Threshold) для подготовки к Tesseract.
|
||
2. **OCR (Tesseract):** Извлечение сырого текста (rus+eng).
|
||
3. **Парсинг (Regex):**
|
||
* Поиск строк, содержащих паттерны цен (например, `120.00 * 2 = 240.00`).
|
||
* Привязка текстового описания (названия товара) к найденным ценам.
|
||
4. **Результат:** Возвращает список товаров, найденных эвристическим путем.
|
||
* **Метаданные ответа:** `source: "ocr"`.
|
||
|
||
## 3. Контракт API (Interface)
|
||
|
||
### Входные данные
|
||
* **Endpoint:** `POST /recognize`
|
||
* **Format:** `multipart/form-data`
|
||
* **Field:** `image` (binary file: jpg, png, heic, etc.)
|
||
|
||
### Выходные данные (JSON)
|
||
Сервис всегда возвращает объект `RecognitionResult`:
|
||
|
||
```json
|
||
{
|
||
"source": "qr_api", // или "ocr"
|
||
"items": [
|
||
{
|
||
"raw_name": "Молоко Домик в Деревне 3.2%", // Название товара
|
||
"amount": 2.0, // Количество
|
||
"price": 89.99, // Цена за единицу
|
||
"sum": 179.98 // Общая сумма позиции
|
||
},
|
||
{
|
||
"raw_name": "Пакет-майка",
|
||
"amount": 1.0,
|
||
"price": 5.00,
|
||
"sum": 5.00
|
||
}
|
||
],
|
||
"raw_text": "..." // Сырой текст (для отладки) или содержимое QR
|
||
}
|
||
```
|
||
|
||
## 4. Технический Стек и Зависимости
|
||
* **Runtime:** Python 3.10+
|
||
* **Web Framework:** FastAPI + Uvicorn
|
||
* **Computer Vision:** OpenCV (`cv2`) — обработка изображений.
|
||
* **OCR Engine:** Tesseract OCR 5 (`pytesseract`) — движок распознавания текста.
|
||
* **QR Decoding:** `pyzbar` + `libzbar0`.
|
||
* **External API:** `proverkacheka.com` (требует валидный токен).
|
||
|
||
## 5. Ограничения и Известные Проблемы
|
||
1. **Качество OCR:** В режиме `ocr` точность зависит от качества фото (освещение, помятость). Возможны ошибки в символах `3/8`, `1/7`, `З/3`.
|
||
2. **Зависимость от API:** Для работы режима `qr_api` необходим доступ в интернет и оплаченный токен провайдера.
|
||
3. **Скорость:** Режим `qr_api` работает быстрее (0.5-1.5 сек). Режим `ocr` может занимать 2-4 сек в зависимости от разрешения фото.
|
||
|
||
## 6. Инструкции для Интеграции
|
||
При встраивании сервиса в общую систему (например, Telegram-бот или Backend приложения):
|
||
1. Всегда проверяйте поле `source`. Если `source == "ocr"`, помечайте данные для пользователя как "Требующие проверки" (Draft). Если `source == "qr_api"`, данные можно считать верифицированными.
|
||
2. Если массив `items` пустой, значит сервис не смог распознать чек (ни QR, ни текст не прочитался). Предложите пользователю переснять фото. |