docs: update file inventory and module header contracts

Refresh both AGENTS guides and clarify module purpose, usage, ownership, threading, return values and wire formats in headers. Remove the unused timeout_heap freed_count field and unimplemented getter.
2026-10-04 13:10:01 +02:00
1 parent c19eff67f6
commit a97e8bcc1f
@@ -1,3 +1,4 @@
+/* Отрисовка строки участника AccountList: аватар, имя, online и служебные значки. */
 #pragma once

 #include <QStyledItemDelegate>
@@ -1,3 +1,5 @@
+/* Панель участников выбранного канала и live-диагностика выбранного узла.
+ * Получает события bridge в GUI-потоке; запросы звонка и PM отдаёт через signals. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Общий GUI-таймер анимированных emoji: регистрирует LottieIcon и выдаёт ticked.
+ * play запускает минимум PlaybackMs; shutdown останавливает таймер и очищает регистрацию. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,5 @@
+/* Настройки capture/playback, Opus, компрессора, AEC и рации; тест микрофона и динамика.
+ * loadFromDb заполняет форму, applyAndSave применяет выбранные значения. */
 #pragma once
 #include <QWidget>
 #include <QComboBox>
@@ -1,3 +1,6 @@
+/* Запись голосового сообщения: capture 48 kHz mono → очередь → worker PCM/компрессора.
+ * GUI управляет init/start/stop/shutdown; meterOnly измеряет уровень без накопления записи.
+ * takeRecording передаёт остановленные PCM/компрессор в attachment_send_req для фоновой подготовки. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,4 @@
+/* Роли модели и отрисовка ChannelList: канал/PM, последнее сообщение, unread и кнопки действий. */
 #pragma once

 #include <QStyledItemDelegate>
@@ -1,3 +1,5 @@
+/* Список каналов и PM с unread/online; загружает данные DbManager и принимает обновления bridge.
+ * Выбор и действия пользователя передаёт наружу signals; виджет используется в GUI-потоке. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Локальные настройки выбранного канала: autoplay голосовых, звук сообщений и режим PTT. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Вид истории сообщений: фон, выделение строк/текста, копирование и прокрутка вниз.
+ * MessageDelegate рисует содержимое; ChatView обрабатывает мышь и клавиатуру. */
 #pragma once

 #include <QListView>
