QMAX/тз.md

# ТЗ: мессенджер в стиле Икар

## Назначение документа

Этот документ является техническим заданием для нейросети или команды разработки, которой нужно создать полноценный мессенджер, функционально и визуально близкий к проекту Икар.

Цель: получить современный мобильный мессенджер с серверной частью, Android-клиентом, real-time сообщениями, медиа-вложениями, звонками, сторис, ботами, каналами, группами, push-уведомлениями, настройками приватности, админкой и механизмом обновления приложения.

Документ нужно читать как product + engineering brief. Если какие-то детали не указаны явно, нужно выбирать решения, близкие к Telegram-подобному пользовательскому опыту: быстрый чат, аккуратные пузырьки, плотная мобильная навигация, удобные вложения, плавная работа с медиа и надежная доставка сообщений.

## Рабочее название

Икар.

## Ключевая идея

Икар - это самостоятельный мессенджер с мобильным Android-клиентом и собственным сервером. Он должен поддерживать личные чаты, группы, каналы, медиа, звонки, сторис, ботов и обновления клиента через собственный каталог релизов.

Пользователь должен воспринимать приложение как быстрый, легкий и приватный мессенджер:

- открыл приложение;
- увидел список чатов;
- вошел в чат;
- написал текст;
- отправил фото, видео, файл или голосовое;
- получил push;
- открыл фото на весь экран;
- позвонил;
- настроил приватность;
- обновил приложение через встроенный механизм.

## Платформы

Минимальный обязательный состав:

- Backend: ASP.NET Core Web API.
- Realtime: SignalR или аналогичный WebSocket transport.
- Android client: Kotlin + Jetpack Compose.
- Storage: локальное файловое хранилище на сервере для вложений и аватаров.
- Database: реляционная БД через ORM, желательно Entity Framework Core или аналог.
- Push: Firebase Cloud Messaging.
- Admin UI: веб-админка, доступная через сервер.
- Distribution: публикация Android APK через каталог обновлений Argus-like.

Дополнительно допустимо:

- Docker-окружение для сервера.
- Отдельный shared-модуль с контрактами API.
- Локальный кэш сообщений и вложений на Android.

## Главные пользовательские сценарии

### Регистрация и вход

Пользователь должен иметь возможность:

- зарегистрироваться по номеру телефона;
- войти по номеру телефона через одноразовый код;
- войти или подтвердить аккаунт через email-код;
- получить JWT/access token;
- восстановить сессию после перезапуска приложения;
- выйти из аккаунта;
- видеть список активных устройств;
- завершать сессии на других устройствах.

В dev/smoke окружении можно использовать тестовые коды, но в production нужно иметь реальную отправку SMS/email или подключаемые провайдеры.

### Профиль пользователя

Пользователь должен иметь:

- display name;
- username или публичный идентификатор, если нужен;
- avatar;
- about/status;
- настройки приватности;
- настройки уведомлений;
- настройки интерфейса чатов.

Нужно поддерживать загрузку аватара с Android-клиента, хранение на сервере и отдачу с авторизацией.

### Список чатов

Главный экран после авторизации - список чатов.

В списке чатов должны отображаться:

- аватар чата или пользователя;
- название;
- последний текст или превью вложения;
- дата/время последнего сообщения;
- бейдж непрочитанных;
- индикатор pinned/muted/archived, если реализовано;
- превью фото для последнего медиа-сообщения;
- статус онлайн для личных чатов.

Список должен обновляться в real-time при новых сообщениях.

### Личные чаты

Пользователь должен иметь возможность:

- создать личный чат с другим пользователем;
- отправлять текст;
- отправлять вложения;
- отвечать на сообщение;
- пересылать сообщение;
- копировать текст;
- удалять сообщение;
- редактировать свое сообщение;
- ставить реакции;
- искать по сообщениям;
- видеть статус доставки.

Статусы доставки:

- sending;
- sent;
- delivered;
- read;
- failed.

### Группы

Групповой чат должен поддерживать:

