# Структура проекта ## Обзор директорий ``` tele-tui/ ├── .github/ # GitHub конфигурация │ ├── ISSUE_TEMPLATE/ # Шаблоны для issue │ │ ├── bug_report.md │ │ └── feature_request.md │ ├── workflows/ # GitHub Actions CI/CD │ │ └── ci.yml │ └── pull_request_template.md │ ├── docs/ # Дополнительная документация │ └── TDLIB_INTEGRATION.md │ ├── src/ # Исходный код │ ├── app/ # Состояние приложения │ │ ├── mod.rs │ │ └── state.rs │ ├── input/ # Обработка пользовательского ввода │ │ ├── mod.rs │ │ ├── auth.rs │ │ └── main_input.rs │ ├── tdlib/ # TDLib интеграция │ │ ├── mod.rs │ │ └── client.rs │ ├── ui/ # Рендеринг интерфейса │ │ ├── mod.rs │ │ ├── auth.rs │ │ ├── chat_list.rs │ │ ├── footer.rs │ │ ├── loading.rs │ │ ├── main_screen.rs │ │ └── messages.rs │ ├── config.rs # Конфигурация приложения │ ├── main.rs # Точка входа │ └── utils.rs # Утилиты │ ├── tdlib_data/ # TDLib сессия (НЕ коммитится) ├── target/ # Артефакты сборки (НЕ коммитится) │ ├── .editorconfig # EditorConfig для IDE ├── .gitignore # Git ignore правила ├── Cargo.lock # Зависимости (точные версии) ├── Cargo.toml # Манифест проекта ├── rustfmt.toml # Конфигурация форматирования │ ├── config.toml.example # Пример конфигурации ├── credentials.example # Пример credentials │ ├── CHANGELOG.md # История изменений ├── CLAUDE.md # Инструкции для Claude AI ├── CONTRIBUTING.md # Гайд по контрибуции ├── CONTEXT.md # Текущий статус разработки ├── DEVELOPMENT.md # Правила разработки ├── FAQ.md # Часто задаваемые вопросы ├── HOTKEYS.md # Список горячих клавиш ├── INSTALL.md # Инструкция по установке ├── LICENSE # MIT лицензия ├── PROJECT_STRUCTURE.md # Этот файл ├── README.md # Главная документация ├── REQUIREMENTS.md # Функциональные требования ├── ROADMAP.md # План развития └── SECURITY.md # Политика безопасности ``` ## Исходный код (src/) ### main.rs **Точка входа приложения** - Инициализация TDLib клиента - Event loop (60 FPS) - Обработка Ctrl+C (graceful shutdown) - Координация между UI, input и TDLib ### config.rs **Конфигурация приложения** - Загрузка/сохранение TOML конфига - Парсинг timezone и цветов - Загрузка credentials (приоритетная система) - XDG directory support ### utils.rs **Утилитарные функции** - `disable_tdlib_logs()` — отключение TDLib логов через FFI - `format_timestamp_with_tz()` — форматирование времени с учётом timezone - `format_date()` — форматирование дат для разделителей - `format_datetime()` — полное форматирование даты и времени - `format_was_online()` — "был(а) X мин. назад" ### app/ — Состояние приложения #### mod.rs - `App` struct — главная структура состояния - `needs_redraw` — флаг для оптимизации рендеринга - Состояние модалок (delete confirm, reaction picker, profile) - Состояние поиска и черновиков - Методы для работы с UI state #### state.rs - `AppScreen` enum — текущий экран (Loading, Auth, Main) ### tdlib/ — Telegram интеграция #### client.rs - `TdClient` — обёртка над TDLib - Авторизация (телефон, код, 2FA) - Загрузка чатов и сообщений - Отправка/редактирование/удаление сообщений - Reply, Forward - Реакции (`ReactionInfo`) - LRU кеши (users, statuses) - `NetworkState` enum #### mod.rs - Экспорт публичных типов ### ui/ — Рендеринг интерфейса #### mod.rs - `render()` — роутинг по экранам - Проверка минимального размера терминала (80x20) #### loading.rs - Экран "Loading..." #### auth.rs - Экран авторизации (ввод телефона, кода, пароля) #### main_screen.rs - Главный экран - Отображение папок сверху #### chat_list.rs - Список чатов - Индикаторы: 📌, 🔇, @, (N) - Онлайн-статус (●) - Поиск по чатам #### messages.rs - Область сообщений - Группировка по дате и отправителю - Markdown форматирование - Реакции под сообщениями - Emoji picker modal - Profile modal - Delete confirmation modal - Pinned message - Динамический инпут - Блочный курсор #### footer.rs - Футер с командами - Индикатор состояния сети ### input/ — Обработка ввода #### mod.rs - Роутинг ввода по экранам #### auth.rs - Обработка ввода на экране авторизации #### main_input.rs - Обработка ввода на главном экране - **Важно**: порядок обработчиков имеет значение! 1. Reaction picker (Enter/Esc) 2. Delete confirmation 3. Profile modal 4. Search в чате 5. Forward mode 6. Edit/Reply mode 7. Message selection 8. Chat list - Поддержка русской раскладки ## Конфигурационные файлы ### Cargo.toml Манифест проекта: - Metadata (name, version, authors, license) - Dependencies - Build dependencies (tdlib-rs) ### rustfmt.toml Конфигурация `cargo fmt`: - max_width = 100 - imports_granularity = "Crate" - Стиль комментариев ### .editorconfig Универсальные настройки для IDE: - Unix line endings (LF) - UTF-8 encoding - Отступы (4 spaces для Rust) ## Рантайм файлы ### tdlib_data/ Создаётся автоматически TDLib: - Токены авторизации - Кеш сообщений и файлов - **НЕ коммитится** (в .gitignore) - **НЕ делиться** (содержит чувствительные данные) ### ~/.config/tele-tui/ XDG config directory: - `config.toml` — пользовательская конфигурация - `credentials` — API_ID и API_HASH ## Документация ### Пользовательская - **README.md** — главная страница, overview - **INSTALL.md** — установка и настройка - **HOTKEYS.md** — все горячие клавиши - **FAQ.md** — часто задаваемые вопросы ### Разработчика - **CONTRIBUTING.md** — как внести вклад - **DEVELOPMENT.md** — правила разработки - **PROJECT_STRUCTURE.md** — этот файл - **ROADMAP.md** — план развития - **CONTEXT.md** — текущий статус, архитектурные решения ### Спецификации - **REQUIREMENTS.md** — функциональные требования - **CHANGELOG.md** — история изменений - **SECURITY.md** — политика безопасности ### Внутренняя - **CLAUDE.md** — инструкции для AI ассистента - **docs/TDLIB_INTEGRATION.md** — детали интеграции TDLib ## Ключевые концепции ### Архитектура - **Event-driven**: TDLib updates → mpsc channel → main loop - **Unidirectional data flow**: TDLib → App state → UI rendering - **Modal stacking**: приоритет обработки ввода для модалок ### Оптимизации - **needs_redraw**: рендеринг только при изменениях - **LRU caches**: user_names, user_statuses (500 записей) - **Limits**: 500 messages/chat, 200 chats - **Lazy loading**: users загружаются батчами (5 за цикл) ### Состояние ``` App { screen: AppScreen, config: Config, needs_redraw: bool, // TDLib state chats: Vec, folders: Vec, // UI state selected_chat_id: Option, input_text: String, cursor_position: usize, // Modals is_delete_confirmation: bool, is_reaction_picker_mode: bool, profile_info: Option, // Search search_query: String, search_results: Vec, // Drafts drafts: HashMap, } ``` ## Потоки выполнения ### Main thread - Event loop (16ms tick для 60 FPS) - UI rendering - Input handling - App state updates ### TDLib thread - `td_client.receive()` в отдельном Tokio task - Updates отправляются через `mpsc::channel` - Неблокирующий для main thread ### Blocking operations - Загрузка конфига (при запуске) - Авторизация (блокирует до ввода кода) - Graceful shutdown (2 sec timeout) ## Зависимости ### UI - `ratatui` 0.29 — TUI framework - `crossterm` 0.28 — terminal control ### Telegram - `tdlib-rs` 1.1 — TDLib bindings - `tokio` 1.x — async runtime ### Data - `serde` + `serde_json` 1.0 — serialization - `toml` 0.8 — config parsing - `chrono` 0.4 — date/time ### System - `dirs` 5.0 — XDG directories - `arboard` 3.4 — clipboard - `open` 5.0 — открытие URL/файлов - `dotenvy` 0.15 — .env файлы ## Workflow разработки 1. Изучить [ROADMAP.md](ROADMAP.md) — понять текущую фазу 2. Прочитать [DEVELOPMENT.md](DEVELOPMENT.md) — правила работы 3. Изучить [CONTEXT.md](CONTEXT.md) — архитектурные решения 4. Найти issue или создать новую фичу 5. Создать feature branch 6. Внести изменения 7. `cargo fmt` + `cargo clippy` 8. Протестировать вручную 9. Создать PR с описанием ## CI/CD ### GitHub Actions (.github/workflows/ci.yml) - **Check**: `cargo check` - **Format**: `cargo fmt --check` - **Clippy**: `cargo clippy` - **Build**: для Ubuntu, macOS, Windows Запускается на: - Push в `main` или `develop` - Pull requests ## Безопасность ### Чувствительные файлы (в .gitignore) - `.env` - `credentials` - `config.toml` (если в корне проекта) - `tdlib_data/` - `target/` ### Рекомендации - Credentials в `~/.config/tele-tui/credentials` - Права доступа: `chmod 600 ~/.config/tele-tui/credentials` - Никогда не коммитить `tdlib_data/`