killingdruid/telegram-tui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
68a2b7a9823b41a755d466bd3ca4f9d0b5a01be5
telegram-tui/CONTEXT.md
Mikhail Kilin 68a2b7a982 fixes
2026-01-28 11:39:21 +03:00

22 KiB
Raw Blame History

Текущий контекст проекта

Статус: Фаза 9 — ЗАВЕРШЕНО + Тестирование (19%)

Что сделано

TDLib интеграция

  • Подключена библиотека tdlib-rs v1.1 с автоматической загрузкой TDLib
  • Реализована авторизация через телефон + код + 2FA пароль
  • Сессия сохраняется автоматически в папке tdlib_data/
  • Отключены логи TDLib через FFI вызов td_execute до создания клиента
  • Updates обрабатываются в отдельном потоке через mpsc канал (неблокирующе)
  • Graceful shutdown: корректное закрытие TDLib при выходе (Ctrl+C)

Функциональность

  • Загрузка списка чатов (до 50 штук)
  • Фильтрация чатов: показываются только чаты из ChatList::Main (без архива)
  • Фильтрация удалённых аккаунтов: "Deleted Account" не отображаются в списке
  • Отображение названия чата, счётчика непрочитанных и @username
  • Иконка 📌 для закреплённых чатов
  • Иконка 🔇 для замьюченных чатов
  • Индикатор @ для чатов с непрочитанными упоминаниями
  • Онлайн-статус: зелёная точка ● для онлайн пользователей
  • Загрузка истории сообщений при открытии чата (множественные попытки)
  • Группировка сообщений по дате (разделители "Сегодня", "Вчера", дата) — по центру
  • Группировка сообщений по отправителю (заголовок с именем)
  • Выравнивание сообщений: исходящие справа (зелёные), входящие слева
  • Перенос длинных сообщений: автоматический wrap на несколько строк
  • Отображение времени и галочек: текст (HH:MM ✓✓) для исходящих, (HH:MM) текст для входящих
  • Галочки прочтения (✓ отправлено, ✓✓ прочитано) — обновляются в реальном времени
  • Отметка сообщений как прочитанных: при открытии чата счётчик непрочитанных сбрасывается
  • Отправка текстовых сообщений
  • Редактирование сообщений: ↑ при пустом инпуте → выбор → Enter → редактирование
  • Удаление сообщений: в режиме выбора нажать d / в / Delete → модалка подтверждения
  • Reply на сообщения: в режиме выбора нажать r / к → режим ответа с превью
  • Forward сообщений: в режиме выбора нажать f / а → выбор чата для пересылки
  • Отображение пересланных сообщений: индикатор "↪ Переслано от" с именем отправителя
  • Индикатор редактирования: ✎ рядом с временем для отредактированных сообщений
  • Новые сообщения в реальном времени при открытом чате
  • Поиск по чатам (Ctrl+S): фильтрация по названию и @username
  • Typing indicator ("печатает..."): отображение статуса набора текста собеседником и отправка своего статуса
  • Закреплённые сообщения: отображение pinned message вверху чата с переходом к нему
  • Поиск по сообщениям в чате (Ctrl+F): поиск текста внутри открытого чата с навигацией по результатам
  • Черновики: автосохранение набранного текста при переключении между чатами
  • Профиль пользователя/чата (i): просмотр информации о собеседнике или группе
  • Копирование сообщений (y/н): копирование текста сообщения в системный буфер обмена
  • Реакции на сообщения:
    • Отображение реакций под сообщениями
    • Логика отображения: 1 человек = только emoji, 2+ = emoji + счётчик
    • Свои реакции в рамках [👍], чужие без рамок 👍
    • Emoji picker с сеткой доступных реакций (8 в ряду)
    • Добавление/удаление реакций (toggle)
    • Обновление реакций в реальном времени через Update::MessageInteractionInfo
  • Конфигурационный файл (~/.config/tele-tui/config.toml):
    • Автоматическое создание дефолтного конфига при первом запуске
    • Настройка timezone: формат "+03:00" или "-05:00"
    • Настройка цветов: incoming_message, outgoing_message, selected_message, reaction_chosen, reaction_other
    • Credentials файл (~/.config/tele-tui/credentials): API_ID и API_HASH
    • Приоритет загрузки: ~/.config/tele-tui/credentials → .env → сообщение об ошибке с инструкциями
  • Кеширование имён пользователей: имена загружаются асинхронно и обновляются в UI
  • Папки Telegram: загрузка и переключение между папками (1-9)
  • Медиа-заглушки: [Фото], [Видео], [Голосовое], [Стикер], [GIF] и др.
  • Markdown форматирование в сообщениях:
    • Жирный (bold)
    • Курсив (italic)
    • Подчёркнутый (underline)
    • Зачёркнутый (strikethrough)
    • Код (inline code, Pre, PreCode) — cyan на тёмном фоне
    • Спойлеры — скрытый текст (серый на сером)
    • Ссылки (URL, TextUrl, Email, Phone) — синий с подчёркиванием
    • @Упоминания — синий с подчёркиванием

