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 сек]
Бот → 🎤 Обробляю голосове повідомлення...
Бот → Привіт! У мене все добре, дякую що запитав. Чим можу допомогти?
```

**Логи** (якщо щось не так):
```bash
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: Бот не відповідає на голосове

**Діагностика**:
```bash
# 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 (файл занадто великий)
- Формат аудіо не підтримується

**Рішення**:
```bash
# Перезапустити STT
docker restart dagi-stt

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

---

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

**Діагностика**:
```bash
docker logs dagi-stt | grep -i "transcrib\\|text"
```

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

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

---

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

**Діагностика**:
```bash
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
```bash
# Всі повідомлення
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
```bash
# Останні транскрипції
docker logs --tail 50 dagi-stt | grep -E '(transcrib|POST /stt)'

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

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

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

---

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

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

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

---

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

### 1. Інтеграція PDF з Parser (пріоритет 🔴)
Додати в `router_handler.py`:
```python
# 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*