# LoveLiveMusicPlayer · 桌面端

基于 **electron-vite** 的 LoveLive! 音乐播放器 PC 端，复刻原 Electron 项目功能。

> 设计目标之一：**为后续移动端（Flutter）预留最大兼容性与可扩展性**。
> 双端联动协议被抽取为独立、框架无关的共享模块 `src/shared/protocol`，移动端可直接对照复用。

## 技术栈

| 维度 | 选型 |
|------|------|
| 框架 | Electron 43 + Vite 7 + React 19 + TypeScript |
| 脚手架 | electron-vite |
| 状态管理 | Zustand |
| 样式 | Tailwind CSS 3（`src/renderer/src/styles/index.css`） |
| 本地数据库 | better-sqlite3（表结构与移动端 SQLite 对齐） |
| 配置存储 | electron-store |
| 局域网通信 | ws（WebSocket 服务端）+ express（HTTP 文件服务），**运行在主进程** |
| 二维码 | qrcode.react |
| 音频转码 | ffmpeg-static（iOS flac→wav，跨平台免编译） |
| 图标 | lucide-react |

## 目录结构

```
src/
├── shared/                     # ★ 双端共享（协议 + 领域模型 + IPC 通道常量）
│   ├── protocol/               #   命令枚举 / 类型 / 端口 / 版本协商（移动端可复用）
│   ├── models/                 #   Album/Music/Menu/Love/History/Lyric（对齐移动端实体）
│   └── ipc/channels.ts
├── main/                       # 主进程
│   ├── index.ts                #   入口（单例锁、生命周期）
│   ├── window/                 #   主窗口 + 桌面歌词窗口
│   ├── ipc/                    #   IPC 注册
│   └── services/               #   store / database / fileServer / musicServer(4388)
│                               #   / dataServer(4389) / transcode / network / lanInfo
├── preload/                    # 类型安全的 window.api 桥接
└── renderer/                   # 渲染进程（React）
    └── src/
        ├── components/         #   TitleBar / Sidebar / PlayerBar / MusicList / ...
        ├── pages/              #   Home / Albums / AlbumDetail / Favorites / Playlists
        │                       #   / History / Lyric / Transfer / Sync / Settings / DesktopLyric
        ├── stores/             #   uiStore / playerStore / libraryStore（Zustand）
        └── lib/                #   repository（DB 访问）/ lrc（歌词解析）/ const
```

## 已复刻的 PC 端功能

- 音乐馆（按企划分组）、专辑、专辑详情
- 播放器（顺序/列表循环/单曲/随机、进度、音量、媒体会话、上一首/下一首）
- 我喜欢、歌单（PC id≤100 / 手机 id>100）、最近播放
- 三语歌词（日/中/罗马音）+ 桌面歌词独立窗口
- **WiFi 传歌**（二维码配对 + WebSocket 4388 + HTTP 文件下载）
- **数据同步**（我喜欢/歌单双向，WebSocket 4389）
- 本地 HTTP 文件服务（端口探测、可配置）
- iOS flac→wav 转码
- 设置：曲库目录、HTTP 端口、主题（深/浅/跟随系统）、强调色
- 无边框窗口（Windows 自定义控制按钮 / macOS 红绿灯位）

## 与移动端的兼容性设计

- **协议单一来源**：`src/shared/protocol/commands.ts` 定义所有命令字（枚举，禁止裸字符串），
  字符串值与旧移动端保持一致，保证新 PC 端可直接与现有 App 联动。
- **版本协商**：`version.ts` 在保留 `transVer=1` 兼容的同时引入 `minCompatVer` + `capabilities`，
  支持向后兼容与能力位扩展。
- **数据结构对齐**：领域模型与移动端 Floor 实体一致，降低同步映射成本。
- 移动端重构时可把 `src/shared` 作为协议对照，甚至用代码生成同步。

## 开发与构建

```bash
npm install                 # 安装依赖（postinstall 会为 Electron 重建原生模块）
npm run dev                 # 开发模式
npm run build               # 类型检查 + 打包
npm run build:win           # 打 Windows 安装包
```

> 首次如遇 `Electron uninstall`，执行 `node node_modules/electron/install.js` 下载 Electron 二进制；
> 原生模块（better-sqlite3）如报 ABI 不匹配，执行 `npx electron-builder install-app-deps`。

## 待接入（占位/后续）

- OSS `data.json` 曲库元数据拉取入库（`main/services/network.ts` 已备 `fetchJson`，UI 触发待接）
- 断点续传 / 完整性校验 / 配对 token 鉴权（协议 `capabilities` 已预留）
- 自动更新（electron-updater 接线）、导出 Excel、托盘