📚 Технический проект

1 Идея¶

Суть идеи такова:

при регистрации на различных ресурсах требуется отметить чек-бокс согласия с правилами. Обычно это правила, касающиеся конфиденциальности и работы ресурса, но бывают и другие случаи
также при регистрации на ресурсах, особенно обучающих, требуется отметить аналогичный чек-бокс согласия с офертой
как правило, подобные документы написаны под копирку и зачастую многие пункты являются "проходными", но иногда встречаются и исключения
в этих исключениях и кроется самая суть. Прочитав такие пункты в тексте, можно изменить своё мнение и отказаться от регистрации.

Поэтому хочется реализовать такой механизм, который будет позволять либо загрузить сам документ, либо вставить текст соглашения/оферты/или что там ещё может быть. После чего этот будут подсвечены наиболее "горячие" места, на которые пользователю стоит обратить внимание.

Вижу это в реализации телеграм-бота в качестве фронтенда. А на бэкенде будет AI-агент, который будет вытаскивать из RAG данные о наиболее частых моментах в подобных соглашениях, сравнивать их с предложенным текстом и извлекать "горячие" места. Как будет реализован RAG я пока не думал, также как и какие будут использоваться тулзы. Но общая суть описана. Как считаешь, стоит оно того? Например, можно сделать отдельное хранилище для российских документов и отдельное для иностранных.

2 Цели и границы проекта¶

Бизнес-цели¶

БЦ-1. Защита интересов пользователя: предоставить инструмент для быстрого (< 1 минуты) выявления юридических рисков в цифровых договорах (оферты, политики конфиденциальности) перед их принятием.

БЦ-2. Снижение когнитивной нагрузки: избавить пользователя от необходимости читать многостраничные юридические тексты, выделяя только критически важные ("горячие") места.

БЦ-3. Монетизация: создать востребованный B2C сервис с freemium-моделью подписки и потенциалом B2B API для образовательных платформ и маркетплейсов.

Границы применимости (Scope)¶

ГП-1. География: Российская Федерация (учёт законодательства РФ: ГК РФ, 152-ФЗ, ЗоЗПП).

ГП-2. Типы документов (MVP):

Пользовательские соглашения (User Agreement),
Политики конфиденциальности (Privacy Policy),
Оферты онлайн-школ и сервисов подписки.

ГП-3. Платформа: Telegram-бот (отсутствие необходимости устанавливать отдельное приложение).

ГП-4. Первоочерёдная доступность в дневное время суток - с 8 до 19 часов.

ГП-5. Явная декларация невозможности хранения документов, загружаемых пользователем.

ГП-6. Вопросы по выбору и способу запуска LLM (локальные, облачные) в рамках данной MVP не обсуждаются - требуется провести отдельную аналитику по способам монетизации решения.

Глоссарий¶

Термин	Определение
Batch Processing (Пакетная обработка)	одновременная обработка нескольких чанков документа для оптимизации скорости
Cosine Similarity (Косинусное сходство)	метрика измерения близости между двумя векторами, значение от 0 (полное несходство) до 1 (полное совпадение)
FSM (Finite State Machine)	машина состояний для базы ключ-значение
LLM (Large Language Model)	большая языковая модель, используемая для анализа текста и генерации отчётов
n8n	платформа для автоматизации рабочих процессов (оркестратор), которая управляет потоками данных между компонентами системы
OCR (Optical Character Recognition)	технология извлечения текста из изображений и сканов документов
PII (Personally Identifiable Information)	персональная информация: ФИО, номера паспортов, ИНН, и другие данные, позволяющие идентифицировать физическое лицо
RAG (Retrieval-Augmented Generation)	подход, при котором система сначала получает релевантные документы из базы знаний (Retrieval), а затем использует их для генерации ответа (Generation)
Rate Limiting (Ограничение частоты запросов)	механизм ограничения числа запросов к API (например, LLM) в единицу времени, чтобы избежать превышения квоты
Similarity Threshold (Порог сходства)	минимальное значение cosine similarity (обычно 0.72-0.80), при котором система считает найденный текст релевантным запросу
Анализ	метод исследования Вложения, отправленного Пользователем
Аттач	прикреплённое вложение
Бакет	контейнер верхнего уровня в S3-хранилищах
Бот	см. Телеграм-бот
Вектор	массив чисел, который представляет смысл текстового фрагмента и используется для поиска похожих текстов в базе знаний
Вложение	данные (в виде текста или приложенного документа), которые Пользователь отправляет на Анализ для выявления несоответствия юридических норм общепринятым стандартам
Дисклеймер	юридическое предупреждение об отказе от ответственности, указывающее на ограничения функций сервиса
ЗоЗПП	Закон РФ "О защите прав потребителей", определяет права потребителей при заключении договоров
"Красные флаги"	пункт в договоре или соглашении, который содержит потенциально рискованные или невыгодные условия для пользователя; особенности, на которые нужно обращать внимание, при загрузке документов в RAG
Маскирование PII	Автоматическое скрытие или замена персональных данных перед передачей в LLM (например, "ФИО [MASKED]")
Метаданные (Metadata)	информация о чанке (номер страницы, источник, тип документа), прикрепляемая при векторизации
Модератор	пользователь решения с расширенными правами
Парсинг	процесс извлечения содержательного текста из файлов (`pdf`, `txt`), удаления артефактов верстки (колонтитулы, нумерация)
Пользователь	пользователь решения, который может отправлять Вложение для Анализа
Платформа	разрабатываемое приложение, оно же сервис "Красные флажки"
Риск	-
Текст договора	любой текст из внешних сервисов, отправляемый на Анализ, с целью выявления его соответствия общепринятым стандартам
Телеграм-бот	основная платформа, с которой взаимодействует Пользователь при выполнении Анализа
Транзитная обработка (Transit Processing)	обработка данных пользователя в оперативной памяти с автоматическим удалением после завершения анализа
Уровень риска	классификация найденных пунктов: - 🔴 Высокий, - 🟡 Средний, - 🟢 Низкий
Чанк	смысловой фрагмент документа (абзац, предложение или блок текста), использующийся как единица для анализа и поиска в векторной базе
Эмбеддинг	численное представление текста в виде вектора, позволяющее измерять семантическую близость между текстами

3 Анализ предметной области¶

Анализ альтернатив¶

Решение	Функциональные возможности	Минусы
Grammarly https://www.grammarly.com/	AI-платформа для проверки и улучшения текстов на английском языке. Сервис анализирует грамматику, орфографию, пунктуацию, стилистику, предлагает варианты улучшения четкости, увлекательности и тона изложения. Платформа доступна как веб-редактор, браузерное расширение, десктопное приложение и мобильная клавиатура. Премиум-версия включает проверку на плагиат, расширение словарного запаса и более 400 типов проверок.	- Отсутствие поддержки русского языка: сервис работает только с английским языком (британский, американский, канадский, австралийский варианты) и не проверяет тексты на русском, распознавая кириллицу как ошибки. - Блокировка в России: Доступ к Grammarly ограничен Роскомнадзором с августа 2022 года по требованию Генпрокуратуры. - Несовместимость с российскими юридическими документами: полностью неприменим для анализа договоров и контрактов на русском языке, не знаком с российским законодательством и терминологией.
LawGeex https://www.lawgeex.com/	AI-система для автоматизированного анализа и редактирования контрактов. Платформа автоматически проверяет договоры на основе предустановленных политик компании, выставляет "красные флаги" (red flags) для проблемных пунктов, может принимать, отклонять или помечать клаузы в контрактах. Система достигает 94% точности при анализе и работает в 3 раза быстрее традиционного юридического анализа, экономя до 90% затрат.	- Ориентация на англосаксонскую правовую систему: Система обучена на англоязычных контрактах и законодательстве США/Великобритании, не учитывает специфику континентального права и российской юрисдикции. - Отсутствие русскоязычного интерфейса: платформа не работает с документами на русском языке и не анализирует контракты по нормам российского законодательства. - Ограниченная применимость: эффективна только со стандартными шаблонами и не подходит для сложных российских правовых конструкций. - Рекомендуется только для простых документов: даже разработчики предлагают использовать систему только для неважных договоров (NDA, текущие закупки), где цена ошибки мала
DocuBank https://www.docubank.com/	Электронная система хранения и доступа к важным документам с функциями шифрования и безопасного доступа. Сервис предназначен для хранения медицинских директив, завещаний, доверенностей, свидетельств о рождении, налоговых деклараций, договоров и других важных документов. Каждое членство включает 2 ГБ защищенного хранилища SAFE с возможностью создания подаккаунтов для семьи и друзей с ограниченным доступом.	- Отсутствие локализации: сервис ориентирован на американский рынок, не имеет русскоязычного интерфейса и поддержки российских форматов документов - Нет функции анализа: система предназначена только для хранения документов, не выявляет ошибки, риски или несоответствия в юридических документах - Несовместимость с российским документооборотом: не интегрируется с российскими системами электронного документооборота и не учитывает требования к хранению документов по законодательству РФ
Zuva https://zuva.ai/	Специализированная B2B-платформа для анализа контрактов с использованием искусственного интеллекта, работающая с 2011 года. Система предлагает два основных продукта: интерфейс Analyze для ускоренного извлечения данных из контрактов (в 3 раза быстрее ручной проверки) API для интеграции AI-анализа контрактов в собственные приложения клиентов. Платформа ориентирована на юридические отделы корпораций, юридические фирмы и разработчиков программного обеспечения.	- Англоязычная база знаний: обучена на англоязычных контрактах с 2011 года, не имеет базы российских правовых документов и прецедентов - B2B-модель для крупных организаций: высокий порог входа и стоимость, ориентация на корпоративный сегмент, отсутствие гибких тарифов для российского рынка - Незнание российского законодательства: система не обучена выявлять несоответствия нормам ГК РФ, специальным федеральным законам и российской судебной практике - Отсутствие интеграции с российскими правовыми базами: не работает с КонсультантПлюс, Гарант и другими российскими справочно-правовыми системами
TermsFeed https://www.termsfeed.com/	Генератор юридических документов для веб-сайтов и приложений. Сервис создаёт политики конфиденциальности, пользовательские соглашения, cookie-политики, дисклеймеры, политики возврата и EULA на основе простой анкеты. Платформа также предоставляет инструменты для управления согласием на использование cookies и баннеры cookie-consent для соответствия GDPR, CCPA и другим законам о конфиденциальности.	- Генерация по западным стандартам: создаёт документы на основе GDPR, CCPA и других западных норм, не учитывает требования российского законодательства о персональных данных (152-ФЗ) - Отсутствие русскоязычных шаблонов: генерирует документы только на английском языке, что делает их неприменимыми для российских компаний - Нет функции анализа: сервис только генерирует новые документы, но не проверяет существующие на ошибки, риски или соответствие законодательству РФ. - Несовместимость с российской юридической терминологией: используемые правовые термины и конструкции не соответствуют российской правовой традиции и могут быть неприменимы в российских судах