- создание группы;
- добавление участников;
- удаление участников;
- роли участников;
- права отправки сообщений;
- название и аватар группы;
- список участников;
- уведомления;
- поиск;
- media/materials view.

Минимальные роли:

- owner;
- admin;
- member.

### Каналы

Каналы должны отличаться от групп:

- подписчики читают публикации;
- писать могут только владелец/админы;
- у публикаций могут быть просмотры;
- у публикаций могут быть комментарии через discussion group;
- канал может иметь invite link;
- канал может быть публичным или приватным.

Для каналов нужны:

- создание канала;
- управление участниками/подписчиками;
- публикация постов;
- пересылка постов;
- счетчик просмотров;
- переход в обсуждение.

### Сообщения

Сообщение должно поддерживать:

- id;
- chatId;
- sender;
- text;
- sentAt;
- editedAt;
- deletedAt;
- replyTo;
- forwardedFrom;
- attachments;
- reactions;
- deliveryState;
- hasProtectedContent;
- viewCount для каналов;
- discussionMessageId для каналов;
- mediaAlbumId для альбомов.

Текст должен поддерживать:

- переносы строк;
- ссылки;
- inline preview для ссылок на изображения;
- spoiler-style разметку, если реализуется;
- большие emoji-сообщения, если сообщение состоит только из 1-3 emoji.

### Вложения

Нужно поддерживать вложения:

- изображения: jpg, jpeg, png, webp, gif, bmp, heic, heif;
- видео: mp4, mov, webm, mkv и похожие;
- аудио;
- голосовые сообщения;
- документы/файлы;
- встроенные GIF;
- стикеры.

Ограничение размера по умолчанию: 25 MB на файл, если не задано другое.

У вложения должны быть:

- id;
- fileName;
- contentType;
- fileSizeBytes;
- downloadPath;
- kind;
- sortOrder.

Типы kind:

- File;
- VoiceNote;
- Image;
- Video;
- Sticker;
- Gif.

Если backend не хранит kind явно для всех типов, клиент должен уметь определять тип по contentType и расширению файла.

### Отправка фото

Отправка фото должна работать надежно.

Требования:

- пользователь выбирает фото через системный picker;
- фото копируется во временный локальный файл приложения;
- приложение отображает preview перед отправкой;
- при отправке файл передается на сервер multipart/form-data;
- сервер сохраняет оригинал;
- сервер возвращает сообщение с attachment metadata;
- получатели видят фото в чате без перезапуска;
- при нажатии фото открывается полноэкранный просмотр.

Важное визуальное требование:

- одиночное фото в чате должно отображаться как media-сообщение без обычного белого текстового пузыря;
- не должно быть широких белых полей вокруг фото;
- preview в чате должно сохранять корректное соотношение сторон;
- если изображение очень широкое или очень высокое, нужно ограничивать максимальную высоту, но не показывать белую пустую область как часть сообщения;
- фон загрузки не должен выглядеть как белый прямоугольник;
- если файл еще не докачан, нельзя показывать частично скачанный JPEG как готовое изображение.

Техническое требование для кэша:

- вложения скачивать сначала во временный файл, например `filename.part`;
- после полной загрузки и проверки размера атомарно переносить во финальный cache-файл;
- UI должен считать cache-файл готовым только если он существует, не пустой и, если известен ожидаемый размер, совпадает с `fileSizeBytes`;
- при несовпадении размера старый cache-файл нужно игнорировать или перекачивать;
- image loader не должен кэшировать частично скачанные изображения.

### Фотоальбомы

Если пользователь отправляет несколько изображений/видео одновременно:

- файлы должны отправляться одним album-сообщением, если все вложения являются media;
- у всех вложений должен быть общий mediaAlbumId;
- в чате нужно показывать collage/grid;
- порядок должен соответствовать выбору пользователя;
- при нажатии открывается просмотрщик с навигацией по фото альбома.

### Просмотр фото

Фото-просмотрщик должен:

