talkis/docs/business-requirements.md

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

Статус: общий продуктовый контракт на 17 июля 2026 года.

Документ кратко фиксирует, что пользователь должен уметь делать в Talkis и какого поведения ожидать. Техническая маршрутизация описана отдельно в архитектуре режимов.

1. Ценность продукта

Talkis помогает быстрее превращать голос, аудио, видео и созвоны в пригодный для работы текст, не заставляя пользователя менять привычное приложение. Пользователь сам выбирает баланс удобства, качества, стоимости и приватности:

• Облако — управляемый сервис без собственных ключей; целевой уровень качества и удобства должен быть максимальным среди штатных конфигураций.
• API — использование аккаунтов и endpoints пользователя с контролируемыми расходами провайдера.
• Локально — обработка на устройстве без обязательной передачи рабочих данных внешнему сервису.

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

2. Матрица доступности

Возможность пользователя	Облако	API	Локально
Диктовать и вставлять текст	Да	Да	Да
Видеть потоковую транскрибацию	Да	Для проверенных моделей	Для streaming-моделей
Переводить выделенный текст	Да	Да	Да
Переводить диктовку перед вставкой	Да	При наличии LLM	При наличии локальной LLM
Транскрибировать аудио и видео	Да	Да	Да
Разделять файл по говорящим	При доступной capability	С локальным diarization комплектом	С локальным diarization комплектом
Записывать микрофон и звук созвона	Да	Да	Да
Переводить системный звук синхронно	Да	Для проверенных Realtime adapters	Нет
Озвучивать синхронный перевод	OpenAI-backed, macOS	OpenAI, macOS	Нет
Создавать summary по записи	Да	При наличии LLM	При наличии локальной LLM
Хранить и просматривать историю	Да, локально	Да, локально	Да, локально

3. Общие правила поведения

1. Пользователь всегда видит активный режим обработки до запуска операции.
2. Просмотр другой вкладки режима не меняет активную конфигурацию без явного подтверждения.
3. Talkis не отправляет данные в другой режим скрыто. Ошибка локальной модели не должна автоматически отправлять аудио в облако.
4. Любая недоступная функция объясняет причину и следующий шаг: войти, выбрать модель, проверить ключ, выдать разрешение или сменить режим.
5. Отмена и повторный запуск имеют приоритет над старым запросом; устаревший результат не должен появляться поверх нового.
6. История пользователя хранится локально во всех режимах.
7. Секреты и API-ключи не показываются в логах и не передаются через UI-события.
8. Ошибка дополнительной обработки не должна без необходимости уничтожать уже полученный исходный текст или аудио.

4. Пользовательские сценарии

BR-01. Первоначальная настройка и разрешения

Пользователь должен:

• выбрать язык интерфейса и распознавания;
• выдать доступ к микрофону;
• на macOS выдать Accessibility для автоматической вставки;
• выдать разрешение на системный звук, когда запускает созвон или синхронный перевод;
• после перезапуска продолжить с завершённого шага, если ОС уже сохранила разрешение.

Кнопка проверки должна повторно читать фактическое состояние ОС. Если macOS применяет разрешение только после перезапуска, Talkis должен предложить перезапуск и после него вернуться к проверке, а не сбросить весь onboarding.

BR-02. Выбор режима

Пользователь должен видеть сверху единый переключатель Облако / API / Локально, состояние подключения и основное ограничение режима. Выбор становится рабочим только после явного подтверждения и успешного сохранения.

• В Облаке пользователь входит в Talkis и видит состояние подписки/capabilities.
• В API пользователь вводит ключ, endpoint и model, проверяет подключение и только затем активирует adapter.
• Локально пользователь устанавливает модель, запускает runtime и выбирает её активной.

BR-03. Диктовка

Пользователь должен уметь:

• начать запись глобальной горячей клавишей или кнопкой;
• удерживать аккорд для обычной диктовки либо использовать закреплённую запись;
• видеть понятные состояния записи, обработки, вставки и ошибки;
• отпустить горячую клавишу и получить текст в том поле, которое было активно до вызова Talkis;
• отменить запись без появления частичного результата в целевом приложении.

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

BR-04. Обработка диктовки

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

BR-05. Горячие клавиши

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

• Комбинации не могут совпадать.
• Комбинация без модификатора не принимается.
• Escape и потеря фокуса отменяют ввод.
• При конфликте, ошибке регистрации или сохранения старая комбинация остаётся активной.
• Успешное изменение действует без перезапуска приложения.

BR-06. Перевод выделенного текста

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

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

BR-07. Транскрибация файлов

Пользователь должен:

• выбрать или перетащить аудио/видео до 8 ГБ;
• выбрать обычный текст или режим говорящих;
• видеть этап и прогресс обработки;
• отменить задачу или повторить её после ошибки;
• получить результат и запись в истории без загрузки всего файла в память интерфейса.

Обработка должна принимать распространённые форматы аудио и видео. Конвертация является внутренней деталью и не требует ручной подготовки файла.