Типы документов¶

Основные типы документов представлены в таблице:

№	Тип документа	Где встречается	Особенности, на которые нужно обратить внимание	Риски
1	Terms of Service (ToS) / Условия использования	практически все онлайн-сервисы	- Одностороннее право на изменение правил без уведомления - Право на сбор неограниченных данных - Отказ от гарантий ("as-is") - Отказ от возврата денег - Сложность отмены подписки
2	Privacy Policy / Политика конфиденциальности	все сервисы с обработкой персональных данных	- Продажа данных третьим лицам - Отсутствие GDPR/CCPA соответствия - Неограниченный срок хранения данных - Отсутствие механизма удаления - Отслеживание поведения (tracking cookies)	для РФ → ВААП, для ЕС → GDPR штрафы
3	User Agreement / Пользовательское соглашение	образовательные платформы, маркетплейсы, социальные сети	- Ограничение ответственности платформы за контент - Право заморозить аккаунт без объяснения - Владение вашим контентом платформой - Обязательность использования платёжной системы платформы - Запрет на параллельные аккаунты (может нарушить закон о конкуренции)	риск потери доступа к аккаунту
4	End User License Agreement (EULA) / Лицензионное соглашение	ПО, видеоигры, мобильные приложения	- Отсутствие права на перепродажу лицензии - Автоматическое обновление с потерей функций - Фонд экрана (HWID привязка → не можешь переустановить) - Отказ от возврата денег - Право отключить ПО удалённо
5	Service Level Agreement (SLA)	облачные сервисы, хостинг, B2B решения	- Uptime гарантия \< 99.5% - Отсутствие гарантии восстановления данных - Чрезмерная стоимость даунтайма - Отсутствие компенсации за нарушение SLA - Исключения (force majeure слишком широко)
6	Оферта	E-commerce, услуги, подписки	- Скрытые комиссии за доставку / обработку - Автоматическое продление подписки - Сложные условия возврата товара - Отсутствие информации о сроке действия оферты - Изменение цены после согласия	финансовые потери
7	Cookie Policy / Политика использования куков	веб-сайты, онлайн-сервисы	- Отслеживание без согласия пользователя - Использование куков для профилирования (targeted ads) - Отсутствие опции отказа Передача данных в третьи страны без защиты
8	Code of Conduct / Кодекс поведения	образовательные платформы, типа Coursera, Udemy, LMS системы	- Запрет на обмен контентом между пользователями - Одностороннее право удалить курс - Отсутствие гарантии на прохождение курса - Запрет на коммерческое использование знаний (невозможно!) - Право забрать сертификат за "нарушение"	потеря контента, сертификата
9	Payment Terms	платёжные системы Стрип, PayPal, Яндекс.Касса, 2Checkout	- Комиссия за неиспользование счёта - Право заморозить средства при подозрении на fraud - Длительный срок вывода средств (30-90 дней) - Отсутствие гарантии на возврат спорных платежей - Смена процессора без уведомления (может быть неприемлем для вас)	блокировка денег
10	Data Processing Agreement (DPA)	облачные сервисы AWS, Google Cloud, Yandex Cloud	- Право передачи данных в другие страны - Отсутствие шифрования данных in transit - Сохранение резервных копий после удаления - Доступ law enforcement без вашего согласия - Отсутствие audit log	утечка данных клиента
11	Seller Agreement	маркетплейсы eBay, Amazon, Avito, Ozon	- Удержание комиссии без причины - Право заморозить аккаунт при жалобе (без доказательств) - Автоматический отказ в возврате средств - Запрет на вывод капитала в течение X дней - Право на отказ в продаже без объяснения	потеря дохода
12	Content License	видеохостинги	- Платформа получает вечную лицензию на ваш контент - Право использовать ваш контент в рекламе - Монетизация контента платформой (вы не получаете) - Удаление контента без объяснения - Запрет на загрузку того же контента на других платформах (может быть!)	потеря авторства
13	Platform Terms	соцсети/мессенджеры	- Сканирование сообщений на предмет запрещённого контента - Право передачи данных спецслужбам - Удаление аккаунта без объяснения - Отсутствие гарантии на доступность - Право на торговлю анонимными данными	потеря доступа и приватности
14	Подписки SaaS / Subscription Terms	Adobe, Figma, Notion, Slack	- Автоматическое возобновление без напоминания - Денежные потери при переезде в другую страну (лицензия теряется) - Отсутствие возврата за неиспользованный период - Отключение функций при задержке платежа - Стоимость данных, если будешь их экспортировать (может взиматься комиссия!)	регулярные платежи
15	API Terms of Service	собственный API, интеграция с банками, платёжными сервисами	- Правовое ограничение на rate limit (не можешь масштабироваться) - Право отключить API без уведомления - Запрет на использование кеша (всегда свежие запросы) - Передача логов третьим лицам - Отсутствие SLA
16	Medical Disclaimer	фитнес-приложения, здоровье-сервисы	- Отказ от ответственности за медицинские рекомендации - Отсутствие консультации врача перед использованием - Сбор медицинских данных без HIPAA соответствия (для US) - Отсутствие гарантии на точность расчётов	правовая защита слаба
17	Policy Terms / Условия полиса	страховые компании	- Исключения слишком широки ("force majeure" определено размыто) - Сроки обработки претензий > 60 дней - Отсутствие гарантии на выплату в валюте полиса - Отказ в страховке за "небрежность" (определение расплывчато) - Скрытые вычеты из суммы компенсации	потеря денег при страховом случае

Дисклеймер¶

Важно прочитать перед использованием

Информационно-справочный характер:
Сервис "Красные флажки" предоставляет автоматизированный анализ текстов контрактных документов в целях информирования пользователя о потенциально рискованных пунктах. Данный анализ носит справочный характер и не является юридической консультацией и не заменяет консультацию квалифицированного юриста.
Отсутствие гарантий на точность:
Система использует искусственный интеллект (нейросетевые модели) для выявления рисков. Несмотря на старания обеспечить высокую точность, система может пропустить некоторые риски или ошибочно отметить безопасные пункты как рискованные. Пользователь самостоятельно несет полную ответственность за принятое решение о заключении договора.
Юридическая ответственность:
ООО "Красные флажки" (далее – Разработчик) не несет ответственности за следующие моменты:
- убытки, понесенные пользователем вследствие применения рекомендаций анализа;
- неполноту или неточность анализа;
- прямые и косвенные убытки от недееспособности сервиса;
- иски третьих лиц, связанные с использованием пользователем информации из сервиса.
Пригодность для конкретного случая:
Сервис создан для массовых сценариев (оферты онлайн-школ, политики конфиденциальности интернет-сервисов). Он может быть неполон для специализированных контрактов (например, высокостоимостные B2B соглашения, договоры в судебных спорах). Рекомендуется проверить анализ с юристом для таких случаев.
Соответствие законодательству:
Сервис разработан с учетом законодательства Российской Федерации (ГК РФ, ФЗ-152 "О защите персональных данных", ЗоЗПП). При анализе иностранных документов применимость выявленных рисков зависит от юрисдикции, в которой действует контракт.
Конфиденциальность загруженных данных:
Загруженные документы обрабатываются в оперативной памяти и удаляются сразу после анализа. Данные пользователя не сохраняются в базах данных (исключение: логи технических ошибок с маскированием PII на срок 30 дней). Однако полная конфиденциальность гарантирована, поскольку при передаче данных во внешние LLM API (OpenAI, YandexGPT) действуют политики конфиденциальности этих сервисов.
Файлы хранятся в зашифрованном виде в изолированном временном хранилище и автоматически удаляются в течение часа после обработки
Ограничение ответственности (Liability Limitation):
В максимальном объеме, разрешенном действующим законодательством, совокупная ответственность Разработчика перед пользователем за все убытки не превышает сумму, уплаченную пользователем за услугу в течение последних 12 месяцев (или 0 рублей для бесплатных пользователей).
Изменение функциональных возможностей:
Разработчик оставляет за собой право изменять функции сервиса, включая полное его прекращение, с уведомлением за 30 дней.
Ваше согласие:
Используя сервис, вы подтверждаете, что ознакомились и согласны со всеми условиями данного дисклеймера.

4 Требования¶

Ниже рассмотрены различные требования, предъявляемые к текущему решению.

Бизнес-требования¶

БТ-01. Система должна работать в режиме "здесь и сейчас".
Пользователь стоит перед экраном регистрации и не готов ждать анализ дольше 30-60 секунд.

БТ-02. Пользователь не должен обладать юридическими знаниями для понимания отчёта. Все риски должны быть переведены на простой язык (Plain Russian).

БТ-03. Сервис должен снимать с себя ответственность за принятие решения пользователем (наличие строгого Дисклеймер).

БТ-04. Возможность обработки документов как в виде файлов (.pdf, .txt), так и в виде простого текста (copy-paste).

БТ-05. Оптимизация затрачиваемых средств на сопровождение решения и, как следствие, снижение затрат пользователей на использование сервиса.

БТ-06. Использование преимущественно доступных средств с возможностью их монетизации.

Функциональные требования¶

ФТ-01: Пользователь может загружать файл для его анализа

Issue #21

Описание

Пользователь может загружать один документ через тг-бот за один анализ.
Загрузка выполняется для файлов формата *.txt и *.pdf.
Максимальный размер файла - 50 МБ.
Система автоматически проверяет наличие текстового слоя в PDF (если файл - сканированное изображение без текстового слоя, система предлагает загрузить обычный PDF или отправить текст вручную).

Критерии приёмки

