meeting-protocol-service/docs/superpowers/specs/2026-04-03-meeting-protocol-service-design.md

Meeting Protocol Service — Design Spec

Сервис транскрибации аудио/видео записей встреч и автоматической генерации протоколов с использованием локальной модели Whisper и внешних LLM.

1. Цели и контекст

• Автоматизация создания протоколов по записям встреч (внутренних и с клиентами)
• Протоколы клиентских встреч — основа для результирующей документации по обследованию процессов
• Бесплатная локальная транскрибация (Whisper на GPU)
• Генерация протоколов через бесплатные/платные LLM API
• Веб-интерфейс + полнофункциональные боты в Telegram и Lensa
• Хранение кода и версионирование в Gitea на http://78.153.7.224:3000

2. Архитектура

Подход: модульный монолит

Единый деплой с изолированными модулями, общение между которыми — через очереди задач (Celery/Redis). Каждый модуль можно выделить в отдельный сервис при необходимости.

Модули

Модуль	Ответственность
API	REST endpoints, авторизация (JWT), загрузка файлов, раздача SPA
Транскрибация	Извлечение аудио (FFmpeg), транскрибация (faster-whisper на GPU)
Протоколирование	Вызов LLM, применение шаблонов промптов, экспорт DOCX/PDF/MD
Мессенджеры	Telegram бот (aiogram 3.x), Lensa бот (SDK/webhook), общий MessengerService

Поток обработки записи

1. Загрузка файла (web / telegram / lensa)
2. Извлечение аудио из видео (FFmpeg) — Celery task
3. Транскрибация (faster-whisper large-v3, GPU) — Celery task
4. Генерация протокола (LLM через LiteLLM) — Celery task
5. Сохранение результата, уведомление пользователя
6. Экспорт по запросу (DOCX/PDF/MD)

Асинхронная обработка

Все тяжёлые операции (шаги 2-4) выполняются в Celery workers и не блокируют API. Пользователь получает обновления о прогрессе через polling (web) и push-уведомления (мессенджеры).

3. Модель данных

User

• id UUID PK
• username str unique
• email str unique
• password_hash str
• role enum: admin, user (расширяемо)
• is_active bool
• created_at timestamp

Recording

• id UUID PK
• user_id FK → User
• title str
• file_path str
• file_size bigint
• duration interval
• format str (mp4, webm, mp3, wav, ogg)
• source enum: web, telegram, lensa
• status enum: uploaded, processing, done, error
• created_at timestamp

Transcription

• id UUID PK
• recording_id FK → Recording (1:1)
• text text
• segments JSONB (массив сегментов с таймкодами)
• language str
• whisper_model str
• processing_time interval
• created_at timestamp

Protocol

• id UUID PK
• transcription_id FK → Transcription
• template_id FK → PromptTemplate
• content JSONB (структурированный по разделам)
• raw_text text
• llm_model str
• status enum: generating, done, error
• created_at timestamp
• updated_at timestamp

PromptTemplate

• id UUID PK
• name str
• description str
• type enum: client_survey, client_intro, internal, custom
• system_prompt text
• user_prompt text
• output_schema JSONB (описание ожидаемых разделов)
• is_default bool
• created_at timestamp

ExportFile

• id UUID PK
• protocol_id FK → Protocol
• format enum: docx, pdf, md
• file_path str
• file_size bigint
• created_at timestamp

Связи

User 1→N Recording 1→1 Transcription 1→N Protocol 1→N ExportFile
PromptTemplate 1→N Protocol

4. Предустановленные шаблоны протоколов

4.1 Обследование процессов клиента

Разделы:

1. Дата, участники, тема встречи
2. Описание обследуемого процесса (задачи бизнеса, подпроцесс)
3. Текущее состояние (as-is)
4. Выявленные проблемы / узкие места
5. Договорённости и решения
6. Открытые вопросы (о которых не договорились)
7. Задачи с ответственными и сроками
8. Следующие шаги

4.2 Вводная встреча-знакомство с клиентом

Разделы:

1. Дата, участники, тема встречи
2. Верхнеуровневые цели клиента
3. Параметры будущего проекта
4. Бюджетные ограничения
5. Ограничения по срокам
6. Лица, принимающие решения (ЛПР)
7. Бенефициары
8. Лица, влияющие на принятие решения
9. Договорённости и решения
10. Открытые вопросы
11. Следующие шаги

4.3 Внутренняя рабочая встреча

Разделы:

1. Дата, участники, тема
2. Обсуждённые вопросы
3. Выявленные проблемы
4. Принятые решения
5. Открытые вопросы
6. Задачи с ответственными и сроками
7. Следующие шаги

4.4 Кастомный шаблон

Пользователь может создать свой шаблон с произвольными разделами и промптом через веб-интерфейс или бот.

5. Веб-интерфейс

Страницы

