---
tags:
---

---

tags:

- mvp
- telegram-bot
- obsidian
- go

---

## 1. Цели MVP

- Принимать текстовые сообщения в Telegram
- Создавать заметки в Obsidian Vault в формате Markdown
- Асинхронно синхронизировать изменения с Git-репозиторием
- Поддерживать базовое форматирование текста (без LLM)
- Поддержка whitelist пользователей

> **Не включаем на первом этапе:**  
> Голосовые сообщения, векторный поиск, Quartz-публикация, LLM интеграция

---

## 2. Компоненты MVP

### 2.1 Bot Handler (Go + Telegram API)

- Используем `telegram-bot-api/v5`
- Поддерживаем команды:
    - `/new <текст>` — создать новую заметку
    - `/append <частичное_имя>` — дописать к существующей заметке (fuzzy search)
    - `/list` — список последних 5 заметок
- Whitelist авторизация по Telegram User ID
- Graceful shutdown с завершением pending операций

### 2.2 Note Service

- Создание Markdown-файлов в директории `vault/notes`
- Умная генерация имени файла: `YYYY-MM-DD-HHMM-slug.md`
- Добавление timestamps в YAML frontmatter
- Базовое форматирование (первая строка = заголовок)
- Fuzzy search для поиска существующих заметок

### 2.3 Git Service (Асинхронный)

- Используем `go-git/v5`
- **Eventual consistency pattern:**
    1. Файл сохраняется мгновенно
    2. Пользователь получает подтверждение
    3. Git sync идет в фоне через канал
    4. Батчевые коммиты каждые 30 секунд
- Retry logic при ошибках сети
- Graceful handling git failures (не влияют на UX)

### 2.4 File Service

- Создает файлы в `vault/notes`
- Atomic file operations
- Проверка уникальности имени файла
- Slug generation для читаемых имен

---

## 3. Поток обработки сообщений

```mermaid
graph TB
    A[User] --> B[Telegram Bot]
    B --> C[Auth Check]
    C --> D["/new text"]
    D --> E[Note Service]
    E --> F[File Service: Save]
    F --> G["✅ Instant Response"]
    G --> A
    
    F --> H[Git Queue]
    H --> I[Background Worker]
    I --> J[Batch Commit + Push]
    
    subgraph "Synchronous (Fast)"
        C
        D
        E
        F
        G
    end
    
    subgraph "Asynchronous (Eventual)"
        H
        I
        J
    end
```

---

## 4. Технологический стек

**Основные зависимости:**

- `telegram-bot-api/v5` - Telegram Bot API
- `go-git/v5` - Git операции
- `viper` - конфигурация
- `logrus` - структурированное логирование

**Конфигурация:**

```yaml
telegram_token: "your_bot_token"
vault_path: "./vault/notes"
allowed_user_ids: [123456789]

git:
  sync_interval: "30s"
  max_queue_size: 100

logging:
  level: "info"
```

**Внешние сервисы:**

- Telegram Bot API
- Git remote repository

---

## 5. Структура проекта

```
obsidian-telegram-bot/
├── cmd/
│   └── bot/
│       └── main.go
├── internal/
│   ├── bot/           # Telegram handlers + auth
│   ├── note/          # Note operations + fuzzy search  
│   ├── git/           # Async git sync
│   └── config/        # Configuration management
├── configs/
│   └── config.yaml
├── vault/
│   └── notes/         # Generated markdown files
├── go.mod
└── README.md
```

---

## 6. Архитектурные решения

### 6.1 Filename Generation

```go
// Пример: "2024-01-15-1430-team-meeting.md"
func generateFilename(text string) string {
    timestamp := time.Now().Format("2006-01-02-1504")
    slug := slugify(extractTitle(text)) // Первые 3 слова
    return fmt.Sprintf("%s-%s.md", timestamp, slug)
}
```

### 6.2 Error Handling Strategy

- **File operations:** Fail fast, немедленный ответ пользователю
- **Git operations:** Fail gracefully, логирование, retry в фоне
- **Network issues:** Не блокируют создание заметок

### 6.3 Fuzzy Search для /append

```go
// /append meeting -> найдет "2024-01-15-1430-team-meeting.md"
func FindNoteByPartialName(query string) ([]string, error)
```

### 6.4 Security

- Whitelist Telegram User IDs в конфиге
- Валидация всех входящих команд
- Rate limiting через git sync intervals

---

## 7. MVP Success Criteria

**Функциональные:**

- ✅ Создание заметки за < 2 секунды
- ✅ Git sync работает в фоне без блокировок
- ✅ Fuzzy search находит заметки по частичному имени
- ✅ Только авторизованные пользователи имеют доступ

**Технические:**

- ✅ Graceful shutdown без потери данных
- ✅ Логирование всех операций
- ✅ Retry logic для git операций
- ✅ Читаемые имена файлов

**Ограничения MVP:**

- Один пользователь (легко расширить до нескольких)
- Только текстовые сообщения
- Базовое форматирование без LLM
- Локальный git (без конфликт-резолюции)

---

## 8. Roadmap после MVP

**v0.2:** YandexGPT интеграция для улучшенного форматирования
**v0.3:** Поддержка голосовых сообщений + транскрипция  
**v0.4:** Векторный поиск по заметкам
**v0.5:** Quartz автопубликация
**v1.0:** Multi-user support с персональными vaults