chore: каркас проекта — контракты, справочник услуг, синтетические фикстуры

2026-06-26 12:30:00 +05:00
commit 3834e4811d
18 changed files with 3409 additions and 0 deletions
@@ -0,0 +1,58 @@
+# MedArchive — обработка архива прайсов клиник-партнёров
+
+Terricon Valley · Medtech Hackathon (26–28.06.2026).
+
+**Живой демо: https://med.secondbrain.tools**
+
+Система автоматически разбирает архив разнородных прайс-листов клиник (PDF, сканы, DOCX,
+XLSX/XLS), извлекает услуги и цены, нормализует их к справочнику из 1281 услуги и даёт поиск
+и сравнение «кто оказывает услугу и по какой цене».
+
+## Результат на тестовом архиве (8 клиник, 10 файлов)
+
+- **8 871 позиция** извлечена: 6 клиник из 8 — нативными парсерами, трудные PDF (битый
+  текстовый слой, нестандартная вёрстка) — через Gemini Vision.
+- **73,9% позиций нормализованы автоматически** (цель ТЗ — не ниже 70%).
+- Остальное уходит в очередь ручной разметки, как и предполагает ТЗ.
+
+Полный отчёт о качестве — `docs/quality_report.json`.
+
+## Стек и решения
+
+| Слой | Решение |
+|---|---|
+| Извлечение | Python: pdfplumber + PyMuPDF, openpyxl/xlrd, python-docx. Таблицы из PDF без линий восстанавливаются по координатам слов |
+| Vision-добор | Gemini (`gemini-2.5-flash`) — для сканов и битого текстового слоя |
+| Нормализация | Каскад: код тарификатора → точное совпадение → эмбеддинги Gemini → нечёткое сравнение → очередь `unmatched` |
+| Валидация | Правила ТЗ §4.4: положительность цены, резидент ≥ нерезидент, аномалии, версионирование |
+| Хранилище | SQLite (MVP, разворачивается без Docker). Боевая схема PostgreSQL + pgvector — в `db/migrations` |
+| API | FastAPI: 7 эндпоинтов ТЗ + `/stats`, OpenAPI на `/docs` |
+| Фронт | Одностраничный (Tailwind): поиск услуги и сравнение цен по клиникам |
+| Деплой | Контейнер API за Caddy на Selectel KZ |
+
+## Запуск локально
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e .
+# архив прайсов → data/raw/, справочник → data/reference/dictionary.xlsx
+GEMINI_API_KEY=... python scripts/run_pipeline.py        # → data/medarchive.db + отчёт
+uvicorn api.main:app                                     # → http://localhost:8000/docs
+# открыть web/index.html?api=http://localhost:8000
+```
+
+Эмбеддинги и Vision вызываются через Gemini API, поэтому локальная модель не нужна и контейнер
+остаётся лёгким. Поиск и сравнение в готовой базе работают без обращений к API.
+
+## Структура
+
+```
+contracts/  — общие модели данных (контракт между модулями)
+db/         — схема PostgreSQL + pgvector
+etl/        — извлечение, нормализация, валидация, конвейер
+api/        — REST API поиска и сравнения
+web/        — одностраничный фронт
+infra/      — деплой (compose, Caddyfile)
+docs/       — отчёт о качестве, план
+pitch/      — презентация и демо-сценарий
+scripts/    — запуск конвейера и проверки
+```