Shelfy

Личный Telegram-бот для учёта сроков годности с одной главной панелью и короткими временными карточками.

Зачем Shelfy · Быстрый запуск · Архитектура · Проверки · Карта репозитория

Зачем Shelfy

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

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

Возможность	Польза
Закреплённая панель	Постоянный вход к спискам, истекающим продуктам, статистике и настройкам.
Подтверждение черновика	Пользователь проверяет извлечённые данные до сохранения.
Текст и голос	Единый сценарий добавления для набранного текста, голосовых и аудиофайлов.
Локальное распознавание	ffmpeg и Vosk преобразуют русскую речь в текст внутри локального окружения.
Ограниченная роль модели	Ollama очищает шумный ввод; окончательный черновик проверяет детерминированный код.
E2E в Telegram	Продуктовые сценарии исполняются соседним тестовым инструментом.

Быстрый запуск

cp .env.example .env
make setup
make runtime-base
make dev

Список команд:

make help

Локальному окружению нужны:

• заполненный .env с настройками Telegram и базы данных;
• Ollama на хосте, доступный из Docker по http://host.docker.internal:11434;
• Vosk small-ru-0.22 в ./models/vosk-model-small-ru-0.22;
• общий образ shelfy-runtime-base:vosk-lib-0.3.45-small-ru-0.22.

make dev запускает Docker Compose. make runtime-base-rebuild пересобирает тяжёлый слой при изменении ASR-зависимостей или окружения.

Архитектура

Shelfy состоит из Go-процессов и PostgreSQL:

Процесс	Ответственность
migrate	Применяет SQL-миграции до запуска долгоживущих сервисов.
telegram-api	Принимает обновления Telegram, обрабатывает /start, callbacks панели и ставит задания в очередь.
pipeline-worker	Обрабатывает текст и аудио, создаёт сессии черновиков, применяет результат очистки.
scheduler-worker	Отправляет утренние дайджесты, выполняет очистку и предоставляет управляющие точки тестового окружения.
postgres	Хранит пользователей, продукты, черновики, задания, сообщения дайджестов, события разбора и виртуальное время.

app_clock и управляющие точки тестового окружения позволяют проверять зависимое от времени поведение. Бизнес-логика использует те же хранилище, планировщик и Telegram-пути, что и бот.

Проверки

Все пакетные тесты:

make test

Форматирование и lint:

make lint

После изменения схемы или запросов перегенерируй типизированный SQL:

make generate

Продуктовые E2E-материалы находятся здесь:

• e2e/telegram/scenarios — сценарии взаимодействия;
• e2e/telegram/date-cases.txt — матрица фраз о продуктах и датах.

Исполнение, фикстуры, протоколы прогонов и общая оркестрация принадлежат соседнему telegram-bot-e2e-test-tool.

Пример запуска:

make -C ../telegram-bot-e2e-test-tool run-scenario \
  CHAT=@your_bot_username \
  SCENARIO="$PWD/e2e/telegram/scenarios/00-home-ready.jsonl $PWD/e2e/telegram/scenarios/03-text-fast-path-complete.jsonl"

Проверка матрицы дат:

make -C ../telegram-bot-e2e-test-tool run-text-matrix \
  CHAT=@your_bot_username \
  CASES="$PWD/e2e/telegram/date-cases.txt"

Локальная диагностика:

make e2e-last-failure
make e2e-trace-logs TRACE_ID=74ca98dc944f13f4
make e2e-trace-logs SCENARIO_LABEL=02-dashboard-navigation-and-settings

Оценка разбора текста и голоса

Для продуктового бенчмарка:

make benchmark-ingest-smoke ARGS='-include voice -dataset-setup'
make benchmark-ingest-prod ARGS='-dataset-setup -emit-report'

Корпус находится рядом с пакетом в internal/ingest/testdata/, согласно соглашению Go. Подробности запуска, метрик и проверки результата — в руководстве бенчмарка.

Карта репозитория

Путь	Назначение
cmd/telegram-api	Основной процесс Telegram-бота.
cmd/pipeline-worker	Фоновая обработка текста и аудио.
cmd/scheduler-worker	Дайджесты и очистка.
cmd/migrate	Запуск миграций БД.
cmd/vosk-transcribe	Небольшая платформенная ASR-команда.
cmd/ingest-benchmark	Бенчмарк: окружение, оценка и отчёт разделены по файлам.
cmd/e2e-triage	Компактная диагностика сбоев E2E.
internal/bot	Telegram-интерфейс, callbacks, панель и черновики.
internal/ingest	Разбор текста и аудио, очистка, ASR и корпус бенчмарка.
internal/scheduler	Дайджесты, очистка и control API тестового окружения.
internal/storage/postgres	Запросы, сгенерированный sqlc и адаптеры хранения.
assets/copy	Рабочий каталог русских текстов.
assets/asr	Грамматики ASR.
assets/brand	Оформление GitHub и README.
e2e/telegram	Продуктовые сценарии и матрицы ввода.
docs/internal	Правила текстов, бенчмарка, настройки очистки и открытые задачи.

Сопровождение

• Рабочие тексты: assets/copy/runtime.ru.yaml.
• Метаданные текстов: docs/internal/message-inventory.ru.yaml. Это отдельная ответственность от рабочего каталога строк.
• Локальные артефакты создаются в tmp/ и исключены из Git.