# Что добавить в API для доведения чата до «как в Telegram»

Клиент уже подстраивается под текущие типы (`ShmChannelMessageType`, `ShmChannelType`, `MemberORUType`). Ниже — поля и эндпоинты, которых не хватает для полноценного совпадения с Telegram по данным (без костылей в UI).

---

## 1. Имена и аватары участников

**Сейчас:** у `MemberORUType` есть `owner`, `role`, `uuid` и т.д., но нет отображаемого имени и ссылки на фото.

**Нужно в API:**

- В ответах `channelInfo`, `channelList`, `joinChannelList` (и в extensions к сообщениям, если удобнее) для каждого `members[]`:
  - `displayName` (string) — имя для шапки чата, reply-превью, строки имени над сообщением в группе;
  - опционально `avatarUrl` (string) или `avatar` (id файла), если аватар не вычисляется только из `owner`.

**Зачем:** убрать плейсхолдеры «Собеседник» / emoji из id и показывать реальные имена в reply и в групповых чатах.

---

## 2. Статус присутствия («в сети», «был(а) …»)

**Сейчас:** в шапке чата показывается заглушка «был(а) недавно» без опоры на сервер.

**Нужно в API:**

- В `channelInfo` (или отдельный `channelPresence` / подписка):
  - для собеседника (или для каждого `member` в группе): `online: boolean`;
  - `lastSeenAt: number` (unix) — когда был в сети последний раз.

**Зачем:** текст как в Telegram («в сети», «был(а) в 14:32», «был(а) недавно») считается на клиенте из этих полей.

---

## 3. Индикатор «печатает…»

**Сейчас:** нет события набора текста.

**Нужно в API:**

- Эндпоинт вида `channelTyping` с телом `{ channel, typing: boolean }` (или heartbeat раз в N секунд пока пользователь печатает).
- Доставка другим участникам через:
  - WebSocket / SSE / long-poll с событием `typing: { channel, userId, until?: number }`,  
  **или**
  - расширение существующего hash-поллинга невозможно без частых запросов — для «как в TG» лучше push-канал.

**Зачем:** подпись «печатает…» под заголовком чата без лагов.

---

## 4. Состояния доставки исходящих (как две галочки в Telegram)

**Сейчас:** у сообщения есть `viewed` (прочитано). Нет явного «доставлено на устройства собеседника».

**Нужно в API (минимум одно из):**

- Расширить `ShmChannelMessageType`:
  - `deliveredAt?: number` (unix) — сообщение доставлено хотя бы одному получателю;  
  **или**
  - `deliveryState: 'sent' | 'delivered' | 'read'` + при необходимости детализация по участникам в группах.

**Зачем:** на клиенте рисовать одну галочку / две серые / две цветные как в Telegram, а не угадывать по одному `viewed`.

---

## 5. Подтверждение отправки и id сообщения

**Сейчас:** клиент делает optimistic UI и потом подтягивает список через `channelMessages`; ответ `channelSendMessage` типизирован как `ShmChannelMessageType | null`.

**Нужно в API:**

- Гарантировать, что `channelSendMessage` **всегда** возвращает созданное сообщение с финальным `_id` и `created_at` (и при желании сразу `deliveryState` / `viewed`).

**Зачем:** можно мгновенно заменить optimistic-сообщение на серверное без гонки с поллингом и без дубля в ленте.

---

## 6. История и пагинация (прокрутка вверх)

**Сейчас:** запрос `channelMessages` с `limit: 50, offset: 0` — только «последняя страница».

**Нужно в API:**

- Поддержка `beforeMessageId` / `beforeCreatedAt` + `limit` для подгрузки старых сообщений при скролле вверх (курсорная пагинация предпочтительнее offset для больших чатов).

**Зачем:** поведение как в Telegram при длинной истории без перезагрузки всего списка.

---

## 7. Реальное время вместо только polling

**Сейчас:** клиент опрашивает hash и при изменении тянет полный список.

**Нужно в API:**

- WebSocket (или SSE) канал `channel:{id}` с событиями:
  - `message.new`, `message.updated`, `message.deleted`;
  - `reactions.updated`;
  - `pinned.updated`;
  - опционально `typing`, `presence`.

**Зачем:** мгновенные входящие/исходящие без задержки поллинга и без лишней нагрузки на `channelMessages` каждые N секунд.

---

## 8. Метаданные голосового сообщения

**Сейчас:** `FileAudioFileType` может содержать `duration` — на клиенте waveform всё ещё синтетическая.

**Нужно в API (опционально):**

- Либо отдавать `waveform: number[]` (нормализованные амплитуды) после обработки на сервере,
- либо URL на превью-спектр — как удобнее бэкенду.

**Зачем:** визуально как waveform в Telegram без случайных баров.

---

## 9. Непрочитанные и «прочитано до»

**Сейчас:** в `ShmChannelType` есть `unreadCounts` по пользователю — хорошо для бейджа в списке чатов.

**Нужно уточнить/добавить в API:**

- Эндпоинт `channelMarkRead` с `{ channel, lastReadMessageId }` (или до `created_at`), чтобы сервер обновлял счётчики и `viewed` у исходящих сообщений собеседника.

**Зачем:** корректные галочки «прочитано» у собеседника и сброс unread при открытии чата.

---

## 10. Редактирование и ответы (если нужны как в TG)

**По желанию продукт:**

- `message.edit` с версией / `editedAt`;
- в сообщении поле `edited?: boolean` для подписи «изменено».

**Зачем:** полное совпадение с привычками Telegram; сейчас в типах этого нет.

---

## Приоритет (кратко)

| Приоритет | Что |
|-----------|-----|
| Высокий | Имена участников (`displayName`), стабильный ответ `channelSendMessage` с полным сообщением |
| Высокий | `delivered` / `read` раздельно или `deliveryState` |
| Средний | `lastSeen` / `online`, mark-read |
| Средний | Real-time (WS/SSE) или хотя бы typing + presence через тот же канал |
| Низкий | Пагинация истории вверх, waveform, редактирование |

После появления полей в API клиентские типы в `src/api/types.ts` нужно синхронизировать с codegen/бэкендом и заменить плейсхолдеры в UI на реальные данные.
