medtech-hackathon/docs/ARCHITECTURE.md

Архитектура MedArchive

Документ описывает систему как она собрана (as-built): поток данных, карту модулей, модель данных, ключевые инженерные решения и их обоснование.

Назначение системы: принять архив разнородных прайс-листов клиник, извлечь услуги и цены, нормализовать их к единому справочнику и отдать поиск и сравнение «кто оказывает услугу и по какой цене». Живая версия — https://med.secondbrain.tools.

---

1. Поток данных

архив (PDF/скан/DOCX/XLSX/XLS)
        │
        ▼
  извлечение по форматам ──(битый слой / 0 строк)──► Gemini Vision
        │
        ▼
   нормализация к справочнику   код → точное → эмбеддинги → нечёткое → очередь
        │
        ▼
      валидация (правила ТЗ §4.4)
        │
        ▼
        SQLite  ── версионирование цен (свежий прайс активен, старые в архив)
        │
        ▼
   FastAPI (поиск, сравнение, верификация, загрузка, экспорт)
        │
        ▼
   статический фронт (поиск и сравнение цен, админка оператора)

Конвейер линейный, каждый шаг — отдельный модуль. Два входа: run() собирает базу с нуля по всему архиву; ingest() догружает новые прайсы в готовую базу (на нём держится приём архива через интерфейс и авто-загрузка из папки).

---

2. Карта модулей

Каталог	Роль
contracts/	Pydantic-модели (контракт между шагами): RawRow, ParsedDocument, MatchResult, выходные DTO API
etl/dictionary.py	Загрузка справочника услуг из xlsx, нормализация названий
etl/extractors/	readers — чтение форматов в «сетки»; grid — определение ролей колонок; common — эвристики прайсов; vision — добор через Gemini; __init__ — диспетчер и триггер Vision
etl/normalize/	embedding — эмбеддинги Gemini; matcher — каскад сопоставления
etl/validate/	Правила валидации позиций (ТЗ §4.4)
etl/pipeline.py	Оркестрация: run (полная сборка), ingest (догрузка), версионирование, отчёт о качестве
api/	FastAPI: поиск, сравнение, верификация, загрузка, экспорт, авто-загрузка, алерты
web/	Одностраничный фронт (Tailwind): поиск и сравнение цен + админка оператора
db/migrations/	Боевая схема PostgreSQL + pgvector (наготове)
infra/	Dockerfile, docker-compose, Caddyfile — деплой за Caddy на Selectel KZ
scripts/	run_pipeline — сборка базы; gen_fixtures — синтетические прайсы; proof/ — разведка форматов

---

3. Модель данных (SQLite, MVP)

• service — справочник: service_id, specialty, name_ru, name_norm, tarificator_code.
• partner — клиника: partner_id, name, name_norm (дедуп), city.
• price_document — загруженный файл: doc_id, partner_id, file_name, file_format (pdf/scan_pdf/docx/xlsx/xls), effective_date, parse_status, rows_count.
• price_item — извлечённая позиция: service_name_raw, service_code_source, service_id (nullable — пусто, если в очереди), prices (JSON тариф → сумма: resident, nonresident, cis, far, insurance, partner), денормализованные price_resident и price_nonresident, unit, effective_date, map_method, map_confidence, is_active, suggested_service_id/suggested_score (кандидат оператору, даже ниже порога).
• learned_synonym (name_norm → service_id) — синонимы, выученные при верификации.
• skipped_item, settings, ingested_file — служебные (очередь, папка авто-загрузки, журнал обработанных файлов); создаются лениво на стороне API.

Боевая схема — PostgreSQL + pgvector (db/migrations): эмбеддинги в vector-колонке с HNSW-индексом, в остальном модель та же.

---

4. Извлечение

Все табличные источники сводятся к «сетке» (список строк из строковых ячеек) и обрабатываются единым кодом — так xlsx, xls, docx и таблицы из PDF проходят через одну логику.

• XLSX/XLS/DOCX — нативные парсеры (openpyxl, xlrd, python-docx). Для DOCX правки принимаются (работаем с финальным текстом).
• PDF с текстовым слоем — таблицы восстанавливаются по координатам слов: у казахстанских прайсов часто нет линий таблицы, поэтому pdfplumber.extract_tables ничего не находит. Слова группируются в строки по вертикали, внутри строки режутся на ячейки по горизонтальным разрывам — так колонки цен (резидент/нерезидент/…) не сливаются.
• Определение ролей колонок (grid.py): ценовые колонки — по заголовку и медиане значений (медуслуга дороже сотни тенге, что отсекает колонку «№» и мелочь); колонка названия — самая «кириллическая», но колонки Код/№/тарификатор исключаются заранее (иначе ключ «услуг» ловит заголовок «Код услуги» и колонка кодов ошибочно становится колонкой названий).
• Gemini Vision (gemini-2.5-flash) — запасной путь для сканов, битого текстового слоя и нестандартной вёрстки. Триггерится автоматически, когда нативный разбор пуст, помечен как scan_pdf или даёт подозрительно мало строк на страницу; большие документы пропускаются ради экономии (это фиксируется в логе). Если Vision полнее нативного разбора — заменяет его.

---

5. Нормализация

Каскад по убыванию надёжности (matcher.py):

