qr-manager fixed for both qr-codes

ocr-service/system-prompt.md

@@ -0,0 +1,87 @@
+Вот подробный системный промпт (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, ни текст не прочитался). Предложите пользователю переснять фото.