212 lines
6.2 KiB
Markdown
212 lines
6.2 KiB
Markdown
---
|
||
tags:
|
||
- mvp
|
||
- telegram
|
||
- 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 |