- открываться на весь экран;
- иметь черный фон;
- показывать фото целиком через ContentScale/Fit;
- поддерживать pinch-to-zoom;
- поддерживать drag при увеличении;
- иметь кнопку закрытия/назад;
- иметь имя отправителя и время;
- поддерживать переход к предыдущему/следующему фото в контексте чата или альбома;
- иметь меню: сохранить, поделиться, открыть внешне, если разрешено.

### Видео

Видео-сообщение должно:

- отображаться карточкой с preview/play;
- открываться в full-screen player;
- проигрываться через Media3/ExoPlayer или аналог;
- поддерживать авторизованные URL;
- иметь play/pause;
- иметь закрытие назад.

### Голосовые сообщения

Нужно поддерживать:

- запись голосового;
- таймер записи;
- отмену записи;
- отправку как attachment kind VoiceNote;
- воспроизведение в чате;
- progress bar;
- stop/play;
- паузу внешней музыки при записи или воспроизведении, если настройка включена.

### Реакции

Сообщения должны поддерживать реакции:

- пользователь может поставить emoji-реакцию;
- повторное нажатие может убрать или сменить реакцию;
- счетчики реакций обновляются real-time;
- реакции отображаются компактно под сообщением.

### Ответы, пересылка, редактирование, удаление

Нужно реализовать:

- reply preview над composer;
- reply preview внутри сообщения;
- переход к исходному сообщению по tap на reply;
- edit mode для своих сообщений;
- delete для себя или для всех, если разрешено;
- forward flow с выбором чата;
- protected content: если сообщение защищено, запретить копирование/пересылку/сохранение.

### Поиск

Нужен глобальный поиск:

- по пользователям;
- по чатам;
- по сообщениям;
- по вложениям;
- по медиа;
- по файлам.

Нужен поиск внутри чата:

- строка поиска в header;
- подсветка результатов;
- навигация вверх/вниз по результатам;
- загрузка старых сообщений при необходимости.



### Уведомления

Push-уведомления должны приходить для:

- новых сообщений;
- входящих звонков;
- важных системных событий.

Требования:

- Firebase token registration;
- настройка звука;
- mute per chat;
- глобальное включение/выключение preview;
- не показывать уведомление, если пользователь уже находится в активном чате;
- действия в уведомлении: открыть чат, принять/отклонить звонок.

### Приватность и безопасность

Нужно реализовать:

- JWT auth;
- авторизацию на всех API;
- проверку членства в чате перед доступом к сообщениям и вложениям;
- запрет скачивания вложений неучастниками;
- privacy settings;
- protected content;
- secure window option на Android;
- rate limiting на API;
- удаление пользователя админом;
- удаление чата и файлов;
- server-side validation для всех upload.

Настройки приватности:

- кто видит номер телефона;
- кто видит avatar;
- кто видит online;
- кто может звонить;
- кто может добавлять в группы;
- показывать или скрывать message preview.

### Настройки приложения

Нужны настройки:

- язык/локаль;
- тема/цвета, если реализуется;
- размер текста сообщений;
- радиус пузырьков;
- обои чата;
- layout списка чатов;
- автоскачивание фото;
- автоскачивание видео по Wi-Fi;
- автоскачивание файлов по Wi-Fi;
- сохранять медиа в галерею;
- защищенный экран;
- push settings;
- настройки звонков.

### Кэш и offline

Android-клиент должен:

- кэшировать последние сообщения;
- показывать кэш при старте;
- хранить scroll position;
- хранить draft text;
- кэшировать скачанные вложения;
- иметь политику очистки кэша;
- поддерживать очередь upload/download через WorkManager;
- показывать прогресс больших передач;
- повторять неудачные передачи.

### Архитектура Android-клиента

Рекомендуемый стек:

- Kotlin;
- Jetpack Compose;
- Material 3;
- Navigation Compose;
- ViewModel;
- StateFlow;
- Room для локального кэша;
- DataStore для настроек;
- OkHttp для API;
- Kotlin serialization;
- SignalR client для realtime;
- Coil для изображений;
- Media3 для видео;
- WorkManager для фоновых upload/download;
- Firebase Messaging.

