From 8e5eda88a29fd5768999923af5aee36676c3def7 Mon Sep 17 00:00:00 2001 From: Max Ronzhin Date: Sat, 1 Aug 2026 22:06:43 +0300 Subject: [PATCH] =?UTF-8?q?feat(room):=20=D0=BF=D0=BE=D0=B4=D0=BD=D1=8F?= =?UTF-8?q?=D1=82=D0=B8=D0=B5=20=D1=80=D1=83=D0=BA=D0=B8=20=D0=B8=20=D0=BE?= =?UTF-8?q?=D1=87=D0=B5=D1=80=D0=B5=D0=B4=D1=8C=20=D0=B4=D0=BB=D1=8F=20?= =?UTF-8?q?=D0=BE=D1=80=D0=B3=D0=B0=D0=BD=D0=B8=D0=B7=D0=B0=D1=82=D0=BE?= =?UTF-8?q?=D1=80=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Транспорт — существующий аутентифицированный WS чата (api/chat.py), а не отдельный эндпоинт: сервер уже держит это соединение на каждого участника (обоснование — докстринг chat_websocket и useChat.ts). Состояние очереди — Redis (services/hand_queue.py), не Postgres: это эфемерное состояние звонка, а не история, и два процесса uvicorn делают наивную память одного процесса недостаточной. HSETNX даёт идемпотентное «поднять» (повторный клик не переставляет в конец очереди), снапшот шлётся всем участникам при любом изменении — организатор, зашедший позже, сразу видит актуальную картину. Опустить чужую руку может организатор (решение оператора) — проверка через conference.owner_id, не через identity клиента. Участник, вышедший из комнаты LiveKit (webhook participant_left), теряет место в очереди автоматически; переподключение WS чата место не сбрасывает (Redis не привязан к жизни соединения). room_finished чистит очередь целиком — она не должна пережить завершение звонка. Побочный эффект транспортного решения: поднять руку нельзя, если чат выключен настройкой инстанса (WS вообще не открывается) — принятый компромисс ради переиспользования уже готового канала. UI: кнопка «Рука» в тулбаре (у всех, бейдж — общий счётчик), бейдж на плитке говорящего (видно всем), панель «Очередь» организатору (HandQueuePanel). Кнопка «Рука» и панель «Очередь» намеренно НЕ прячутся в мобильную шторку настроек, в отличие от «Вида», — поднятие руки посреди разговора требует кнопки под рукой, а не в два клика вглубь настроек. Этим же коммитом (файлы разделяемые с задачей B2, RoomParticipantTile.tsx/ useChat.ts/RoomStage.tsx/RoomPage.tsx/room.css) — проброс conferenceId и каркас forced_mute-обработки, без которых кнопки принудительного мьюта не скомпилировались бы; сама реализация мьюта — следующим коммитом. --- backend/api/chat.py | 106 +++++-- backend/schemas/room_events.py | 61 ++++ backend/services/hand_queue.py | 144 ++++++++++ backend/services/webhook_handlers.py | 16 ++ backend/tests/test_chat_ws.py | 12 +- backend/tests/test_hand_queue_ws.py | 272 ++++++++++++++++++ backend/tests/test_livekit_webhook.py | 48 ++++ .../src/components/room/HandQueuePanel.tsx | 60 ++++ .../components/room/RoomParticipantTile.tsx | 136 ++++++++- frontend/src/components/room/RoomStage.tsx | 22 +- frontend/src/components/room/RoomToolbar.tsx | 77 ++++- frontend/src/hooks/useChat.ts | 112 +++++++- frontend/src/pages/RoomPage.tsx | 29 ++ frontend/src/styles/room.css | 114 ++++++++ 14 files changed, 1147 insertions(+), 62 deletions(-) create mode 100644 backend/schemas/room_events.py create mode 100644 backend/services/hand_queue.py create mode 100644 backend/tests/test_hand_queue_ws.py create mode 100644 frontend/src/components/room/HandQueuePanel.tsx diff --git a/backend/api/chat.py b/backend/api/chat.py index 6d4bcc9..d570ef1 100644 --- a/backend/api/chat.py +++ b/backend/api/chat.py @@ -1,10 +1,17 @@ -"""WS-роутер текстового чата конференции: `WS /api/v1/conferences/{id}/chat`. +"""WS-роутер комнаты конференции: `WS /api/v1/conferences/{id}/chat`. Протокол: `connect` -> `accept()` -> клиент шлёт `{"type":"auth","token":...}` первым сообщением (таймаут 10 с; токен не query-параметр — не палим его в логах nginx) -> сервер проверяет тоггл `chat.enabled` и LiveKit-токен -> -история последних 50 сообщений открытой сессии -> двунаправленный обмен -`{"type":"message","text":...}` через Redis pub/sub (echo отправителю тоже). +история последних 50 сообщений чата + текущая очередь поднятых рук -> +двунаправленный обмен: `{"type":"message","text":...}` (чат, Redis pub/sub, +echo отправителю тоже), `{"type":"raise_hand"}`/`{"type":"lower_hand"}` +(очередь рук, задача B1 — состояние в Redis, см. `services/hand_queue.py`, +НЕ в БД: это эфемерное состояние звонка, а не история). Название файла и +эндпоинта («чат») оставлено как есть — эндпоинт исторически первый и +единственный аутентифицированный WS комнаты, поэтому очередь рук едет по +нему же, а не заводит отдельное соединение (дешевле: сервер уже держит +это соединение на каждого участника). """ import asyncio @@ -13,7 +20,7 @@ import uuid from typing import Annotated from fastapi import APIRouter, Depends, WebSocket, WebSocketDisconnect -from pydantic import ValidationError +from pydantic import Field, TypeAdapter, ValidationError from redis.asyncio.client import PubSub from sqlalchemy.ext.asyncio import AsyncSession @@ -28,6 +35,8 @@ from schemas.chat import ( ChatMessageIn, ChatMessageOut, ) +from schemas.room_events import LowerHandIn, RaiseHandIn +from services import hand_queue from services.chat import ChatAuthError, ChatIdentity, ChatService, InvalidTokenError, chat_channel logger = logging.getLogger(__name__) @@ -37,6 +46,14 @@ router = APIRouter(prefix="/api/v1/conferences", tags=["chat"]) # Таймаут ожидания первого (auth) сообщения клиента. AUTH_TIMEOUT_SECONDS = 10.0 +# Дискриминированное объединение сообщений клиента ПОСЛЕ auth — по полю `type`. +_ClientEnvelope = Annotated[ + ChatMessageIn | RaiseHandIn | LowerHandIn, Field(discriminator="type") +] +_client_envelope_adapter: TypeAdapter[ChatMessageIn | RaiseHandIn | LowerHandIn] = TypeAdapter( + _ClientEnvelope +) + @router.websocket("/{conference_id}/chat") async def chat_websocket( @@ -44,7 +61,7 @@ async def chat_websocket( conference_id: uuid.UUID, session: Annotated[AsyncSession, Depends(get_session)], ) -> None: - """WS-эндпоинт текстового чата конференции — единая аутентификация LiveKit-токеном.""" + """WS-эндпоинт комнаты конференции — единая аутентификация LiveKit-токеном.""" await websocket.accept() service = ChatService(session) @@ -57,21 +74,26 @@ async def chat_websocket( pubsub = redis_client.pubsub() channel = chat_channel(conference.id) - # Подписка ДО чтения истории: сообщение, - # опубликованное другим клиентом в окне между SELECT истории и - # subscribe, иначе теряется для подключающегося клиента — Redis начинает + room_channel = hand_queue.hand_queue_channel(conference.id) + # Подписка ДО чтения истории/снапшота очереди: событие, + # опубликованное другим клиентом в окне между SELECT/HGETALL и subscribe, + # иначе теряется для подключающегося клиента — Redis начинает # буферизовать входящие publish для этого соединения сразу после # subscribe, до первого вызова `get_message`. На стыке возможен дубликат - # (то же сообщение и в history, и в первом pub/sub-сообщении) — безопаснее - # дедуплицировать по `id`, чем потерять сообщение. - await pubsub.subscribe(channel) + # (то же сообщение чата и в history, и в первом pub/sub-сообщении) — + # безопаснее дедуплицировать по `id`, чем потерять сообщение; снапшот + # очереди дублировать безвредно (полная замена состояния на клиенте). + await pubsub.subscribe(channel, room_channel) try: history = await service.history(conference) await websocket.send_json(ChatHistoryOut(messages=history).model_dump(mode="json")) seen_ids = {item.id for item in history} + queue_out = await hand_queue.get_snapshot_out(conference.id) + await websocket.send_json(queue_out.model_dump(mode="json")) + async with asyncio.TaskGroup() as tg: - tg.create_task(_pump_pubsub_to_websocket(websocket, pubsub, seen_ids)) + tg.create_task(_pump_pubsub_to_websocket(websocket, pubsub, channel, seen_ids)) tg.create_task(_pump_websocket_to_service(websocket, service, conference, identity)) except* WebSocketDisconnect: # Штатное закрытие соединения клиентом — не ошибка. @@ -91,7 +113,7 @@ async def chat_websocket( finally: # Всегда отписываемся и закрываем pubsub-соединение, иначе при частых # обрывах соединений копятся забытые подписки на стороне Redis. - await pubsub.unsubscribe(channel) + await pubsub.unsubscribe(channel, room_channel) # `PubSub.aclose` в redis-py не аннотирован (untyped def) несмотря на # `py.typed` пакета — узкий игнор именно этого вызова. await pubsub.aclose() # type: ignore[no-untyped-call] @@ -111,37 +133,71 @@ async def _authenticate(websocket: WebSocket, service: ChatService) -> ChatIdent async def _pump_pubsub_to_websocket( - websocket: WebSocket, pubsub: PubSub, seen_ids: set[int] + websocket: WebSocket, pubsub: PubSub, chat_channel_name: str, seen_ids: set[int] ) -> None: - """Читать сообщения Redis pub/sub канала чата и пересылать их подключённому клиенту. + """Читать оба Redis pub/sub канала комнаты (чат + очередь рук) и пересылать клиенту. - `seen_ids` — id сообщений, уже отправленных клиенту в `history` (на + `seen_ids` — id сообщений чата, уже отправленных клиенту в `history` (на стыке подписки и SELECT истории возможен дубликат, см. докстринг - `chat_websocket`) — такие сообщения не пересылаются повторно. + `chat_websocket`) — такие сообщения не пересылаются повторно. Снапшоты + очереди рук такой дедупликации не требуют (полная замена состояния). """ while True: raw = await pubsub.get_message(ignore_subscribe_messages=True, timeout=None) if raw is None: continue - message = ChatMessageOut.model_validate_json(raw["data"]) - if message.id in seen_ids: - continue - seen_ids.add(message.id) - await websocket.send_json(ChatMessageEventOut(message=message).model_dump(mode="json")) + if raw["channel"] == chat_channel_name: + message = ChatMessageOut.model_validate_json(raw["data"]) + if message.id in seen_ids: + continue + seen_ids.add(message.id) + await websocket.send_json( + ChatMessageEventOut(message=message).model_dump(mode="json") + ) + else: + # Канал комнаты (`hand_queue.hand_queue_channel`) — уже готовый + # JSON исходящего конверта (`HandQueueOut`/`ForcedMuteOut`, + # см. `services/hand_queue.py::publish_snapshot` и эндпоинт мьюта + # в `api/conferences.py`), пересылаем как есть без пересборки. + await websocket.send_text(raw["data"]) async def _pump_websocket_to_service( websocket: WebSocket, service: ChatService, conference: Conference, identity: ChatIdentity ) -> None: - """Читать текстовые сообщения клиента, валидировать и сохранять+публиковать их.""" + """Читать сообщения клиента (текст чата / поднять-опустить руку), валидировать и обработать.""" + is_organizer = conference.owner_id is not None and conference.owner_id == identity.user_id while True: raw = await websocket.receive_text() try: - envelope = ChatMessageIn.model_validate_json(raw) + envelope = _client_envelope_adapter.validate_json(raw) except ValidationError: await websocket.send_json(ChatErrorOut(code="invalid_message").model_dump(mode="json")) continue - await service.persist_and_publish(conference, identity=identity, text=envelope.text) + + if isinstance(envelope, ChatMessageIn): + await service.persist_and_publish(conference, identity=identity, text=envelope.text) + elif isinstance(envelope, RaiseHandIn): + await hand_queue.raise_hand( + conference.id, identity=_identity_key(identity), name=identity.author_name + ) + await hand_queue.publish_snapshot(conference.id) + else: + target = envelope.identity or _identity_key(identity) + if target != _identity_key(identity) and not is_organizer: + await websocket.send_json( + ChatErrorOut(code="forbidden").model_dump(mode="json") + ) + continue + await hand_queue.lower_hand(conference.id, identity=target) + await hand_queue.publish_snapshot(conference.id) + + +def _identity_key(identity: ChatIdentity) -> str: + """Identity участника в формате LiveKit/очереди рук — `str(user_id)` либо `guest:{id}`.""" + if identity.user_id is not None: + return str(identity.user_id) + return f"guest:{identity.guest_access_id}" async def _close_quietly(websocket: WebSocket, code: int) -> None: diff --git a/backend/schemas/room_events.py b/backend/schemas/room_events.py new file mode 100644 index 0000000..c8928f3 --- /dev/null +++ b/backend/schemas/room_events.py @@ -0,0 +1,61 @@ +"""Pydantic-схемы событий комнаты, мультиплексируемых поверх WS-чата (`api/chat.py`). + +Отдельный протокол от собственно чата (`schemas/chat.py`): очередь поднятых +рук и уведомления о принудительном мьюте — эфемерное состояние звонка +(Redis, не БД, см. `services/hand_queue.py`) и не должны попадать в +персистентную историю сообщений чата, хотя и едут по тому же соединению. +""" + +from datetime import UTC, datetime +from typing import Literal + +from pydantic import BaseModel, Field, field_serializer + + +class RaiseHandIn(BaseModel): + """Клиент поднимает свою руку.""" + + type: Literal["raise_hand"] + + +class LowerHandIn(BaseModel): + """Клиент опускает руку — свою (без `identity`) либо, только для организатора, чужую.""" + + type: Literal["lower_hand"] + identity: str | None = None + + +class HandQueueEntryOut(BaseModel): + """Один участник в очереди поднятых рук.""" + + identity: str + name: str + raised_at: datetime + + @field_serializer("raised_at") + def _serialize_raised_at(self, value: datetime) -> str: + return value.astimezone(UTC).isoformat().replace("+00:00", "Z") + + +class HandQueueOut(BaseModel): + """Снапшот очереди поднятых рук — рассылается всем участникам при любом изменении.""" + + type: Literal["hand_queue"] = "hand_queue" + queue: list[HandQueueEntryOut] = Field(default_factory=list) + + +ForcedMuteSource = Literal["microphone", "camera"] + + +class ForcedMuteOut(BaseModel): + """Организатор принудительно выключил трек участника (задача B2) — уведомление всем. + + Рассылается всем (не только затронутому), как и `HandQueueOut`: канал — + общий broadcast, а не адресная доставка одному соединению; получатели, + для которых `identity` не совпадает с их собственной, событие + игнорируют. + """ + + type: Literal["forced_mute"] = "forced_mute" + identity: str + source: ForcedMuteSource diff --git a/backend/services/hand_queue.py b/backend/services/hand_queue.py new file mode 100644 index 0000000..1e67ea0 --- /dev/null +++ b/backend/services/hand_queue.py @@ -0,0 +1,144 @@ +"""Очередь поднятых рук конференции — состояние в Redis, не в Postgres (задача B1). + +Транспорт для клиентов — тот же аутентифицированный WS чата (`api/chat.py`): +переиспользуем уже открытые и держащиеся сервером соединения вместо отдельного +эндпоинта. Хранение — Redis, а не БД: очередь существует ровно во время звонка +и не должна переживать его завершение (в отличие от истории чата), а два +процесса uvicorn (`UVICORN_WORKERS`) делают наивное состояние в памяти одного +процесса недостаточным — организатор и участник могут оказаться на разных +воркерах. + +Один Redis-ключ (HASH) на конференцию: поле — identity участника (тот же +формат, что в LiveKit-токене и вебхуках — `str(user_id)` или +`guest:{guest_access.id}`), значение — JSON `{"name": ..., "raised_at": }`. `HSETNX` даёт атомарное «добавить, только если ещё нет» — повторное +поднятие уже поднятой руки НЕ сбрасывает её место в очереди (идемпотентно). +Порядок — сортировкой по `raised_at` при чтении снапшота (участников в одной +конференции — единицы-десятки, сортировка в Python здесь дешевле, чем держать +вторую структуру (ZSET) синхронно с первой). +""" + +import json +import time +import uuid +from dataclasses import dataclass +from datetime import UTC, datetime + +from core.redis import redis_client +from schemas.room_events import ForcedMuteOut, ForcedMuteSource, HandQueueEntryOut, HandQueueOut + +# TTL ключа очереди — подстраховка на случай пропущенного webhook +# `room_finished` (см. `services/webhook_handlers.py::_on_room_finished`, +# который чистит очередь явно при штатном завершении). Сама конференция +# столько не длится ни при каких сценариях. +HAND_QUEUE_TTL_SECONDS = 24 * 60 * 60 + + +def hand_queue_key(conference_id: uuid.UUID) -> str: + """Redis-ключ HASH очереди поднятых рук конкретной конференции.""" + return f"hand_queue:{conference_id}" + + +def hand_queue_channel(conference_id: uuid.UUID) -> str: + """Redis pub/sub канал событий комнаты (очередь рук + принудительный мьют, задача B2).""" + return f"room_events:{conference_id}" + + +@dataclass(frozen=True, slots=True) +class HandQueueEntry: + """Один участник в очереди поднятых рук.""" + + identity: str + name: str + raised_at: float + + +async def raise_hand(conference_id: uuid.UUID, *, identity: str, name: str) -> bool: + """Поднять руку участника; `True` — рука реально поднялась (не была поднята раньше). + + `HSETNX` — атомарная проверка-и-запись: если участник уже в очереди, + ничего не меняет (в т.ч. НЕ обновляет `raised_at`) — переподключение и + повторный клик не переставляют его в конец очереди. + """ + key = hand_queue_key(conference_id) + payload = json.dumps({"name": name, "raised_at": time.time()}) + added = await redis_client.hsetnx(key, identity, payload) + await redis_client.expire(key, HAND_QUEUE_TTL_SECONDS) + return bool(added) + + +async def lower_hand(conference_id: uuid.UUID, *, identity: str) -> bool: + """Опустить руку участника; `True` — рука была поднята и теперь снята.""" + removed = await redis_client.hdel(hand_queue_key(conference_id), identity) + return bool(removed) + + +async def snapshot(conference_id: uuid.UUID) -> list[HandQueueEntry]: + """Текущая очередь, упорядоченная по времени поднятия (раньше — раньше в списке).""" + raw = await redis_client.hgetall(hand_queue_key(conference_id)) + entries = [] + for identity, payload in raw.items(): + try: + data = json.loads(payload) + entries.append( + HandQueueEntry( + identity=str(identity), name=data["name"], raised_at=data["raised_at"] + ) + ) + except (ValueError, KeyError, TypeError): + # Побитый/устаревшего формата элемент — пропускаем, а не роняем всю очередь. + continue + entries.sort(key=lambda entry: entry.raised_at) + return entries + + +async def clear(conference_id: uuid.UUID) -> None: + """Полностью снести очередь конференции (штатное завершение — `room_finished`).""" + await redis_client.delete(hand_queue_key(conference_id)) + + +def _to_out(entries: list[HandQueueEntry]) -> HandQueueOut: + """Собрать исходящий снапшот из внутренних записей очереди.""" + return HandQueueOut( + queue=[ + HandQueueEntryOut( + identity=entry.identity, + name=entry.name, + raised_at=datetime.fromtimestamp(entry.raised_at, tz=UTC), + ) + for entry in entries + ] + ) + + +async def get_snapshot_out(conference_id: uuid.UUID) -> HandQueueOut: + """Текущая очередь в исходящем формате — для отправки сразу после подключения к WS.""" + return _to_out(await snapshot(conference_id)) + + +async def publish_snapshot(conference_id: uuid.UUID) -> None: + """Опубликовать текущий снапшот очереди всем подписчикам канала комнаты. + + Вызывается после любого изменения очереди (`raise_hand`/`lower_hand` — + из `api/chat.py`, а также `participant_left`/`room_finished` — из + `services/webhook_handlers.py`), чтобы у всех участников (и особенно у + организатора, зашедшего позже) была всегда актуальная картина. + """ + payload = _to_out(await snapshot(conference_id)) + await redis_client.publish(hand_queue_channel(conference_id), payload.model_dump_json()) + + +async def publish_forced_mute( + conference_id: uuid.UUID, *, identity: str, source: ForcedMuteSource +) -> None: + """Оповестить всех участников комнаты о принудительном мьюте (задача B2). + + Тот же канал, что и у очереди рук (`hand_queue_channel`) — `api/chat.py` + пересылает с него ЛЮБОЙ JSON как есть, различая события по полю `type` + (см. `_pump_pubsub_to_websocket`). Рассылается ВСЕМ, а не адресно + затронутому участнику: канал общий на конференцию, адресной доставки + одному соединению тут нет, поэтому клиент сам сверяет `identity` со + своей (см. `ForcedMuteOut` в `schemas/room_events.py`). + """ + payload = ForcedMuteOut(identity=identity, source=source) + await redis_client.publish(hand_queue_channel(conference_id), payload.model_dump_json()) diff --git a/backend/services/webhook_handlers.py b/backend/services/webhook_handlers.py index f21ce83..1000821 100644 --- a/backend/services/webhook_handlers.py +++ b/backend/services/webhook_handlers.py @@ -27,6 +27,7 @@ from repositories.conferences import ( ConferenceRepository, ConferenceSessionRepository, ) +from services import hand_queue from services.egress import run_track_egress from services.instance_settings import InstanceSettingsService from services.pipeline_producer import enqueue_pipeline @@ -154,6 +155,17 @@ class WebhookDispatcher: return user_id, guest_id = identity + # Очередь поднятых рук живёт в Redis по `conference.id`, независимо + # от `ConferenceSession` (задача B1) — снимаем руку СРАЗУ, до guard'а + # на отсутствующий открытый сеанс ниже: пропущенный/задержанный + # `room_started` не должен оставлять фантомную запись в очереди у + # реально вышедшего участника. Не путать с обрывом WS-соединения + # самой очереди рук — то живёт своей жизнью и переживается без + # потери места (см. `services/hand_queue.py`). + removed = await hand_queue.lower_hand(conference.id, identity=event.participant.identity) + if removed: + await hand_queue.publish_snapshot(conference.id) + session_record = await self._sessions.get_open_by_conference(conference.id) if session_record is None: logger.warning( @@ -308,6 +320,10 @@ class WebhookDispatcher: now = datetime.now(UTC) await self._sessions.close(session_record, t_end=now) await self._sessions.close_all_open_participants(session_id=session_record.id, left_at=now) + # Очередь поднятых рук — состояние звонка, не история; следующий + # заход (в т.ч. у закреплённой конференции) должен начинать с чистой + # очереди, а не наследовать поднятые руки из прошлого раза. + await hand_queue.clear(conference.id) # Незакреплённая умирает по завершении (история/саммари остаются); # закреплённая возвращается в ожидание следующего вхождения (ADR-001, п.2). diff --git a/backend/tests/test_chat_ws.py b/backend/tests/test_chat_ws.py index 80fbe77..ec0b0eb 100644 --- a/backend/tests/test_chat_ws.py +++ b/backend/tests/test_chat_ws.py @@ -85,11 +85,19 @@ def _guest_token(conference: Conference, guest: GuestAccess) -> str: async def _connect_and_auth(session: ASGIWebSocketSession, token: str) -> dict[str, Any]: - """Подключиться, аутентифицироваться и вернуть первое сообщение (`history`).""" + """Подключиться, аутентифицироваться и вернуть первое сообщение (`history`). + + После `history` сервер сразу шлёт снапшот очереди поднятых рук + (`{"type":"hand_queue",...}`, задача B1) — здесь он молча вычитывается + и отбрасывается, чтобы не путать существующие тесты чата, которым он + не интересен (см. `tests/test_hand_queue_ws.py` для тестов самой очереди). + """ accept = await session.connect() assert accept["type"] == "websocket.accept" await session.send_json({"type": "auth", "token": token}) - return await session.receive_json() + history = await session.receive_json() + await session.receive_json() + return history # --- Основной сценарий: обмен сообщениями + история ------------------------- diff --git a/backend/tests/test_hand_queue_ws.py b/backend/tests/test_hand_queue_ws.py new file mode 100644 index 0000000..9487001 --- /dev/null +++ b/backend/tests/test_hand_queue_ws.py @@ -0,0 +1,272 @@ +"""Тесты очереди поднятых рук поверх WS комнаты (`WS /api/v1/conferences/{id}/chat`, задача B1). + +Протокол и аутентификация — общие с чатом (`api/chat.py`), поэтому структура +тестов и хелперы намеренно зеркалят `tests/test_chat_ws.py`. +""" + +import uuid +from collections.abc import Callable +from typing import Any + +from sqlalchemy.ext.asyncio import AsyncSession + +from core.security import hash_password +from models.conference import Conference +from models.guest import GuestAccess +from models.user import User +from services.conference_ids import generate_number, generate_slug +from services.livekit_tokens import create_room_access_token +from tests.conftest import ASGIWebSocketSession + +WSFactory = Callable[[str], ASGIWebSocketSession] + + +# --- Хелперы (см. tests/test_chat_ws.py) ------------------------------------ + + +async def _make_user(session: AsyncSession, *, name: str = "Hand Tester") -> User: + user = User( + email=f"{uuid.uuid4()}@example.com", + name_user=name, + password_hash=hash_password("password123"), + email_verified=True, + ) + session.add(user) + await session.flush() + return user + + +async def _make_conference( + session: AsyncSession, *, owner_id: uuid.UUID | None = None, status: str = "active" +) -> Conference: + conference = Conference( + number=generate_number(), + slug=generate_slug(), + title="Hand Queue Test", + status=status, + owner_id=owner_id, + ) + session.add(conference) + await session.flush() + return conference + + +async def _make_guest(session: AsyncSession, conference: Conference, *, name: str) -> GuestAccess: + guest = GuestAccess(conference_id=conference.id, display_name=name) + session.add(guest) + await session.flush() + return guest + + +def _chat_path(conference_id: uuid.UUID) -> str: + return f"/api/v1/conferences/{conference_id}/chat" + + +def _user_token(conference: Conference, user: User) -> str: + return create_room_access_token( + room_name=conference.slug, identity=str(user.id), name=user.name_user + ) + + +def _guest_token(conference: Conference, guest: GuestAccess) -> str: + return create_room_access_token( + room_name=conference.slug, identity=f"guest:{guest.id}", name=guest.display_name + ) + + +async def _connect_auth_and_queue( + session: ASGIWebSocketSession, token: str +) -> dict[str, Any]: + """Подключиться, аутентифицироваться, вычитать `history` и вернуть снапшот очереди.""" + accept = await session.connect() + assert accept["type"] == "websocket.accept" + await session.send_json({"type": "auth", "token": token}) + await session.receive_json() # history — не интересен этим тестам + return await session.receive_json() + + +def _identities(queue_frame: dict[str, Any]) -> list[str]: + return [entry["identity"] for entry in queue_frame["queue"]] + + +# --- Поднять/опустить свою руку ----------------------------------------------- + + +async def test_raise_and_lower_own_hand_broadcasts_to_everyone( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + conference = await _make_conference(db_session) + alice = await _make_user(db_session, name="Alice") + bob = await _make_user(db_session, name="Bob") + await db_session.commit() + + path = _chat_path(conference.id) + ws1 = ws_client(path) + await _connect_auth_and_queue(ws1, _user_token(conference, alice)) + ws2 = ws_client(path) + initial2 = await _connect_auth_and_queue(ws2, _user_token(conference, bob)) + assert initial2 == {"type": "hand_queue", "queue": []} + + await ws1.send_json({"type": "raise_hand"}) + + queue1 = await ws1.receive_json() + assert _identities(queue1) == [str(alice.id)] + assert queue1["queue"][0]["name"] == "Alice" + assert queue1["queue"][0]["raised_at"].endswith("Z") + + queue2 = await ws2.receive_json() + assert queue2 == queue1 + + await ws1.send_json({"type": "lower_hand"}) + queue1_after = await ws1.receive_json() + assert queue1_after == {"type": "hand_queue", "queue": []} + queue2_after = await ws2.receive_json() + assert queue2_after == queue1_after + + +async def test_raise_hand_order_is_preserved( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + """Порядок в очереди — по времени поднятия, не по алфавиту/подключению.""" + conference = await _make_conference(db_session) + alice = await _make_user(db_session, name="Alice") + bob = await _make_user(db_session, name="Bob") + await db_session.commit() + + path = _chat_path(conference.id) + ws1 = ws_client(path) + await _connect_auth_and_queue(ws1, _user_token(conference, alice)) + ws2 = ws_client(path) + await _connect_auth_and_queue(ws2, _user_token(conference, bob)) + + # Боб поднимает руку ПЕРВЫМ, хотя подключился вторым — он и должен + # оказаться первым в очереди. + await ws2.send_json({"type": "raise_hand"}) + await ws2.receive_json() + await ws1.receive_json() + + await ws1.send_json({"type": "raise_hand"}) + queue = await ws1.receive_json() + + assert _identities(queue) == [str(bob.id), str(alice.id)] + + +async def test_re_raising_hand_does_not_move_position( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + """Повторное поднятие уже поднятой руки — идемпотентно, место в очереди не меняется.""" + conference = await _make_conference(db_session) + alice = await _make_user(db_session, name="Alice") + bob = await _make_user(db_session, name="Bob") + await db_session.commit() + + path = _chat_path(conference.id) + ws1 = ws_client(path) + await _connect_auth_and_queue(ws1, _user_token(conference, alice)) + ws2 = ws_client(path) + await _connect_auth_and_queue(ws2, _user_token(conference, bob)) + + await ws1.send_json({"type": "raise_hand"}) + first = await ws1.receive_json() + await ws2.receive_json() + + await ws2.send_json({"type": "raise_hand"}) + await ws2.receive_json() + await ws1.receive_json() + + # Алиса (уже в очереди первой) поднимает руку ещё раз. + await ws1.send_json({"type": "raise_hand"}) + repeated = await ws1.receive_json() + await ws2.receive_json() + + assert _identities(repeated) == [str(alice.id), str(bob.id)] + assert repeated["queue"][0]["raised_at"] == first["queue"][0]["raised_at"] + + +async def test_guest_can_raise_hand(db_session: AsyncSession, ws_client: WSFactory) -> None: + conference = await _make_conference(db_session) + guest = await _make_guest(db_session, conference, name="Guest Carl") + await db_session.commit() + + ws = ws_client(_chat_path(conference.id)) + await _connect_auth_and_queue(ws, _guest_token(conference, guest)) + + await ws.send_json({"type": "raise_hand"}) + queue = await ws.receive_json() + assert _identities(queue) == [f"guest:{guest.id}"] + assert queue["queue"][0]["name"] == "Guest Carl" + + +# --- Права организатора ------------------------------------------------------- + + +async def test_non_organizer_cannot_lower_someone_elses_hand( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + owner = await _make_user(db_session, name="Owner") + conference = await _make_conference(db_session, owner_id=owner.id) + alice = await _make_user(db_session, name="Alice") + bob = await _make_user(db_session, name="Bob") + await db_session.commit() + + path = _chat_path(conference.id) + ws1 = ws_client(path) + await _connect_auth_and_queue(ws1, _user_token(conference, alice)) + ws2 = ws_client(path) + await _connect_auth_and_queue(ws2, _user_token(conference, bob)) + + await ws1.send_json({"type": "raise_hand"}) + await ws1.receive_json() + await ws2.receive_json() + + # Боб (обычный участник, не организатор) пытается опустить руку Алисы. + await ws2.send_json({"type": "lower_hand", "identity": str(alice.id)}) + error = await ws2.receive_json() + assert error == {"type": "error", "code": "forbidden"} + + +async def test_organizer_can_lower_someone_elses_hand( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + owner = await _make_user(db_session, name="Owner") + conference = await _make_conference(db_session, owner_id=owner.id) + alice = await _make_user(db_session, name="Alice") + await db_session.commit() + + path = _chat_path(conference.id) + ws_alice = ws_client(path) + await _connect_auth_and_queue(ws_alice, _user_token(conference, alice)) + ws_owner = ws_client(path) + await _connect_auth_and_queue(ws_owner, _user_token(conference, owner)) + + await ws_alice.send_json({"type": "raise_hand"}) + await ws_alice.receive_json() + await ws_owner.receive_json() + + await ws_owner.send_json({"type": "lower_hand", "identity": str(alice.id)}) + queue_owner = await ws_owner.receive_json() + queue_alice = await ws_alice.receive_json() + + assert queue_owner == {"type": "hand_queue", "queue": []} + assert queue_alice == queue_owner + + +async def test_organizer_joining_late_sees_already_raised_hands( + db_session: AsyncSession, ws_client: WSFactory +) -> None: + """Организатор зашёл позже, когда руки уже подняты, — видит актуальную очередь сразу.""" + owner = await _make_user(db_session, name="Owner") + conference = await _make_conference(db_session, owner_id=owner.id) + alice = await _make_user(db_session, name="Alice") + await db_session.commit() + + path = _chat_path(conference.id) + ws_alice = ws_client(path) + await _connect_auth_and_queue(ws_alice, _user_token(conference, alice)) + await ws_alice.send_json({"type": "raise_hand"}) + await ws_alice.receive_json() + + ws_owner = ws_client(path) + initial_queue = await _connect_auth_and_queue(ws_owner, _user_token(conference, owner)) + + assert _identities(initial_queue) == [str(alice.id)] diff --git a/backend/tests/test_livekit_webhook.py b/backend/tests/test_livekit_webhook.py index aee7014..89570d6 100644 --- a/backend/tests/test_livekit_webhook.py +++ b/backend/tests/test_livekit_webhook.py @@ -34,6 +34,7 @@ from models.instance_setting import InstanceSetting from models.participant import ConferenceParticipant from models.session import ConferenceSession from models.user import User +from services import hand_queue from services.conference_ids import generate_number, generate_slug from services.egress import EgressStartResult @@ -217,6 +218,53 @@ async def test_full_cycle_joined_left_finished( assert conference.ended_at is not None +async def test_participant_left_removes_raised_hand_from_queue( + client: httpx.AsyncClient, db_session: AsyncSession +) -> None: + """Задача B1: участник с поднятой рукой вышел из конференции — рука исчезает из очереди.""" + conference = await _make_conference(db_session, generate_slug()) + user = await _make_user(db_session, "webhook-hand-1@example.com") + await db_session.commit() + + identity = str(user.id) + await hand_queue.raise_hand(conference.id, identity=identity, name=user.name_user) + assert [e.identity for e in await hand_queue.snapshot(conference.id)] == [identity] + + left = _load_fixture( + "participant_left.json", + event_id=f"evt-{uuid.uuid4()}", + room_name=conference.slug, + identity=identity, + ) + resp = await _post_webhook(client, left) + assert resp.status_code == 200 + + assert await hand_queue.snapshot(conference.id) == [] + + +async def test_room_finished_clears_hand_queue( + client: httpx.AsyncClient, db_session: AsyncSession +) -> None: + """Задача B1: очередь поднятых рук — состояние звонка, не переживает его завершение.""" + conference = await _make_conference(db_session, generate_slug()) + await db_session.commit() + + started = _load_fixture( + "room_started.json", event_id=f"evt-{uuid.uuid4()}", room_name=conference.slug + ) + assert (await _post_webhook(client, started)).status_code == 200 + + await hand_queue.raise_hand(conference.id, identity="guest:leftover", name="Leftover Guest") + assert len(await hand_queue.snapshot(conference.id)) == 1 + + finished = _load_fixture( + "room_finished.json", event_id=f"evt-{uuid.uuid4()}", room_name=conference.slug + ) + assert (await _post_webhook(client, finished)).status_code == 200 + + assert await hand_queue.snapshot(conference.id) == [] + + async def test_pinned_conference_returns_to_scheduled_on_finish( client: httpx.AsyncClient, db_session: AsyncSession ) -> None: diff --git a/frontend/src/components/room/HandQueuePanel.tsx b/frontend/src/components/room/HandQueuePanel.tsx new file mode 100644 index 0000000..1fdba37 --- /dev/null +++ b/frontend/src/components/room/HandQueuePanel.tsx @@ -0,0 +1,60 @@ +import { Hand, X } from 'lucide-react' +import { useIsOrganizer } from '@/hooks/useIsOrganizer' +import type { HandQueueEntry } from '@/hooks/useChat' + +interface HandQueuePanelProps { + queue: HandQueueEntry[] + onLower: (identity: string) => void + onClose: () => void +} + +/** + * Панель очереди поднятых рук — видна только организатору (задача B1). + * Визуально — тот же боковой контейнер, что и `ChatPanel` (`.chat-panel`, + * включая мобильное поведение «во весь экран» на ≤900px), содержимое своё: + * упорядоченный список с позицией и кнопкой «Опустить» на каждой строке — + * организатору разрешено опускать чужую руку (решение оператора, задача B1). + * + * `RoomPage` гейтит рендер по `handQueueOpen` (как и `ChatPanel` по + * `chatOpen`) — свой `useIsOrganizer()` здесь ДОПОЛНИТЕЛЬНАЯ, а не + * единственная защита: `RoomToolbar` уже не показывает кнопку открытия + * не-организатору, это подстраховка на случай прямого рендера. + */ +export function HandQueuePanel({ queue, onLower, onClose }: HandQueuePanelProps) { + const isOrganizer = useIsOrganizer() + if (!isOrganizer) return null + + return ( + + ) +} diff --git a/frontend/src/components/room/RoomParticipantTile.tsx b/frontend/src/components/room/RoomParticipantTile.tsx index d08e07d..80bcb52 100644 --- a/frontend/src/components/room/RoomParticipantTile.tsx +++ b/frontend/src/components/room/RoomParticipantTile.tsx @@ -1,4 +1,4 @@ -import { Pin, PinOff, ScreenShare } from 'lucide-react' +import { Hand, Mic, Pin, PinOff, ScreenShare, Video } from 'lucide-react' import { Track } from 'livekit-client' import { AudioTrack, @@ -20,21 +20,79 @@ import { } from '@livekit/components-react' import { Avatar } from '@/components/ui/Avatar' import { stageTrackKey } from '@/components/room/stageFocus' +import { parseParticipantMetadata } from '@/lib/participantMetadata' +import { useIsOrganizer } from '@/hooks/useIsOrganizer' +import { useToast } from '@/components/ui/ToastProvider' +import { muteParticipant } from '@/api/conferences' -/** Метаданные участника из LiveKit access-токена (см. `AccessToken.with_metadata` на backend) — JSON `{"avatar_url": "..."}`; у гостей отсутствуют. */ -interface ParticipantMetadata { - avatar_url?: string | null +/** Достаёт URL аватара из метаданных участника — `null`, если поля нет (гость/без аватара). */ +function parseAvatarUrl(metadata: string | undefined): string | null { + const parsed = parseParticipantMetadata(metadata) + return typeof parsed.avatar_url === 'string' && parsed.avatar_url ? parsed.avatar_url : null } -/** Разбирает `participant.metadata` в URL аватара — `null`, если поля нет, метаданные пусты или невалидны (гость). */ -function parseAvatarUrl(metadata: string | undefined): string | null { - if (!metadata) return null - try { - const parsed = JSON.parse(metadata) as ParticipantMetadata - return typeof parsed.avatar_url === 'string' && parsed.avatar_url ? parsed.avatar_url : null - } catch { - return null +/** + * Кнопки принудительного мьюта организатором (задача B2) — микрофон/камера + * ЧУЖОГО участника. Видны только организатору (`useIsOrganizer`, подсказка + * UI — сервер перепроверяет права по владельцу конференции в БД) и только на + * чужой плитке камеры (на своей — обычный тулбарный toggle, мьютить себя + * через «принудительное» действие не нужно). + * + * Не проверяют текущее состояние мьюта заранее (усложнило бы плитку ради + * малополезной оптимизации): клик по уже выключенному треку — не ошибка, а + * no-op на backend (`muted: false` в ответе, см. `services/room_control.py`). + */ +function OrganizerMuteControls({ + conferenceId, + identity, + displayName, +}: { + conferenceId: string + identity: string + displayName: string +}) { + const toast = useToast() + + async function handleMute(source: 'microphone' | 'camera') { + try { + const result = await muteParticipant(conferenceId, identity, source) + if (!result.muted) { + toast.show( + source === 'microphone' ? 'Микрофон и так выключен' : 'Камера и так выключена', + 'info', + ) + } + } catch { + toast.show('Не удалось выключить трек участника', 'error') + } } + + return ( +
+ + +
+ ) } /** @@ -44,8 +102,15 @@ function parseAvatarUrl(metadata: string | undefined): string | null { * разметке (см. `node_modules/@livekit/components-react/src/components/participant/ParticipantTile.tsx`, * версия 2.9.23 — источник этой копии). */ -function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps) { +function TileBody({ + onStopSharing, + pinnedKey, + onTogglePin, + raisedHandIdentities, + conferenceId, +}: TileControlsProps) { const trackReference = useEnsureTrackRef() + const isOrganizer = useIsOrganizer() const isEncrypted = useIsEncrypted(trackReference.participant) const autoManageSubscription = useFeatureContext()?.autoSubscription // useParticipantInfo — реактивные name/metadata участника (переподписка на @@ -67,6 +132,18 @@ function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps) // рендерятся шаблоном без пропсов, снаружи «какая это плитка» не передать. const tileKey = stageTrackKey(trackReference) const isPinned = pinnedKey === tileKey + // Бейдж поднятой руки (задача B1) — только на плитке КАМЕРЫ участника, не + // на плитке его демонстрации экрана (рука — про человека, не про экран). + const isHandRaised = + trackReference.source === Track.Source.Camera && + Boolean(raisedHandIdentities?.has(trackReference.participant.identity)) + // Кнопки принудительного мьюта (задача B2) — организатору, только на + // чужой плитке камеры (см. докстринг `OrganizerMuteControls`). + const showOrganizerMuteControls = + isOrganizer && + Boolean(conferenceId) && + trackReference.source === Track.Source.Camera && + !trackReference.participant.isLocal return ( <> @@ -88,6 +165,11 @@ function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps)
+ {isHandRaised && ( +
+
+ )}
{trackReference.source === Track.Source.Camera ? ( @@ -141,6 +223,13 @@ function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps)
)} + {showOrganizerMuteControls && conferenceId && ( + + )} ) } @@ -166,6 +255,17 @@ interface TileControlsProps { * Не передан — кнопки-булавки на плитке нет (мини-плеер: плитка одна). */ onTogglePin?: (key: string) => void + /** + * Identity участников с поднятой рукой прямо сейчас (задача B1, из + * `useChat().handQueue`) — плитка сама решает, её ли это identity. Не + * передан — бейдж нигде не рендерится (мини-плеер). + */ + raisedHandIdentities?: Set + /** + * Id конференции (не slug/номер) — нужен для вызова эндпоинта мьюта + * (задача B2). Не передан — кнопок мьюта на плитке нет (мини-плеер). + */ + conferenceId?: string } interface RoomParticipantTileProps extends TileControlsProps { @@ -197,6 +297,8 @@ export function RoomParticipantTile({ onStopSharing, pinnedKey, onTogglePin, + raisedHandIdentities, + conferenceId, }: RoomParticipantTileProps) { return ( - + ) } diff --git a/frontend/src/components/room/RoomStage.tsx b/frontend/src/components/room/RoomStage.tsx index 1f85321..28f89b0 100644 --- a/frontend/src/components/room/RoomStage.tsx +++ b/frontend/src/components/room/RoomStage.tsx @@ -204,6 +204,8 @@ export function RoomStage({ initialFocusKey = null, onFocusKeyChange, onPinFocus, + raisedHandIdentities, + conferenceId, }: { variant?: 'full' | 'pip' /** Выбранный пользователем режим показа; игнорируется при `variant="pip"`. */ @@ -226,6 +228,10 @@ export function RoomStage({ * переключаем (см. докстринг `RoomPage`, обоснование решения в коммите). */ onPinFocus?: () => void + /** Identity участников с поднятой рукой (задача B1) — бейдж на плитке; игнорируется при `variant="pip"`. */ + raisedHandIdentities?: Set + /** Id конференции (задача B2) — кнопки принудительного мьюта на чужих плитках; игнорируется при `variant="pip"`. */ + conferenceId?: string }) { const room = useRoomContext() const isCompact = useIsCompactViewport() @@ -415,21 +421,23 @@ export function RoomStage({ const showCarousel = !hideOthers && sideTracks.length > 0 // Булавка закрепления есть на КАЖДОЙ плитке во всех режимах (задача 3.3): // сама кнопка вызывает переключение на `standard`, где закреплённый и - // попадёт в фокус (см. `handleTogglePin`/`onPinFocus`). - const pinProps = { pinnedKey, onTogglePin: handleTogglePin } + // попадёт в фокус (см. `handleTogglePin`/`onPinFocus`). Бейдж поднятой + // руки (задача B1) и кнопки принудительного мьюта (задача B2) едут тем же + // спредом — тоже нужны на КАЖДОЙ плитке. + const tileProps = { pinnedKey, onTogglePin: handleTogglePin, raisedHandIdentities, conferenceId } function renderMain(): ReactNode { if (effectiveMode === 'tiles') { return ( - + ) } if (effectiveMode === 'live-tiles') { return ( 0 ? liveCameraTracks : cameraTracks}> - + ) } @@ -438,7 +446,7 @@ export function RoomStage({ if (sideTracks.length === 0 && !hideOthers) { return ( - + ) } @@ -446,7 +454,7 @@ export function RoomStage({ // (см. её исходник), поэтому вместо неё используем свою обёртку // напрямую с тем же trackRef (аватар в фокус-плитке). return ( - focusTrack && + focusTrack && ) } @@ -470,7 +478,7 @@ export function RoomStage({ )} - +
{renderMain()} diff --git a/frontend/src/components/room/RoomToolbar.tsx b/frontend/src/components/room/RoomToolbar.tsx index 662c0dc..a6bba41 100644 --- a/frontend/src/components/room/RoomToolbar.tsx +++ b/frontend/src/components/room/RoomToolbar.tsx @@ -1,4 +1,6 @@ import { + Hand, + ListOrdered, LogOut, Maximize, MessageSquare, @@ -13,9 +15,11 @@ import { VideoOff, } from 'lucide-react' import { Track, type ScreenShareCaptureOptions } from 'livekit-client' -import { DisconnectButton, useTrackToggle } from '@livekit/components-react' +import { DisconnectButton, useLocalParticipant, useTrackToggle } from '@livekit/components-react' import { useToast } from '@/components/ui/ToastProvider' import { useIsCompactViewport } from '@/hooks/useIsCompactViewport' +import { useIsOrganizer } from '@/hooks/useIsOrganizer' +import type { HandQueueEntry } from '@/hooks/useChat' import { StageViewMenu, type StageViewProps } from '@/components/room/StageViewOptions' /** @@ -55,18 +59,35 @@ interface RoomToolbarProps extends StageViewProps { pipSupported: boolean pipActive: boolean onTogglePiP: () => void + /** + * Очередь поднятых рук целиком (задача B1, `useChat().handQueue`) — сама + * решает, поднята ли СВОЯ рука (сравнивая с `localParticipant.identity` + * через `useLocalParticipant`), и показывает бейдж общего счётчика. + */ + handQueue: HandQueueEntry[] + onRaiseHand: () => void + onLowerHand: () => void + handQueueOpen: boolean + onToggleHandQueue: () => void } /** - * Нижний тулбар комнаты: микрофон/камера/демонстрация экрана/вид сцены/ - * настройки устройств/полноэкранный режим/мини-плеер/чат/выход — собственные - * кнопки на хуках LiveKit (useTrackToggle/DisconnectButton) и панели чата, - * стилизованные по design/mockups/room.html. + * Нижний тулбар комнаты: микрофон/камера/демонстрация экрана/рука/очередь + * рук/вид сцены/настройки устройств/полноэкранный режим/мини-плеер/чат/выход — + * собственные кнопки на хуках LiveKit (useTrackToggle/DisconnectButton) и + * панели чата, стилизованные по design/mockups/room.html. * * Кнопка «Вид» (режимы показа и скрытие остальных) рендерится ТОЛЬКО на * широком экране — условным рендерингом, а не скрытием через CSS: тулбар на - * мобильном и так ужат до пяти кнопок, а те же настройки там доступны секцией - * «Вид» в шторке настроек (`DeviceSettingsDialog`). + * мобильном и так ужат до пяти «безусловных» кнопок (демонстрация/ + * полноэкранный режим/мини-плеер скрыты на узком экране через CSS, см. + * `styles/room.css`), а те же настройки там доступны секцией «Вид» в шторке + * настроек (`DeviceSettingsDialog`). «Рука» — сознательное исключение из этой + * экономии: поднять руку посреди разговора — действие со временем жизни в + * секунды, прятать его в шторку настроек означало бы делать его практически + * недоступным с телефона. «Очередь» показывается только организатору — + * встречается редко, но по той же причине оставлена в тулбаре, а не в + * шторке: организатору с телефона тоже нужно видеть очередь сразу. */ export function RoomToolbar({ chatVisible, @@ -80,6 +101,11 @@ export function RoomToolbar({ pipSupported, pipActive, onTogglePiP, + handQueue, + onRaiseHand, + onLowerHand, + handQueueOpen, + onToggleHandQueue, layoutMode, onLayoutModeChange, hideOthers, @@ -87,6 +113,9 @@ export function RoomToolbar({ }: RoomToolbarProps) { const toast = useToast() const isCompact = useIsCompactViewport() + const isOrganizer = useIsOrganizer() + const { localParticipant } = useLocalParticipant() + const handRaised = handQueue.some((entry) => entry.identity === localParticipant.identity) const mic = useTrackToggle({ source: Track.Source.Microphone }) const camera = useTrackToggle({ source: Track.Source.Camera }) const screenShare = useTrackToggle({ @@ -152,6 +181,40 @@ export function RoomToolbar({ Демонстрация + + + {isOrganizer && ( + + )} + {!isCompact && ( void + /** + * Очередь поднятых рук, упорядоченная по времени поднятия — сервер + * присылает полный снапшот при любом изменении (см. `schemas/room_events.py` + * backend), поэтому клиенту не нужно вести собственное состояние очереди. + * Пуста, пока WS не открыт/не пришёл первый снапшот. + */ + handQueue: HandQueueEntry[] + /** Поднять СВОЮ руку — повторный вызов на уже поднятой руке безвреден (идемпотентно на сервере). */ + raiseHand: () => void + /** + * Опустить руку — свою (без аргумента) либо чужую по `identity` (только + * организатору, иначе сервер отклонит `{type:"error",code:"forbidden"}`, + * см. `statusMessage`). + */ + lowerHand: (identity?: string) => void + /** Последнее событие принудительного мьюта (задача B2) — `null` до первого. */ + lastForcedMute: ForcedMuteEvent | null } /** Close-коды сервера — см. зафиксированный протокол WS. */ @@ -61,16 +112,30 @@ function buildChatWsUrl(conferenceId: string): string { } /** - * WS-клиент чата комнаты конференции. Реализует зафиксированный протокол: - * connect → `{type:"auth"}` → `{type:"history"}` → далее входящие - * `{type:"message"}`/`{type:"error"}`. + * WS-клиент комнаты конференции (несмотря на имя — не только чат, задача + * B1). Реализует зафиксированный протокол: connect → `{type:"auth"}` → + * `{type:"history"}` → `{type:"hand_queue"}` → далее входящие + * `{type:"message"}`/`{type:"hand_queue"}`/`{type:"error"}`. * - * Optimistic-append собственных сообщений НЕ делается: сервер всегда + * Очередь поднятых рук (`raiseHand`/`lowerHand`/`handQueue`) едет по тому же + * соединению, что и чат, — переиспользование уже открытого аутентифицированного + * WS дешевле отдельного эндпоинта (см. `backend/api/chat.py`). Следствие: + * поднять руку нельзя, если чат выключен настройкой инстанса (`enabled=false`, + * соединение вообще не открывается) — принятый компромисс, обоснование в + * коммите задачи B1. + * + * Optimistic-append собственных сообщений чата НЕ делается: сервер всегда * присылает наше же сообщение обратно echo-фреймом `message` — если * добавлять его на клиенте сразу при отправке, оно задублируется в списке. + * Очередь рук устроена иначе: сервер шлёт ПОЛНЫЙ снапшот на каждое + * изменение, поэтому `raiseHand`/`lowerHand` ничего не трогают в состоянии + * сами — ждут снапшот. */ export function useChat({ conferenceId, token, enabled }: UseChatOptions): UseChatResult { const [messages, setMessages] = useState([]) + const [handQueue, setHandQueue] = useState([]) + const [lastForcedMute, setLastForcedMute] = useState(null) + const forcedMuteNonceRef = useRef(0) // `wsStatus` меняется ТОЛЬКО из колбэков реального WS-соединения (см. ниже) — // никогда синхронно в теле эффекта, иначе react-hooks/set-state-in-effect // (эффект без активной подписки, только синхронизирующий производное @@ -106,6 +171,7 @@ export function useChat({ conferenceId, token, enabled }: UseChatOptions): UseCh ws.onopen = () => { if (stale) return setMessages([]) + setHandQueue([]) setStatusMessage(null) setUnavailable(false) setWsStatus('open') @@ -124,9 +190,19 @@ export function useChat({ conferenceId, token, enabled }: UseChatOptions): UseCh setMessages(frame.messages) } else if (frame.type === 'message') { setMessages((prev) => [...prev, frame.message]) + } else if (frame.type === 'hand_queue') { + setHandQueue(frame.queue) + } else if (frame.type === 'forced_mute') { + forcedMuteNonceRef.current += 1 + setLastForcedMute({ + identity: frame.identity, + source: frame.source, + nonce: forcedMuteNonceRef.current, + }) } else if (frame.type === 'error') { - // Ошибка отдельной операции (например, отклонённое сообщение) — соединение - // не рвётся, просто короткое пояснение пользователю. + // Ошибка отдельной операции (например, отклонённое сообщение или + // запрет опустить чужую руку не-организатору, code:"forbidden") — + // соединение не рвётся, просто короткое пояснение пользователю. setStatusMessage(`Ошибка чата: ${frame.code}`) } } @@ -168,10 +244,32 @@ export function useChat({ conferenceId, token, enabled }: UseChatOptions): UseCh ws.send(JSON.stringify({ type: 'message', text: trimmed })) }, []) + const raiseHand = useCallback(() => { + const ws = wsRef.current + if (!ws || ws.readyState !== WebSocket.OPEN) return + ws.send(JSON.stringify({ type: 'raise_hand' })) + }, []) + + const lowerHand = useCallback((identity?: string) => { + const ws = wsRef.current + if (!ws || ws.readyState !== WebSocket.OPEN) return + ws.send(JSON.stringify({ type: 'lower_hand', identity: identity ?? null })) + }, []) + // Наружу — производный статус: пока подключаться нечем (выключено/нет // conferenceId/token), всегда `closed`, даже если внутренний `wsStatus` // ещё хранит значение от предыдущего подключения. const status: ChatConnectionStatus = canConnect ? wsStatus : 'closed' - return { messages, status, statusMessage, unavailable, sendMessage } + return { + messages, + status, + statusMessage, + unavailable, + sendMessage, + handQueue, + raiseHand, + lowerHand, + lastForcedMute, + } } diff --git a/frontend/src/pages/RoomPage.tsx b/frontend/src/pages/RoomPage.tsx index f807a71..0f5f3a8 100644 --- a/frontend/src/pages/RoomPage.tsx +++ b/frontend/src/pages/RoomPage.tsx @@ -16,6 +16,8 @@ import { RoomTopbar } from '@/components/room/RoomTopbar' import { RoomStage } from '@/components/room/RoomStage' import { RoomToolbar } from '@/components/room/RoomToolbar' import { ChatPanel } from '@/components/room/ChatPanel' +import { HandQueuePanel } from '@/components/room/HandQueuePanel' +import { ForcedMuteWatcher } from '@/components/room/ForcedMuteWatcher' import { DeviceSettingsDialog } from '@/components/room/DeviceSettingsDialog' import { loadAudioOutputDeviceId } from '@/lib/audioOutputDevice' import { loadStageLayoutMode, saveStageLayoutMode, type StageLayoutMode } from '@/lib/stageLayoutMode' @@ -145,6 +147,18 @@ export function RoomPage() { // изначально JoinOut.chat_enabled был true (рассинхрон с админкой в моменте). const chatVisible = Boolean(joinState?.chatEnabled) && !chat.unavailable + // Панель очереди поднятых рук — открыта/закрыта организатором (задача B1). + // Саму видимость кнопки/панели решает `useIsOrganizer()` внутри + // `RoomToolbar`/`HandQueuePanel` (эти компоненты — дети `LiveKitRoom`, а + // `RoomPage` — нет, `useLocalParticipant` здесь не вызвать). + const [handQueueOpen, setHandQueueOpen] = useState(false) + // Identity участников с поднятой рукой — множеством, для дешёвого `.has()` + // на каждой плитке сцены (см. `RoomParticipantTile`). + const raisedHandIdentities = useMemo( + () => new Set(chat.handQueue.map((entry) => entry.identity)), + [chat.handQueue], + ) + // Корневой контейнер комнаты — цель для fullscreen и источник video-элемента // для video-PiP-фолбэка. const roomRootRef = useRef(null) @@ -277,6 +291,8 @@ export function RoomPage() { initialFocusKey={stageFocusKey} onFocusKeyChange={setStageFocusKey} onPinFocus={handlePinFocus} + raisedHandIdentities={raisedHandIdentities} + conferenceId={joinState.conferenceId} /> )} {chatVisible && chatOpen && ( @@ -288,6 +304,13 @@ export function RoomPage() { onClose={() => setChatOpen(false)} /> )} + {handQueueOpen && ( + chat.lowerHand(identity)} + onClose={() => setHandQueueOpen(false)} + /> + )} chat.lowerHand()} + handQueueOpen={handQueueOpen} + onToggleHandQueue={() => setHandQueueOpen((open) => !open)} layoutMode={layoutMode} onLayoutModeChange={handleLayoutModeChange} hideOthers={hideOthers} @@ -327,6 +355,7 @@ export function RoomPage() { , pip.pipWindow.document.body, )} + ) diff --git a/frontend/src/styles/room.css b/frontend/src/styles/room.css index 3e2778c..29c4198 100644 --- a/frontend/src/styles/room.css +++ b/frontend/src/styles/room.css @@ -323,6 +323,12 @@ video[data-lk-source='screen_share'] { object-fit: contain; background: #000; } .tb-btn.is-sharing span.label { color: var(--color-room-mic-on); font-weight: 700; } .tb-btn:disabled { opacity: 0.6; cursor: default; } +/* Кнопка «Рука» — та же зелёная подсветка активного состояния, что у + «Демонстрации» (задача B1): своя поднятая рука — такой же позитивный + индикатор «я сейчас что-то сигнализирую комнате». */ +.tb-btn.is-hand-raised .icon-shell { background: var(--color-room-mic-on); border-color: var(--color-room-mic-on); color: #10331f; } +.tb-btn.is-hand-raised span.label { color: var(--color-room-mic-on); font-weight: 700; } + .tb-btn.danger .icon-shell { border-color: var(--color-room-danger); color: var(--color-room-danger); background: transparent; } .tb-btn.danger:hover .icon-shell { background: var(--color-room-danger-bg); color: #fff; border-color: var(--color-room-danger-bg); } .tb-btn.danger span.label { color: var(--color-room-danger); font-weight: 700; } @@ -574,6 +580,66 @@ video[data-lk-source='screen_share'] { object-fit: contain; background: #000; } } } +/* ---------- Панель очереди поднятых рук (`HandQueuePanel`, задача B1) ---------- + * Контейнер — `.chat-panel` (та же геометрия и мобильное поведение), список + * — свой. */ +.hand-queue-list { + list-style: none; + margin: 0; + padding: var(--space-3); + display: flex; + flex-direction: column; + gap: var(--space-2); + overflow-y: auto; +} +.hand-queue-item { + display: flex; + align-items: center; + gap: 10px; + padding: 10px 12px; + border-radius: var(--radius-md); + background: var(--color-room-tile); +} +.hand-queue-position { + flex-shrink: 0; + width: 22px; + height: 22px; + border-radius: 50%; + background: var(--color-room-mic-on); + color: #10331f; + font: var(--text-caption); + font-weight: 700; + display: flex; + align-items: center; + justify-content: center; +} +.hand-queue-name { + flex: 1; + min-width: 0; + display: flex; + align-items: center; + gap: 6px; + font: var(--text-body); + color: var(--color-room-text-primary); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.hand-queue-name svg { width: 16px; height: 16px; flex-shrink: 0; color: var(--color-room-mic-on); } +.hand-queue-lower { + flex-shrink: 0; + padding: 6px 10px; + border-radius: var(--radius-md); + border: 1px solid var(--color-room-tile-border); + background: transparent; + color: var(--color-room-text-secondary); + font: var(--text-caption); + text-transform: none; + letter-spacing: normal; + cursor: pointer; +} +.hand-queue-lower:hover { background: var(--color-room-tile-hover); color: var(--color-room-text-primary); } + /* * ---------- Диалог «Настройки устройств» ---------- * Нет отдельного макета для диалога в design/mockups/room.html — собран из @@ -762,6 +828,54 @@ video[data-lk-source='screen_share'] { object-fit: contain; background: #000; } outline-offset: -2px; } +/* Бейдж поднятой руки (задача B1) — левый верхний угол, зеркально булавке + закрепления (правый верхний). В отличие от булавки ВСЕГДА видим, пока + рука поднята, — это статус для ВСЕХ участников, а не собственный + элемент управления, видимый по наведению. */ +.room-hand-badge { + position: absolute; + top: 0.25rem; + left: 0.25rem; + z-index: 5; + display: flex; + padding: 0.25rem; + border-radius: calc(var(--lk-border-radius, 0.5rem) / 2); + background: var(--color-room-mic-on); + color: #10331f; +} +.room-hand-badge svg { width: 18px; height: 18px; } + +/* Кнопки принудительного мьюта организатором (задача B2) — нижний правый + угол чужой плитки, видны по наведению (как булавка закрепления) — + элемент управления, а не статус, прятать по умолчанию уместно. */ +.room-organizer-controls { + position: absolute; + bottom: 0.25rem; + right: 0.25rem; + z-index: 5; + display: flex; + gap: 4px; + opacity: 0; + transition: opacity 0.2s ease-in-out; + transition-delay: 0.2s; +} +.lk-participant-tile:hover .room-organizer-controls, +.lk-participant-tile:focus-within .room-organizer-controls { opacity: 1; transition-delay: 0s; } +@media (hover: none) { + .room-organizer-controls { opacity: 1; transition-delay: 0s; } +} +.room-organizer-controls button { + display: flex; + padding: 0.25rem; + border: none; + border-radius: calc(var(--lk-border-radius, 0.5rem) / 2); + background: rgba(0, 0, 0, 0.5); + color: var(--color-room-text-primary); + cursor: pointer; +} +.room-organizer-controls button:hover { background: var(--color-room-danger-bg); color: #fff; } +.room-organizer-controls svg { width: 18px; height: 18px; } + /* ---------- Заглушка «конференция в мини-окне» (Document PiP) ---------- */ .room-pip-placeholder { flex: 1;