# 项目概述

## 简介

OFPlayer 是一个本地优先的网页音乐播放器，设计目标是提供干净、克制、高端、桌面级的音乐播放体验。项目采用纯前端架构，所有数据存储在用户设备上，无需账号系统或云服务。

## 核心特性

### 音乐管理
- 本地音频文件导入（支持 MP3、WAV、OGG、M4A、FLAC、AAC）
- 多库（Library）管理，支持本地和外部数据源
- 播放列表（Playlist）系统，包含系统播放列表和用户播放列表
- 智能视图：最近播放、收藏、当前队列、专辑浏览、艺术家浏览

### 播放功能
- 播放/暂停/上一首/下一首
- 进度条拖拽定位
- 音量控制
- 播放历史记录
- 当前队列管理

### 界面特性
- 响应式布局（左-中-右三栏）
- 虚拟列表优化（大列表性能）
- 多主题支持（Mist/Paper/Material）
- 国际化（中文/英文）
- 沉浸式播放视图
- 歌词显示

### 数据持久化
- IndexedDB 主存储
- localStorage 降级方案
- 版本化存储（构建 ID 感知）

## 技术栈

### 核心依赖

```json
{
  "vue": "^3.5.32",
  "lucide-vue-next": "^1.0.0",
  "music-metadata": "^11.12.3"
}
```

### 开发依赖

```json
{
  "@vitejs/plugin-vue": "^6.0.6",
  "vite": "^8.0.8"
}
```

### 技术选型理由

| 技术 | 选择理由 |
|------|----------|
| Vue 3 | Composition API 提供更好的逻辑复用，轻量级 |
| Vite 8 | 极快的 HMR，原生 ESM 支持 |
| lucide-vue-next | 树摇优化，仅打包使用的图标（约 46 个） |
| music-metadata | 浏览器端音频元数据解析 |
| HTMLAudioElement | 浏览器原生 API，零依赖 |
| IndexedDB | 大容量本地存储，支持 Blob |

## 项目结构

```
ofplayer/
├── src/
│   ├── main.js              # 应用入口
│   ├── App.vue              # 根组件
│   ├── style.css            # 全局样式
│   │
│   ├── app/
│   │   └── ofplayerApp.js   # 应用编排层（中央门面）
│   │
│   ├── components/          # Vue 组件
│   │   ├── PlayerPanel.vue
│   │   ├── LibraryPanel.vue
│   │   ├── SettingsModal.vue
│   │   └── ...
│   │
│   ├── composables/         # Vue 组合式函数
│   │   ├── useAudioPlayer.js
│   │   ├── useI18n.js
│   │   └── ...
│   │
│   ├── models/              # 数据模型
│   │   ├── library.js
│   │   ├── playlist.js
│   │   ├── track.js
│   │   └── ...
│   │
│   ├── services/            # 业务服务
│   │   ├── libraryService.js
│   │   ├── playlistService.js
│   │   ├── trackService.js
│   │   ├── data/            # 数据访问层
│   │   └── ...
│   │
│   ├── stores/              # 响应式状态
│   │   ├── libraryStore.js
│   │   ├── playerStore.js
│   │   ├── preferencesStore.js
│   │   └── ...
│   │
│   ├── themes/              # 主题系统
│   │   ├── index.js
│   │   ├── mist.js / mist.css
│   │   ├── paper.js / paper.css
│   │   └── material.js / material.css
│   │
│   └── utils/               # 工具函数
│       ├── lrcParser.js
│       ├── colorExtractor.js
│       └── ...
│
├── packages/
│   └── ofplayer-ui/         # 可复用 UI 组件包
│
├── public/                  # 静态资源
├── vite.config.js           # Vite 配置
└── package.json             # 项目清单
```

## 路由结构

| 路径 | 组件 | 用途 |
|------|------|------|
| `/` | PlayerPage.vue | 主播放器页面 |
| `/product` | ProductPage.vue | 产品介绍页 |
| `/download` | DownloadPage.vue | 下载页面 |
| `/privacy` | PrivacyPage.vue | 隐私政策页 |

## 开发命令

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 预览构建结果
npm run preview
```

## 部署

项目通过 Vercel 部署，配置了 SPA 路由重写：

```json
{
  "rewrites": [{ "source": "/(.*)", "destination": "/" }]
}
```

## 浏览器兼容性

- Chrome 90+
- Firefox 90+
- Safari 15+
- Edge 90+

主要依赖特性：
- ES2022
- IndexedDB
- HTMLAudioElement
- CSS Custom Properties
- Web Crypto API (用于 UUID 生成)