Структура клиента:

- `app` - dependency container, app bootstrap;
- `core/network` - ApiClient, ServerConfig;
- `core/model` - DTO/model classes;
- `core/realtime` - realtime service;
- `core/local` - Room entities/DAO/cache;
- `core/settings` - DataStore settings;
- `core/push` - Firebase/push;
- `feature/login`;
- `feature/chats`;
- `feature/chat`;
- `feature/profile`;
- `feature/settings`;
- `feature/stories`;
- `feature/call`;
- `feature/bots`;
- `feature/search`;
- `feature/forward`;
- `feature/chatinfo`;
- `feature/transfer`.

### Архитектура backend

Рекомендуемый стек:

- ASP.NET Core;
- Controllers для REST API;
- SignalR Hub для realtime;
- EF Core;
- JWT Bearer auth;
- SQLite/PostgreSQL;
- hosted services для фоновых задач;
- local file storage для uploads;
- Dockerfile.

Структура backend:

- `Controllers/AuthController`;
- `Controllers/UsersController`;
- `Controllers/ChatsController`;
- `Controllers/StoriesController`;
- `Controllers/BotsController`;
- `Controllers/BotApiController`;
- `Controllers/PushController`;
- `Controllers/AppUpdatesController`;
- `Controllers/AdminController`;
- `Infrastructure/Hubs/MessengerHub`;
- `Infrastructure/Storage/AttachmentStorageService`;
- `Infrastructure/Storage/AvatarStorageService`;
- `Infrastructure/Auth/TokenService`;
- `Infrastructure/Push`;
- `Infrastructure/Calls`;
- `Infrastructure/Bots`;
- `Infrastructure/Admin`;
- `Data/IkarDbContext`;
- `Data/Entities`.

### Основные backend entities

Нужно спроектировать сущности:

- User;
- UserSession;
- Chat;
- ChatMember;
- Message;
- MessageAttachment;
- MessageReaction;
- MessageReadReceipt;
- ChatInviteLink;
- ChatTopic;
- Story;
- StoryAttachment;
- Bot;
- BotCommand;
- BotUpdate;
- PushDevice;
- CallSession;
- Admin/moderation logs.

### REST API

Минимальные API группы:

#### Auth

- `POST /api/auth/phone/request-code`;
- `POST /api/auth/phone/verify`;
- `POST /api/auth/email/request-code`;
- `POST /api/auth/email/verify`;
- `POST /api/auth/refresh`;
- `POST /api/auth/logout`;
- `GET /api/auth/sessions`;
- `DELETE /api/auth/sessions/{id}`.

#### Users

- `GET /api/users/me`;
- `PUT /api/users/me`;
- `POST /api/users/me/avatar`;
- `GET /api/users/{id}`;
- `GET /api/users/search?q=...`;
- `GET /api/users/{id}/avatar`.

#### Chats

- `GET /api/chats`;
- `POST /api/chats/direct`;
- `POST /api/chats/groups`;
- `POST /api/chats/channels`;
- `GET /api/chats/{chatId}`;
- `PUT /api/chats/{chatId}`;
- `DELETE /api/chats/{chatId}`;
- `GET /api/chats/{chatId}/messages`;
- `POST /api/chats/{chatId}/messages`;
- `PUT /api/chats/{chatId}/messages/{messageId}`;
- `DELETE /api/chats/{chatId}/messages/{messageId}`;
- `POST /api/chats/{chatId}/messages/{messageId}/reactions`;
- `POST /api/chats/{chatId}/attachments`;
- `POST /api/chats/{chatId}/attachments/album`;
- `GET /api/chats/{chatId}/attachments/{attachmentId}/content`;
- `POST /api/chats/{chatId}/members`;
- `DELETE /api/chats/{chatId}/members/{userId}`;
- `GET /api/chats/{chatId}/search`.



#### Push

