## Кратко о компоненте AI Medical Archive
AI Medical Archive — это компонент для МЗБ.РФ, который превращает сайт в умный медицинский архив. Он бережно хранит результаты анализов и обследований, распознаёт бланки с помощью нейросетей, подсвечивает критические значения и помогает обычному пользователю понять сложные медицинские термины простым языком.
Компонент особенно полезен:
- для пациентов, которые годами копят бумажные бланки и теряются в них;
- для родителей, ведущих архив анализов ребёнка;
- для людей с хроническими заболеваниями, где важно следить за динамикой показателей;
- для онлайн‑сервисов и клиник, которые хотят дать клиенту удобный личный кабинет с историей анализов и консультациями.
Все данные группируются по «архивам» родственников, интегрируются с Rewardify (система баллов) и JomSocial (пользовательские профили), а тяжёлая работа по распознаванию и первичной аналитике перекладывается на подключаемый AI‑API.
## Основные задачи, которые решает компонент
- **Цифровой медицинский архив**: структурированное хранение анализов, приёмов и обследований по каждому члену семьи.
- **Автоматическое распознавание бланков**: загрузка фото или PDF, конвертация в нормализованный JSON с показателями.
- **Отслеживание динамики показателей**: удобный трекер, который строится по распознанным маркерам.
- **Контроль критических значений**: база референсных интервалов, предупреждения и подсветка опасных показателей.
- **Объяснение непонятных терминов и маркеров**: встроенная база знаний и диалог с ИИ для расшифровки.
- **Подготовка к приёму у врача**: автоматизированный «бриф» по выбранным анализам и документам.
- **Монетизация и геймификация**: начисление и списание баллов через Rewardify за распознавание, консультации и запросы к ИИ.
Далее — подробный разбор, как устроен компонент и что за что отвечает.
## Пользовательский интерфейс: личный медицинский архив
### Архивы родственников
Входная точка компонента — страница «Мой архив». Здесь пользователь видит список архивов:
- **ФИО родственника**;
- **год рождения**;
- **статус согласия** (получено/ожидается).
Каждый архив — это отдельная история наблюдения за конкретным человеком. Через кнопку «Добавить архив» создаётся карточка с ФИО, датой рождения и отметкой о разрешении на обработку данных. Форма проста и не перегружена, но при этом подчёркивается важный момент: владелец аккаунта берёт на себя ответственность за хранение и обработку медицинской информации родственника.
### Загрузка бланков анализов и обследований
После выбора архива открывается ключевая зона — **блок загрузки документов**. Пользователь:
1. Выбирает тип документа:
- анализ (laboratory analysis),
- приём (осмотр, консультация врача),
- обследование (УЗИ, МРТ, КТ и т.п.).
2. При необходимости указывает название документа (например, «Биохимия крови 12.03.2026» или «УЗИ брюшной полости»).
3. Загружает файл в формате **JPG, JPEG, PNG или PDF**.
Дальше включается механизм очереди: файл отправляется в AI‑сервис, создаётся задача на распознавание, а на стороне пользователя отображается статус — от «ожидает обработки» до «готово» или «ошибка». Если компонент подключён к Rewardify и настроены баллы, рядом выводится подсказка, сколько баллов спишется за одно распознавание.
### Ручной ввод результатов
Не каждый бланк удобно фотографировать, и не всегда есть файл под рукой. Для таких случаев предусмотрен **ручной ввод**:
- выбор типа документа (анализ / приём / обследование);
- отдельное поле для названия (для приёмов и обследований);
- кнопка «Добавить элемент анализа/обследования», открывающая модальное окно со справочником показателей;
- выбор показателя из таблицы (для анализов — маркеры, для обследований — коды из приказа 804н);
- ввод значения и единиц измерения (для обследований — результата в свободной форме);
- текстовое поле для полного описания — сюда можно вставить выдержки из заключения, заметки врача, свои комментарии.
Компонент аккуратно следит, чтобы пользователь не отправлял пустые документы: без текста и без добавленных маркеров форма не будет сохранена. Это защищает от «заспамленных» записей и держит архив аккуратным.
### Список документов и рабочие сценарии
Ниже на странице архива расположен **список всех документов**, привязанных к этому человеку:
- дата создания записи;
- тип (анализ, приём, обследование) + опциональное название;
- статус (`ожидает`, `обрабатывается`, `готов`, `ошибка`);
- действия: открыть карточку, отправить на повторное распознавание, запустить проверку критических значений.
Список можно отсортировать:
- по дате (новые/старые),
- по типу,
- по статусу.
Для документов со статусом `готов` становятся доступны **групповые операции**:
- **оценка стоимости анализа**: компонент отправляет AJAX‑запрос и показывает, сколько баллов уйдёт на разбор выбранных документов, сколько осталось на балансе и какой суммарный объём текста;
- **запрос анализа**: формируется запрос к ИИ, который учитывает выбранные документы и (опционально) автоматический промпт;
- **подготовка к приёму**: на основе тех же документов генерируется структурированная сводка, которую удобно показать врачу или сохранить для себя.
Перед списанием баллов компонент обязательно спрашивает подтверждение пользователя, подставляя реальные цифры из Rewardify.
### Трекер динамики показателей
Если в архиве накопилось хотя бы несколько документов с распознанными маркерами, появляется кнопка «Показать динамику». Она ведёт на отдельный **трекер**, который:
- подтягивает значения показателей из таблицы маркеров;
- группирует их по типам анализов и коду показателя;
- строит временные ряды, наглядно показывая, как менялись, например, глюкоза, ферритин или креатинин.
Благодаря тому, что при распознавании используется единый стандарт кодов (glc, ca, k, iron, ferritin, creat и т.д.), трекер не путается в русских названиях и считает динамику по единым маркерам.
### Карточка отдельного документа
При переходе в документ пользователь видит:
- базовую информацию — тип, дата, статус;
- блок с предупреждениями:
- критические значения;
- отсутствие показателей для проверки;
- результат последней проверки;
- таблицу маркеров:
- человекочитаемое название (по справочнику),
- значение,
- единица измерения,
- кнопка «Объяснить термин» для каждого маркера.
Ниже, если данные пришли от AI‑распознавания, можно развернуть **полный JSON‑ответ** — это полезно для продвинутых пользователей и технических специалистов. Там же хранится «сырой текст» бланка, приведённый к понятному виду.
Отдельный блок посвящён **неизвестным маркерам**: если показатель не найден в справочнике критических значений, компонент предложит отправить его в ИИ для оценки и сохранения в базу знаний. Стоимость такого запроса также регулируется через систему баллов.
### Объяснение медицинских терминов
Компонент решает еще одну боль пациента — непонятные названия анализов и терминов. В карточке документа и через отдельное модальное окно пользователь может:
- ввести любой термин;
- отправить запрос;
- получить понятное, адаптированное объяснение «для человека без медицинского образования».
Ответ формируется на основе:
- собственной базы знаний,
- при необходимости — внешнего AI‑сервиса (через RagService и chat‑методы).
Кнопка и тексты вокруг неё настраиваются в админке, поэтому владелец сайта может подобрать тональность под свой бренд.
## Система баллов и интеграция Rewardify
AI‑запросы и распознавание бланков — ресурсоёмкие операции, поэтому компонент сразу готов к монетизации или лимитированию нагрузки.
В настройках задаются:
- **points_recognize** — сколько баллов списывать за распознавание одного файла;
- **points_consultation** — стоимость консультационного анализа;
- **points_per_million_chars** — тариф за объём текста;
- **points_term** — стоимость объяснения одного термина;
- **points_preparation** — цена подготовки к приёму.
За учёт и операции с баллами отвечает **RewardifyService**:
- проверяет баланс пользователя;
- списывает баллы при успешной операции;
- при необходимости возвращает (например, если задача распознавания упала с ошибкой).
Благодаря этому, компонент можно:
- использовать как платный сервис на сайте клиники;
- комбинировать бесплатный базовый функционал с платными «премиум» возможностями (подробные консультации, продвинутая аналитика и т.д.).
## Критические значения и безопасность пациента
Отдельный важный слой компонента — **контроль критических значений**. За него отвечает таблица `#__ai_med_critical_values` и админский интерфейс «Критические значения».
Администратор может:
- импортировать пороговые значения в удобном текстовом формате:
- `glc 3.5 6.0 ммоль/л`
- `chol 0 5.2 ммоль/л`
- `tsh 0.4 4.0 мЕд/л`
- добавлять и редактировать записи вручную;
- восстанавливать значения по умолчанию одной кнопкой.
Каждая запись содержит:
- **marker_name** — внутренний код маркера (glc, tsh, ferritin и т.д.);
- **display_name** — человекочитаемое название;
- **med_code** — код по медицинской номенклатуре;
- **минимум и максимум** нормы;
- **единицу измерения**.
Когда документ готов, компонент:
1. Нормализует названия показателей (учитывая популярные синонимы и русские варианты).
2. Находит соответствующие записи в справочнике критических значений.
3. Сравнивает реальное значение с интервалом нормы.
4. Формирует:
- список критичных показателей,
- предупреждения,
- список «неизвестных маркеров», которые надо доучить системе.
Пользователь видит результат проверки в карточке документа: либо список тревожных показателей, либо аккуратное сообщение о том, что опасных значений не найдено.
## База знаний и термины
Компонент умеет работать не только с цифрами, но и с текстом. В административной части есть раздел «База знаний», где хранятся:
- медицинские термины;
- описания и объяснения;
- при необходимости — референсные диапазоны и единицы.
Эта база:
- используется для быстрых ответов на типичные запросы («что такое ферритин», «что показывает TSH»);
- дополняется через запросы к ИИ, когда пользователь сталкивается с неизвестным маркером;
- обеспечивает единый стиль и качество объяснений по всему сайту.
Для администратора это удобный инструмент:
- дообучать систему под конкретную специализацию (эндокринология, онкология, педиатрия и т.д.);
- хранить свои формулировки, согласованные с врачами клиники.
## Пошаговая инструкция: как работать обычному пользователю
1. **Авторизация на сайте**. Компонент рассчитан на связку с пользовательским профилем, поэтому сначала нужно войти в личный кабинет.
2. **Переход в «Мой архив»**. В меню сайта выбрать соответствующий пункт.
3. **Создание архива родственника**:
- указать ФИО;
- дату рождения;
- подтвердить согласие на хранение данных.
4. **Добавление документа**:
- выбрать нужный архив;
- в блоке загрузки указать тип документа;
- при необходимости задать понятное название;
- загрузить файл или воспользоваться ручным вводом.
5. **Ожидание обработки**:
- при загрузке файла дождаться, пока статус изменится на «готов»;
- система сама поставит задачу в очередь и выполнит распознавание.
6. **Просмотр результата**:
- открыть документ;
- посмотреть таблицу показателей и их значения;
- при наличии — обратить внимание на блок критических значений.
7. **Объяснение непонятных терминов**:
- нажать кнопку «Объяснить термин» напротив нужного показателя;
- либо открыть отдельное окно и ввести термин вручную;
- получить развёрнутое пояснение простыми словами.
8. **Подготовка к приёму**:
- на странице архива выделить несколько готовых документов;
- оценить стоимость анализа (по баллам);
- подтвердить списание и перейти к сгенерированному резюме, которое удобно показать врачу.
9. **Отслеживание динамики**:
- при накоплении нескольких анализов, перейти в трекер;
- посмотреть, как менялись ключевые показатели во времени.
Все эти шаги укладываются в привычную логику личного кабинета и не требуют от пользователя технических знаний — сложная часть спрятана внутри компонента.
## Варианты использования и сценарии внедрения
AI Medical Archive гибко вписывается в разные модели:
- **Семейный медицинский архив** на личном сайте или портале:
- акцент на приватность и удобство;
- минимум публичных функций, максимум пользы для владельца.
- **Онлайн‑сервис по расшифровке анализов**:
- публичная регистрация пользователей;
- чёткая тарифная сетка по баллам;
- упор на понятные объяснения и проверку критических значений.
- **Сервис сопровождения хронических пациентов**:
- трекер динамики как основной инструмент;
- регулярная загрузка анализов;
- шаблонные «подготовки к приёму» с подсветкой ключевых изменений.
- **Интеграция с клиникой или телемедицинским сервисом**:
- связка с Социальной сетью МЗЬ.РФ и внутренними профилями;
- возможность подключить врачей к просмотру архивов;
- собственная база знаний, согласованная с медицинским отделом.
Архитектура компонента и продуманная структура БД позволяют постепенно наращивать функциональность: от простого хранения результатов анализов до полноценного, интеллектуального помощника пациента и врача.