目录结构
根目录
music-together/
├── packages/
│ ├── client/ # React 前端
│ ├── server/ # Node.js 后端
│ └── shared/ # 共享类型与常量
├── docs/ # 项目文档（含本文件 PROJECT_ARCHITECTURE.md）
├── package.json # 根 package（工作区编排）
├── pnpm-workspace.yaml # pnpm 工作区定义
├── pnpm-lock.yaml
├── README.md
└── .gitignore
packages/client/src/ — 前端源码
src/
├── main.tsx # 入口：ReactDOM.createRoot
├── App.tsx # 根组件：Router + Provider + ErrorBoundary + Suspense 懒加载
├── index.css # 全局样式：Tailwind + 配色变量 + 自定义动画
│
├── pages/ # 页面级组件
│ ├── HomePage.tsx # 大厅：创建/加入房间、房间列表
│ ├── RoomPage.tsx # 房间：播放器 + 聊天（桌面侧栏/移动端 Drawer） + 覆盖层弹窗
│ └── NotFoundPage.tsx # 404 页面
│
├── components/ # UI 组件
│ ├── Chat/
│ │ ├── ChatMessage.tsx # 单条消息（用户/系统）
│ │ └── ChatPanel.tsx # 聊天面板（消息列表 + 输入框）
│ ├── Lobby/
│ │ ├── CreateRoomDialog.tsx # 创建房间弹窗
│ │ ├── NicknameDialog.tsx # 设置昵称弹窗
│ │ ├── PasswordDialog.tsx # 输入房间密码弹窗
│ │ ├── RoomCard.tsx # 房间列表卡片
│ │ ├── UserPopover.tsx # 用户信息气泡
│ │ ├── HeroSection.tsx # 首页 Hero 标题区域
│ │ ├── ActionCards.tsx # 创建/加入房间卡片
│ │ └── RoomListSection.tsx # 活跃房间列表区域
│ ├── TrackListItem.tsx # 共享曲目行渲染（序号+封面+标题VIP+歌手可点击+时长+isAdded 添加按钮，memo 优化）
│ ├── VirtualTrackList.tsx # 共享虚拟滚动曲目列表（@tanstack/react-virtual + 无限加载 + skeleton + 空态，forwardRef 暴露 scrollToTop）
│ ├── Overlays/
│ │ ├── QueueDrawer.tsx # 播放队列抽屉（vaul Drawer，移动端底部/桌面端右侧）
│ │ ├── SearchDialog.tsx # 音乐搜索弹窗（VirtualTrackList 虚拟滚动 + 自动无限加载 + AbortController 竞态防护）
│ │ ├── SettingsDialog.tsx # 设置弹窗（壳，Tab 导航：房间/成员/账号/个人/外观，移动端 nav scrollbar-hide）
│ │ └── Settings/
│ │ ├── SettingRow.tsx # 设置行共享组件
│ │ ├── RoomSettingsSection.tsx # 房间设置（名称、密码）
│ │ ├── MembersSection.tsx # 成员列表（角色管理）
│ │ ├── PlatformAuthSection.tsx # 平台账号认证（VIP Cookie，旧版，已被 PlatformHub 替代）
│ │ ├── PlatformHub.tsx # 平台中心（登录 + 歌单浏览 + 导入，替代 PlatformAuthSection）
│ │ ├── LoginSection.tsx # 精简版平台登录区域（PlatformHub 子组件）
│ │ ├── PlaylistSection.tsx # 歌单列表 + 手动输入（PlatformHub 子组件）
│ │ ├── PlaylistDetail.tsx # 歌单详情（header + VirtualTrackList + queueKeys/addedIds 去重 + 动态全部添加过滤重复）
│ │ ├── ProfileSettingsSection.tsx # 个人设置（昵称）
│ │ ├── AppearanceSection.tsx # 外观设置（歌词 + 背景 + 布局）
│ │ ├── OtherSettingsSection.tsx # 其他设置
│ │ ├── ManualCookieDialog.tsx # 手动输入 Cookie 弹窗
│ │ └── QrLoginDialog.tsx # 通用 QR 扫码登录弹窗（网易云 + 酷狗 + QQ 音乐）
│ ├── Player/
│ │ ├── constants.ts # 共享动画常量（SPRING / LAYOUT_TRANSITION），NowPlaying 和 SongInfoBar 统一导入
│ │ ├── AudioPlayer.tsx # 主播放器布局（桌面：左右分栏；移动：双模式封面/歌词切换）
│ │ ├── LyricDisplay.tsx # AMLL 歌词渲染（LRC 正则支持 [mm:ss] / [mm:ss.x] / [mm:ss.xx] / [mm:ss.xxx]）
│ │ ├── NowPlaying.tsx # 当前曲目展示（支持 compact 小封面横排模式 + layoutId 共享动画）
│ │ ├── SongInfoBar.tsx # 歌曲信息栏（标题/艺术家 + 音量/聊天按钮，竖屏模式自适应缩放）
│ │ └── PlayerControls.tsx # 进度条+播放控制+播放模式切换
│ ├── Room/
│ │ └── RoomHeader.tsx # 房间头部（房间名/人数/连接状态；移动端 DropdownMenu 收纳设置/离开等操作）
│ ├── Vote/
│ │ └── VoteBanner.tsx # 投票横幅（进行中的投票显示 + 投票按钮）
│ ├── InteractionGate.tsx # 浏览器交互解锁（点击后才能播放音频）
│ └── ui/ # shadcn/ui 基础组件
│ ├── avatar.tsx
│ ├── badge.tsx
│ ├── button.tsx
│ ├── card.tsx
│ ├── dialog.tsx
│ ├── drawer.tsx
│ ├── dropdown-menu.tsx
│ ├── input.tsx
│ ├── label.tsx
│ ├── popover.tsx
│ ├── resize-handle.tsx
│ ├── scroll-area.tsx
│ ├── select.tsx
│ ├── separator.tsx
│ ├── marquee-text.tsx
│ ├── responsive-dialog.tsx
│ ├── sheet.tsx
│ ├── skeleton.tsx
│ ├── slider.tsx
│ ├── switch.tsx
│ ├── tabs.tsx
│ └── tooltip.tsx
│
├── hooks/ # 自定义 Hooks
│ ├── useSocketEvent.ts # 通用 Socket 事件订阅工具 Hook（自动 on/off，ref 稳定）
│ ├── usePlayer.ts # 播放器主 hook（组合 useHowl + useLyric + usePlayerSync）
│ ├── useHowl.ts # Howler.js 音频实例管理
│ ├── useLyric.ts # 歌词加载（TTML → 平台逐词 YRC/KRC → LRC）
│ ├── usePlayerSync.ts # 播放同步（Scheduled Execution + conductor 上报 + 周期性漂移校正）
│ ├── useClockSync.ts # NTP 时钟同步 hook（校准客户端时钟与服务器对齐）
│ ├── useRoom.ts # 房间组合 hook（编排 5 个子 hook，对外 API 不变）
│ ├── room/ # useRoom 子 hook（按职责拆分）
│ │ ├── useRoomState.ts # ROOM_STATE / JOIN / LEFT / SETTINGS / ROLE_CHANGED / ERROR + 挂载时补发 cookie（覆盖 HomePage 提前消费 ROOM_STATE 的场景）
│ │ ├── useChatSync.ts # CHAT_HISTORY / CHAT_MESSAGE
│ │ ├── useQueueSync.ts # QUEUE_UPDATED
│ │ ├── useAuthSync.ts # AUTH_SET_COOKIE_RESULT + localStorage 持久化（验证失败只做 toast 反馈，永不删除 cookie；删除权仅在 useAuth.logout）
│ │ └── useConnectionGuard.ts # disconnect → resetAllRoomState
│ ├── useAuth.ts # 平台认证 UI & Socket 事件
│ ├── useVote.ts # 投票（使用 useSocketEvent）
│ ├── useChat.ts # 聊天消息收发
│ ├── useLobby.ts # 大厅房间列表与操作（使用 useSocketEvent）
│ ├── useQueue.ts # 播放队列操作（含 addBatchTracks 批量添加）
│ ├── usePlaylist.ts # 歌单管理（用户歌单列表、分页曲目获取 + 无限加载、URL 解析、批量导入）
│ ├── useIsMobile.ts # 布局维度：orientation 检测（portrait=竖屏布局，landscape=横屏布局）
│ ├── useHasHover.ts # 交互维度：hover 能力检测（(hover: hover) 媒体查询，触控设备=false）
│ ├── useContainerPortrait.ts # 容器宽高比检测（ResizeObserver，用于播放器横竖屏切换）
│ └── useCoverWidth.ts # 封面容器最小尺寸测量（约束信息栏/控件宽度与封面对齐）
│
├── stores/ # Zustand 状态仓库
│ ├── playerStore.ts # 播放状态（currentTrack, isPlaying, volume 等）
│ ├── roomStore.ts # 房间状态（room, currentUser, users）
│ ├── chatStore.ts # 聊天（messages, unreadCount, isChatOpen）
│ ├── lobbyStore.ts # 大厅（rooms 列表, isLoading）
│ └── settingsStore.ts # 设置（歌词参数、背景参数，持久化到 localStorage）
│
├── providers/ # React Context Provider
│ ├── SocketProvider.tsx # Socket.IO 连接管理，提供 socket + isConnected + 断线/重连 Toast
│ └── AbilityProvider.tsx # CASL 权限上下文（基于 currentUser.role）
│
└── lib/ # 工具库
├── config.ts # 配置常量（SERVER_URL）
├── constants.ts # 命名常量（定时器、阈值、布局尺寸）
├── clockSync.ts # NTP 时钟同步引擎（采样、offset 计算、getServerTime）
├── resetStores.ts # 全局 store 重置工具
├── socket.ts # Socket.IO 客户端实例
├── storage.ts # localStorage 封装（带类型校验）
├── platform.ts # 平台常量（PLATFORM_LABELS / PLATFORM_SHORT_LABELS / PLATFORM_COLORS / VIP_LABELS / 状态查找函数）
├── format.ts # 格式化工具（时间、文本等）
├── audioUnlock.ts # 浏览器音频自动播放解锁
└── utils.ts # cn() + trackKey() 等通用工具
packages/server/src/ — 后端源码
src/
├── index.ts # 入口：Express + HTTP + Socket.IO 服务启动与优雅关闭
├── config.ts # 环境变量配置（PORT, CLIENT_URL, CORS）
│
├── controllers/ # 控制器：注册 Socket 事件处理器（薄编排层，不含业务逻辑）
│ ├── index.ts # 统一注册入口
│ ├── roomController.ts # 房间生命周期（创建/加入/离开/发现/设置/角色）
│ ├── playerController.ts # 播放控制（play/pause/seek/next/prev/sync/set_mode）+ NTP ping/pong
│ ├── queueController.ts # 队列管理（add/remove/reorder/clear）
│ ├── chatController.ts # 聊天消息（含限流反馈）
│ ├── voteController.ts # 投票系统（发起/投票/超时/执行，支持 set-mode / play-track / remove-track 投票）
│ ├── authController.ts # 平台认证（QR 登录/Cookie 管理/状态查询；支持网易云/酷狗/QQ 音乐三平台；策略模式——通过 AUTH_PROVIDERS 映射表统一处理；fast path: 内存池命中跳过 API；slow path: getUserInfo + 任意失败重试 1 次）
│ └── playlistController.ts # 歌单管理（获取用户歌单列表 via Socket，使用 getUserCookie 取请求者自己的 cookie，歌单私有）
│
├── services/ # 服务层：业务逻辑
│ ├── roomService.ts # 房间 CRUD + 角色管理 + 加入校验（validateJoinRequest）
│ ├── roomLifecycleService.ts # 房间生命周期定时器（空置删除）+ 防抖广播
│ ├── playerService.ts # 播放状态管理 + 流 URL 解析 + 切歌防抖 + 加入播放同步
│ ├── queueService.ts # 队列操作（reorder 保留未包含曲目防丢歌，getNextTrack 支持 4 种播放模式，clearQueue 清空，addBatchTracks 批量添加）
│ ├── chatService.ts # 聊天消息处理 + HTML 转义（含系统消息）
│ ├── syncService.ts # 播放位置估算工具（estimateCurrentTime）
│ ├── musicProvider.ts # 音乐数据聚合（3 层引用式 LRU 缓存 + 外部 API 超时保护 + 歌单分页获取；Netease 歌单使用 ncmApi.playlist_track_all 分块请求突破 1000 首限制，Kugou 用户歌单使用原生 API (get_other_list_file_nofilt) + Meting fallback，Tencent 使用 Meting 原始模式保留 VIP/时长字段）
│ ├── authService.ts # Cookie 池管理（房间级作用域；getAnyCookie 用于 VIP 播放共享，getUserCookie 用于歌单等用户私有操作）
│ ├── authProvider.ts # 统一认证接口（AuthProvider 接口定义 + GetUserInfoResult/UserInfoData 共享类型 + AUTH_PROVIDERS 策略映射表）
│ ├── neteaseAuthService.ts # 网易云 API 认证（QR / Cookie 验证 / 用户信息 / 用户歌单列表；getUserInfo 返回 { ok, data? } | { ok: false, reason: 'expired' | 'error' } 区分过期与临时故障）
│ ├── kugouAuthService.ts # 酷狗 API 认证（QR 扫码登录 + VIP 检查 + 用户昵称(RSA) + 用户歌单列表 + 歌单歌曲获取；kugouRequest 含 HTTP 状态检查与 JSON 安全解析；自包含签名实现，状态码归一化为 800-803 与网易云统一）
│ ├── tencentAuthService.ts # QQ 音乐认证（5 步 OAuth QR 扫码登录：ptqrshow/ptqrlogin/check_sig/authorize/QQLogin 换取 musickey；zzc 签名防风控；getUserInfo 获取昵称 + VIP 状态；getUserPlaylists 获取自建 + 收藏歌单；getPlaylistTracks 分页获取歌单歌曲）
│ └── voteService.ts # 投票状态管理
│
├── repositories/ # 数据仓库：内存状态与 SQLite 持久化
│ ├── types.ts # 接口定义（RoomRepository, ChatRepository）
│ ├── roomRepository.ts # 房间数据 + Socket 映射 + per-socket RTT + roomToSockets 反向索引（Map<string, RoomData>）
│ ├── chatRepository.ts # 聊天记录（内存最多 200 条；永久房间同步持久化到 SQLite）
│ └── audioProxyPolicyRepository.ts # 全局酷狗音频代理策略（SQLite server_settings）
│
├── middleware/ # Socket.IO 中间件
│ ├── types.ts # TypedServer, TypedSocket, HandlerContext
│ ├── withRoom.ts # 房间成员身份校验
│ ├── withControl.ts # 操作权限校验（包装 withRoom）
│ └── socketRateLimiter.ts # Socket 事件速率限制（per-socket，10次/5秒）+ 断连清理（cleanupSocketRateLimit）
│
├── routes/ # Express REST 路由
│ ├── music.ts # GET /api/music/search|url|lyric|cover|playlist|ttml（统一 validated() 路由包装器消除重复 try/catch + Zod 模式）
│ └── rooms.ts # GET /api/rooms/:roomId/check（房间预检）
│
├── types/
│ └── meting.d.ts # @meting/core 类型声明
│
└── utils/
├── logger.ts # 结构化日志（基于 pino，info/warn/error + JSON context）
└── roomUtils.ts # 房间数据转换纯函数（toPublicRoomState / toPublicRoomStateForOwner，密码仅 owner 可见）
packages/shared/src/ — 共享代码
src/
├── index.ts # 统一导出（re-export 所有模块）
├── types.ts # 核心类型：ERROR_CODE, Track, RoomState, PlayState, ScheduledPlayState, PlayMode, AudioQuality, User, ChatMessage, VoteAction (incl. play-track, remove-track), VoteState, RoomListItem, Playlist
├── events.ts # 事件常量：EVENTS 对象（room:*, player:*, queue:*, chat:*, auth:*, ntp:*, playlist:*）
├── socket-types.ts # Socket.IO 类型：ServerToClientEvents, ClientToServerEvents
├── constants.ts # 业务常量：LIMITS（长度/数量限制）, TIMING（同步间隔/宽限期）, NTP（时钟同步参数）, QR_STATUS（扫码状态码）, QR_TIMING（轮询间隔）
├── schemas.ts # Zod 验证 schema
└── abilities.ts # CASL 权限定义（Actions incl. set-mode, Subjects, defineAbilityFor）
