✨ Реорганизация структуры заметок v2.0
- Создана новая организационная структура с эмодзи-папками - Добавлена система Inbox для быстрого захвата идей - Созданы шаблоны для всех типов заметок с YAML метаданными - Перенесен весь контент из старой структуры в новую - Добавлен главный дашборд с динамическими запросами - Создано подробное руководство по использованию системы - Техническая документация реорганизована по типам Основные улучшения: ✅ Inbox-first подход для новых заметок ✅ Тематическая организация по 8 областям знаний ✅ Шаблоны с метаданными для структурированности ✅ Система связей между заметками ✅ Динамические дашборды с аналитикой ✅ Централизованная техническая документация без дублирования
This commit is contained in:
Andrey Epifancev
@@ -0,0 +1,428 @@
|
||||
## 1. Обзор системы
|
||||
|
||||
### 1.1 Назначение
|
||||
Система представляет собой Telegram бота для автоматизации создания и управления заметками в Obsidian с интеграцией в существующий Git + Quartz workflow.
|
||||
|
||||
### 1.2 Ключевые функции
|
||||
- Создание заметок из текстовых и голосовых сообщений
|
||||
- Семантический поиск по базе знаний
|
||||
- Дополнение существующих заметок
|
||||
- Автоматическое форматирование через YandexGPT
|
||||
- Интеграция с 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
|
||||
- `yandexcloud-sdk-go` - YandexGPT API интеграция
|
||||
- `go-git/v5` - Git операции
|
||||
- `viper` - конфигурация
|
||||
- `logrus` - структурированное логирование
|
||||
|
||||
**Внешние сервисы:**
|
||||
- YandexGPT API (YandexGPT Lite/Pro, SpeechKit для голоса)
|
||||
- Telegram Bot API
|
||||
- Векторная база данных (Qdrant/Chroma)
|
||||
|
||||
## 3. Архитектура системы
|
||||
|
||||
### 3.1 Общая диаграмма системы
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Telegram User] --> B[Monolithic Bot App]
|
||||
B --> A
|
||||
B --> C[External Services]
|
||||
C --> B
|
||||
|
||||
subgraph "External Services"
|
||||
D[YandexGPT API]
|
||||
E[Vector DB]
|
||||
F[Telegram API]
|
||||
end
|
||||
|
||||
B --> G[File System]
|
||||
|
||||
subgraph "File System"
|
||||
H[Obsidian Vault]
|
||||
I[Git Repository]
|
||||
J[Vector Index]
|
||||
end
|
||||
|
||||
G --> K[Git Hooks]
|
||||
K --> L[Quartz Rebuild]
|
||||
|
||||
C --> D
|
||||
C --> E
|
||||
C --> F
|
||||
```
|
||||
|
||||
### 3.2 Компонентная диаграмма
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Monolithic Application"
|
||||
A[Bot Handler]
|
||||
B[HTTP Server]
|
||||
C[CLI Tools]
|
||||
|
||||
subgraph "Business Logic Layer"
|
||||
D[Note Service]
|
||||
E[Search Service]
|
||||
F[Voice Service]
|
||||
G[LLM Service]
|
||||
H[File Service]
|
||||
I[Git Service]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure Layer"
|
||||
J[Config Manager]
|
||||
K[Logger]
|
||||
L[Cache]
|
||||
end
|
||||
end
|
||||
|
||||
A --> D
|
||||
A --> E
|
||||
A --> F
|
||||
B --> D
|
||||
B --> E
|
||||
B --> F
|
||||
C --> D
|
||||
C --> E
|
||||
C --> F
|
||||
|
||||
D --> G
|
||||
D --> H
|
||||
D --> I
|
||||
E --> G
|
||||
E --> H
|
||||
F --> G
|
||||
F --> H
|
||||
|
||||
G --> J
|
||||
H --> J
|
||||
I --> J
|
||||
G --> K
|
||||
H --> K
|
||||
I --> K
|
||||
```
|
||||
|
||||
### 3.3 Диаграмма потоков данных
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Telegram Message] --> B[Bot Handler]
|
||||
B --> C[Router]
|
||||
|
||||
C --> D[Create Note]
|
||||
C --> E[Search Notes]
|
||||
C --> F[Append Note]
|
||||
|
||||
D --> G[Format with YandexGPT]
|
||||
F --> H[Find & Update]
|
||||
|
||||
G --> I[Save File]
|
||||
E --> J[Vector Search]
|
||||
H --> I
|
||||
|
||||
I --> K[Git Commit]
|
||||
J --> K
|
||||
|
||||
K --> L[Quartz Rebuild]
|
||||
|
||||
subgraph "Message Processing"
|
||||
A
|
||||
B
|
||||
C
|
||||
end
|
||||
|
||||
subgraph "Note Operations"
|
||||
D
|
||||
E
|
||||
F
|
||||
end
|
||||
|
||||
subgraph "Processing"
|
||||
G
|
||||
H
|
||||
J
|
||||
end
|
||||
|
||||
subgraph "Storage"
|
||||
I
|
||||
K
|
||||
L
|
||||
end
|
||||
```
|
||||
|
||||
## 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
|
||||
- Зависимости: Yandex SpeechKit API, File Service
|
||||
|
||||
**LLM Service**
|
||||
- Ответственность: Интеграция с YandexGPT, форматирование, генерация контента
|
||||
- Интерфейсы: Text processing API
|
||||
- Зависимости: YandexGPT 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 Внешние интеграции
|
||||
|
||||
**YandexGPT API**
|
||||
- Назначение: YandexGPT Lite/Pro для форматирования, SpeechKit для транскрипции
|
||||
- Протокол: HTTPS REST API
|
||||
- Аутентификация: API Key (IAM токен)
|
||||
- Обработка ошибок: Retry with exponential backoff
|
||||
- Модели: yandexgpt-lite, yandexgpt-pro
|
||||
|
||||
**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
|
||||
- YandexGPT API response times
|
||||
- Git operation success/failure rates
|
||||
|
||||
**Алерты:**
|
||||
- Application down
|
||||
- High error rate
|
||||
- YandexGPT 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 секунд включая YandexGPT обработку
|
||||
- Голосовые сообщения: < 10 секунд для транскрипции и создания заметки
|
||||
|
||||
### 9.2 Надежность
|
||||
- Graceful degradation при недоступности YandexGPT API
|
||||
- Retry mechanisms для внешних API
|
||||
- Data consistency через atomic git operations
|
||||
|
||||
### 9.3 Maintainability
|
||||
- Четкое разделение ответственности между слоями
|
||||
- Интерфейсы для всех основных компонентов
|
||||
- Comprehensive logging для отладки
|
||||
- Configuration management через environment variables
|
||||
|
||||
## 10. Риски и ограничения
|
||||
|
||||
### 10.1 Технические риски
|
||||
- **YandexGPT 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
|
||||
|
||||
## 11. Конфигурация YandexGPT
|
||||
|
||||
### 11.1 API Ключи и аутентификация
|
||||
- **IAM Token:** Основной способ аутентификации для YandexGPT API
|
||||
- **API Key:** Альтернативный способ для некоторых сервисов
|
||||
- **Folder ID:** Идентификатор каталога в Yandex Cloud
|
||||
|
||||
### 11.2 Модели YandexGPT
|
||||
- **yandexgpt-lite:** Быстрая модель для базового форматирования
|
||||
- **yandexgpt-pro:** Продвинутая модель для сложных задач
|
||||
- **speechkit:** Для обработки голосовых сообщений
|
||||
|
||||
### 11.3 Переменные окружения
|
||||
```
|
||||
YANDEX_API_KEY=your_api_key
|
||||
YANDEX_FOLDER_ID=your_folder_id
|
||||
YANDEX_IAM_TOKEN=your_iam_token
|
||||
TELEGRAM_BOT_TOKEN=your_bot_token
|
||||
VAULT_PATH=/path/to/obsidian/vault
|
||||
```
|
||||
Reference in New Issue
Block a user