Состояние сети

  • Индикатор в футере: показывает текущее состояние подключения
    • ⚠ Нет сети — красный, ожидание сети
    • ⏳ Прокси... — cyan, подключение к прокси
    • ⏳ Подключение... — cyan, подключение к серверам
    • ⏳ Обновление... — cyan, синхронизация данных

Оптимизации

  • 60 FPS ready: poll таймаут 16ms, рендеринг только при изменениях (needs_redraw флаг)
  • Оптимизация памяти:
    • Очистка сообщений при закрытии чата
    • Лимит кэша пользователей (500)
    • Периодическая очистка неактивных записей
  • Минимальное разрешение: предупреждение если терминал меньше 80x20

Динамический инпут

  • Автоматическое расширение: поле ввода увеличивается при длинном тексте (до 10 строк)
  • Перенос текста: длинные сообщения переносятся на новые строки
  • Блочный курсор: vim-style курсор █ с возможностью перемещения по тексту

Управление

  • ↑/↓ стрелки — навигация по списку чатов
  • Enter — открыть чат / отправить сообщение
  • Esc — закрыть открытый чат / отменить поиск
  • Ctrl+S — поиск по чатам (фильтрация по названию и username)
  • Ctrl+R — обновить список чатов
  • Ctrl+C — выход (graceful shutdown)
  • ↑/↓ в открытом чате — скролл сообщений (с подгрузкой старых)
  • ↑ при пустом инпуте — выбор сообщения для редактирования
  • Enter в режиме выбора — начать редактирование
  • r / к в режиме выбора — ответить на сообщение (reply)
  • f / а в режиме выбора — переслать сообщение (forward)
  • d / в / Delete в режиме выбора — удалить сообщение (с подтверждением)
  • y / н / Enter — подтвердить удаление в модалке
  • n / т / Esc — отменить удаление в модалке
  • Esc — отменить выбор/редактирование/reply
  • 1-9 — переключение папок (в списке чатов)
  • Ctrl+F — поиск по сообщениям в открытом чате
  • n / N — навигация по результатам поиска (следующий/предыдущий)
  • i — открыть профиль пользователя/чата
  • y / н в режиме выбора — скопировать сообщение в буфер обмена
  • e / у в режиме выбора — добавить реакцию (открывает emoji picker)
  • ← / → / ↑ / ↓ в emoji picker — навигация по сетке реакций
  • Enter в emoji picker — добавить/удалить реакцию
  • Esc в emoji picker — закрыть picker
  • Редактирование текста в инпуте:
    • ← / → — перемещение курсора
    • Home — курсор в начало
    • End — курсор в конец
    • Backspace — удалить символ слева
    • Delete — удалить символ справа

Структура проекта