Прикреплённый документ отображается в тг
Активна кнопка "Выполнить анализ"
Отображается число оставшихся попыток
При завершении числа попыток на бесплатном тарифе отображается надпись о необходимости перейти на платный тариф
Система отклоняет файлы размером > 50 МБ с сообщением об ошибке
При загрузке pdf без текстового слоя пользователю отображается сообщение: "❌ Не удалось прочитать файл. Попробуйте отправить обычный PDF (не скан) или скопируйте текст вручную."

Предусловия

Пользователь запустил тг-бот
Отображается номер текущей попытки (для первого раза ⅓)
Активна кнопка добавления файла

Сценарии (основной)

Пользователь нажимает кнопку добавления документа в тг-бот
Открывается файловой менеджер ОС
Отображаются только файлы перечисленных форматов
Пользователь выбрал файл (размером не более 50 Мб)
Система начинает загрузку и показывает прогресс-бар (если размер файла > 5 Мб)
Файл отображается в тг-боте в виде аттача с названием и размером
Кнопка "Выполнить анализ" становится активной

Альтернативные сценарии

Отмена выбора:

4а. Пользователь нажимает кнопку отмены
5а. Отображается кнопка добавления файла
6а. Число попыток не изменено

Отказ от анализа:

6б. Пользователь нажимает на кнопку очистки тг-бота от аттача

Добавление файла на платном тарифе:

6в. Число попыток не отображается
7в. Повторяются шаги основного сценария

Добавление файла размером более 50 Мб:

4г. Пользователь выбрал файл размером более 50 Мб
5г. Система начинает выполнять загрузку файла
6г. Система отклоняет файл с сообщением: "Размер Вашего файла превышает установленный размер 50 Мб"

Загрузка файла pdf без текстового слоя:

4д. Пользователь выбрал файл pdf формата, в котором отсутствует текстовый слой
5д. Загрузка прерывается
6д. Пользователю отображается сообщение: "❌ Не удалось прочитать файл. Попробуйте отправить обычный PDF (не скан) или скопируйте текст вручную."

Примечания

На платном тарифе число добавляемых документов не ограничено

ФТ-02. Пользователь может прикреплять Текст договора для его анализа

Issue #23

Описание

Бот должен принимать текстовые сообщения (до 6000 символов) для запуска одного Анализа на бесплатном тарифе
На платном тарифе ограничение на количество символов отсутствует (см. примечания).

Критерии приёмки

Текст договора введён
Активна кнопка "Выполнить анализ"
Отображается номер оставшейся попытки
При завершении числа попыток на бесплатном тарифе отображается надпись о необходимости перейти на платный тариф
Если пользователь вводит текст длинной более 6000 символов на бесплатном тарифе, система отсекает текст и выводит сообщение: "⚠️ Текст ограничен до 6000 символов. Используйте платный тариф для анализа больших документов."
Если текст менее 100 символов, кнопка "Выполнить анализ" остается неактивной с подсказкой "Для выполнения анализа текст договора должен содержать не менее 100 символов"

Предусловия

Пользователь запустил тг-бот
Отображается номер текущей попытки (для первого раза ⅓)
Кнопка "Выполнить анализ" неактивна

Сценарии (основной)

Пользователь добавляет скопированный Текст договора в тг-бот
Отображается число использованных символов (хххх/6000)

Альтернативные сценарии

Пользователь вставил скопированный Текст договора выше установленной длины (на бесплатном тарифе):

1а. Пользователь добавляет скопированный Текст договора длиной в 7000 символов в тг-бот
2а. Отображаются только первые 6000 символов автоматически
3а. Счётчик показывает (6000/6000)

Пользователь перетащил Текст договора методом drag'n'drop на ПК:

1а. Пользователь перетаскивает Текст договора мышкой
2а. Отображается число использованных символов (хххх/6000)

Примечания

На платном тарифе количество символов Текста договора не ограничено
На бесплатном тарифе каждый новый запрос обнуляет счётчик символов
Необходимо рассмотреть ограничение на число символов для платного тарифа

ФТ-03. При загрузке данных для анализа должно отображаться количество используемых попыток на бесплатном тарифе

Issue #24

Описание

В ходе загрузки данных при активной кнопке "Выполнить анализ" отображается запись о текущей попытке [из трёх] на бесплатном тарифе. Число попыток отображается в меню тг-бота в формате:

x - номер текущей попытки,
3 - общее число попыток на бесплатном тарифе (х/3).

На платном тарифе счетчик попыток не отображается - количество запусков Анализа не ограничено.

Критерии приёмки

На платном тарифе счётчик попыток не отображается
При завершении лимита (3/3) кнопка "Выполнить анализ" становится неактивной
Отображается сообщение о необходимости обновления подписки

Предусловия

Пользователь в первый раз запустил тг-бот
Отображается число попыток ⅓

Сценарии (основной)

Кнопка "Выполнить анализ" неактивна
Пользователь добавляет данные для анализа
Кнопка "Выполнить анализ" активна
Пользователь запускает анализ
Результат анализа отображается в тг-боте
Счётчик увеличен на 1 (2 / 3)

Альтернативные сценарии

Достижение лимита попыток:

1а. Счётчик выставлен 3/3
2а. Выполнено 3 попытки
3а. Кнопка "Выполнить анализ" неактивна

Примечания

Нумерацию попыток можно впоследствие пересмотреть
На платном тарифе лимит анализов отсутствует

ФТ-04. Анализ документов российской юрисдикции

Issue #25

Описание

Документы российской юрисдикции должны явно распознаваться при анализе в зависимости от типа документа:

Оферта,
Пользовательское соглашение,
Политика конфиденциальности,
и т.д.

Система использует отдельную базу знаний для выявления рисков, характерных для российского права:

ФЗ-152,
ЗоЗПП,
ГК РФ.

Критерии приёмки

Анализ выполнен успешно и результат отображается в тг-боте
Система корректно определяет, что документ относится к российской юрисдикции (проверка языка, наличие ссылок на российское законодательство)
Результат анализа содержит ссылки на соответствующие статьи российского законодательства, если это применимо

Предусловия

Пользователь запустил тг-бот
Попытки анализа доступны

Сценарии (основной)

Загружены данные из российской юридической сферы для анализа
Кнопка "Выполнить анализ" нажата
Результат выполнения анализа отображается в тг-боте

Альтернативные сценарии

Загружен документ японской юрисдикции:

1а. Загружен документ японской юрисдикции
2а. Кнопка "Выполнить анализ" нажата
3а. Отображается сообщение о невозможности выполнить анализ

Примечания

Система в приоритете поддерживает анализ документов российской юрисдикции.
При обнаружении документа на иностранном языке или явно относящегося к иной юрисдикции система переключается на ФТ-05 (англосаксонская юрисдикция) или выдает сообщение о неподдерживаемой юрисдикции

ФТ-05. Анализ документов англосаксонской юрисдикции

Issue #26

Описание

Документы английской, американской и других англосаксонских юрисдикций (UK, US, Canada, Australia) должны явно распознаваться при анализе. Система использует отдельную базу знаний для выявления рисков, характерных для этих регионов (GDPR для ЕС, CCPA для Калифорнии и т.д.). Анализ таких документов может быть менее точен, чем для документов РФ.

Критерии приёмки

Анализ выполнен успешно
Система корректно определяет, что документ относится к англосаксонской юрисдикции (проверка языка, наличие ссылок на зарубежное законодательство)
При анализе документа англосаксонской юрисдикции система добавляет дополнительное уведомление: "⚠️ Анализ документов иностранной юрисдикции менее точен. Рекомендуется проверить результаты с местным юристом."

Предусловия

Пользователь запустил тг-бот
Попытки анализа доступны

Сценарии (основной)

Загружены данные из зарубежной юридической сферы для анализа
Кнопка "Выполнить анализ" нажата
Результат выполнения анализа отображается в тг-боте

Альтернативные сценарии

Загружен документ неподдерживаемой юрисдикции:

1а. Загружен документ неподдерживаемой (например, японской) юрисдикции
2а. Кнопка "Выполнить анализ" нажата
3а. Система определяет, что это иная юрисдикция
4а. Отображается сообщение о невозможности выполнить анализ
5а. Попытка не засчитывается

Примечания

Текст сообщения: "❌ Извините, анализ документов данной юрисдикции пока не поддерживается. Поддерживаются документы РФ, США, Великобритании и ЕС."

ФТ-06. Пользователь может прикреплять Текст договора в виде ссылки на Google Docs

Issue #27

Описание

Вместо Текста договора или файла пользователь может указать ссылку на Google Docs, где расположен документ в открытом доступе. Система автоматически загружает и парсит документ. Максимальный размер документа в Google Docs — 50 МБ.

Критерии приёмки

Система проверяет доступность ссылки перед анализом (без полной загрузки)
Документ успешно загружен и распарсен
Анализ документа выполнен в течение 60 сек
При успешной загрузке документ отображается в тг-боте с указанием названия и предполагаемого размера
Если ссылка недоступна или права недостаточны, система возвращает соответствующее сообщение (не расходует попытку)

Предусловия

Пользователь запустил тг-бот
Попытки анализа доступны
Кнопка "Выполнить анализ" неактивна

Сценарии (основной)

Пользователь нажимает кнопку "Указать ссылку"
Добавляет ссылку на Google Docs с правами, достаточными для чтения документа
Кнопка "Выполнить анализ" стала активной
Пользователь нажимает кнопку "Выполнить анализ"
Результат выполнения анализа отображается в тг-боте

Альтернативные сценарии

Документ не доступен для чтения:

2а. Добавляет ссылку на Google Docs с правами, недостаточными для чтения документа
3а. Кнопка "Выполнить анализ" стала активной
4а. Пользователь нажимает кнопку "Выполнить анализ"
5а. Возвращается сообщение о недостатке прав

Ссылка на документ недоступна:

2а. Добавляет недоступную ссылку на Google Docs
3а. Кнопка "Выполнить анализ" стала активной
4а. Пользователь нажимает кнопку "Выполнить анализ"
5а. Возвращается сообщение о недоступности ссылки

Примечания

Текст сообщения о недостатке прав: "🔒 Доступ ограничен. Убедитесь, что документ открыт для всех, кто имеет ссылку, или сделайте его публичным."
Текст сообщения о недоступности ссылки: "❌ Ссылка недоступна или повреждена. Проверьте URL и повторите попытку."

ФТ-07. Очистка текста от артефактов вёрстки

Issue #28

Описание

