380 lines
19 KiB
Markdown
380 lines
19 KiB
Markdown
## 1. Обзор системы
|
||
|
||
### 1.1 Назначение
|
||
Система представляет собой Telegram бота для автоматизации создания и управления заметками в Obsidian с интеграцией в существующий Git + Quartz workflow.
|
||
|
||
### 1.2 Ключевые функции
|
||
- Создание заметок из текстовых и голосовых сообщений
|
||
- Семантический поиск по базе знаний
|
||
- Дополнение существующих заметок
|
||
- Автоматическое форматирование через GPT
|
||
- Интеграция с Git для версионирования
|
||
- Автоматическая публикация через Quartz
|
||
|
||
### 1.3 Ограничения и допущения
|
||
- Один пользователь (личное использование)
|
||
- Развертывание на VPS с ограниченными ресурсами
|
||
- Интеграция с существующей инфраструктурой Git + Quartz
|
||
- Приоритет простоты разработки над масштабируемостью
|
||
|
||
## 2. Архитектурные решения
|
||
|
||
### 2.1 Выбор архитектурного стиля: Модульный монолит
|
||
|
||
**Обоснование:**
|
||
- Простота разработки и развертывания
|
||
- Оптимальное использование ресурсов VPS
|
||
- Быстрая итерация для единственного пользователя
|
||
- Легкость отладки и мониторинга
|
||
|
||
**Альтернативы рассмотренные:**
|
||
- Микросервисная архитектура (отклонена из-за избыточной сложности)
|
||
- Serverless функции (отклонена из-за холодного старта и ограничений по времени)
|
||
|
||
### 2.2 Технологический стек
|
||
|
||
**Основной язык:** Go 1.21+
|
||
- Высокая производительность
|
||
- Простое развертывание (единый бинарник)
|
||
- Отличная поддержка конкурентности
|
||
- Богатая экосистема для Telegram ботов
|
||
|
||
**Ключевые зависимости:**
|
||
- `telegram-bot-api/v5` - Telegram Bot API
|
||
- `go-openai` - OpenAI API интеграция
|
||
- `go-git/v5` - Git операции
|
||
- `viper` - конфигурация
|
||
- `logrus` - структурированное логирование
|
||
|
||
**Внешние сервисы:**
|
||
- OpenAI API (GPT-4, Whisper)
|
||
- Telegram Bot API
|
||
- Векторная база данных (Qdrant/Chroma)
|
||
|
||
## 3. Архитектура системы
|
||
|
||
### 3.1 Общая диаграмма системы
|
||
|
||
```
|
||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||
│ Telegram │ │ │ │ External │
|
||
│ User │◄──►│ Monolithic │◄──►│ Services │
|
||
│ │ │ Bot App │ │ │
|
||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||
│ │
|
||
▼ ├─ OpenAI API
|
||
┌─────────────────┐ ├─ Vector DB
|
||
│ File System │ └─ Telegram API
|
||
│ │
|
||
├─ Obsidian Vault │
|
||
├─ Git Repository │
|
||
└─ Vector Index │
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ Git Hooks │
|
||
│ │
|
||
└─ Quartz Rebuild │
|
||
```
|
||
|
||
### 3.2 Компонентная диаграмма
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Monolithic Application │
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ Bot │ │ HTTP │ │ CLI │ │
|
||
│ │ Handler │ │ Server │ │ Tools │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ │ │ │ │
|
||
│ └─────────────────┼─────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────────┼─────────────────────────┐ │
|
||
│ │ Business Logic Layer │ │
|
||
│ │ │ │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
|
||
│ │ │ Note │ │ Search │ │ Voice │ │ │
|
||
│ │ │ Service │ │ Service │ │ Service │ │ │
|
||
│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
|
||
│ │ │ LLM │ │ File │ │ Git │ │ │
|
||
│ │ │ Service │ │ Service │ │ Service │ │ │
|
||
│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │
|
||
│ └─────────────────────┼─────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────────────────────┼─────────────────────────────┐ │
|
||
│ │ Infrastructure Layer │ │
|
||
│ │ │ │ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
|
||
│ │ │ Config │ │ Logger │ │ Cache │ │ │
|
||
│ │ │ Manager │ │ │ │ │ │ │
|
||
│ │ └─────────────┘ └─────────────┘ └───────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.3 Диаграмма потоков данных
|
||
|
||
```
|
||
User Message Flow:
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Telegram │───►│ Bot │───►│ Router │
|
||
│ Message │ │ Handler │ │ │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│
|
||
┌─────────────────────────┼─────────────────────────┐
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Create │ │ Search │ │ Append │
|
||
│ Note │ │ Notes │ │ Note │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│ │ │
|
||
▼ │ ▼
|
||
┌─────────────┐ │ ┌─────────────┐
|
||
│ Format │ │ │ Find & │
|
||
│ with GPT │ │ │ Update │
|
||
└─────────────┘ │ └─────────────┘
|
||
│ │ │
|
||
▼ │ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Save │ │ Vector │ │ Save │
|
||
│ File │ │ Search │ │ File │
|
||
└─────────────┘ └─────────────┘ └─────────────┘
|
||
│ │ │
|
||
└─────────────────────────┼─────────────────────────┘
|
||
▼
|
||
┌─────────────┐
|
||
│ Git │
|
||
│ Commit │
|
||
└─────────────┘
|
||
│
|
||
▼
|
||
┌─────────────┐
|
||
│ Quartz │
|
||
│ Rebuild │
|
||
└─────────────┘
|
||
```
|
||
|
||
## 4. Детальное описание компонентов
|
||
|
||
### 4.1 Presentation Layer
|
||
|
||
**Bot Handler**
|
||
- Ответственность: Обработка Telegram API, маршрутизация команд
|
||
- Интерфейсы: Telegram Bot API
|
||
- Зависимости: Router, Context Manager
|
||
|
||
**HTTP Server** (опциональный)
|
||
- Ответственность: Health checks, метрики, webhook endpoint
|
||
- Интерфейсы: HTTP REST API
|
||
- Зависимости: Monitoring tools
|
||
|
||
### 4.2 Business Logic Layer
|
||
|
||
**Note Service**
|
||
- Ответственность: Создание, обновление заметок, управление жизненным циклом
|
||
- Интерфейсы: Note CRUD операции
|
||
- Зависимости: LLM Service, File Service, Git Service
|
||
|
||
**Search Service**
|
||
- Ответственность: Векторный поиск, индексация, семантический анализ
|
||
- Интерфейсы: Search API, Indexing API
|
||
- Зависимости: Vector Database, Embedding Service
|
||
|
||
**Voice Service**
|
||
- Ответственность: Обработка голосовых сообщений, транскрипция
|
||
- Интерфейсы: Audio processing API
|
||
- Зависимости: Whisper API, File Service
|
||
|
||
**LLM Service**
|
||
- Ответственность: Интеграция с GPT, форматирование, генерация контента
|
||
- Интерфейсы: Text processing API
|
||
- Зависимости: OpenAI API
|
||
|
||
### 4.3 Infrastructure Layer
|
||
|
||
**File Service**
|
||
- Ответственность: Файловые операции, управление Obsidian vault
|
||
- Интерфейсы: File system operations
|
||
- Зависимости: OS file system
|
||
|
||
**Git Service**
|
||
- Ответственность: Version control, автоматические коммиты
|
||
- Интерфейсы: Git operations API
|
||
- Зависимости: Git repository
|
||
|
||
## 5. Интеграционная архитектура
|
||
|
||
### 5.1 Внешние интеграции
|
||
|
||
**OpenAI API**
|
||
- Назначение: GPT-4 для форматирования, Whisper для транскрипции
|
||
- Протокол: HTTPS REST API
|
||
- Аутентификация: API Key
|
||
- Обработка ошибок: Retry with exponential backoff
|
||
|
||
**Telegram Bot API**
|
||
- Назначение: Получение сообщений, отправка ответов
|
||
- Протокол: HTTPS REST API / WebHooks
|
||
- Аутентификация: Bot Token
|
||
- Режим работы: Long polling (рекомендуется для VPS)
|
||
|
||
**Vector Database**
|
||
- Назначение: Семантический поиск по заметкам
|
||
- Варианты: Qdrant (HTTP API) или Chroma (HTTP API)
|
||
- Протокол: HTTPS REST API
|
||
- Данные: Embeddings + метаданные заметок
|
||
|
||
### 5.2 Файловая система
|
||
|
||
**Obsidian Vault Structure**
|
||
```
|
||
vault/
|
||
├── notes/ # Основные заметки
|
||
├── daily/ # Ежедневные заметки
|
||
├── templates/ # Шаблоны
|
||
├── attachments/ # Медиа файлы
|
||
└── .obsidian/ # Конфигурация Obsidian
|
||
```
|
||
|
||
**Git Integration**
|
||
- Автоматические коммиты после каждого изменения
|
||
- Meaningful commit messages
|
||
- Direct push в main branch
|
||
- Git hooks для триггера Quartz rebuild
|
||
|
||
## 6. Данные и хранение
|
||
|
||
### 6.1 Модель данных
|
||
|
||
**Note Entity**
|
||
```
|
||
Note {
|
||
ID: UUID
|
||
Title: string
|
||
Content: string (Markdown)
|
||
Filename: string
|
||
Created: timestamp
|
||
Updated: timestamp
|
||
Tags: []string
|
||
Links: []string
|
||
Embedding: []float32
|
||
}
|
||
```
|
||
|
||
**User Context**
|
||
```
|
||
UserContext {
|
||
UserID: int64
|
||
State: enum (idle, creating_note, appending, searching)
|
||
Data: map[string]interface{}
|
||
LastActivity: timestamp
|
||
}
|
||
```
|
||
|
||
### 6.2 Хранение данных
|
||
|
||
**Файловая система**
|
||
- Obsidian заметки: Markdown файлы в vault directory
|
||
- Конфигурация: .env файл или environment variables
|
||
- Логи: Rotated log files или stdout для containerized deployment
|
||
|
||
**Временное хранение**
|
||
- User contexts: In-memory map (single user)
|
||
- Cache: In-memory или embedded BoltDB
|
||
- Vector embeddings: External vector database
|
||
|
||
## 7. Развертывание и операционные аспекты
|
||
|
||
### 7.1 Архитектура развертывания
|
||
|
||
```
|
||
VPS Server
|
||
├── Application Binary
|
||
├── Configuration Files
|
||
├── Obsidian Vault (Git Repository)
|
||
├── Vector Database (если локальная)
|
||
└── Monitoring & Logs
|
||
```
|
||
|
||
### 7.2 Масштабирование
|
||
|
||
**Текущие ограничения:**
|
||
- Один пользователь
|
||
- Один экземпляр приложения
|
||
- Локальные файловые операции
|
||
|
||
**Возможности роста:**
|
||
- Horizontal scaling: добавление Redis для shared state
|
||
- Vertical scaling: увеличение ресурсов VPS
|
||
- Service extraction: выделение vector search в отдельный сервис
|
||
|
||
### 7.3 Мониторинг и наблюдаемость
|
||
|
||
**Логирование:**
|
||
- Structured logging (JSON format)
|
||
- Log levels: ERROR, WARN, INFO, DEBUG
|
||
- Log rotation для экономии места
|
||
|
||
**Метрики:**
|
||
- Application health status
|
||
- Message processing time
|
||
- OpenAI API response times
|
||
- Git operation success/failure rates
|
||
|
||
**Алерты:**
|
||
- Application down
|
||
- High error rate
|
||
- OpenAI API quota exceeded
|
||
- Git push failures
|
||
|
||
## 8. Безопасность
|
||
|
||
### 8.1 Аутентификация и авторизация
|
||
- Telegram User ID whitelist (только владелец)
|
||
- API keys в environment variables
|
||
- No public endpoints кроме Telegram webhook
|
||
|
||
### 8.2 Защита данных
|
||
- API keys не в коде
|
||
- Логи не содержат sensitive данные
|
||
- HTTPS для всех внешних API calls
|
||
- Git repository может быть private
|
||
|
||
## 9. Качественные атрибуты
|
||
|
||
### 9.1 Производительность
|
||
- Время отклика бота: < 2 секунды для текстовых сообщений
|
||
- Время создания заметки: < 5 секунд включая GPT обработку
|
||
- Голосовые сообщения: < 10 секунд для транскрипции и создания заметки
|
||
|
||
### 9.2 Надежность
|
||
- Graceful degradation при недоступности OpenAI API
|
||
- Retry mechanisms для внешних API
|
||
- Data consistency через atomic git operations
|
||
|
||
### 9.3 Maintainability
|
||
- Четкое разделение ответственности между слоями
|
||
- Интерфейсы для всех основных компонентов
|
||
- Comprehensive logging для отладки
|
||
- Configuration management через environment variables
|
||
|
||
## 10. Риски и ограничения
|
||
|
||
### 10.1 Технические риски
|
||
- **OpenAI API limits:** Rate limiting может замедлить обработку
|
||
- **Vector DB performance:** Поиск может замедляться с ростом количества заметок
|
||
- **VPS resources:** Ограниченная память и CPU для vector operations
|
||
|
||
### 10.2 Операционные риски
|
||
- **Single point of failure:** Монолитная архитектура
|
||
- **Manual deployment:** Отсутствие автоматизированного CI/CD
|
||
- **Backup dependency:** Зависимость от Git для backup заметок
|
||
|
||
### 10.3 Митигация рисков
|
||
- Monitoring и alerting для раннего обнаружения проблем
|
||
- Регулярные backups Git repository
|
||
- Graceful fallbacks при недоступности внешних сервисов
|
||
- Resource monitoring для предотвращения исчерпания ресурсов VPS |