# 语音房间功能设计

## 概述

在组队功能中加入实时语音通话，基于 LiveKit（开源 WebRTC SFU），独立语音房间页面。

## 架构

```
Vue 前端 (VoiceRoom) ←→ PocketBase (token 签发 hook) ←→ LiveKit (音视频 SFU)
```

## 技术选型

- **LiveKit Server** — 开源 WebRTC SFU，Docker 部署
- **livekit-client** — 前端核心 SDK
- **@livekit/components-vue** — Vue 组件封装
- **livekit-server-sdk (Node.js)** — PocketBase hook 中签发 token

## 数据模型

team_sessions 新增字段：
- `voiceRoom: string` — LiveKit 房间名
- `voiceActive: boolean` — 语音房间是否活跃

## Token 签发

PocketBase JS hook (`/api/voice-token/{sessionId}`)：
1. 验证请求者是 session 成员
2. 用 LiveKit API key/secret 签发 JWT
3. room = `team-{sessionId}`，identity = userId
4. 返回 `{ token: "..." }`

## 前端

### 路由

`/group/:groupId/voice/:sessionId` — 独立语音房间页面

### 页面结构 (VoiceRoom.vue)

- 顶部：房间名 + 离开按钮
- 中部：成员头像网格，说话时绿圈动画
- 底部：麦克风开关、扬声器开关、成员列表

### 入口

GroupView 组队卡片上加"语音"按钮，recruiting/playing 状态时显示。

## 文件变更

### 新增

- `frontend/src/views/VoiceRoom.vue`
- `frontend/src/api/voice.ts`
- `frontend/src/composables/useVoiceRoom.ts`
- `frontend/src/components/voice/VoiceMemberGrid.vue`
- `frontend/src/components/voice/VoiceControls.vue`
- `backend/pb_hooks/voice-token.pb.js`
- `backend/pb_hooks/package.json`

### 修改

- `frontend/src/types/index.ts` — TeamSession 加字段
- `frontend/src/router/index.ts` — 加路由
- `frontend/src/views/GroupView.vue` — 加入口按钮
- `docker-compose.backend.yml` — 加 LiveKit 容器
- `docker-compose.uat.yml` — 同步加 LiveKit

## 部署

- PocketBase 启用 JS hooks
- LiveKit 端口：7880 (HTTP)、7881 (UDP/RTC)
- 局域网无需 TURN 服务器