Система должна извлекать содержательный текст из загруженных файлов (*.pdf, *.txt), автоматически удаляя технические элементы верстки, чтобы исключить попадание "мусора" в контекст анализа. Что нуждается в удалении:

колонтитулы (header/footer),
нумерация страниц,
повторяющиеся на каждой странице дисклеймеры.

Критерии приёмки

При обработке многостраничного документа текст колонтитулов (например, "Страница Х из Y" или "Конфиденциально") отсутствует в итоговом массиве чанков
Склейка страниц происходит корректно: предложение, разорванное разрывом страницы в исходном файле, в итоговом тексте объединено в одно целое
Результат возвращается в виде переменной (строка или список строк) в оперативной памяти, готовой к векторизации
Система удаляет не только колонтитулы, но и нумерацию страниц (в любом формате: "Page 1 of 10", "Стр. 1 из 10", etc.)
Повторяющиеся на каждой странице дисклеймеры (например, "Конфиденциально" в footer) удаляются полностью
При обнаружении непарсируемого слоя (сканированное изображение) система возвращает ошибку и предлагает OCR (если реализовано) или загрузку текстом

Предусловия

Система поддерживает парсинг файлов форматов: pdf и txt
Загружен файл, содержащий заведомо известные колонтитулы и разрывы страниц
Модуль парсинга (Client Document Parser или нода n8n) запущен и доступен

Сценарии (основной)

Загрузка файла с колонтитулами
Получение текста
Автоматическая проверка регулярными выражениями
Просмотр JSON-вывода ноды парсера в интерфейсе n8n

Альтернативные сценарии

Обработка "битого" слоя:

2а. Если текст невозможно извлечь программно, система возвращает статус ошибки парсинга
3а. Попытка не засчитывается

Примечания

Тестирование производится на уровне unit-теста функции очистки или путем анализа Output Data соответствующей ноды в n8n. Векторное хранилище в этом тесте не участвует
Статус ошибки парсинга: "❌ Не удалось прочитать файл. Файл может быть защищен или представляет собой изображение. Пожалуйста, загрузите текстовый PDF или скопируйте текст вручную."

ФТ-08. Гибридный анализ (векторный+полнотекстовый) Текста договора

Issue #29

Описание

Система должна использовать гибридный поиск:

находить семантически похожие опасные формулировки в Базе Знаний и верифицировать их наличие в контексте анализируемого документа через RAG
использовать методы полнотекстового поиска (например, алгоритм BM25)

Для каждого чанка документа система выполняет поиск Top-5 похожих "красных флагов" в основной БД с использованием cosine similarity (threshold = 0.72).

Процесс: Парсинг → Чанки → Параллельные запросы (Qdrant + PostgreSQL BM25) → Merge & Rank → LLM-верификация

Критерии приёмки

Поиск вернул валидные результаты
Каждый найденный риск содержит ссылку на источник в Базе Знаний
LLM проверил релевантность найденных совпадений и отсеял false positives
Анализ завершён в течение 60 сек
Визуально найдено соответствие в векторном хранилище Тексту договора

Предусловия

Загружены данные (Текст договора, файл) для анализа
Пользователь нажал кнопку "Выполнить анализ"

Сценарии (основной)

Получен результат выполнения Анализа
Пользователь ознакамливается с результатом

Альтернативные сценарии

Недоступность векторного хранилища:

1а. Пользователю возвращается сообщение о недоступности векторного хранилища
2а. Недоступность логируется

Риски не выявлены в документе:

2а. Пользователю выводится сообщение об отсутствии выявленных рисков
3а. Классификация рисков отсутствует

Примечания

Нода Code/Python получает текст, бьет на чанки, и в цикле (или батчем) дергает ноду Vector Store (в режиме Operation: Retrieve / Search), подавая чанки пользователя как input query
Текст сообщения недоступности векторного хранилища: "⚙️ Временный сбой при анализе. Пожалуйста, повторите попытку через несколько минут. Если проблема повторяется, обратитесь в поддержку."
Текст сообщения об отсутствии выявленных рисков: "✅ Риски не выявлены. Документ содержит стандартные условия."

ФТ-09. Система должна выполнять классификацию рисков

Issue #30

Описание

Классификация основана на потенциальном воздействии на пользователя:

🔴 Высокий: Прямая потеря денег, прав на контент или блокировка без причин
🟡 Средний: Неудобные условия, спам, передача данных партнерам
🟢 Низкий: Стандартные, но важные оговорки

Критерии приёмки

Каждый выявленный риск содержит маркировку (🔴/🟡/🟢) в соответствии с уровнем
Рядом с маркировкой указывается краткое объяснение уровня (например, "🔴 Высокий риск: потеря денег")
Система не смешивает риски разных уровней в один пункт (один пункт = один риск)
Активна кнопка выгрузки результата

Предусловия

Загружены данные (Текст договора, файл) для анализа
Пользователь нажал кнопку "Выполнить анализ"

Сценарии (основной)

Получен результат выполнения анализа
Пользователь ознакамливается с результатом
Каждое выявленное несоответствие сопровождается маркировкой риска

Альтернативные сценарии

В результате анализа не выявлены риски:

1а. Получен результат выполнения анализа без выявленных рисков
2а. Пользователю выводится явное сообщение
3а. Классификация рисков (маркировки цветом) отсутствует

Примечания

Текст сообщения: "✅ Риски не выявлены. Документ содержит стандартные условия, характерные для данного типа сервиса."

ФТ-10. По результату выполнения Анализа пользователю возвращается структурированный отчёт

Issue #31

Описание

Тг-бот должен выдавать структурированный отчёт:

Заголовок с указанием результата
Сводка: "Найдено X критических пунктов (Y высоких, Z средних, W низких)"
Список рисков, сгруппированный по уровню, с цитатами и объяснениями
Маркировка каждого риска в соответствии с ФТ-09
Рекомендация (если нужна консультация юриста)
Дисклеймер в конце отчёта

Критерии приёмки

Отчёт содержит структуру: Заголовок → Сводка → Риски по категориям
Каждый риск содержит: маркировка + цитата (максимум 150 символов) + объяснение (1-2 предложения)
Отчёт читабелен на мобильных устройствах (не превышает размер одного Telegram сообщения или разбит на несколько)
Дата и время анализа указаны в конце отчёта
Активна кнопка выгрузки результата

Предусловия

Загружены данные (Текст договора, файл) для анализа
Пользователь нажал кнопку "Выполнить анализ"

Сценарии (основной)

Пользователь выполняет анализ Текста договора
Получает результат в виде структурированного текста в соответствии с шаблоном
Кнопка "Выгрузить результат" активна

Альтернативные сценарии

Вывод отчёта без найденных рисков:

2а. Пользователь получает результат в виде текста без описания рисков в соответствии с шаблоном
3а. Кнопка "Выгрузить результат" активна

Примечания

Шаблон структурированного вывода результатов Анализа:

🚨 РЕЗУЛЬТАТЫ АНАЛИЗА ДОГОВОРА

📊 Сводка: Найдено 5 рисков: 2 высоких 🔴, 2 средних 🟡, 1 низкий 🟢

🔴 ВЫСОКИЕ РИСКИ (2): 1. "Платформа может заблокировать аккаунт без объяснения причин" → Почему это плохо: Вы можете потерять доступ к оплаченным услугам. Рекомендуется наличие процедуры обжалования.

"Платформа имеет право передавать данные третьим лицам без уведомления" → Почему это плохо: Нарушение ФЗ-152 о защите персональных данных. Требуется явное согласие.

🟡 СРЕДНИЕ РИСКИ (2): [...]

🟢 НИЗКИЕ РИСКИ (1): [...]

⚠️ ДИСКЛЕЙМЕР: Данный анализ носит справочный характер и не является юридической консультацией. Рекомендуется проверить результаты с квалифицированным юристом перед подписанием документа.

📅 Анализ выполнен: 14 декабря 2025 г., 22:30 МСК

Шаблон вывода при отсутствии рисков, найденных в ходе Анализа:

✅ АНАЛИЗ ЗАВЕРШЕН

Риски не выявлены. Документ содержит стандартные условия, характерные для данного типа сервиса.

💡 Совет: Даже при отсутствии выявленных рисков рекомендуется прочитать документ полностью перед подписанием.

⚠️ ДИСКЛЕЙМЕР: Данный анализ носит справочный характер и не является юридической консультацией.

📅 Анализ выполнен: 14 декабря 2025 г., 22:30 МСК

ФТ-11. При ожидании вывода результатов Анализа пользователь должен видеть прогресс-бар

Issue #32

Описание

Пользователю отображается процентная шкала выполнения анализа с отчётом времени, прошедшего с начала анализа. Система информирует, что процесс не должен занять более 60 сек, и предлагает подождать. Прогресс-бар обновляется каждые 2-3 сек.

Критерии приёмки

После запуска анализа пользователю отображается прогресс-бар
Прогресс-бар отображает приблизительный % выполнения (0% → 100%)
Рядом с полоской отображается прошедшее время (например, "15 сек из ~45 сек")
Текст сообщения информирует: "⏳ Анализ документа... Это займет примерно 30-45 секунд. Пожалуйста, подождите."
При завершении анализа прогресс-бар исчезает и выводится результат

Предусловия

Пользователь добавил данные в тг-бот для анализа
Кнопка "Выполнить анализ" активна

Сценарии (основной)

Пользователь нажимает кнопку "Выполнить анализ"
Кнопка "Выполнить анализ" становится неактивной и не отображается
В тг-боте отображается сообщение с прогресс-баром: "⏳ Анализ документа..."
Прогресс-бар обновляется в реальном времени (каждые 2-3 сек)
Кнопка "Выгрузить результат" не отображается
Анализ выполнен
Отображается результат его выполнения в виде структурированного текста
Прогресс-бар исчезает
Кнопка "Выгрузить результат" становится активной

ФТ-12. Пользователь может перетаскивать документ для его анализа методом drag'n'drop

Issue #33

Описание

Расширение ФТ-01.

Пользователь может загружать один документ через тг-бот за один анализ методом drag'n'drop. Загрузка выполняется для файлов формата *.txt и *.pdf.

Критерии приёмки

Прикреплённый документ отображается в тг
Активна кнопка "Выполнить анализ"
Отображается число оставшихся попыток
При завершении числа попыток на бесплатном тарифе отображается надпись о необходимости перейти на платный тариф

Предусловия