src/
├── main.rs           # Точка входа, event loop, TDLib инициализация, graceful shutdown
├── lib.rs            # Библиотечный интерфейс (для тестов)
├── config.rs         # Конфигурация (TOML), загрузка credentials
├── app/
│   ├── mod.rs        # App структура и состояние (needs_redraw флаг)
│   └── state.rs      # AppScreen enum
├── ui/
│   ├── mod.rs        # Роутинг UI по экранам, проверка минимального размера
│   ├── loading.rs    # Экран загрузки
│   ├── auth.rs       # Экран авторизации
│   ├── main_screen.rs # Главный экран с папками
│   ├── chat_list.rs  # Список чатов (pin, mute, online, mentions)
│   ├── messages.rs   # Область сообщений (wrap, группировка, динамический инпут)
│   └── footer.rs     # Подвал с командами и статусом сети
├── input/
│   ├── mod.rs        # Роутинг ввода
│   ├── auth.rs       # Обработка ввода на экране авторизации
│   └── main_input.rs # Обработка ввода на главном экране
├── utils.rs          # Утилиты (disable_tdlib_logs, format_timestamp_with_tz, format_date, get_day)
└── tdlib/
    ├── mod.rs        # Модуль экспорта (TdClient, UserOnlineStatus, NetworkState)
    └── client.rs     # TdClient: авторизация, чаты, сообщения, кеш, NetworkState, ReactionInfo

tests/
├── helpers/
│   ├── mod.rs          # Экспорт тестовых утилит
│   ├── app_builder.rs  # TestAppBuilder для создания тестовых App
│   ├── fake_tdclient.rs # FakeTdClient (mock TDLib клиент, для будущих интеграционных тестов)
│   ├── snapshot_utils.rs # Утилиты для snapshot тестов (render_to_buffer, buffer_to_string)
│   └── test_data.rs    # Builders для тестовых данных (TestChatBuilder, TestMessageBuilder)
├── chat_list.rs        # Snapshot тесты для списка чатов (9 тестов)
└── messages.rs         # Snapshot тесты для сообщений (19 тестов)

Тестирование

Статус: В процессе (19% завершено)

Стратегия: Комбо подход — 70% snapshot tests, 25% integration tests, 5% e2e smoke tests

Инфраструктура (Фаза 0): ✅ Завершена

  • Добавлены зависимости: insta = "1.34", tokio-test = "0.4"
  • Создан src/lib.rs для экспорта модулей в тесты
  • Созданы test helpers:
    • TestAppBuilder — fluent builder для создания тестовых App
    • TestChatBuilder / TestMessageBuilder — builders для тестовых данных
    • FakeTdClient — in-memory mock TDLib клиента
    • render_to_buffer / buffer_to_string — утилиты для snapshot тестов

Snapshot Tests (Фаза 1): 28/57 (49%)

  • ✅ 1.1 Chat List (9/10): пустой список, множественные чаты, unread, pinned, muted, mentions, selected, long title, search mode
  • ✅ 1.2 Messages (19/19): empty chat, incoming/outgoing, date separators, sender grouping, read receipts, edited, long message wrap, markdown (bold/italic/code/links/mentions/spoiler), media placeholder, reply, forwarded, reactions (single/multiple), selected message
  • 1.3-1.6: Modals, Input Field, Footer, Screens (0/29)

Прогресс: 28/151 тестов (19%)

Подробный план и roadmap: см. TESTING_ROADMAP.md

