File size: 4,383 Bytes
00a912e | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | # Music Together — 项目速查手册
> 供 AI 助手快速理解项目全貌的参考文档。
## 1. 项目概览
**Music Together** 是一个在线同步听歌平台，允许多人在同一房间内实时同步播放音乐、聊天互动。
### 核心功能
| 功能 | 说明 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 房间系统 | 创建/加入房间，房间号邀请，可选密码保护；永久房间在用户加入时按 30 分钟间隔按需刷新当前播放链接 |
| 多音源搜索 | 网易云、QQ音乐、酷狗 |
| 同步播放 | 房间内播放进度实时同步 |
| 实时聊天 | 房间内文字聊天 |
| 权限控制 | RBAC 三级权限（owner > admin > member）基于 @casl/ability，hostId 为自动选举的播放主持（conductor） |
| 播放模式 | 顺序播放、列表循环、单曲循环、随机播放（Owner/Admin 直接切换，Member 投票切换） |
| 投票系统 | 普通成员通过投票控制播放（暂停/恢复/切歌/切换播放模式/指定播放/移除歌曲） |
| VIP 认证 | 平台账号登录（网易云/QQ/酷狗），房间级 Cookie 池（VIP 播放共享）+ 用户级歌单（私有） |
| 歌词展示 | Apple Music 风格歌词动画 (AMLL)，四级优先级：TTML 在线逐词（网易云/QQ，可配置）> 平台原生逐词（网易云 YRC / 酷狗 KRC）> LRC 行级歌词 |
### 技术栈
- **前端**: React 19 + Vite 7 + TypeScript 5.9 + Tailwind CSS v4 + shadcn/ui + Zustand
- **后端**: Node.js + Express 4 + Socket.IO 4 + @meting/core
- **Monorepo**: pnpm workspaces（3 个包：`client`、`server`、`shared`）
---
## 子文档索引
本文档已拆分为多个子文件，位于 `docs/architecture/` 目录：
| 章节 | 文件 | 内容 |
| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| 2. 目录结构 | [directory-structure.md](architecture/directory-structure.md) | client / server / shared 三包目录树 |
| 3. 架构与数据流 | [data-flow.md](architecture/data-flow.md) | 分层架构、Socket 事件清单、核心类型定义、NTP 同步、播放同步、播放模式、音频质量等 |
| 4. 第三方库依赖 | [dependencies.md](architecture/dependencies.md) | 前端/后端/共享/开发依赖清单 |
| 5. 设计模式 | [design-patterns.md](architecture/design-patterns.md) | Zustand Store、Hook 组合、Dialog、Provider、分层架构、Repository 等 |
| 6. 代码规范 | [coding-standards.md](architecture/coding-standards.md) | 语言模块、路径别名、状态更新、错误处理 |
| 7. UI 设计规范 | [ui-design.md](architecture/ui-design.md) | 组件库、颜色系统、动画、歌词、响应式 |
| 8. 开发指南 | [dev-guide.md](architecture/dev-guide.md) | 快速启动、构建、添加组件、注意事项 |
| 9. 部署方案 | [deployment.md](architecture/deployment.md) | Docker、CORS、Watchtower、1Panel |
|