Пользователь запустил тг-бот
Отображается число оставшихся попыток (для первого раза 3/3) на бесплатном тарифе
Кнопка добавления файла активна (либо явно, либо зона drop активна)

Сценарии (основной)

Пользователь перетаскивает файл указанного формата методом drag'n'drop
Файл отображается в тг-боте в виде аттача

Альтернативные сценарии

Выбор файла неподдерживаемого формата:

1а. Пользователь пытается перетащить файл неподдерживаемого формата
2а. Платформа отклоняет файл
3а. Отображается соответствующее сообщение

ФТ-13. Пользователь может загружать изображения для его анализа

Issue #34

Описание

Пользователь может загружать изображения (скриншоты договоров) для анализа через тг-бот. Система использует OCR для извлечения текста из изображения и далее выполняет стандартный анализ.

Критерии приёмки

Система принимает изображения в форматах: PNG, JPG, JPEG, PDF (скан как изображение)
Максимальный размер изображения — 10 МБ
OCR корректно распознает текст на русском и английском языках
Распознанный текст отображается пользователю перед анализом для подтверждения
Если OCR не может распознать текст (слишком размытое, низкое качество), система возвращает соответствующее сообщение

Предусловия

Пользователь запустил тг-бот
Попытки анализа доступны

Сценарии (основной)

Пользователь загружает изображение
Система применяет OCR
Отображается распознанный текст с кнопкой "Подтвердить и выполнить Анализ"
Пользователь подтверждает
Выполняется стандартный Анализ

Альтернативные сценарии

OCR не может распознать текст:

2а. OCR не может извлечь текст
3а. Отображается сообщение: "❌ Не удалось распознать текст на изображении. Попробуйте загрузить изображение лучшего качества или введите текст вручную."

ФТ-14. Выгрузка результата анализа

Issue #35

Описание

После завершения анализа пользователь может выгрузить результат в виде PDF или TXT файла для дальнейшего использования.

Критерии приёмки

После завершения Анализа активна кнопка "Выгрузить результат"
При нажатии пользователь может выбрать формат: PDF или TXT
Файл содержит полный структурированный отчёт с теми же данными, что отображались в тг-боте
Файл автоматически загружается на устройство пользователя
Имя файла содержит дату и время проведения Анализа

Предусловия

Анализ завершён
Результат отображается в тг-боте

Сценарии (основной)

Пользователь нажимает кнопку "Выгрузить результат"
Система предлагает выбрать формат (PDF / TXT)
Пользователь выбирает формат
Файл генерируется и отправляется пользователю через тг-бот

Альтернативные сценарии

Ошибка генерации файла:

4а. Платформа не может сгенерировать файл
5а. Отображается сообщение: "❌ Не удалось создать файл. Попробуйте позже."

ФТ-15. Пользователь может отредактировать Текст договора до отправки на Анализ

Issue #36

Описание

Перед запуском Анализа пользователь может отредактировать загруженный или вставленный Текст договора. Это позволяет удалить или добавить части текста перед запуском процедуры Анализа.

Критерии приёмки

После загрузки файла или вставки текста отображается кнопка "Редактировать"
При нажатии открывается текстовое поле с текущим текстом
Пользователь может изменить текст
После подтверждения изменений кнопка "Выполнить анализ" остается активной
Счётчик символов обновляется в соответствии с новым текстом

Предусловия

Пользователь загрузил файл или вставил текст
Кнопка "В_ыполнить анализ_" активна

Сценарии (основной)

Пользователь нажимает кнопку "Редактировать"
Открывается текстовое поле с текущим текстом
Пользователь вносит изменения
Нажимает "Сохранить изменения"
Текст обновляется
Кнопка "Выполнить анализ" остается активной

Альтернативные сценарии

Отмена редактирования:

4а. Пользователь нажимает "Отмена"
5а. Текст остается без изменений

ФТ-16. При невозможности выполнения Анализа из-за нерелевантных данных пользователю отображается соответствующее сообщение

Issue #37

Описание

Если загруженный документ или текст не является юридическим документом (например, художественная литература, техническая документация), система должна определить это и уведомить пользователя.

Критерии приёмки

Система анализирует содержимое перед полным Анализом
Если документ не относится к типам, поддерживаемым системой, отображается сообщение
Попытка не засчитывается
Пользователю предлагается загрузить другой документ

Предусловия

Пользователь загрузил нерелевантный документ
Нажал кнопку "Выполнить анализ"

Сценарии (основной)

Платформа начинает предварительный Анализ
Определяет, что документ нерелевантен
Отображается сообщение: "⚠️ Загруженный документ не является юридическим. Пожалуйста, загрузите договор, оферту, политику конфиденциальности или пользовательское соглашение."
Попытка не засчитывается

ФТ-17. Проверка актуальности российских законов в реальном времени

Issue #38

Описание

Система должна проверять, что ссылки на российские законы в анализируемом документе актуальны. Если закон изменен или отменен, система должна уведомить пользователя.

Критерии приёмки

Платформа распознает упоминания законов (ГК РФ, ФЗ-152, ЗоЗПП и др.)
Проверяет актуальность через API КонсультантПлюс или из аналогичных источников
Если закон изменён, в отчёте добавляется предупреждение
Предупреждение содержит информацию о том, что закон изменен и когда

Предусловия

Документ содержит ссылки на российские законы
Анализ запущен

Сценарии (основной)

Система находит упоминание закона в документе
Проверяет его актуальность
Если закон актуален, продолжает Анализ
Если закон изменен, добавляет предупреждение в отчёт

Альтернативные сценарии

API проверки недоступен:

2а. API недоступен
3а. Система продолжает анализ без проверки актуальности
4а. В отчёте указывается: "⚠️ Не удалось проверить актуальность законов. Рекомендуется проверить ссылки вручную."

ФТ-18. Пользователь при осуществлении поиска может уточнять особенности, которые ему хотелось прояснить

Issue #39

Описание

После получения результатов анализа пользователь может задать уточняющие вопросы о найденных рисках. Платформа использует контекст документа и выданных рисков для ответа.

Критерии приёмки

После отображения результатов доступна кнопка "Задать вопрос"
Пользователь может задать вопрос в текстовом виде
Платформа отвечает на вопрос, используя контекст документа и базу знаний
Ответ отображается в тг-боте
Возможность задать несколько вопросов подряд

Предусловия

Анализ завершён
Результаты отображены

Сценарии (основной)

Пользователь нажимает кнопку "Задать вопрос"
Вводит вопрос
Платформа обрабатывает вопрос
Отображается ответ

Альтернативные сценарии

Вопрос выходит за рамки контекста:

3а. Платформа определяет, что вопрос не относится к документу
4а. Отображается сообщение: "⚠️ Вопрос не относится к анализируемому документу. Пожалуйста, уточните вопрос."

ФТ-19. Пользователь может выдавать обратную связь по полученному в ходе Анализа ответу

Issue #40

Описание

После получения результатов Анализа пользователь может оценить качество анализа (👍/👎) и оставить комментарий. Данные о фидбэке обрабатываются.

Критерии приёмки

После отображения результатов доступны кнопки "👍 Полезно" и "👎 Не полезно"
При нажатии на любую кнопку отображается форма для комментария (опционально)
Обратная связь сохраняется в системе для дальнейшего анализа
Пользователь получает благодарность за обратную связь

Предусловия

Анализ завершён
Результаты отображены

Сценарии (основной)

Пользователь нажимает "👍 Полезно" или "👎 Не полезно"
Отображается форма для комментария
Пользователь вводит комментарий (опционально)
Нажимает "Отправить"
Отображается сообщение: "✅ Спасибо за обратную связь! Это поможет нам улучшить сервис."

Альтернативные сценарии

Пользователь не оставляет комментарий:

3а. Пользователь пропускает комментарий
4а. Нажимает "Пропустить"
5а. Обратная связь сохраняется без комментария

ФТ-20. Обработка ошибок и graceful degradation

Issue #41

Описание

Платформа должна корректно обрабатывать ошибки и продолжать работу в ограниченном режиме при недоступности отдельных компонентов.

Критерии приёмки

При недоступности векторной базы система переключается на полнотекстовый поиск
При недоступности LLM Платформа возвращает предзаполненные шаблоны рисков
Все ошибки логируются с достаточной информацией для отладки
Пользователю отображаются понятные сообщения об ошибках
При ошибке осуществления полнотекстового и семантического поиска сразу попытка не засчитывается

Предусловия

Платформа запущена
Один или несколько компонентов недоступны

Сценарии (основной)

Пользователь запускает Анализ
Платформа обнаруживает недоступность компонента
Переключается на альтернативный режим
Выполняет Анализ в ограниченном режиме
Уведомляет пользователя о работе в ограниченном режиме

Альтернативные сценарии

Критическая ошибка:

2а. Платформа не может выполнить Анализ даже в ограниченном режиме
3а. Отображается сообщение об ошибке
4а. Попытка не засчитывается

ФТ-21. Обеспечение защищённого доступа к рабочему месту администратора

Issue #42

Описание

Администратор должен иметь защищённый доступ к административной панели для управления Платформой.

Критерии приёмки

Доступ осуществляется через отдельный интерфейс (веб-панель)
Требуется аутентификация (логин/пароль + 2FA)
Доступ логируется (кто, когда, какие действия)
Сессии имеют ограниченное время жизни
При подозрительной активности система блокирует доступ

Предусловия

Администратор имеет учётные данные
Административная панель запущена

Сценарии (основной)

Администратор открывает веб-панель
Вводит логин и пароль
Проходит 2FA
Получает доступ к административным функциям

Альтернативные сценарии

Неверные учетные данные:

2а. Введены неверные данные
3а. Доступ запрещён
4а. Попытка логируется

ФТ-22. Управление массивом рисков (Красных флажков)

Issue #43

Описание

Администратор должен иметь возможность управлять базой знаний:

добавлять,
редактировать,
удалять риски и их описания.

Критерии приёмки

Интерфейс для просмотра всех рисков
Возможность добавить новый риск с описанием, категорией, уровнем
Возможность отредактировать существующий риск
Возможность удалить риск
Все изменения логируются
Изменения применяются после ревекторизации

Предусловия

Администратор авторизован
Открыта административная панель

Сценарии (основной)

