258 lines
9.5 KiB
Markdown
258 lines
9.5 KiB
Markdown
# tele-tui
|
||
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://www.rust-lang.org/)
|
||
|
||
Консольный Telegram клиент с Vim-style навигацией.
|
||
|
||
|
||
|
||
## Возможности
|
||
|
||
- **Полная интеграция с Telegram**: отправка/получение сообщений, редактирование, удаление, пересылка
|
||
- **Vim-style навигация**: hjkl + поддержка русской раскладки (ролд)
|
||
- **Markdown форматирование**: жирный, курсив, подчёркивание, зачёркивание, код, спойлеры, ссылки
|
||
- **Реакции на сообщения**: emoji picker с навигацией стрелками
|
||
- **Папки Telegram**: переключение между папками (1-9)
|
||
- **Поиск**: по чатам (Ctrl+S) и внутри чата (Ctrl+F)
|
||
- **Черновики**: автосохранение набранного текста при переключении чатов
|
||
- **Typing indicator**: показывает когда собеседник печатает
|
||
- **Закреплённые сообщения**: отображение и переход к закреплённому сообщению
|
||
- **Копирование в буфер**: copy сообщений в системный буфер обмена
|
||
- **Профиль**: просмотр информации о пользователе/чате
|
||
- **Конфигурация**: настройка цветов и часового пояса через TOML
|
||
- **Оптимизация**: 60 FPS, умное кеширование, graceful shutdown
|
||
|
||
## Установка
|
||
|
||
### Требования
|
||
|
||
- Rust 1.70+
|
||
- TDLib (скачивается автоматически через tdlib-rs)
|
||
|
||
### Сборка
|
||
|
||
```bash
|
||
git clone https://github.com/your-username/tele-tui.git
|
||
cd tele-tui
|
||
cargo build --release
|
||
```
|
||
|
||
### API Credentials
|
||
|
||
Получите API credentials на https://my.telegram.org/apps
|
||
|
||
Создайте файл `~/.config/tele-tui/credentials`:
|
||
```
|
||
API_ID=your_api_id
|
||
API_HASH=your_api_hash
|
||
```
|
||
|
||
Или используйте `.env` файл в директории проекта:
|
||
```
|
||
API_ID=your_api_id
|
||
API_HASH=your_api_hash
|
||
```
|
||
|
||
## Использование
|
||
|
||
```bash
|
||
cargo run --release
|
||
```
|
||
|
||
При первом запуске нужно пройти авторизацию (телефон + код + опционально 2FA пароль).
|
||
|
||
## Конфигурация
|
||
|
||
Конфигурационный файл создаётся автоматически в `~/.config/tele-tui/config.toml`:
|
||
|
||
```toml
|
||
[general]
|
||
# Часовой пояс в формате "+03:00" или "-05:00"
|
||
timezone = "+03:00"
|
||
|
||
[colors]
|
||
# Поддерживаемые цвета: black, red, green, yellow, blue, magenta, cyan, gray, white,
|
||
# darkgray, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan
|
||
incoming_message = "white"
|
||
outgoing_message = "green"
|
||
selected_message = "yellow"
|
||
reaction_chosen = "yellow"
|
||
reaction_other = "gray"
|
||
```
|
||
|
||
## Горячие клавиши
|
||
|
||
### Навигация
|
||
- `↑/↓` или `k/j` (р/о) — навигация по списку чатов
|
||
- `Enter` — открыть чат / отправить сообщение
|
||
- `Esc` — закрыть чат / отменить действие
|
||
- `1-9` — переключение между папками
|
||
- `Ctrl+S` — поиск по чатам
|
||
- `Ctrl+R` — обновить список чатов
|
||
- `Ctrl+C` — выход
|
||
|
||
### В открытом чате
|
||
- `↑/↓` — скролл сообщений
|
||
- `Ctrl+F` — поиск в чате
|
||
- `n/N` — следующий/предыдущий результат поиска
|
||
- `i` — информация о чате/пользователе
|
||
|
||
### Работа с сообщениями
|
||
- `↑` при пустом инпуте — выбор сообщения
|
||
- `Enter` в режиме выбора — редактировать
|
||
- `r` / `к` — ответить (reply)
|
||
- `f` / `а` — переслать (forward)
|
||
- `d` / `в` / `Delete` — удалить
|
||
- `y` / `н` — скопировать в буфер
|
||
- `e` / `у` — добавить реакцию
|
||
|
||
### Emoji Picker (реакции)
|
||
- `←/→/↑/↓` — навигация по сетке
|
||
- `Enter` — добавить/удалить реакцию
|
||
- `Esc` — закрыть picker
|
||
|
||
### Редактирование текста
|
||
- `←/→` — перемещение курсора
|
||
- `Home` — в начало строки
|
||
- `End` — в конец строки
|
||
- `Backspace` — удалить символ слева
|
||
- `Delete` — удалить символ справа
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
src/
|
||
├── main.rs # Точка входа, event loop
|
||
├── config.rs # Конфигурация (TOML), credentials
|
||
├── app/ # Состояние приложения
|
||
├── ui/ # Отрисовка интерфейса
|
||
├── input/ # Обработка ввода
|
||
├── utils.rs # Утилиты (форматирование времени, логи)
|
||
└── tdlib/ # TDLib интеграция
|
||
```
|
||
|
||
## Зависимости
|
||
|
||
- `ratatui` 0.29 — TUI framework
|
||
- `crossterm` 0.28 — terminal handling
|
||
- `tdlib-rs` 1.1 — Telegram API
|
||
- `tokio` 1.x — async runtime
|
||
- `serde` + `serde_json` — serialization
|
||
- `toml` 0.8 — config parsing
|
||
- `dirs` 5.0 — XDG directories
|
||
- `clipboard` 0.5 — clipboard access
|
||
- `chrono` 0.4 — date/time formatting
|
||
|
||
## Тестирование
|
||
|
||
tele-tui использует **snapshot тестирование** для UI и интеграционные тесты для логики.
|
||
|
||
### Запуск всех тестов
|
||
|
||
```bash
|
||
cargo test
|
||
```
|
||
|
||
### Snapshot тесты
|
||
|
||
Snapshot тесты проверяют отображение UI компонентов через виртуальный терминал:
|
||
|
||
```bash
|
||
# Прогнать snapshot тесты
|
||
cargo test --test chat_list
|
||
cargo test --test messages
|
||
|
||
# Посмотреть изменения в snapshots
|
||
cargo insta review
|
||
|
||
# Принять все новые snapshots
|
||
cargo insta accept
|
||
|
||
# Отклонить все изменения
|
||
cargo insta reject
|
||
```
|
||
|
||
### Установка cargo-insta
|
||
|
||
Для работы со snapshot тестами нужен `cargo-insta`:
|
||
|
||
```bash
|
||
cargo install cargo-insta
|
||
```
|
||
|
||
### Структура тестов
|
||
|
||
```
|
||
tests/
|
||
├── helpers/ # Тестовые утилиты
|
||
│ ├── app_builder.rs # TestAppBuilder для создания тестовых App
|
||
│ ├── test_data.rs # Builders для чатов и сообщений
|
||
│ ├── snapshot_utils.rs # Утилиты для snapshot тестов
|
||
│ └── fake_tdclient.rs # Mock TDLib клиент (для будущих integration тестов)
|
||
├── chat_list.rs # Snapshot тесты для списка чатов (9 тестов)
|
||
└── messages.rs # Snapshot тесты для сообщений (19 тестов)
|
||
```
|
||
|
||
### Создание snapshot теста
|
||
|
||
```rust
|
||
use helpers::test_data::TestChatBuilder;
|
||
use helpers::app_builder::TestAppBuilder;
|
||
use helpers::snapshot_utils::{render_to_buffer, buffer_to_string};
|
||
use insta::assert_snapshot;
|
||
|
||
#[test]
|
||
fn snapshot_my_feature() {
|
||
let chat = TestChatBuilder::new("Test Chat", 123)
|
||
.unread_count(5)
|
||
.build();
|
||
|
||
let mut app = TestAppBuilder::new()
|
||
.with_chat(chat)
|
||
.selected_chat(123)
|
||
.build();
|
||
|
||
let buffer = render_to_buffer(80, 24, |f| {
|
||
tele_tui::ui::chat_list::render(f, f.area(), &mut app);
|
||
});
|
||
|
||
let output = buffer_to_string(&buffer);
|
||
assert_snapshot!("my_feature", output);
|
||
}
|
||
```
|
||
|
||
### Покрытие тестами
|
||
|
||
**Текущий прогресс**: 35/151 тестов (23%)
|
||
|
||
- ✅ Фаза 0: Инфраструктура (100%)
|
||
- ✅ Фаза 1.1: Chat List snapshots (90%)
|
||
- ✅ Фаза 1.2: Messages snapshots (95%)
|
||
- ✅ Фаза 1.3: Modals snapshots (100%)
|
||
- 🔄 Фаза 1.4-1.6: Input, Footer, Screens (0%)
|
||
- 📋 Фаза 2: Integration тесты для логики (0%)
|
||
|
||
Подробный план: [TESTING_ROADMAP.md](TESTING_ROADMAP.md)
|
||
|
||
## Документация
|
||
|
||
- [INSTALL.md](INSTALL.md) — подробная инструкция по установке
|
||
- [HOTKEYS.md](HOTKEYS.md) — все горячие клавиши
|
||
- [FAQ.md](FAQ.md) — часто задаваемые вопросы
|
||
- [CONTRIBUTING.md](CONTRIBUTING.md) — как внести вклад
|
||
- [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md) — структура проекта
|
||
- [SECURITY.md](SECURITY.md) — политика безопасности
|
||
- [CHANGELOG.md](CHANGELOG.md) — история изменений
|
||
- [REQUIREMENTS.md](REQUIREMENTS.md) — функциональные требования
|
||
- [DEVELOPMENT.md](DEVELOPMENT.md) — правила разработки
|
||
- [ROADMAP.md](ROADMAP.md) — план развития проекта
|
||
- [REFACTORING_ROADMAP.md](REFACTORING_ROADMAP.md) — план рефакторинга кода
|
||
- [TESTING_ROADMAP.md](TESTING_ROADMAP.md) — план покрытия тестами
|
||
- [TESTING_PROGRESS.md](TESTING_PROGRESS.md) — прогресс тестирования
|
||
- [CONTEXT.md](CONTEXT.md) — текущий статус разработки
|
||
|
||
## Лицензия
|
||
|
||
MIT
|