BR-08. Говорящие

В транскрипте с diarization первый обнаруженный speaker отображается как Вы, остальные — как Гость N. Это удобная исходная подпись, а не биометрическая идентификация.

Пользователь должен спокойно удалить имя целиком, ввести новое без прыжков курсора и применить его ко всем репликам того же говорящего. Последовательные части одного speaker должны визуально восприниматься как одна связанная реплика, если между ними нет реальной смены канала/говорящего.

BR-09. Запись созвона

Пользователь должен запустить запись из виджета и получить:

• собственный микрофон как дорожку Вы;
• системный звук собеседников как дорожку Созвон;
• общий транскрипт;
• синхронное воспроизведение обеих дорожек в истории;
• возможность повторной транскрибации при сохранённом аудио.

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

BR-10. Синхронный перевод

Пользователь в разделе Перевод выбирает Синхронный перевод (Облако/API), целевой язык, нужные аудиоканалы и при доступности озвучку. Запуск и остановка выполняются из плавающего виджета.

Требования к результату:

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

В локальном режиме кнопка запуска недоступна и честно сообщает, что для realtime нужен режим Облако или API. Остальные функции перевода локального режима остаются доступны.

BR-11. Озвучка перевода

При поддерживаемом Realtime adapter пользователь может включить перевод голосом. Оригинальный системный звук приглушается до выбранного уровня, а звук Talkis не должен снова попадать в захват и создавать петлю. Изменение громкости отображается сразу, но не должно вызывать тяжёлое сохранение/перезапуск сессии на каждое движение ползунка.

BR-12. История

Пользователь должен фильтровать историю по голосу, файлам, созвонам и синхронным переводам, раскрывать полный текст, копировать его, прослушивать сохранённое аудио, создавать summary, повторять поддерживаемые операции и удалять записи.

Меню действий должно оставаться полностью видимым у границ таблицы/окна. Удаление записи должно согласованно удалить связанные локальные данные согласно политике хранения.

BR-13. Summary и промпты

Пользователь может применить готовый или собственный промпт к транскрипту и сохранить несколько последних summary в записи истории. Большой текст должен обрабатываться частями и собираться в единый результат. Недоступная LLM не должна блокировать просмотр исходного транскрипта.

BR-14. ИИ-поиск по истории

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

Поиск должен:

• сначала использовать локальный индекс и универсальные классы намерений;
• использовать embeddings как необязательное улучшение при доступном backend;
• передавать модели ограниченный релевантный контекст;
• показывать источники ответа;
• честно сообщать, если подтверждающих записей нет.

До отдельного product decision функция остаётся доступной только в dev-сборке.

BR-15. Плавающий виджет и текстовая плашка

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

Текстовая плашка должна:

• открываться сразу при первом partial-событии;
• заменять старое содержимое новым активным запросом;
• переноситься мышью;
• поддерживать светлую и тёмную темы;
• сохранять читабельный размер текста и компактное разделение говорящих;
• автоматически закрываться через десять секунд после финального результата, кроме продолжающейся realtime-сессии.

BR-16. Ошибки и восстановление

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

Логи должны позволять службе поддержки определить режим, этап, модель/adapter, request/session ID, длительность, уровни входного аудио и причину остановки без раскрытия секретов.

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

• Приватность: место обработки соответствует выбранному режиму; история остаётся локальной.
• Предсказуемость: одна и та же пользовательская команда имеет одинаковый lifecycle во всех режимах, даже если backend различается.
• Отзывчивость: UI сразу подтверждает нажатие и не ждёт исчезновения предыдущего результата.
• Отменяемость: длительные сетевые и файловые операции можно остановить.
• Устойчивость: поздние ответы отменённых запросов игнорируются.
• Наблюдаемость: ключевые этапы имеют структурированные логи и идентификаторы.
• Кроссплатформенность: основные сценарии работают на macOS, Windows и Linux; platform-specific ограничения сообщаются до или при запуске.
• Доступность: контролы доступны с клавиатуры, имеют понятные состояния фокуса и не зависят только от цвета.

6. Вне текущего обязательного объёма

• Локальный синхронный перевод системного звука.
• Биометрическое узнавание владельца по голосу в импортированном смешанном файле.
• Озвучка Realtime-перевода на Windows и Linux.
• Гарантированная diarization силами любого произвольного API-провайдера.
• Production-доступ к ИИ-чату истории до отдельного решения о UX, лимитах и приватности.

7. Критерий готовности новой функции

Функция считается готовой, когда:

1. Для каждого из трёх режимов явно определено: поддерживается, поддерживается условно или недоступна.
2. Есть успешный сценарий, отмена, ошибка backend и восстановление.
3. Нет скрытой смены режима и утечки секретов в лог.
4. Старый запрос не может перезаписать новый результат.
5. История и аудиофайлы сохраняются или удаляются согласованно.
6. Поведение покрыто целевыми TypeScript/Rust тестами в соответствии с уровнем риска.
7. Пользовательский текст и документация обновлены одновременно с реализацией.