@@ -1,3 +1,4 @@
+/* Диалог ввода имени нового канала. groupName возвращает имя для создания канала вызывающим кодом. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,4 @@
+/* Макросы логирования GUI через общий debug_config, категория GENERAL. */
 #pragma once

 extern "C" {
@@ -1,3 +1,5 @@
+/* Каталог Unicode/анимированных emoji и соответствие Unicode → ресурс анимации.
+ * detectEmojiOnly возвращает 1..3 для текста только из emoji/пробелов; иначе 0. */
 #pragma once

 #include <QString>
@@ -1,3 +1,4 @@
+/* Панель выбора emoji по категориям; выбранный Unicode передаётся в composer через emojiSelected. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Отрисовка вкладок категорий EmojiPanel с собственным стилем выбранной вкладки. */
 #pragma once

 #include <QTabBar>
@@ -1,3 +1,4 @@
+/* Отрисовка флагов участника (supernode/admin/moder/deleted) и отдельного значка storage. */
 #ifndef FLAGPAINTER_H
 #define FLAGPAINTER_H

@@ -1,3 +1,5 @@
+/* Окно просмотра локального изображения: масштаб колесом, перенос мышью и fullscreen.
+ * loadFile загружает изображение; closed сообщает владельцу о закрытии окна. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,6 @@
+/* Composer канала/PM: текст, emoji, запись голосового и выбор вложений.
+ * Контекст target фиксируется в запросе вложения; подготовку и отправку выполняет ядро.
+ * Переданный submitAttachment request должен принять и освободить обработчик сигнала. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Qt-кодек utun://: channelId/joinKey, пароль, Reality и адреса connection-узла.
+ * decodeInviteLink возвращает ошибку в InviteData.error; подключения выполняет UtunNode/chat_sync. */
 #pragma once

 #include <QString>
@@ -1,3 +1,4 @@
+/* Диалог приглашения узла по его utun:// ссылке в текущий канал; ждёт результата ядра через bridge. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Диалог выдачи invite-ссылки и QR: запрашивает кандидатов и зарегистрированную ссылку у ядра.
+ * requestId связывает асинхронный ответ с текущим запросом; URL отображается после LINK_READY. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Диалог входа в канал по utun://: проверяет ссылку, отправляет запрос ядру и ждёт CONNECT_RESULT.
+ * joined сообщает об успешном входе, а не только о создании транспорта к connection-узлу. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Обёртка rlottie для TGS: распаковывает анимацию, хранит текущий кадр и рисует QImage.
+ * Воспроизведение координирует AnimTimer; объект освобождает свой animation handle. */
 #pragma once

 #include <QImage>
@@ -1,3 +1,5 @@
+/* Главное окно desktop-чата: связывает списки, bridge-события, UtunNode, media и звонки.
+ * Координирует запуск/остановку ядра, tray и отдельные окна; UI-обработчики работают в GUI-потоке. */
 #pragma once

 #include <QMainWindow>
@@ -1,3 +1,6 @@
+/* Локальное чтение медиа из целого файла или набора блоков по localAttrs.
+ * readRange/readAll читают доступные данные; assembleAndCleanup собирает файл и удаляет фрагменты.
+ * media_split_to_blocks по умолчанию удаляет исходник после разбиения; сетевую загрузку модуль не выполняет. */
 #pragma once

 #include <QString>
@@ -1,3 +1,5 @@
+/* Qt-модель участников канала: ленивый кэш строк, обновления CHAT_EVT_MEMBER_* и RTT.
+ * События bridge применяются в GUI-потоке; данные строки доступны через Qt roles. */
 #ifndef MEMBERLISTMODEL_H
 #define MEMBERLISTMODEL_H

@@ -1,3 +1,4 @@
+/* Диалог имени и прав участника канала; сохранение подписанных изменений и передача admin-ключа через ядро. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,5 @@
+/* Роли модели сообщений и отрисовка text/voice/file/image/video, статусов и progress.
+ * Рассчитывает геометрию для ChatView и обрабатывает действия по media-элементам строки. */
 #pragma once
 #include <cstdint>

@@ -1,3 +1,5 @@
+/* История и composer выбранного канала/PM: модель сообщений, позиция чтения, загрузки и воспроизведение.
+ * Применяет события bridge в GUI-потоке; сетевые операции передаёт ядру. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,4 @@
+/* Генерация QR и распознавание штрихкодов из QImage через ZXingQt. Ошибка генерации — пустой QImage. */
 #pragma once

 #include <QImage>
@@ -1,3 +1,4 @@
+/* Локальное переименование участника: сохраняет local_nick в таблице peers канала для этого UI. */
 #pragma once

 #include <QDialog>
@@ -1,3 +1,6 @@
+/* Общий miniaudio-контекст и выход desktop-приложения: звуки событий, PCM и голосовые потоки.
+ * GUI управляет устройствами и playback-сессиями; output смешивает звук и отдаёт reference для AEC.
+ * init/shutdown ограничивают время жизни контекста; зависимые capture devices закрываются перед его сбросом. */
 #pragma once

 #include <QObject>
@@ -1,3 +1,4 @@
+/* Форма звуков уведомлений: общий enable/volume и индивидуальные настройки событий SoundManager. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* Настройки media-хранилища: автозагрузка, лимит файла и общий размер.
+ * applyAndSave сохраняет значения и передаёт их chat_setting через uasync. */
 #pragma once

 #include <QWidget>
@@ -1,3 +1,5 @@
+/* GUI-настройка preset голосовых (0 Low, 1 Standard, 2 High) и создание media-каталога.
+ * Кодирование PCM в Opus выполняет общий voice_file через attachment_send. */
 #pragma once

 #include <QString>
@@ -1,3 +1,7 @@
+/* Воспроизведение собственного Opus-файла voice_file: worker декодирует PCM, SoundManager проигрывает.
+ * Управление — в GUI-потоке; ready(duration,id) вызывается там же, 0 означает ошибку/busy.
+ * cancelPending подавляет результат, не останавливая worker; уничтожение context также подавляет callback.
+ * decodeOpusFile синхронно возвращает число кадров или -1; это отдельный API для worker. */
 #pragma once

 #include <QString>