# План архитектуры obdai.ru/receipt

## 1. Цель

Создать независимый Python API-сервис для распознавания рукописных рецептов. API принимает изображение рецепта или фрагменты с названиями лекарств и дозировками, а возвращает структурированный текст для отображения в Android-приложении.

ФИО пациента, дата рождения, адрес и другие идентификаторы не должны извлекаться, сохраняться или возвращаться.

## 2. Размещение

```text
Android
  -> HTTPS
nginx: obdai.ru/receipt/
  -> 127.0.0.1:8768
receipt.service
  -> FastAPI/Gunicorn
  -> OCR/vision-модель
  -> нормализация по справочнику лекарств
  -> JSON
```

`elmer` остаётся полностью независимым:

- код: `/opt/receipt/`;
- virtualenv: `/opt/receipt/venv/`;
- пользователь systemd: отдельный `receipt`;
- порт: `127.0.0.1:8768`;
- юнит: `/etc/systemd/system/receipt.service`;
- отдельные логи и секреты;
- отдельный deploy/restart;
- отсутствие общих импортов, virtualenv и файлов с `elmer`.

## 3. API

Основной endpoint: `POST /receipt/recognize`.

Формат: `multipart/form-data`.

Поля:

- `image` — JPEG, PNG или WEBP, до 10 MB;
- `request_id` — UUID клиента;
- `masked_zones` — координаты зон, которые нужно закрыть до OCR;
- при необходимости отдельный тип запроса для уже выделенных фрагментов.

Ответ должен содержать:

- `request_id`;
- дату рецепта, если она распознана;
- список лекарств;
- исходный распознанный фрагмент без PII;
- bounding box;
- дозировку и режим приёма как написано;
- `confidence`;
- `uncertain`;
- кандидатов из справочника при сомнительном совпадении.

Ошибки: `400`, `401`, `413`, `422`, `429`, `503`.

## 4. Pipeline

1. Проверить API-ключ, размер, magic bytes и разрешение изображения.
2. Применить маскирование зон до передачи изображения модели.
3. Выполнить масштабирование и deskew.
4. Получить OCR-текст и bounding boxes.
5. Выделить роли: лекарство, дозировка, режим, дата, прочее.
6. Удалить PII из результата.
7. Сопоставить название со справочником через нормализацию и `rapidfuzz`.
8. При близких или слабых совпадениях установить `uncertain=true`.
9. Валидировать ответ Pydantic.
10. Вернуть JSON без записи изображения и медицинского текста на диск.

## 5. Модель и OCR

Сначала проверить, поддерживает ли используемый endpoint `gpt-oss-120b` изображения. Размер 120B сам по себе не означает наличие vision-возможностей.

- Если модель vision-capable: изображение -> модель -> строгий JSON.
- Если text-only: Tesseract 5 или облачный OCR с русским языком и bounding boxes -> `gpt-oss-120b` для структурного разбора -> справочник.
- Финальное название лекарства нельзя принимать только от LLM: источник истины — справочник и fuzzy matching.
- Дозировка возвращается как распознанный текст, без медицинской интерпретации.

## 6. Справочник лекарств

Для MVP использовать локальную read-only SQLite БД.

Минимальные сущности:

- препарат;
- МНН;
- торговое название;
- форма выпуска;
- дозировка;
- производитель;
- синонимы и распространённые варианты написания;
- поисковый индекс;
- пары опасно похожих названий.

Возможный базовый источник — ГРЛС. Перед использованием необходимо проверить формат, условия использования, полноту данных и порядок обновления. Коммерческие справочники требуют отдельной лицензии.

Рекомендуемая логика:

- высокий score: совпадение;
- средний score: `uncertain=true` и список кандидатов;
- низкий score: совпадение не подтверждать;
- при близости двух похожих препаратов принудительно требовать подтверждение пользователя.

## 7. Персональные данные

- Android маскирует ФИО/ДР до отправки.
- Сервер повторно применяет `masked_zones` до OCR.
- В response schema отсутствуют поля пациента.
- Изображения и raw OCR не записываются на диск.
- В логах только `request_id`, статус, размер, latency и количество сомнительных позиций.
- TLS обеспечивается nginx.
- API требует Bearer-ключ.
- Должны быть TTL, rate limiting и аудит без медицинского содержимого.

## 8. Надёжность

- Жёсткие timeout для nginx, Gunicorn, HTTP-клиента модели и SQLite.
- На MVP синхронная обработка без Redis/Celery.
- При недоступности модели возвращать `503`.
- Ограничить размер запроса и частоту запросов.
- Health endpoint не должен требовать API-ключ.
- Metrics endpoint доступен только локально.
- Бэкапить только справочник и конфигурацию ключей, не изображения.

