docs: clean up project markdown

2026-05-17 03:56:04 +03:00
parent 90776448ce
commit 1208aa5afb
12 changed files with 287 additions and 2099 deletions
--- a/README.md
+++ b/README.md
@@ -1,261 +1,69 @@
 # tele-tui

-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
-
-Консольный Telegram клиент с Vim-style навигацией.
-
-![tele-tui screenshot](docs/screenshot.png)
+Консольный Telegram-клиент на Rust с Vim-style навигацией, Normal/Insert режимами, TDLib и поддержкой русской раскладки.

 ## Возможности

- **Полная интеграция с Telegram**: отправка/получение сообщений, редактирование, удаление, пересылка
- **Vim-style навигация**: hjkl + поддержка русской раскладки (ролд)
- **Markdown форматирование**: жирный, курсив, подчёркивание, зачёркивание, код, спойлеры, ссылки
- **Реакции на сообщения**: emoji picker с навигацией стрелками
- **Папки Telegram**: переключение между папками (1-9)
- **Поиск**: по чатам (Ctrl+S) и внутри чата (Ctrl+F)
- **Черновики**: автосохранение набранного текста при переключении чатов
- **Typing indicator**: показывает когда собеседник печатает
- **Закреплённые сообщения**: отображение и переход к закреплённому сообщению
- **Копирование в буфер**: copy сообщений в системный буфер обмена
- **Профиль**: просмотр информации о пользователе/чате
- **Конфигурация**: настройка цветов и часового пояса через TOML
- **Оптимизация**: 60 FPS, умное кеширование, graceful shutdown
+- Авторизация через TDLib, список чатов, история и realtime updates.
+- Отправка, редактирование, удаление, reply, forward, copy и реакции.
+- Поиск по чатам и внутри открытого чата.
+- Telegram-папки, pinned/muted/mentions/unread indicators.
+- Markdown entities, inline фото, fullscreen image modal и фото-альбомы.
+- Голосовые сообщения через `ffplay`.
+- Desktop notifications, clipboard и открытие URL через feature flags.
+- Multi-account profiles, account switcher и per-account lock files.

 ## Установка

-### Требования
+Требования:

- Rust 1.70+
- TDLib (скачивается автоматически через tdlib-rs)
-
-### Сборка
+- Rust stable, рекомендовано 1.85+.
+- TDLib скачивается автоматически через `tdlib-rs` feature `download-tdlib`.
+- Для голосовых сообщений нужен `ffplay` из ffmpeg.

 ```bash
-git clone https://github.com/your-username/tele-tui.git
-cd tele-tui
 cargo build --release
 ```

-### API Credentials
+## Credentials

-Получите API credentials на https://my.telegram.org/apps
+Получите Telegram API credentials на <https://my.telegram.org/apps> и сохраните их в:

-Создайте файл `~/.config/tele-tui/credentials`:
+```text
+~/.config/tele-tui/credentials
 ```
+
+Формат:
+
+```text
 API_ID=your_api_id
 API_HASH=your_api_hash
 ```

-Или используйте `.env` файл в директории проекта:
-```
-API_ID=your_api_id
-API_HASH=your_api_hash
-```
+Для локальной разработки можно использовать `.env` в корне проекта с теми же ключами.

-## Использование
+## Запуск

 ```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
+cargo run --release -- --account work
 ```

-### 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 тесты для сообщений (18 тестов)
-├── modals.rs             # Snapshot тесты для модалок (8 тестов)
-└── input_field.rs        # Snapshot тесты для поля ввода (7 тестов)
-```
-
-### Создание 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);
-}
-```
-
-### Покрытие тестами
-
-**Текущий прогресс**: 81/151 тестов (54%)
-
- ✅ Фаза 0: Инфраструктура (100%)
- ✅ Фаза 1: UI Snapshot Tests (100%)
-  - Chat List, Messages, Modals, Input Field, Footer, Screens  
- 🔄 Фаза 2: Integration Tests (35%)
-  - ✅ Send Message Flow (6 тестов)
-  - ✅ Edit Message Flow (6 тестов)
-  - ✅ Delete Message Flow (6 тестов)
-  - ✅ Reply & Forward Flow (8 тестов)
-  - 📋 Reactions, Search, Drafts, Navigation, Profile, Network (0/48)
-
-Подробный план: [TESTING_ROADMAP.md](TESTING_ROADMAP.md)
+Runtime-конфиг создаётся в `~/.config/tele-tui/config.toml`; пример лежит в [config.toml.example](config.toml.example).

 ## Документация

- [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) — текущий статус разработки
+- [AGENT.md](AGENT.md) - краткие правила для агента.
+- [DEVELOPMENT.md](DEVELOPMENT.md) - локальные правила разработки и проверок.
+- [CONTEXT.md](CONTEXT.md) - текущий статус, риски и следующие шаги.
+- [docs/HOTKEYS.md](docs/HOTKEYS.md) - горячие клавиши.
+- [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) - карта подсистем.
+- [docs/TDLIB_INTEGRATION.md](docs/TDLIB_INTEGRATION.md) - проектные заметки по TDLib.

 ## Лицензия