- `POST /api/push/devices`;
- `DELETE /api/push/devices/{id}`;
- `PUT /api/push/settings`.



#### Admin

- `GET /admin/api/status`;
- `GET /admin/api/users`;
- `GET /admin/api/chats`;
- `GET /admin/api/messages`;
- `GET /admin/api/attachments`;
- `GET /admin/api/attachments/{id}/content`;
- `DELETE /admin/api/attachments/{id}`;
- `DELETE /admin/api/users/{id}`;
- `DELETE /admin/api/chats/{id}`.

### Realtime hub

Realtime должен поддерживать:

- подключение авторизованного пользователя;
- join/leave chat groups;
- отправку нового сообщения всем участникам;
- обновление сообщения;
- удаление сообщения;
- reaction update;
- typing indicator;
- read receipts;
- online/presence;
- call signaling;
- story changed notification;
- chat list invalidation.

Пример событий:

- `MessageCreated`;
- `MessageUpdated`;
- `MessageDeleted`;
- `ReactionUpdated`;
- `TypingChanged`;
- `ChatUpdated`;
- `UserPresenceChanged`;
- `IncomingCall`;
- `CallAccepted`;
- `CallDeclined`;
- `CallEnded`;
- `WebRtcOffer`;
- `WebRtcAnswer`;
- `IceCandidate`;
- `StoriesChanged`.

### UI/UX стиль

Общее направление:

- Telegram-like;
- чистый светлый интерфейс;
- быстрые списки;
- минимум декоративности;
- акцентный голубой цвет;
- аккуратные rounded shapes;
- сообщения компактные;
- медиа без лишних рамок;
- настройки плотные и понятные;
- нижняя composer-панель всегда удобная.

Цвета можно использовать примерно такие:

- accent blue: `#3390EC`;
- text dark: `#17212B`;
- muted text: `#6C7883`;
- incoming bubble: `#FFFFFF`;
- outgoing bubble: `#E7F7C8`;
- app background: `#F3F7FA`;
- media placeholder: лучше прозрачный или нейтральный, но не белый прямоугольник вокруг фото.

### Экран чата

Экран чата должен включать:

- header с back, avatar, title, subtitle/online, menu;
- список сообщений;
- date separators;
- pinned message banner;
- search mode;
- selection mode;
- reply/edit panel;
- composer;
- attach button;
- emoji/GIF/sticker picker;
- voice record button;
- send button;
- scroll-to-bottom button;
- active transfer cards;
- call banner.

Поведение:

- новые сообщения добавляются снизу;
- автоскролл вниз, если пользователь уже внизу;
- если пользователь выше по истории, показывать кнопку вниз;
- свайп сообщения влево/вправо для reply;
- long press для selection/context actions;
- double tap для reaction, если реализуется.

### Composer

Composer должен поддерживать:

- многострочный ввод;
- attach picker;
- отправку текста;
- отправку вложений;
- preview выбранного файла;
- preview альбома;
- remove attachment;
- reply state;
- edit state;
- emoji/sticker/GIF panel;
- voice recording.

### Встроенный image loader

Для авторизованных картинок:

- использовать access token в Authorization header;
- иметь disk/memory cache key, зависящий от URL и token;
- поддерживать callback успешной загрузки, чтобы UI мог узнать intrinsic size;
- не показывать частично скачанный файл;
- для full-screen использовать fit;
- для chat preview использовать crop только когда aspect ratio контейнера отличается от изображения.

### Admin panel

Admin UI должен быть web-страницей внутри сервера.

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

- dashboard server status;
- список пользователей;
- список чатов;
- список сообщений;
- список вложений;
- скачивание вложения;
- удаление вложения;
- удаление пользователя;
- удаление чата;
- фильтры и поиск;
- отображение размера файлов и количества записей.

### Обновления приложения

Нужен механизм обновления Android-клиента:

- сервер или отдельный catalog endpoint отдает manifest;
- приложение проверяет latest release;
- сравнивает versionName/versionCode;
- скачивает APK;
- проверяет SHA-256;
- запускает Android package installer;
- записывает установленную версию только после успешной установки.