## 9. Этапы

### MVP

1. FastAPI, health и recognize.
2. Отдельные `/opt/receipt`, virtualenv, systemd и nginx location.
3. Загрузка справочника в SQLite.
4. OCR и базовый matcher.
5. Pydantic response без PII.
6. API-ключ, лимиты и journald.

### Следующий этап

- интеграция vision-модели;
- calibrated confidence;
- подтверждение кандидатов в Android;
- автообновление справочника;
- Prometheus metrics;
- circuit breaker;
- расширенная защита от похожих названий.

## 10. Основные риски

- `gpt-oss-120b` может оказаться text-only;
- рукописный русский текст может распознаваться с низкой точностью;
- fuzzy matching может выбрать похожий препарат;
- ГРЛС может быть неполным или неудобным для автоматической синхронизации;
- клиент может случайно отправить PII;
- медицинский сценарий требует явного отказа от диагностики и назначения лечения.

## 11. Утверждённый вариант распознавания

Сервис не строится как `OCR -> исправление строки`. Основной принцип: vision-модель возвращает несколько гипотез наблюдаемого текста, после чего локальный справочник участвует в выборе допустимого препарата.

```text
crop лекарственной строки
  -> несколько вариантов preprocessing
  -> DeepSeek Vision: observed_text + alternatives
  -> exact/alias/fuzzy candidate resolver
  -> проверка дозировки и лекарственной формы
  -> scoring
  -> CONFIDENT / NEED_CONFIRMATION / UNKNOWN
```

Ключевые правила:

- не просить модель угадывать единственный препарат без альтернатив;
- не отправлять весь словарь в prompt;
- сначала получать ограниченный набор кандидатов локальным поиском, затем передавать модели только top-N;
- название, strength и схему приёма распознавать отдельными полями;
- несовместимую дозировку использовать для снижения уверенности, а не для автоматического исправления;
- при близких названиях показывать варианты пользователю;
- добавить endpoint подтверждения результата, чтобы собирать обезличенные correction samples;
- начать с SQLite и перейти на отдельный PostgreSQL только при появлении требований к параллельной записи, админке или нескольким экземплярам сервиса.

Перед фиксацией порогов и коэффициентов scoring провести эксперимент на 50–200 обезличенных рецептах.

## 12. Критический план по результатам валидации Opus (2026-08-31)

### Подтвержденные проблемы и приоритет

1. `recipe_service/metrics.py`: убрать `initialize()` из `record()`; инициализация должна быть только на старте сервиса.
2. `recipe_service/app.py`: устранить дублирование `record(...)` через единый финализатор/обертку завершения запроса.
3. `recipe_service/app.py`: считать `duration_ms` во всех ветках, а не только при `401`.
4. `recipe_service/app.py`: заменить сравнение токена на constant-time (`hmac.compare_digest`).
5. `recipe_service/app.py`: минимизировать детализацию `502` для клиента, подробности оставлять в логах.
6. `recipe_service/app.py`: добавить учет заголовков прокси (`ProxyFix`) для корректного client IP.
7. Тесты: добавить `recipe_service/test_app.py` с кейсами `401/400/415/413/200`.
8. `requirements.txt`: выровнять root и `recipe_service/requirements.txt` по version bounds.

### Android-блок (после подтверждения модели безопасности)

1. Убрать долговременный статический секрет из APK или перейти на схему краткоживущих токенов.
2. Оптимизировать pipeline камеры: снизить частоту тяжелой конвертации или заменить способ получения bitmap.
3. Убрать двойной вывод результата (`Column` и `ResultOverlay`) и оставить один источник отображения.
4. Пересмотреть `containsPatientData` в `MedicationZoneDetector`: дата сама по себе не должна блокировать распознавание.

### Вопросы к Opus (требуют уточнения до правок)

1. `api_key_override` в `gemini_proxy/app.py`: удалять полностью или оставить только для локального debug-режима за флагом окружения?
2. По `502`: какой клиентский формат ошибки нужен — единое сообщение или кодизированные причины без деталей провайдера?
3. Для `ProxyFix`: доверяем ровно одному прокси (`x_for=1`) или нужен более строгий trust chain?
4. Для Android: подтверждаем перенос от статического API-токена к короткоживущему серверному token exchange?
5. По privacy-гейту: дата рецепта в medication-зоне допустима или должна только понижать confidence без блокировки?

### План выполнения после подтверждения

1. Backend фаза A: `metrics.py` + `app.py` (инициализация, duration, record-finalizer, compare_digest, ProxyFix).
2. Backend фаза B: тесты `recipe_service/test_app.py` + проверка pytest.
3. Backend фаза C: harmonize requirements.
4. Android фаза D: безопасность токена + оптимизация камеры + privacy-gate.