1. Код тарификатора — точное совпадение по канонической части кода, если клиника его указала (бесплатно и точно).
2. Точное совпадение нормализованного названия со справочником.
3. Эмбеддинги Gemini (gemini-embedding-001, 768 измерений; справочник — RETRIEVAL_DOCUMENT, запрос — RETRIEVAL_QUERY) — семантическая близость названий. Порог косинуса 0.70: у Gemini эмбеддинги «в конусе» (несвязанные названия дают 0.6–0.7), ниже порога ловится мусор.
4. Нечёткое сравнение (RapidFuzz) — запасной сигнал.
5. Иначе — очередь ручной разметки (unmatched), но кандидат сохраняется оператору.

Эмбеддинги справочника кэшируются (dict_emb.npy): при догрузке нового прайса справочник не пересчитывается, эмбеддится только новый файл. Подтверждение оператора пишет learned_synonym — следующий прогон сопоставит синоним автоматически (система дообучается).

Качество на тестовом архиве (8 клиник, 10 файлов): 16 140 позиций извлечено, 73,7% нормализовано автоматически (код 4397, точное 291, эмбеддинги 7083, нечёткое 128), плюс 273 неуверенных матча сняты guard'ом переобобщения в очередь.

---

6. Валидация и версионирование

Движок проверок (validate/rules.py, правила ТЗ §4.4): цена положительна и числовая; нерезидент не дешевле резидента; название не пустое и не код; дата не в будущем. Нарушения помечают позицию на ручную проверку.

Версионирование: если у клиники по той же услуге есть более свежий прайс, старые позиции архивируются (is_active = 0), а не удаляются — история цен сохраняется и питает алерты об изменении цен.

---

7. API (FastAPI)

root_path="/api" — за Caddy сервис живёт на /api, иначе Swagger ищет спеку в корне. Документация на /api/docs.

Эндпоинт	Назначение
GET /services, GET /services/{id}/partners	Справочник и ядро WOW: кто оказывает услугу и по какой цене (от выгодной)
GET /partners, GET /partners/{id}/services	Клиники и их прайсы
GET /search	Регистронезависимый поиск по услугам и клиникам (по name_norm)
GET /unmatched, GET /unmatched/count, POST /match, POST /skip	Очередь верификации, ручное сопоставление с дообучением, пропуск
POST /ingest	Приём ZIP-архива через интерфейс (§4.1)
GET/POST /settings, POST /scan	Папка авто-загрузки и её обработка (вызывается кроном)
GET /price-changes	Услуги, у которых цена изменилась между прайсами (детектор аномалий в интерфейсе)
GET /export.xlsx	Выгрузка каталога в Excel: лист «Каталог» (одна строка на услугу×клинику) + лист «Все позиции»
GET /stats, GET /health	Сводка качества (из базы) и проверка живости

Тяжёлые зависимости (конвейер, Gemini) в /ingest и /scan импортируются лениво — read-only API живёт и без них; эмбеддинги при загрузке — best-effort (при сбое Gemini обрабатываем без них).

---

8. Фронт

Один статический web/index.html (Tailwind CDN, vanilla JS), без сборки и Next.js:

• Поиск → сравнение: услуга → таблица клиник с ценами, подсветка самой выгодной и переплаты к медиане.
• Админка оператора: дашборд качества; загрузка ZIP; авто-загрузка из папки; алерты об изменении цен; экспорт в Excel; очередь верификации с предложенным кандидатом и дообучением.

---

9. Инфраструктура и деплой

Контейнер API (Docker-образ с зависимостями, код монтируется томом) за общим Caddy на VPS Selectel (Казахстан). Caddy маршрутизирует /api/* → контейнер, / → фронт, /pitch /day1 /day2 → презентации. Авто-загрузка: папка /app/inbox (том хоста) + крон каждые 10 минут дёргает /scan.

Read-only поиск работает на готовой SQLite-базе без обращений к Gemini; ключ Gemini нужен только для /ingest//scan (живая догрузка) и при сборке базы.

---

10. Ключевые решения и обоснование

• SQLite для MVP — разворачивается без Docker (на Mac его нет), быстрый старт. Боевая схема PostgreSQL + pgvector готова в db/migrations.
• Эмбеддинги и Vision через Gemini API, не локальный torch — контейнер на маленьком VPS не раздувается и не держит модель в RAM.
• Реконструкция таблиц PDF по координатам слов — реальные прайсы часто без линий таблицы, обычный парсер таблиц их не находит.
• Порог эмбеддингов 0.70 + очередь unmatched — у Gemini несвязанные названия лежат «в конусе» 0.6–0.7; порог отсекает мусор, спорное уходит оператору (ТЗ §4.3), а не сопоставляется наугад.
• Кэш эмбеддингов справочника — догрузка нового прайса не пересчитывает тысячи услуг.
• Гибкая модель цен prices jsonb — у клиник не «резидент/нерезидент», а N тарифов (СНГ, дальнее зарубежье, страховые, партнёр); две главные колонки денормализованы под ТЗ и API.
• Vision как добор, а не основной путь — чистое берут быстрые парсеры, трудное добирает Vision; большие документы не отправляются в Vision ради стоимости и времени.

---

11. Что дальше

• Миграция на PostgreSQL + pgvector (схема готова) для продакшн-нагрузки.
• Извлечение БИН и города партнёра (модель есть, поля пока не заполняются).
• Экспорт каталога в биллинг/CRM по API (не только Excel).
• Мультиязычные синонимы справочника (KAZ/ENG) для роста автонормализации.