Администратор выбирает "Управление рисками"
Отображается список всех рисков
Администратор выбирает действие (добавить/редактировать/удалить)
Вносит изменения
Сохраняет
Платформа ревекторизует базу знаний

Альтернативные сценарии

Ошибка при сохранении:

5а. Платформа не может сохранить изменения
6а. Отображается сообщение об ошибке
7а. Изменения не применяются

ФТ-23. Логирование и резервное копирование изменений Базы Знаний

Issue #44

Описание

Все изменения в Базе Знаний должны логироваться и создаваться резервные копии для возможности восстановления.

Критерии приёмки

Каждое изменение в базе знаний логируется (кто, когда, что изменено)
Автоматическое создание резервной копии перед применением изменений
Возможность откатить изменения к предыдущей версии
Резервные копии хранятся минимум 90 дней
Логи доступны администратору для просмотра

Предусловия

Платформа запущена
База Знаний существует

Сценарии (основной)

Администратор вносит изменения в базу знаний
Платформа создает резервную копию
Применяет изменения
Логирует действие
Резервная копия сохраняется

Альтернативные сценарии

Откат изменений:

1а. Администратор выбирает "Откатить изменения"
2а. Выбирает версию для восстановления
3а. Платформа восстанавливает Базу знаний из резервной копии
4а. Логирует восстановление

ФТ-24. Обеспечение транзитной обработки данных

Issue #45

Описание

Данные пользователя (загруженные документы, текст) должны обрабатываться только в оперативной памяти и удаляться сразу после завершения Анализа.

Критерии приёмки

Документы не сохраняются на диск (только в RAM)
После завершения Анализа данные удаляются из памяти
Логи не содержат содержимого документов (только метаданные: размер, формат, время)
PII-данные маскируются перед передачей в LLM
Все промежуточные файлы удаляются

Предусловия

Платформа запущена
Пользователь загрузил документ

Сценарии (основной)

Пользователь загружает документ
Платформа загружает его в RAM
Выполняет Анализ
Отдаёт результат пользователю
Удаляет данные из памяти

Альтернативные сценарии

Ошибка при анализе:

3а. Анализ прерывается ошибкой
4а. Платформа все равно удаляет данные из памяти
5а. Пользователю отображается сообщение об ошибке

ФТ-25. Пользователь имеет возможность выполнить 3 проверки на бесплатном тарифе

Issue #46

Описание

На бесплатном тарифе пользователь может выполнить 3 анализа. По завершению попыток возможность выполнить Анализ прекращается. Открыта возможность перехода на платный тариф.

Критерии приёмки

При первом запуске бота счётчик установлен на ⅓
После каждого успешного анализа счётчик увеличивается
При достижении 3/3 кнопка "Выполнить анализ" становится неактивной
Отображается предложение перейти на платный тариф
Счётчик не увеличивается при ошибках анализа

Предусловия

Пользователь на бесплатном тарифе
Тг-бот запущен

Сценарии (основной)

Пользователь запускает бот
Отображается счётчик ⅓
Выполняет Анализ
Счётчик увеличивается до ⅔
Повторяет до 3/3
Кнопка "Выполнить анализ" становится неактивной

Альтернативные сценарии

Переход на платный тариф:

6а. Пользователь нажимает "Перейти на платный тариф"
7а. Открывается страница оплаты
8а. После оплаты счётчик скрывается

ФТ-26. Пользователь может выполнить глубокий Анализ одного документа

Issue #47

Описание

Глубокий анализ (Deep Analysis) — расширенный режим, покрывающий возможности:

Анализ документа на нескольких уровнях (структура, формулировки, ссылки на законы)
Сравнение с лучшими практиками отрасли
Предоставление рекомендации по улучшению документа

Глубокий анализ доступен только на тарифе Pro+

Критерии приёмки

Опция "Глубокий анализ" доступна только на тарифе Pro+
Анализ занимает не более 2-3 минут
Результат содержит дополнительные разделы:
Структурный анализ
Сравнение с best practices
Рекомендации по улучшению
Активна кнопка выгрузки расширенного отчёта

Предусловия

Пользователь на тарифе Pro+
Документ загружен

Сценарии (основной)

Пользователь загружает документ
Выбирает "Глубокий анализ"
Платформа выполняет расширенный анализ
Отображается расширенный отчёт

Альтернативные сценарии

Пользователь не на тарифе Pro+:

2а. Опция "Глубокий анализ" неактивна
3а. Отображается подсказка: "Доступно только на тарифе Pro+"

ФТ-27: Телеграм-бот имеет заполненное поле About (краткое описание)

Issue #86

Описание

При просмотре профиля телеграм-бота в Telegram пользователю отображается краткое описание бота (поле About / Short Description). Текст задаётся через метод setMyShortDescription Telegram Bot API и не может превышать 120 символов. Текст About должен лаконично передавать суть сервиса -автоматизированный анализ договоров и соглашений на предмет юридических рисков. Поле About отображается на странице профиля бота, а также передаётся при пересылке бота другим пользователям.

Критерии приёмки

Поле About заполнено и содержит не более 120 символов,
Текст About отображается на странице профиля телеграм-бота,
Текст About передаётся при пересылке ссылки на бота другим пользователям,
Текст содержит ключевое назначение сервиса (анализ документов на предмет рисков),
Текст About задан для русскоязычной локали (language_code: "ru").

Предусловия

Телеграм-бот зарегистрирован через @BotFather,
Доступен токен бота для выполнения API-запросов.

Сценарии (основной)

Администратор или CI/CD-пайплайн вызывает метод setMyShortDescription с заданным текстом About (≤ 120 символов) и language_code: "ru"
Telegram API возвращает True — описание успешно установлено
Пользователь открывает профиль бота в Telegram
В поле About отображается заданный текст

Примечания

Пример текста About (109 символов):

Анализ договоров и соглашений на юридические риски с помощью ИИ. Быстро, понятно, без юриста.
При изменении позиционирования сервиса текст About необходимо актуализировать.
Рекомендуется задать About также для language_code: "en" при расширении географии (см. ГП-1).

ФТ-28: При старте телеграм-бота отображается Description со ссылкой на дисклеймер

Issue #87

Описание

При первом открытии чата с ботом (когда история сообщений пуста) пользователю отображается приветственное описание бота (Description). Текст задаётся через метод setMyDescription Telegram Bot API и не может превышать 512 символов. Описание должно кратко информировать пользователя о назначении сервиса, основных возможностях и содержать активную ссылку на полный текст дисклеймера. Наличие ссылки на дисклеймер обеспечивает выполнение бизнес-требования БТ-03 (снятие ответственности за принятие решения пользователем).

Критерии приёмки

Поле Description заполнено и содержит не более 512 символов
Description отображается пользователю при первом открытии чата с ботом (пустая история)
Текст Description содержит:
краткое назначение сервиса,
перечисление ключевых возможностей (анализ документов, поддерживаемые форматы),
активную ссылку на полный текст дисклеймера.
При переходе по ссылке на дисклеймер пользователь может ознакомиться с его полным содержимым (10 пунктов)
Страница дисклеймера доступна по ссылке без авторизации
Текст Description задан для русскоязычной локали (language_code: "ru")

Предусловия

Телеграм-бот зарегистрирован через @BotFather
Доступен токен бота для выполнения API-запросов
Полный текст дисклеймера размещён по публично доступному URL-адресу

Сценарии (основной)

Администратор или CI/CD-пайплайн вызывает метод setMyDescription с заданным текстом Description (≤ 512 символов) и language_code: "ru"
Telegram API возвращает True — описание успешно установлено
Новый пользователь открывает чат с ботом впервые
Отображается блок «What can this bot do?» с текстом Description
Пользователь видит ссылку на дисклеймер в тексте описания
Пользователь нажимает на ссылку
Открывается страница с полным текстом дисклеймера

Альтернативные сценарии

Текст превышает 512 символов

1а. Администратор передаёт текст длиной более 512 символов
2а. Telegram API возвращает ошибку
3а. Текст Description не обновляется, предыдущее значение сохраняется

Ссылка на дисклеймер недоступна

6а. Пользователь нажимает на ссылку
7а. Страница не загружается (ошибка сети, 404 и т.д.)
8а. Пользователь не может ознакомиться с дисклеймером
9а. Администратор получает уведомление о недоступности ресурса (через мониторинг)

Пользователь уже общался с ботом

3б. Пользователь открывает чат с ботом, в котором уже есть история сообщений
4б. Блок Description не отображается
5б. Пользователь может ознакомиться с дисклеймером через команду /disclaimer или через профиль бота

Примечания

Пример текста Description (≤ 512 символов):

🔍 Сервис «Красные флажки» — AI-анализ договоров и соглашений.

Загрузите документ (PDF, TXT) или вставьте текст, и бот выявит потенциально рискованные пункты:

🔴 Высокий риск 🟡 Средний риск 🟢 Низкий риск

Результат — через 30-60 секунд, простым языком.

⚠️ Сервис носит информационный характер и не является юридической консультацией. Полный дисклеймер: https://trofimovelijah.github.io/red-flag-analysis/technical_project/#дисклеймер

Ссылка на дисклеймер должна вести на актуальную опубликованную версию раздела «Дисклеймер» из технического проекта
При невозможности разместить полную ссылку в рамках 512 символов рекомендуется использовать сокращённый URL
Для пользователей, у которых уже есть история сообщений с ботом, рекомендуется дублировать ссылку на дисклеймер в ответе на команду /start или /disclaimer

Нефункциональные требования¶

Масштабируемость¶

Мш-1: Платформа должна поддерживать до 1000 одновременных пользователей

Issue #49

Мш-2: Векторная база должна масштабироваться горизонтально

Issue #51

Мш-3: n8n workflows должны поддерживать параллельную обработку

Issue #52

Производительность¶

Пр-1: Время анализа документа: не более 60 секунд

Issue #53

Пр-2: Время отклика бота: не более 2 секунд

Issue #54

Пр-3: Время загрузки файла зависит от размера

Issue #55

Описание

Время загрузки файла:

зависит от размера,
при этом не более 30 секунд для файла размером 50 МБ.

Удобство использования¶

УИ-1: Пользовательский интерфейс тг-бота должен соответствовать правилу "трёх кликов"

Issue #56

УИ-2: Все сообщения в боте должны быть на русском языке

Issue #57

Доступность¶

Дос-1: Uptime: 99,5 % в рабочее время

Issue #58

Описание

