feat(room): поднятие руки и очередь для организатора

Транспорт — существующий аутентифицированный 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-обработки, без которых кнопки принудительного мьюта не
скомпилировались бы; сама реализация мьюта — следующим коммитом.

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 (
+    <aside className="chat-panel hand-queue-panel">
+      <div className="chat-head">
+        <h2>Поднятые руки</h2>
+        <button type="button" aria-label="Закрыть очередь" onClick={onClose}>
+          <X className="lucide" aria-hidden="true" />
+        </button>
+      </div>
+
+      {queue.length === 0 ? (
+        <p className="chat-empty">Пока никто не поднял руку</p>
+      ) : (
+        <ol className="hand-queue-list">
+          {queue.map((entry, index) => (
+            <li className="hand-queue-item" key={entry.identity}>
+              <span className="hand-queue-position">{index + 1}</span>
+              <span className="hand-queue-name">
+                <Hand className="lucide" aria-hidden="true" />
+                {entry.name}
+              </span>
+              <button
+                type="button"
+                className="hand-queue-lower"
+                onClick={() => onLower(entry.identity)}
+              >
+                Опустить
+              </button>
+            </li>
+          ))}
+        </ol>
+      )}
+    </aside>
+  )
+}

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 (
+    <div className="room-organizer-controls">
+      <button
+        type="button"
+        title={`Выключить микрофон: ${displayName}`}
+        aria-label={`Выключить микрофон: ${displayName}`}
+        onClick={(e) => {
+          e.stopPropagation()
+          void handleMute('microphone')
+        }}
+      >
+        <Mic aria-hidden="true" />
+      </button>
+      <button
+        type="button"
+        title={`Выключить камеру: ${displayName}`}
+        aria-label={`Выключить камеру: ${displayName}`}
+        onClick={(e) => {
+          e.stopPropagation()
+          void handleMute('camera')
+        }}
+      >
+        <Video aria-hidden="true" />
+      </button>
+    </div>
+  )
 }
 
 /**
@@ -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)
       <div className="lk-participant-placeholder">
         <Avatar name={displayName} avatarUrl={avatarUrl} className="room-tile-avatar" />
       </div>
+      {isHandRaised && (
+        <div className="room-hand-badge" title={`${displayName}: поднята рука`}>
+          <Hand className="lucide" aria-hidden="true" />
+        </div>
+      )}
       <div className="lk-participant-metadata">
         <div className="lk-participant-metadata-item">
           {trackReference.source === Track.Source.Camera ? (
@@ -141,6 +223,13 @@ function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps)
           </button>
         </div>
       )}
+      {showOrganizerMuteControls && conferenceId && (
+        <OrganizerMuteControls
+          conferenceId={conferenceId}
+          identity={trackReference.participant.identity}
+          displayName={displayName}
+        />
+      )}
     </>
   )
 }
@@ -166,6 +255,17 @@ interface TileControlsProps {
    * Не передан — кнопки-булавки на плитке нет (мини-плеер: плитка одна).
    */
   onTogglePin?: (key: string) => void
+  /**
+   * Identity участников с поднятой рукой прямо сейчас (задача B1, из
+   * `useChat().handQueue`) — плитка сама решает, её ли это identity. Не
+   * передан — бейдж нигде не рендерится (мини-плеер).
+   */
+  raisedHandIdentities?: Set<string>
+  /**
+   * Id конференции (не slug/номер) — нужен для вызова эндпоинта мьюта
+   * (задача B2). Не передан — кнопок мьюта на плитке нет (мини-плеер).
+   */
+  conferenceId?: string
 }
 
 interface RoomParticipantTileProps extends TileControlsProps {
@@ -197,6 +297,8 @@ export function RoomParticipantTile({
   onStopSharing,
   pinnedKey,
   onTogglePin,
+  raisedHandIdentities,
+  conferenceId,
 }: RoomParticipantTileProps) {
   return (
     <ParticipantTile
@@ -204,7 +306,13 @@ export function RoomParticipantTile({
       disableSpeakingIndicator={disableSpeakingIndicator}
       onParticipantClick={onParticipantClick}
     >
-      <TileBody onStopSharing={onStopSharing} pinnedKey={pinnedKey} onTogglePin={onTogglePin} />
+      <TileBody
+        onStopSharing={onStopSharing}
+        pinnedKey={pinnedKey}
+        onTogglePin={onTogglePin}
+        raisedHandIdentities={raisedHandIdentities}
+        conferenceId={conferenceId}
+      />
     </ParticipantTile>
   )
 }

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<string>
+  /** 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 (
         <StageGrid tracks={tracks}>
-          <RoomParticipantTile {...pinProps} />
+          <RoomParticipantTile {...tileProps} />
         </StageGrid>
       )
     }
     if (effectiveMode === 'live-tiles') {
       return (
         <StageGrid tracks={liveCameraTracks.length > 0 ? liveCameraTracks : cameraTracks}>
-          <RoomParticipantTile {...pinProps} />
+          <RoomParticipantTile {...tileProps} />
         </StageGrid>
       )
     }
@@ -438,7 +446,7 @@ export function RoomStage({
     if (sideTracks.length === 0 && !hideOthers) {
       return (
         <StageGrid tracks={tracks}>
-          <RoomParticipantTile {...pinProps} />
+          <RoomParticipantTile {...tileProps} />
         </StageGrid>
       )
     }
@@ -446,7 +454,7 @@ export function RoomStage({
     // (см. её исходник), поэтому вместо неё используем свою обёртку
     // напрямую с тем же trackRef (аватар в фокус-плитке).
     return (
-      focusTrack && <RoomParticipantTile trackRef={focusTrack} onStopSharing={handleStopSharing} {...pinProps} />
+      focusTrack && <RoomParticipantTile trackRef={focusTrack} onStopSharing={handleStopSharing} {...tileProps} />
     )
   }
 
@@ -470,7 +478,7 @@ export function RoomStage({
               </button>
             )}
             <CarouselLayout tracks={sideTracks}>
-              <RoomParticipantTile {...pinProps} />
+              <RoomParticipantTile {...tileProps} />
             </CarouselLayout>
           </div>
           {renderMain()}

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({
         <span className="label">Демонстрация</span>
       </button>
 
+      <button
+        type="button"
+        className={`tb-btn${handRaised ? ' is-hand-raised' : ''}`}
+        aria-pressed={handRaised}
+        aria-label={handRaised ? 'Опустить руку' : 'Поднять руку'}
+        onClick={() => (handRaised ? onLowerHand() : onRaiseHand())}
+      >
+        <span className="icon-shell">
+          <Hand className="lucide" aria-hidden="true" />
+          {handQueue.length > 0 && (
+            <span className="badge-count">{handQueue.length > 9 ? '9+' : handQueue.length}</span>
+          )}
+        </span>
+        <span className="label">Рука</span>
+      </button>
+
+      {isOrganizer && (
+        <button
+          type="button"
+          className={`tb-btn${handQueueOpen ? ' is-panel-open' : ''}`}
+          aria-pressed={handQueueOpen}
+          aria-label={handQueueOpen ? 'Свернуть очередь поднятых рук' : 'Открыть очередь поднятых рук'}
+          onClick={onToggleHandQueue}
+        >
+          <span className="icon-shell">
+            <ListOrdered className="lucide" aria-hidden="true" />
+            {handQueue.length > 0 && (
+              <span className="badge-count">{handQueue.length > 9 ? '9+' : handQueue.length}</span>
+            )}
+          </span>
+          <span className="label">Очередь</span>
+        </button>
+      )}
+
       {!isCompact && (
         <StageViewMenu
           layoutMode={layoutMode}