Manifest должен содержать:

- slug;
- name;
- version;
- androidVersionCode;
- channel;
- platform;
- packageKind;
- downloadPath;
- packageSizeBytes;
- sha256;
- notes;
- publishedAt.

Важно:

- все APK-обновления должны быть подписаны одним и тем же release/upload key;
- нельзя публиковать APK с новым случайным ключом поверх уже установленного приложения.

### Хранение файлов

Сервер должен:

- сохранять вложения в отдельную директорию;
- генерировать безопасные имена файлов;
- хранить оригинальное имя отдельно;
- не доверять client filename;
- определять content type по заголовку и расширению;
- удалять физический файл при удалении attachment/message/chat/user;
- запрещать path traversal;
- отдавать файл только авторизованным участникам чата.

### Docker и deployment

Нужно подготовить:

- `Dockerfile.server`;
- docker-compose для сервера и БД, если нужно;
- appsettings для production/development;
- переменные окружения для JWT, storage path, admin password, SMTP, Firebase;
- scripts для smoke tests;
- scripts для публикации Android APK.

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

Обязательные тесты backend:

- auth flow;
- create direct chat;
- send message;
- upload attachment;
- download attachment access control;
- group member permissions;
- channel post permissions;
- reactions;
- stories visibility;
- bot sendMessage/sendPhoto;
- admin delete user/chat/attachment;
- push dispatcher.

Обязательные проверки Android:

- compileDebugKotlin;
- assembleRelease;
- отправка текста;
- отправка фото;
- фото в чате без белого прямоугольника;
- full-screen preview открывает полное фото;
- получатель видит фото без частичного JPEG;
- отправка альбома;
- voice note;
- video preview/player;
- push notification;
- login/session restore.

### Критерии приемки MVP

MVP считается готовым, если:

- пользователь может зарегистрироваться/войти;
- видит список чатов;
- может создать личный чат;
- может отправить и получить текст в real-time;
- может отправить фото;
- фото отображается в чате без белого пузыря и без поломанного partial preview;
- фото открывается на весь экран;
- можно отправить файл;
- можно отправить voice note;
- есть push для новых сообщений;
- есть локальный кэш сообщений;
- backend проверяет права доступа;
- Android APK собирается release-сборкой;
- APK обновляется через manifest/catalog.

### Критерии приемки полной версии

Полная версия считается готовой, если дополнительно есть:

- группы;
- каналы;
- обсуждения каналов;
- сторис;
- аудио/видео звонки;
- боты;
- глобальный поиск;
- админка;
- настройки приватности;
- настройки чатов;
- media gallery/materials;
- transfer queue;
- Argus-like publication flow;
- smoke tests;
- базовая документация для запуска.

## Особые требования к качеству

- Приложение должно ощущаться быстрым.
- Все сетевые ошибки должны иметь понятное сообщение.
- Нельзя блокировать UI во время upload/download.
- Нельзя показывать недокачанный файл как готовый.
- Нельзя терять draft при повороте/перезапуске.
- Нельзя отдавать вложения неучастникам чата.
- Нельзя публиковать Android update с другим signing certificate.
- Нужно очищать временные файлы.
- Нужно избегать больших белых полей вокруг медиа.
- Нужно хранить секреты только в env/local ignored files.

## Подсказка для нейросети-разработчика

Если ты создаешь проект по этому ТЗ, сначала сгенерируй архитектуру и каркас:

1. Backend API + database entities.
2. Android app shell + auth/session.
3. Chat list + chat screen.
4. Realtime messages.
5. Attachments upload/download.
6. Correct image rendering and cache safety.
7. Push notifications.
8. Groups/channels/stories/calls/bots.
9. Admin panel.
10. Release/update flow.

Не начинай с лендинга. Первый экран приложения после входа - список чатов. Если пользователь не авторизован - экран входа.

Главный UX-ориентир: это должен быть рабочий мессенджер, а не демонстрационная страница.