Исходим из предположения, что пользователями приложения в рамках MVP являются люди рабочие, поэтому им важно узнавать подробности документации (Пользовательское соглашение, Оферта и т.д.) с 8:00 до 19:00 МСК

Дос-2: Платформа должна автоматически восстановливаться после сбоев

Issue #59

Дос-3: Graceful degradation при недоступности компонентов

Issue #60

Безопасность¶

Без-1: Транзитная обработка данных

Issue #61

Описание

Транзитная обработка данных без сохранения загружаемых пользователями материалов (отправленных на Анализ) на файловое хранилище Платформы

Без-2: Маскирование PII перед передачей в LLM

Issue #62

Без-3: Шифрование данных при передаче (HTTPS/TLS)

Issue #63

Без-4: Логирование без содержимого документов

Issue #64

Защищённость¶

Защ-1: Защита от DDoS атак

Issue #65

Защ-2: Rate limiting для API

Issue #66

Защ-3: Защищённый доступ к административной панели (2FA)

Issue #67

Без-4: Регулярные резервные копии базы знаний

Issue #68

Описание

Порядок резервного копирования будет определён ближе к вводу в эксплуатацию

Совместимость¶

Сов-1: Платформа поддерживает Анализ документов ряда форматов

Issue #69

Описание

Текстовые:

PDF,
TXT.

изображения:

PNG,
JPG,
JPEG,
PDF (OCR).

Сов-2: Поддержка кроссплатформенности телеграм-клиентов

Issue #70

Описание

iOS,
Android,
Desktop:
Linux,
Windows,
MacOS.

Переносимость¶

Пер-1: Возможность развёртывания на облачных платформах

Issue #71

Пер-2: Контейнеризация компонентов

Issue #72

Пер-3: Использование стандартных протоколов и форматов данных

Issue #73

5 Ролевая модель¶

Представлена ролевая модель работы всего ИТ-решения

Роль	Описание и права	Пользователь тг-бота?
Пользователь (User)	- Отправляет документы на Анализ, - Получает отчёт, - Выставляет оценку качеству ответа (👍/👎), - Не требует регистрации в рамках MVP	Да
Юрист-аналитик (Legal Expert)	- Формирует и валидирует базу "`Красных флажков`", - Размечает эталонные документы для оценки качества модели.	Нет
Администратор / Модератор	- Загружает базу `Красных флажков` в векторное хранилище, - Имеет доступ к дашборду n8n, логам ошибок и статистике использования, - Управляет балансом API-ключей LLM.	Да
AI-Агент (System)	- Автоматическая сущность, - Выполняет оркестрацию, поиск в векторной базе и генерацию ответов.	Нет

6 Архитектура Платформы¶

Контекстная диаграмма архитектуры решения¶

Платформа принимает запросы от пользователей, а при необходимости проведения оплаты выполняется обращение к внешнему платёжному сервису, действующему в российской юрисдикции. Администратор также обращается к Платформе для загрузки данных (“красных флажков”), которые предварительно составили юристы.

Диаграмма контейнеров архитектуры решения¶

Администратор взаимодействует с Платформой через Jupyter-notebook, развёрнутый на выделенном сервере. Клиент Jupyter-notebook располагается локально на рабочем месте Администратора. Тем самым Администратор выполняет загрузку “красных флажков” в Flags Parser Service, откуда они попадают в векторное хранилище в виде эмбеддингов.

Взаимодействие Пользователей с Платформой осуществляется через тг-бот. Дальнейшее взаимодействие бота происходит через оркестратор n8n, который выполняет функциональное связывание всех компонентов Платформы, включая взаимодействие с внешним платёжным сервисом через Payment_Service. После загрузки документа в Client Document Parser происходит очистка документов от избыточных для дальнейшего анализа артефактов (колонтитулы, оглавление и т.д.). Все действия Пользователя фиксируются в реляционной СУБД PostgreSQL, полученные после очистки и чанкинга эмбеддинги размещаются в Client Document Parser, а загруженные документы в хранилище MinIO для выполнения ФТ-24. В ходе анализа выполняется сравнение эмбеддингов из векторного хранилища и обработка результата с помощью LLM. При необходимости Пользователь может через Сервис оплаты обратиться к внешнему платёжному сервису для снятия лимитов на бесплатном тарифном плане.

7 Требования к данным¶

Физическая модель реляционной базы данных¶

Словарь данных реляционной базы данных¶

Словарь содержит описание всех полей для следующих таблиц:

Users (Пользователи)
Sessions (Сессии анализа)
Analysis_Results (Результаты анализа)
Chunks (Чанки)
Feedbacks (Обратная связь)
Risks (Риски)
Risk_Categories (Категории рисков)
Jurisdictions (Юрисдикции)
Document_Types (Типы документов)
Tariff (Тариф)
Payments (Платежи)
Payments_Types (Типы платежей)
Rate_Limit_Log (Отслеживание лимитов)

Элемент данных	Описание	Тип данных	Длина	Значение
Users (Пользователи)	физическое лицо, достигшее 18 лет, имеющее доступ к телеграм-боту Платформы и выполняющее Анализ	PK: user_id FK: tariff_id
user_id	Уникальный идентификатор пользователя в рамках Платформы	BIGINT	10
tariff_id	Идентификатор тарифа пользователя	INTEGER	20
telegram_id	Идентификатор аккаунта Telegram	BIGINT	20
subscription_start		DATE	100
subscription_end		DATE	20
is_active		BOOLEAN	1
created_at	Дата и время создания аккаунта	TIMESTAMP	19	Не может быть позже текущей даты
updated_at	Дата и время последнего обновления	TIMESTAMP	19	Не может быть раньше created_at
deleted_at		TIMESTAMP	19	Не может быть раньше created_at
Sessions (Сессии пользователя)	сессии пользователя Платформы, во время которых осуществляется выполнение Анализа	PK: session_id FK: user_id FK: file_format_id FK: jurisdiction_id FK: document_type_id
session_id	Уникальный идентификатор активной сессии пользователя	BIGINT	20
user_id	Ссылка на Users	BIGINT	10
document_s3_key	Идентификатор документа в S3 хранилище - временный объект	VARCHAR	255
file_name	Наименование загружаемого документа	VARCHAR	255
file_size_bytes	Размер загружаемого документа в байтах	INTEGER	10
document_type_id		INTEGER	100
jurisdiction_id	Идентификатор юрисдикции	INTEGER	20
language_code	Код языка	VARCHAR	5	RU (по-умолчанию) EN
upload_status	Статус загрузки документа	VARCHAR	20	PENDING (по-умолчанию) PROCESSING COMPLETED FAILED
processing_duration_ms		INTEGER	1
error_message	Сообщение об ошибке	TEXT	-
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
updated_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Chunks (Чанки)	Чанки для RAG и полнотекстового поиска	PK: chunk_id FK: session_id FK: embedding_vector_id
chunk_id	Уникальный идентификатор чанка	BIGINT	20
session_id	Уникальный идентификатор активной сессии пользователя	BIGINT	20
embedding_vector_id		VARCHAR	100	Идентификатор в Qdrant
chunk_number		INTEGER
chunk_text		TEXT	2000
tsvector		TSVECTOR	10	для BM25 полнотекстового поиска
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
deleted_at		TIMESTAMP	19	soft delete
Analysis_Results (Результаты Анализа)	Результаты выполнения Анализа в рамках активной сессии пользователя	PK: result_id FK: session_id FK: risk_id FK: analysis_type_id FK: evidence_chunk_id
result_id	Уникальный идентификатор результата Анализа	BIGINT	20
session_id	Уникальный идентификатор активной сессии пользователя	BIGINT	20
risk_id	Идентификатор риска	INTEGER	20
analysis_type_id	Идентификатор типа анализа	INTEGER	20
evidence_chunk_id		BIGINT	10
found_severity	Уровень риска	VARCHAR	20	HIGH MEDIUM LOW
confidence_score		INTEGER	100
evidence_text	Цитата из документа, где найден риск	TEXT	200
recommendation	Специфичная рекомендация для документа	TEXT	10000
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Analysis_Types (Типы Анализа)	Справочник типов результатов Анализа	PK: analysis_type_id
analysis_type_id	Уникальный идентификатор типа анализа	INTEGER	20
type_name	Наименование типа	VARCHAR	50	STANDARD (по-умолчанию) DEEP
token_multiplier		DECIMAL	3, 1	1.0 - для STANDARD 2.0 - для DEEP
cost_multiplier	Для расчёта стоимости	DECIMAL	3, 1	1.0 - по умолчанию
Risk_Definitions (Определение Рисков)	Справочник определения рисков	PK: risk_id FK: risk_category_id FK: jurisdiction_id
risk_id	Идентификатор риска	INTEGER	20
risk_category_id	Идентификатор категории рисков	INTEGER	20
jurisdiction_id	Идентификатор юрисдикции	INTEGER	20
risk_name		VARCHAR	255
default_severity		VARCHAR	20	HIGH MEDIUM LOW
description	Описание	TEXT	-	не пустое
language_code	Код языка	VARCHAR	5	RU (по-умолчанию) EN
version	Версия	INTEGER	1	1 - по-умолчанию
is_active		BOOLEAN		True - по-умолчанию
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
updated_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Risk_Categories (Категории рисков)	Справочник категорий рисков	PK: category_id
category_id	Идентификатор категории рисков	INTEGER	20
category_name	Наименование категории	VARCHAR	100	Financial Legal Operational Compliance
description	Описание категории	TEXT
Jurisdictions (Юрисдикция)	Справочник юрисдикций	PK: jurisdiction_id
jurisdiction_id	Идентификатор юрисдикции	INTEGER	20
jurisdiction_code	Код юрисдикции	VARCHAR	20	RF COMMON_LAW EU OTHER
jurisdiction_name	Наименование юрисдикции	VARCHAR	100
language_code		VARCHAR	5	RU (по-умолчанию) EN
Document_Types (Типы документов)	Справочник типов документов	PK: document_type_id
document_type_id	Идентификатор типа документа	INTEGER	100
type_name	Уникальное наименование типа документа	VARCHAR	100	CONTRACT NDA SLA EMPLOYMENT etc
description	Описание типа документа	TEXT
jurisdiction_name	Наименование юрисдикции	VARCHAR	100
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Tariff (Тариф)	Справочник тарифов	PK: tariff_id
tariff_id	Идентификатор тарифа пользователя	INTEGER	20
tariff_name	Уникальное наименование тарифа	VARCHAR	50	FREE PRO PRO+
tariff_price		DECIMAL	10, 2	0 299 599
daily_limit		INTEGER		3 (Free) 0 (Pro, Pro+)
monthly_limit		INTEGER
allows_deep_analysis		BOOLEAN		False (Free, Pro) True (Pro+)
allows_batch_processing		BOOLEAN		False (Free) True (Pro, Pro+)
priority_support		BOOLEAN		False (Free, Pro) True (Pro+)
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Payments (Платежи)	Платежи	PK: payment_id FK: user_id FK: payment_type_id FK: tariff_id
payment_id	Уникальный идентификатор платежа	BIGINT
user_id	Ссылка на Users	BIGINT	10
payment_type_id	Идентификатор типа платежа	INTEGER
tariff_id	Идентификатор тарифа пользователя	INTEGER	20
amount	Сумма платежа	DECIMAL	10, 2
currency	Валюта платежа	VARCHAR	3	'RUB' по умолчанию
payment_status	Статус платежа	VARCHAR	50	PENDING COMPLETED FAILED REFUNDED
transaction_id	Идентификатор транзакции	VARCHAR	255
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
completed_at		TIMESTAMP
Payments_Types (Типы платежей)	Типы платежей	PK: payment_type_id
payment_type_id	Идентификатор типа платежа	INTEGER
type_name	Наименование типа платежа	VARCHAR	100	SUBSCRIPTION ONE_TIME TOP_UP
Rate_Limit_Log (Отслеживание лимитов)	Таблица для отслеживания лимитов на текущем тарифе пользователя	PK: log_id FK: user_id FK: tariff_id
log_id	Идентификатор лога	BIGINT
user_id	Ссылка на Users	BIGINT	10
tariff_id	Идентификатор тарифа пользователя	INTEGER	20
analysis_date		DATE		не пустое
analysis_count		INTEGER		по-умолчанию 0
limit_exceeded		BOOLEAN		False - по-умолчанию
timestamp		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Feedback (Обратная связь)	Обратная связь от пользователя по результату выполнения Анализа	PK: feedback_id FK: result_id FK: user_id FK: feedback_type_id
feedback_id	Идентификатор обратной связи	BIGINT	20
result_id	Уникальный идентификатор результата Анализа	BIGINT	20
user_id	Ссылка на Users	BIGINT	10
feedback_type_id	Идентификатор типа обратной связи	INTEGER	10
comment	Комментарий по обратной связи	TEXT		Необязательное
created_at		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Feedback_Types		PK: feedback_type_id
feedback_type_id	Идентификатор типа обратной связи	INTEGER	10
type_name	Уникальное наименование типа обратной связи	VARCHAR	50	HELPFUL NOT_HELPFUL NEEDS_CLARIFICATION
Audit_Log	Аудит и логирование	PK: log_id FK: user_id FK: resource_id
log_id	Идентификатор лога аудита	BIGINT	20
user_id	Ссылка на Users	BIGINT	10
resource_id	Идентификатор логируемого ресурса	VARCHAR	100
action	Действие пользователя, которое фиксируется в логах	VARCHAR	100	UPLOAD ANALYZE DOWNLOAD DELETE LOGIN LOGOUT
old_value		JSONB
new_value		JSONB
ip_address		INET
user_agent		TEXT
status	Статус	VARCHAR	20	SUCCESS - по умолчанию FAILED
error_message	Сообщение об ошибке	TEXT
timestamp		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP
Resource_Types (Типы ресурсов)	Типы ресурсов, выявленных в ходе логирования	PK: resource_id
resource_id	Идентификатор логируемого ресурса	VARCHAR	100
resource_type	Тип логируемого ресурса	VARCHAR	100	SESSION RESULT USER CHUNK
Analysis_Metric	Метрики производительности	PK: metric_id FK: session_id
metric_id	Идентификатор метрики	BIGINT	20
session_id	Уникальный идентификатор активной сессии пользователя	BIGINT	20
llm_tokens_used		INTEGER
search_latency_ms		INTEGER
embedding_latency_ms		INTEGER
total_duration_ms		INTEGER
chunk_count		INTEGER
result_count		INTEGER
confidence_avg		DECIMAL	5, 2
timestamp		TIMESTAMP	19	DEFAULT CURRENT_TIMESTAMP

