microdao-daarion/docs/testing/voice_and_docs_test_instructions.md

Інструкції для тестування голосових повідомлень та PDF файлів

Дата: 2025-11-18
Статус: ✅ Імплементовано

---

✅ Що працює зараз

1. Голосові повідомлення (STT)

• Формати: voice, audio, video_note (кружечки)
• Обробка:
  1. Telegram Gateway отримує голосове
  2. Завантажує через Local Telegram Bot API
  3. Відправляє на dagi-stt:9000/stt (Whisper)
  4. Отримує транскрибований текст
  5. Публікує в NATS як текстове повідомлення
  6. Router обробляє як звичайний текст
  7. Бот відповідає

2. PDF Документи

• Формати: PDF (application/pdf або .pdf)
• Обробка:
  1. Telegram Gateway отримує документ
  2. Перевіряє, чи це PDF
  3. Отримує file_url через Telegram API
  4. Публікує в NATS з metadata.document
  5. Router може викликати Parser Service
  6. Бот відповідає результатом парсингу

---

🧪 Як протестувати

Test 1: Голосове повідомлення (українською)

Кроки:

1. Відкрити Telegram
2. Знайти одного з ботів:
   • @DAARWIZZBot
   • @energyunionBot (Helion)
   • @greenfoodliveBot (GREENFOOD)
3. Натиснути мікрофон та записати: "Привіт, як справи?"
4. Відправити

Очікуваний результат:

Ти → 🎤 [Голосове 3 сек]
Бот → 🎤 Обробляю голосове повідомлення...
Бот → Привіт! У мене все добре, дякую що запитав. Чим можу допомогти?

Логи (якщо щось не так):

ssh root@144.76.224.179 "docker logs --tail 50 telegram-gateway | grep -E '(🎤|voice|transcrib)'"
ssh root@144.76.224.179 "docker logs --tail 20 dagi-stt | grep -E '(POST|/stt)'"

---

Test 2: Голосове повідомлення (англійською)

Кроки:

1. Записати голосове: "Hello, what can you do?"
2. Відправити

Очікуваний результат:

Ти → 🎤 [Голосове 2 сек]
Бот → 🎤 Обробляю голосове повідомлення...
Бот → Hello! I can help you with...

---

Test 3: Довге голосове (> 10 секунд)

Кроки:

1. Записати довге голосове (15-30 сек)
2. Розповісти про щось (проєкт, ідея, питання)
3. Відправити

Очікуваний результат:

• Транскрипція має зайняти 5-15 секунд
• Бот має відповісти на основі транскрибованого тексту
• Якщо > 30 сек - можлива timeout помилка

---

Test 4: PDF документ

Кроки:

1. Підготувати PDF файл (будь-який, < 10 MB)
2. Відправити як файл боту
3. Дочекатися відповіді

Очікуваний результат:

Ти → 📄 document.pdf (500 KB)
Бот → 📄 Обробляю документ: document.pdf...
Бот → [Результат парсингу або повідомлення що документ отримано]

Примітка: Повна обробка PDF через Parser потребує додаткової інтеграції в router_handler.py.

---

Test 5: Не-PDF документ (DOCX, TXT)

Кроки:

1. Відправити DOCX або TXT файл
2. Дочекатися відповіді

Очікуваний результат:

• Бот не має відповісти "Обробляю документ"
• Документ має бути проігнорований (немає обробки)
• Логи: ⏭️ Skipping non-PDF document

---

🐛 Troubleshooting

Проблема 1: Бот не відповідає на голосове

Діагностика:

# 1. Перевірити логи telegram-gateway
ssh root@144.76.224.179 "docker logs --tail 100 telegram-gateway | grep -E '(🎤|voice|ERROR)'"

# 2. Перевірити чи працює STT
ssh root@144.76.224.179 "docker ps | grep dagi-stt"
ssh root@144.76.224.179 "docker logs --tail 50 dagi-stt"

# 3. Тест STT вручну
ssh root@144.76.224.179 "curl -X POST http://localhost:9000/stt -F 'file=@test_audio.ogg'"

Можливі причини:

• STT сервіс не запущено
• Помилка завантаження аудіо з Telegram
• Timeout (файл занадто великий)
• Формат аудіо не підтримується

Рішення:

# Перезапустити STT
docker restart dagi-stt

# Перезапустити telegram-gateway
docker restart telegram-gateway

---

Проблема 2: STT повертає пусту транскрипцію

Діагностика:

docker logs dagi-stt | grep -i "transcrib\\|text"

Можливі причини:

• Занадто тихе/шумне аудіо
• Дуже короткий файл (< 1 сек)
• Мова не підтримується

Рішення:

• Говорити чіткіше та голосніше
• Записувати мінімум 2-3 секунди
• Використовувати українську/англійську

---

Проблема 3: Бот не реагує на PDF

Діагностика:

ssh root@144.76.224.179 "docker logs --tail 100 telegram-gateway | grep -E '(📄|document|pdf)'"

Можливі причини:

• Файл занадто великий (> 50 MB)
• Не PDF формат
• Router handler не обробляє документи

Рішення:

• Перевірити router_handler.py для обробки metadata.document
• Додати інтеграцію з Parser Service

---

📊 Логи для діагностики

Telegram Gateway

# Всі повідомлення
docker logs --tail 100 telegram-gateway

# Тільки voice/document
docker logs --tail 200 telegram-gateway | grep -E '(🎤|📄|voice|document)'

# Помилки
docker logs --tail 100 telegram-gateway | grep ERROR

STT Service

# Останні транскрипції
docker logs --tail 50 dagi-stt | grep -E '(transcrib|POST /stt)'

# Помилки
docker logs --tail 100 dagi-stt | grep -E '(ERROR|error|exception)'

Parser Service

# Останні парсинги
docker logs --tail 50 dagi-parser | grep -E '(POST /ocr|parse)'

# Помилки
docker logs --tail 100 dagi-parser | grep ERROR

---

✅ Критерії успіху

Голосові повідомлення:

• Бот відправляє "🎤 Обробляю голосове повідомлення..."
• Транскрипція займає < 10 сек (для 5-10 сек аудіо)
• Бот відповідає на основі транскрибованого тексту
• Підтримка української та англійської

PDF документи:

• Бот відправляє "📄 Обробляю документ: filename.pdf..."
• Документ публікується в NATS з metadata.document
• Router викликає Parser Service (потребує інтеграції)
• Бот повертає результат парсингу

---

🚀 Наступні кроки

1. Інтеграція PDF з Parser (пріоритет 🔴)

Додати в router_handler.py:

# If event has document metadata
if event.metadata and "document" in event.metadata:
    doc_info = event.metadata["document"]
    # Call Parser Service
    # Return parsed result

2. TTS інтеграція (пріоритет 🟡)

• Додати опцію для голосових відповідей
• Користувач може отримувати відповідь голосом

3. Оптимізація STT (пріоритет 🟢)

• Використовувати tiny або base модель Whisper
• Додати GPU підтримку
• Кешування для повторюваних фраз

---

Тест створено: 2025-11-18
Оновлено: після імплементації voice/document handlers