Ключевые решения

  1. Неблокирующий receive: TDLib updates приходят в отдельном потоке и передаются в main loop через mpsc::channel. Это позволяет UI оставаться отзывчивым.

  2. FFI для логов: Используем прямой вызов td_execute для отключения логов синхронно, до создания клиента, чтобы избежать вывода в терминал.

  3. Синхронизация чатов: Чаты загружаются асинхронно через updates. Main loop периодически синхронизирует app.chats с td_client.chats.

  4. Кеширование имён: При получении Update::User сохраняем имя (first_name + last_name) и username в HashMap. Имена подгружаются асинхронно через очередь pending_user_ids. Кэш ограничен 500 записями.

  5. Группировка сообщений: Сообщения группируются по дате (разделители по центру) и по отправителю (заголовки). Исходящие выравниваются вправо, входящие влево.

  6. Отметка прочтения: При открытии чата вызывается view_messages для всех сообщений. Новые входящие сообщения автоматически отмечаются как прочитанные. Update::ChatReadOutbox обновляет статус галочек.

  7. Graceful shutdown: При Ctrl+C устанавливается флаг остановки, закрывается TDLib клиент, ожидается завершение polling задачи с таймаутом 2 сек.

  8. Оптимизация рендеринга: Флаг needs_redraw позволяет пропускать перерисовку когда ничего не изменилось. Триггеры: TDLib updates, пользовательский ввод, изменение размера терминала.

  9. Перенос текста: Длинные сообщения автоматически разбиваются на строки с учётом ширины терминала. Для исходящих — time_mark на последней строке, для входящих — время на первой строке с отступом для остальных.

  10. Конфигурационный файл: TOML конфиг создаётся автоматически при первом запуске в ~/.config/tele-tui/config.toml. Поддерживает настройку timezone (применяется к отображению времени через format_timestamp_with_tz) и цветовой схемы (парсится в ratatui::style::Color). Credentials загружаются с приоритетом: XDG config dir → .env → ошибка с инструкциями.

  11. Реакции: Хранятся в Vec<ReactionInfo> для каждого сообщения. Обновляются в реальном времени через Update::MessageInteractionInfo. Emoji picker использует сетку 8x6 с навигацией стрелками. Приоритет обработки ввода: reaction picker → delete confirmation → остальные модалки (важно для корректной работы Enter/Esc).

Зависимости (Cargo.toml)

ratatui = "0.29"
crossterm = "0.28"
tdlib-rs = { version = "1.1", features = ["download-tdlib"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
dotenvy = "0.15"
chrono = "0.4"
clipboard = "0.5"
toml = "0.8"
dirs = "5.0"

API Credentials

Приоритет загрузки (от высшего к низшему):

  1. Файл credentials (~/.config/tele-tui/credentials):
API_ID=your_api_id
API_HASH=your_api_hash
  1. Переменные окружения (.env файл в текущей директории):
API_ID=your_api_id
API_HASH=your_api_hash
  1. Если ничего не найдено — показывается сообщение об ошибке с инструкциями.

Конфигурационный файл

Создаётся автоматически при первом запуске в ~/.config/tele-tui/config.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"

Последние обновления (2026-01-28)

Тестирование — Фаза 1.3 завершена

Добавлено:

  • 📝 8 snapshot тестов для модальных окон (tests/modals.rs)
  • 🔧 Обновлён TestAppBuilder с методами: with_chats(), message_search(), forward_mode()
  • 🐛 Исправлены нестабильные date separator тесты (заменены на фиксированную дату)
  • 📚 Обновлена документация тестирования

Покрытие: 35/151 тестов (23%)

  • ✅ Chat List: 9 тестов
  • ✅ Messages: 18 тестов (empty chat, incoming/outgoing, date separators, grouping, read receipts, editing, wrap, markdown, media, reply, forward, reactions, selection)
  • ✅ Modals: 8 тестов (delete confirmation, emoji picker x2, profile x2, pinned message, search, forward mode)

Все тесты проходят: cargo test → 71 passed ✅

Подробности: TESTING_PROGRESS.md

Что НЕ сделано / TODO

Все пункты Фазы 9 завершены! Можно переходить к следующей фазе разработки или продолжить написание тестов.

Технический долг

См. REFACTORING_ROADMAP.md для детального плана рефакторинга.

Основные области для улучшения:

  1. ChatState enum — схлопнуть boolean состояния в type-safe enum
  2. Разделение TdClient — слишком много ответственности в одном модуле
  3. Типобезопасность — newtype pattern для ID, error enum
  4. UI компоненты — выделить переиспользуемые компоненты
  5. Тестирование — добавить юнит-тесты для критичных функций

Известные проблемы

  1. При первом запуске нужно пройти авторизацию
Reference in New Issue View Git Blame Copy Permalink