Исследование векторного хранилища¶

Сбор требований¶

К реализации требований к векторному хранилищу можно отнести указанные ниже моменты.

ВХ-1: Размерность эмбеддингов 768-1024

Issue #76

Описание

Для решения цели в рамках выполнения требования ФТ-08 предлагается использовать решение на базе технологии RAG. Для сложных задач семантического поиска принято использовать BERT-подобные модели модели эмбеддингов размерностью 768-1024.

ВХ-2: Модели эмбеддингов необходимо для продакшн-среды брать с платформы Hugging Face

Issue #77

ВХ-03: Поддержка эмбеддингов для работы с русским языком

Issue #78

Описание

В рамках MVP на первом плане стоит работа с российскими юридическими документами, следовательно эмбеддинги должны быть заточены на русский язык, либо быть мультиязычными.

ВХ-4: Требования к росту объёма данных

Issue #79

Описание

Необходимо зафиксировать текущий объем данных и прогнозируемый рост. Это критично, поскольку объём данных определяет выбор алгоритма индексирования и архитектуру развертывания. При объёме более 100 млн векторов требуются специализированные гибридные стратегии индексирования.

ВХ-5: Требования к паттернам запросов

Issue #80

Описание

семантический поиск (KNN/ANN) - обязателен в рамках MVP
гибридный поиск (вектор + фильтрация по метаданным)
пре/пост фильтрация
конкретные примеры запросов

ВХ-6: RAG-приложения требуют задержки < 100 мс для всей цепочки (поиск+генерация)

Issue #81

ВХ-7: Пропускная способность Throughput = 1000 QPS

Issue #82

ВХ-8: Полнота поиска Recall rate = 95%

Issue #83

ВХ-9: Использование разноязычных коллекций

Issue #84

Примечания

Для текущего объёма данных возможно рассмотреть использование одной коллекции

Выбор стратегии индексирования¶

После создания чанков в реляционной БД необходимо выполнять индексирование. Это связано с процессом загрузки данных. Процесс выглядит следующим образом:

Чанк загружается из chunks таблицы
Текст преобразуется в эмбеддинг (BERT, 768-1024 размерность)
Эмбеддинг сохраняется в vector_documents векторного хранилища
Статус обновляется → INDEXED
Индекс HNSW инкрементально перестраивается

При выборе стратегии индексирования опираемся на таблицу.

Объем	Latency	Recall	Алгоритм	Параметры	Метрика
< 1M	< 50ms	≥95%	HNSW	M=16, ef=200, search=40	косинусное сходство
1-100M	< 100ms	≥90%	IVF	nlist=1024, nprobe=32	косинусное сходство
> 100M	< 200ms	≥85%	Гибридный	IVF коарс + HNSW файн

Расчёт ёмкости и ресурсов¶

Расчёт рекомендуемой RAM для Qdrant:

память = количество_векторов × размерность × размер одного вектора в float32
4096 Мб = 1000000 × 1024 × 4 байта

С индексом HSWF:

память_с_индексом = память × 1.5
6144 Мб = 4096 Мб × 1.5
С репликацией:
итого = память_с_индексом × 3
18,4 Гб = 6144 Мб × 3
С метаданными:
все_вместе = итого + метаданные
19,7 Гб = 18,4 Гб + (4096 Мб × 30%)

Проектирование схемы данных¶

Типичная схема векторного хранилища состоит из компонентов:

первичный ключ,
скалярные поля,
формат метаданных,
тип векторов.

Реализация представлена в таблице

Элемент данных	Описание	Тип данных	Длина	Значение	Связь с таблицей реляционной БД
ru_vector_documents	Таблица “красных флажков” в векторном хранилище	PK: document_vector_id FK: chunk_id FK: session_id FK: user_id
document_vector_id		UUID
chunk_id		INTEGER			chunks.chunk_id
session_id		INTEGER			sessions.session_id
user_id		INTEGER			users.user_id
	Векторные данные
embedding	Векторные данные	DenseVector	768-1024		float32
embedding_model	Модель встраивания	VARCHAR	-
embedding_timestamp		TIMESTAMP	19
	Текстовые данные
chunk_text	Текстовые данные	TEXT	5000
chunk_summary	Текстовые данные	VARCHAR	500
metadata	JSON payload	title source_url created_date category language
document_title		VARCHAR	255
document_type		VARCHAR	50	CONTRACT NDA etc
source_url		VARCHAR	512
category		VARCHAR	50	Legal Financial etc
language_code		VARCHAR	5	RU EN etc
jurisdiction		VARCHAR	10	RF US EU etc
created_date		TIMESTAMP	19
processing_date		TIMESTAMP	19
ttl_expires_at	Удаление через 90 дней	TIMESTAMP
	Индексы поиска
HNSW-индекс					для embedding
BTree-индекс					для chunk_id, session_id, user_id
Full-text-индекс					для chunk_text
	Служебные поля
indexing_status		VARCHAR		PENDING INDEXED FAILED
relevance_score	усредненный score	DECIMAL
is_active	актуальность для поиска	BOOLEAN
created_at		TIMESTAMP	19
updated_at		TIMESTAMP	19
Vector_search_log	Таблица поисковых запросов в векторном хранилище	PK: search_id FK: session_id FK: user_id FK: result_id
search_id
session_id
user_id
result_id
	Параметры поиска
query_text		TEXT
query_embedding		DenseVector	768-1024
query_type		VARCHAR		RAG_CONTEXT SIMILARITY etc
top_k	кол-во возвращаемых результатов	INTEGER
similarity_threshold		DECIMAL		0,72-0,80
	Результаты поиска
matched_chunks		JSONB array
match_scores		DECIMAL array
matched_count		INTEGER
search_latency_ms		INTEGER
	Служебные поля			SUCCESS FAILED TIMEOUT
status		VARCHAR
error_message		TEXT
created_at		TIMESTAMP

Общая информация о коллекции:

Название: ru_documents_embeddings
Назначение: хранение эмбеддингов документов для RAG
Объем: 1M текущих, 5M через год
TTL: 90 дней