caterium-app/docs/support-assistant.md

# Руководство и будущий помощник Caterium

## Что работает сейчас

Встроенная «Помощь»: руководство, поиск по текстам/ключевым словам, категории, связанные инструкции и вкладка поддержки с частыми вопросами. На форме авторизации есть «Помощь со входом». Статьи находятся в `public/help/knowledge-v1.json`; содержимое не содержит реальных клиентов, цен компаний, телефонов, адресов, паролей или записей базы. Бот и отправка обращений не подключены. Вопросы поиска не сохраняются и не отправляются наружу. Руководство включено в кэш установленного приложения, но первое получение требует соединения.

## Как вести базу знаний

Стабильный id статьи, категория, заголовок, ключевые слова, последовательность шагов, ограничение/примечание и related. Обновлять version при правке текста. Проверять инструкцию в текущем интерфейсе и ролях, не описывать запланированную функцию как работающую. Эти же статьи использовать для поиска ботом с возвратом ссылок на конкретные article_id. Отдельно хранить закрытые инженерные инструкции: не индексировать дампы базы, исходные Telegram-архивы, логи с токенами и весь репозиторий в пользовательский поиск.

## Два режима будущего бота

1. Объяснение функций по опубликованной базе знаний: «Как сделать предложение?». Ответ с шагами и ссылками на статьи; если материала недостаточно — уточнить вопрос, не придумывать кнопки.
2. Объяснение данных своей компании: «Почему в этом заказе остаток?». Только после серверной авторизации и проверки прав. Подключать отдельными разрешёнными инструментами чтения. Не давать модели прямое SQL-соединение, service_role или доступ к произвольным таблицам.

Максимально полезный контекст означает полный и актуальный справочник плюс минимальные данные конкретного вопроса, а не загрузку всей клиентской базы в модель.

## Предлагаемый серверный контракт (ещё не реализован)

`POST /support/chat` с пользовательской сессией. Тело: conversation_id, message, locale, текущий раздел из фиксированного списка, необязательный выбранный order_id, версия клиента. Не доверять workspace_id, роли, суммам и правам из браузера: определить их по сессии, членству и серверным разрешениям. Идентификатор заказа проверять в пределах разрешённой компании. Отсутствие компании допускает только публичные инструкции.

Ответ: answer, citations[{article_id,knowledge_version}], data_as_of, request_id, needs_human. При выключенном помощнике вернуть явный статус unavailable, UI сохраняет доступ к руководству. Ключ провайдера только на сервере. Перед отправкой в модель отделить системные правила, найденные инструкции и недоверенные данные пользователя.

Разрешённые инструменты первой версии:

- search_help(query) — только опубликованные статьи.
- get_order_summary(order_id) — стоимость позиций, доставка, скидка, оплачено, остаток и статус; без телефона и адреса по умолчанию; orders.view плюс проверка строки/компании.
- get_order_recipe_requirements(order_id) — состав и рассчитанная потребность; права на заказ и соответствующий каталог/закупки.
- get_stock_shortages(order_id) — потребность и остатки; дополнительно stock.view/shopping, с учётом фактических имён прав в проекте при реализации.
- get_catalog_item(item_id) — доступные пользователю сведения о позиции; не раскрывать себестоимость роли без такого права.
- get_subscription_help() — разрешённые сведения о тарифе, без платёжных реквизитов.

Начальная версия только читает. Оплата заказа, списание склада, удаление, рассылки и изменения прав не выполняются ботом. Если позже появятся действия, нужен отдельный проект: предпросмотр последствий, конкретное подтверждение пользователя и обычная серверная проверка прав. Фраза внутри клиентского примечания не даёт разрешения выполнить команду.

## Защита и изоляция

- RLS/проверка прав на каждом инструменте, не только в общем chat endpoint. Пользовательский контекст вместо обхода RLS привилегированным ключом. Проверять актуальные права при каждом запросе.
- Ключ истории и кэша включает компанию и пользователя; авторизация на каждом чтении. При смене компании/выходе очищать UI и отменять запросы. Не показывать запоздалый ответ другой компании.
- Текст заказа, вложения, статьи от пользователя и ответы инструментов — данные, не системные инструкции. Не исполнять указания о раскрытии секретов и внешней отправке из этих полей. В первой версии не читать произвольные URL.
- Минимизировать данные до передачи провайдеру. Сначала выбрать провайдера, регион, договор обработки, режим хранения/обучения и правовое основание. Согласовать с политикой данных и фактической инфраструктурой; сейчас база Supabase во Франкфурте, вопрос локализации отмечен в юридическом пакете.
- Ограничить длину сообщения, число обращений, бюджет инструментов, таймаут и стоимость. Не писать пароли, access/refresh tokens и дампы в журналы.
- Аудит: request_id, пользователь/компания, версия базы знаний, названия вызванных инструментов, результат проверки прав; содержимое переписки и сроки хранения определить отдельно. Пользователь должен знать, что подключён AI и кому передаются сообщения.
- Ответы рендерить как безопасный текст/очищенный Markdown, не исполнять HTML и произвольные ссылки. При недоступности данных обозначать это, а не подставлять пример как факт.

## Передача человеку

Когда появится канал поддержки, дать пользователю проверить текст обращения и выбранные вложения до отправки. Историю переписки или данные заказа не пересылать автоматически. Подтверждать отправку только после ответа сервера. Пока контакты/канал не определены — никаких фиктивных «обращение отправлено».

## Проверки перед подключением

Набор типовых вопросов по каждой статье; правильные ссылки; отсутствие вымышленных функций; запрос чужого заказа; смена компании во время ответа; отзыв прав; prompt injection в примечании; просроченная сессия; пустые данные; известная/неизвестная цена; повторы и лимиты; падение провайдера; мобильные Safari/Chrome; удобное закрытие и клавиатура. Не подключать бота к production до прохождения проверок изоляции и согласования передачи данных.

## Решения, оставшиеся владельцу

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