# 01 - OrangeRadio 技术架构

> 版本：v0.3 · 最后更新：2026-07-05 · 代码总量约 15000 行（Rust 7900 + 前端 4400 + CSS 2800）

## 一、产品定位

OrangeRadio 是一款基于 **Tauri 2 + Rust** 的**全平台沉浸式智能音乐播放器**。核心特色：多音源聚合、节奏粒子视觉、跨源歌单收藏、全屏沉浸播放。

## 二、系统架构

```
┌───────────────────────────────────────────────────────────────────────┐
│                      客户端 (Tauri 2 桌面壳)                           │
│                                                                       │
│  ┌──────────────────────────────┐    ┌─────────────────────────────┐  │
│  │  前端 WebView (React 18+TS)   │    │  Rust 核心层 (11 个 crate)   │  │
│  │                              │    │                             │  │
│  │  • 音频播放 + 频谱分析       │    │  • 核心抽象 / 音源 trait      │  │
│  │  • Three.js 节奏粒子 + Bloom │◄──►│  • 本地库 + SQLite 持久化    │  │
│  │  • Zustand 状态管理          │IPC │  • 多音源适配层              │  │
│  │  • 全屏沉浸播放页            │    │  • IPC 命令桥接              │  │
│  │  • 跨源歌单/收藏/评论        │    │  • AI 创作 / 社交同步        │  │
│  └──────────────────────────────┘    └─────────────────────────────┘  │
│                                                                       │
│  数据层：~/.orangeradio/                                              │
│    ├── library.sqlite (本地库+歌单+收藏)                              │
│    ├── covers/ (本地封面缓存)                                         │
│    ├── cache/ (流缓存)                                                │
│    └── logs/ (按天滚动日志)                                           │
└───────────────────────────────────────────────────────────────────────┘
        │                    │                │              │
        ▼                    ▼                ▼              ▼
   网易云音乐            QQ音乐           Spotify         网络电台
   扫码/Cookie           扫码/Cookie      OAuth2          播客 RSS
   4万+ 电台                                                                
```

## 三、播放架构（v0.3 实际链路）

### 跨源播放引擎（核心设计）

```
用户双击歌曲
  → 引擎按 source_kind 分发取流方式
      ├─ local              → 本地文件 → <audio>
      ├─ netease_cloud_music → 网易云取流 → <audio>
      ├─ qq_music            → QQ 音乐取流 → <audio>
      │                        → 自定义流代理处理跨域
      └─ web_radio/podcast   → URL 直接 → <audio>
  → 竞态防护：请求序号 + 防抖锁
  → <audio>.play() → 频谱分析 → 节拍检测 → 粒子视觉
```

### 跨域与流代理

部分 CDN 对跨域有限制，前端 `<audio>` 直接播放会被拦截。方案是：Tauri 侧注册自定义 URI 协议处理器，由 Rust 后端代理拉取音频流并透传必要请求头，支持 Range 与进度拖动。

## 四、模块职责（v0.3 真实状态）

| Crate | 职责 | 行数 | v0.3 状态 |
|---|---|---|---|
| `orange-core` | 核心抽象：Track/SourceKind/AudioSource/AuthSource/Player/Recommendation trait | 891 | ✅ 完整 |
| `orange-library` | SQLite 持久化 + lofty 扫描 + 用户歌单 + 跨源收藏 | 755 | ✅ 完整 |
| `orange-sources` | 6 大音源：网易云/QQ/Spotify/电台/播客/本地 + 登录态管理 | 3560 | ✅ 完整 |
| `orange-tauri` | 50 个 IPC 命令 + 后台健康检查/续期 | 1079 | ✅ 完整 |
| `orange-audio` | Hi-Res 解码/DSP/EQ/空间音频 | 261 | 🔜 stub |
| `orange-ai` | AI 推荐/歌词译注/语音助手 | 271 | 🔜 stub |
| `orange-studio` | AI 创作（MiniMax）/ DAW / 人声合成 | 623 | 🔜 stub |
| `orange-sync` | 投屏/接力/一起听 | 84 | 🔜 stub |
| `orange-hue` | 智能灯光联动 | 71 | 🔜 stub |
| `orangeradio-desktop` | Tauri 桌面入口 + 流代理协议 + 日志 | 242 | ✅ 完整 |
| `orangeradio-server` | 社交后端（Axum） | 85 | 🔜 骨架 |

## 五、前端架构（v0.3）

前端采用 React 18 + TypeScript + Vite 构建，主要模块：

- **视觉层**：Three.js 节奏粒子、Bloom 后处理、全屏沉浸播放页
- **组件层**：侧边栏、播放器控制栏、歌词组件、聚合搜索、歌单弹窗
- **状态层**：Zustand 管理播放、本地库、搜索、视觉参数等状态
- **功能模块**：播放器引擎、本地音乐库、多音源视图、创作工作室、社交视图

## 六、数据库设计（SQLite）

本地数据使用 SQLite 持久化：

- `tracks` 表：保存本地歌曲与跨源收藏的 Track 元数据
- `user_playlists` 表：用户自建歌单
- `playlist_tracks` 表：歌单与歌曲的多对多关联

跨源收藏机制：网易云/QQ 歌曲加入本地歌单时，完整 Track 元数据（含来源类型、封面、歌曲信息）存入本地数据库；播放时引擎根据来源类型自动取流。

## 七、关键技术决策记录

1. **播放方案**：前端 `<audio>` 播放，通过 Tauri 自定义协议代理绕过部分 CDN 的跨域限制，并获取真实频谱驱动视觉。
2. **登录态持久化**：用户登录凭据经本地加密后写入 SQLite，下次启动自动恢复；定期后台健康检查续期。
3. **竞态防护**：异步取流使用请求序号 + 防抖锁，避免快速切歌导致的串音或资源浪费。
4. **跨源播放**：统一 Track 抽象，引擎按 `source_kind` 分发到对应音源适配器取流。

## 八、技术栈

| 层 | 技术 | 版本 |
|---|---|---|
| 桌面壳 | Tauri | 2.x |
| 核心 | Rust | stable-msvc |
| 前端 | React + TypeScript | 18 + 5.x |
| 构建 | Vite | 5.x |
| 视觉 | Three.js + @react-three/fiber | 0.169 |
| 状态 | Zustand | 4.x |
| 数据库 | rusqlite (SQLite) | 0.31 |
| 元数据 | lofty | 0.21 |
| 后端 | Axum（社交，占位） | 0.7 |