Страница	Функционал
Записи	Список записей с фильтрами по источнику/дате, загрузка файлов, статус обработки
Протоколы	Просмотр, редактирование, экспорт (DOCX/PDF/MD), перегенерация с другим шаблоном
Шаблоны	Управление промптами, создание кастомных шаблонов, предпросмотр
Настройки	LLM провайдер/модель, API-ключи, retention period, очистка данных, профиль

Навигация

Шапка: логотип, разделы (Записи, Протоколы, Шаблоны, Настройки), индикатор занятого дискового пространства ("Занято: N ГБ"), профиль пользователя.

Стек фронтенда

• React + TypeScript
• Vite (сборка)
• Tailwind CSS
• React Query (работа с API)
• React Router

6. Интеграция с мессенджерами

Сценарий работы

1. Пользователь отправляет файл в бот
2. Бот предлагает выбрать тип протокола (inline-кнопки)
3. Бот показывает прогресс обработки
4. Бот отправляет готовый протокол + кнопки: экспорт (DOCX/PDF/MD), перегенерация, открыть в вебе

Команды бота

Основные: /start (авторизация), /upload (или просто отправить файл), /list (записи), /protocols (протоколы)

Работа с протоколами: /view [id], /export [id] [формат], /regenerate [id], /templates

Настройки: /settings (шаблон по умолчанию), /help, /logout

Технические детали

• Telegram — aiogram 3.x, webhook mode через FastAPI, inline-кнопки
• Lensa — SDK/webhook интеграция с аналогичным интерфейсом
• MessengerService — общий слой абстракции, единая логика для обоих мессенджеров
• Лимит файлов — Telegram Bot API ограничивает 50 МБ; для больших файлов — ссылка на веб-загрузку
• Авторизация — привязка аккаунта мессенджера к учётной записи через /start (логин/пароль)

7. Авторизация

• Базовая: логин/пароль, JWT-токены
• Роли: admin, user (расширяемо в будущем)
• Все авторизованные пользователи видят все протоколы
• Привязка аккаунтов мессенджеров к учётной записи
• Подготовлена структура для расширения ролевой модели (поле role — enum, легко расширить)

8. Управление хранилищем

• Retention policies — настраиваемый срок хранения для записей, транскрипций и экспортов (по умолчанию: 90 дней)
• Ручная очистка — админ может удалить старые данные из настроек (записи + связанные файлы)
• Автоочистка — Celery beat задача по расписанию удаляет данные старше retention period
• Индикатор — в шапке навигации отображается занятое место ("Занято: N ГБ")
• Стратегия хранения — SSD для активных данных (ОС, Docker, БД), HDD для архива (старые записи)

9. Деплой

Сервер

• Адрес: 78.153.7.224
• ОС: Windows (Docker Desktop установлен, PostgreSQL и другие сервисы уже развёрнуты)
• CPU: Intel i9-10900 (10 ядер, 2.8 GHz)
• RAM: 32 GB
• GPU: NVIDIA RTX 3070 Ti (8 GB VRAM)
• Хранилище: 1 TB SSD + 1 TB HDD

Docker Compose — контейнеры

Контейнер	Назначение
app	FastAPI + Uvicorn, API + раздача SPA, port 8000
worker	Celery worker с GPU доступом (Whisper + LLM вызовы)
beat	Celery beat — планировщик (автоочистка, scheduled tasks)
redis	Redis 7 — брокер задач + кэш
db	PostgreSQL 16
nginx	Reverse proxy, static files, port 80/443

Распределение ресурсов

• GPU (8 GB VRAM) — faster-whisper large-v3 (~3 GB модель, остальное — буфер)
• RAM — ~4 GB PostgreSQL, ~2 GB Redis, ~4 GB FastAPI + workers, ~8 GB Whisper worker, остальное — ОС
• CPU — 10 ядер достаточно для параллельной работы API + воркеров

Портативность

Архитектура на Docker Compose полностью переносима: docker-compose.yml + .env → docker compose up -d на любом сервере. При отсутствии GPU на целевом сервере — переключение faster-whisper на CPU-режим через переменную окружения.

CI/CD

• Код — Gitea на http://78.153.7.224:3000
• Деплой — docker compose up -d --build (ручной или через Gitea webhook)
• Миграции — alembic upgrade head при старте контейнера app

10. Технологический стек — сводка

Слой	Технологии
Backend	Python 3.11+, FastAPI, Uvicorn, Celery, Redis, SQLAlchemy, Alembic, Pydantic v2
AI/ML	faster-whisper large-v3, CUDA 12 + cuDNN, FFmpeg, LiteLLM
Frontend	React, TypeScript, Vite, Tailwind CSS, React Query, React Router
Мессенджеры	aiogram 3.x (Telegram), Lensa SDK/webhook
Экспорт	python-docx (DOCX), WeasyPrint (PDF), Jinja2 (шаблоны)
Инфра	Docker, Docker Compose, NVIDIA Container Toolkit, Nginx, Gitea, Alembic