av
4d1c2bf44c
docs/ по канону 12: паспорт с целью проекта, архитектура сегодняшнего устройства, схема хранилища, модель угроз, конвенции кода, журнал ревью. Конвенции перенесены из jellybit; места, где код им не следует, помечены строкой «Расхождение» как объявленный долг. tasks/ с роадмапом: две достигнутые цели, две запланированные (веб и многопользовательский режим), два направления (все форматы, долгие записи) и пять задач в беклоге. openspec/config.yaml — маршрутизатор с адресами документов, спек пока нет. CLAUDE.md переписан по форме канона: инварианты с severity, семантика гейта, запреты с путями. Taskfile получил task gate.
74 lines
5.7 KiB
Markdown
74 lines
5.7 KiB
Markdown
# Паспорт проекта
|
|
|
|
Зачем это и для кого. [architecture.md](architecture.md) отвечает «как
|
|
устроено», [tasks/ROADMAP.md](../tasks/ROADMAP.md) — «в каком порядке», паспорт —
|
|
«зачем и для кого».
|
|
|
|
## Цель
|
|
|
|
Превращать записанную речь в текст, который можно читать и искать.
|
|
|
|
**Потребители** — список закрытый: он определяет, что считать нужным, а что
|
|
интересным.
|
|
|
|
| Кто | Что ему нужно от нас |
|
|
| --- | --- |
|
|
| Владелец сервиса | Отправить голосовое сообщение из Telegram и получить текст ответом. Работает сегодня |
|
|
| Приглашённый пользователь | Войти в веб через свою учётную запись, загрузить запись, забрать текст. Каждый видит только свои записи |
|
|
| Внешняя программа | Отдать файл по HTTP и опросить готовность. Работает сегодня, без разграничения доступа |
|
|
|
|
Цель достигнута, когда:
|
|
|
|
- запись любого распространённого формата принимается без предварительной
|
|
подготовки, включая дорожку из видео;
|
|
- запись длиной в несколько часов доходит до текста, а не прерывается ошибкой при
|
|
достижении предела;
|
|
- сервисом пользуются несколько человек, и записи одного не видны другому;
|
|
- текст доступен там же, где загружали, — в вебе и в Telegram.
|
|
|
|
## Что целью не является
|
|
|
|
Граница домена. По ней в теме `architecture` судят, не перенесено ли понятие
|
|
через границу.
|
|
|
|
- **Редактор текста.** Расшифровку отдаём как есть; правка, разметка, экспорт в
|
|
форматы документов — не наша работа.
|
|
- **Хранилище записей.** Отдаём текст и на этом заканчиваем: библиотекой, архивом
|
|
и поиском по прошлым записям сервис не становится. Сколько запись лежит на
|
|
диске после обработки — вопрос срока хранения, а его нет вовсе:
|
|
[database.md](database.md), «Представление данных».
|
|
- **Понимание сказанного.** Пересказ, выжимка, ответы на вопросы по записи, поиск
|
|
по смыслу — за границей: мы отдаём текст, а не выводы из него.
|
|
- **Собственное распознавание.** Модель не обучаем и не держим у себя, речь
|
|
распознаёт внешний сервис.
|
|
- **Управление учётными записями.** Пользователей заводит и проверяет внешний
|
|
провайдер, свою регистрацию и свои пароли не делаем.
|
|
- **Живая расшифровка.** Работаем с готовой записью, поток в реальном времени не
|
|
обрабатываем.
|
|
|
|
## Типовые сценарии
|
|
|
|
1. **Голосовое из Telegram.** Пользователь шлёт боту голосовое сообщение, бот
|
|
отвечает «обрабатываю», через минуту приходит текст ответом на то же
|
|
сообщение. Записи, чей текст длиннее предела сообщения Telegram, приходят
|
|
несколькими частями.
|
|
2. **Файл через Telegram.** То же для аудиофайла или документа с аудио: бот
|
|
отличает их по MIME-типу и расширению.
|
|
3. **Загрузка по HTTP.** Программа шлёт `POST /api/audio`, получает идентификатор
|
|
задачи и опрашивает `GET /api/status/:id`, пока не увидит `done` и текст.
|
|
4. **Отказ на середине.** Конвертация или распознавание не удались — задача
|
|
переходит в `failed`, а пользователь Telegram получает сообщение о том, что
|
|
именно не вышло, и предложение повторить.
|
|
|
|
## Референсы
|
|
|
|
Где смотреть prior art, когда упёрлись.
|
|
|
|
- **Yandex SpeechKit, отложенное распознавание** — модель `deferred-general`,
|
|
которой пользуемся: она и задаёт потолок по длине записи и формату.
|
|
- **Whisper и его серверные обёртки** — запасной путь, если внешний сервис
|
|
перестанет устраивать по цене или по качеству русской речи.
|
|
- **PocketBase** — кандидат в хранилище взамен сегодняшнего SQLite. Источником
|
|
учётных записей его не рассматриваем: вход решено делать через OIDC у Authelia
|
|
([architecture.md](architecture.md), «Открытые вопросы»).
|