渲染进程架构

本文聚焦 src/renderer/。渲染进程已经从早期 src/js 和全局 app.js 组织方式迁移到 Vite + TypeScript + feature 分层结构。旧的 core/、services/ 目录仍存在，但只作为兼容转发层。

入口与构建

• Vite 配置：src/renderer/vite.config.js
• Vite root：src/renderer/src
• 构建输出：src/renderer/public
• 主窗口入口：src/renderer/src/index.html
• 桌面歌词入口：src/renderer/src/DesktopLyrics.html
• 主 renderer 入口：src/renderer/src/app/bootstrap/main.ts

app/bootstrap/main.ts 会先加载工具、应用 API、插件框架、页面、组件和弹窗，再导入 ./app 创建应用实例。

Canonical 目录

src/renderer/src/app/
  bootstrap/               应用入口与 createMusicBoxApp
  composition/             组合根和 host ports
  lifecycle/               初始化、清理、首屏生命周期
  runtime/                 路由、快捷键、事件绑定、插件启动、UI facade
  shell/                   顶层 shell 视图控制

src/renderer/src/features/
  appShell/                应用外壳、窗口、托盘、通知、更新
  audioDriver/             音频驱动 UI/设置协调
  desktopLyrics/           桌面歌词窗口与同步
  equalizer/               图形/参量均衡器
  events/                  应用事件服务
  extensions/              插件管理功能
  library/                 音乐库、扫描、元数据编辑
  media/                   文件选择、音频读取、媒体文件系统
  mediaAssets/             歌词、封面、本地/在线/内嵌资源
  networkDrive/            SMB / WebDAV 网络磁盘
  playback/                播放队列、状态、音频引擎、UI 绑定
  playlists/               歌单数据、播放、封面、导入
  settings/                设置页 controller/service/renderer
  userData/                心情、日记等用户数据

src/renderer/src/ui/
  base/                    基础 Component
  pages/                   页面级组件
  widgets/                 播放器、导航、列表、歌词等常驻组件
  dialogs/                 轻量对话框
  modals/                  模态窗口

src/renderer/src/infrastructure/electron/
  ElectronBridge.ts        window.electronAPI 访问基础
  *Gateway.ts              按领域封装 preload API

src/renderer/src/shared/
  cache/                   renderer 本地缓存
  lyrics/                  歌词时间线和逐字渲染共享逻辑
  network/                 网络请求 client
  types/                   app contracts

依赖方向

推荐依赖方向：

ui -> features -> infrastructure/electron -> preload -> main
app composition -> features/ui/shared
features -> shared
extensions -> public Extension API

避免的方向：

• features 直接依赖具体 UI DOM 细节，除非在 ui-bindings 中作为显式绑定层。
• ui 直接调用 window.electronAPI。
• 新代码从 @/core、@/services 或 @js 导入。
• 插件 host/framework 硬编码某个具体插件 ID、命令前缀或插件私有行为。

组合根

app/composition/AppCompositionRoot.ts 是渲染进程重构后的关键文件。它负责：

• 创建 ComponentRegistry、DOMEventBinder、APIEventBinder、ViewRouter。
• 创建播放、音乐库、歌单、快捷键、插件、网络磁盘等 app controller。
• 将 feature service 与 MusicBoxApp facade、UI facade、legacy plugin app bridge 显式连接。
• 配置跨功能依赖，例如 desktopLyricsService 获取播放快照，equalizerService 获取当前音频引擎。

当新功能需要跨模块协作时，应优先在组合根注入一个明确端口，而不是在模块内部读取全局对象。

运行时 facade

app/runtime/MusicBoxApp.ts 仍然暴露很多应用级方法，例如 scanMusicFolder()、handleViewChange()、playTrackFromPlaylist()。这些方法主要用于兼容旧 UI 绑定和插件调用，真实实现已经下沉到 features/*。

新增代码不要继续扩大 MusicBoxApp 的职责，除非它是应用级 facade 必须暴露的兼容入口。

Feature 模块约定

一个 feature 通常由以下部分组成：

features/<domain>/
  index.ts                 对外导出
  <Domain>Controller.ts    可选，状态编排或 UI 入口
  service/                 领域服务、gateway adapter、纯业务逻辑
  ui-bindings/             可选，连接 UI component 与 feature 的适配层
  domain/                  可选，纯领域模型

放置建议：

• 与 Electron IPC 交互的代码放在 service，并通过 infrastructure/electron gateway 访问。
• 只处理页面/组件事件绑定的代码放到 ui-bindings。
• 可测试、与 DOM 无关的规则放到 domain 或 service。
• 多个 feature 共享的纯工具放到 shared/。

Electron Gateway

infrastructure/electron/ElectronBridge.ts 提供两个基础能力：

• getElectronAPI()：读取 preload 暴露的 window.electronAPI，缺失时抛出明确错误。
• ElectronNamespaceAdapter：包装某个命名空间的 call() 和 on()。

新增 IPC 应按以下路径接入：

1. 主进程 controller 增加 IPC handler。
2. preload 增加对应 namespace 方法。
3. infrastructure/electron 增加或扩展 gateway。
4. feature service 调用 gateway。
5. controller/UI 只依赖 feature service。

兼容层与架构检查

core/ 和 services/ 目录是迁移期兼容层。每个文件必须：

• 包含 @deprecated 注释。
• 只包含注释和 import/export 转发。
• 不包含新的业务逻辑。

src/renderer/scripts/check-architecture-boundaries.mjs 会检查：

• 禁止新代码从旧 @/core、@/services、@js 路径导入。
• 禁止在主 renderer 中使用 eval 或注入 script 标签加载插件代码。
• 禁止把 createExtensionAPI 暴露到主 renderer window。
• 禁止 plugin host/framework 硬编码内置插件 ID 或命令前缀。

运行：

cd src/renderer
npm run check:architecture
npm run lint

播放模块

播放相关代码集中在 features/playback/：

• PlaybackController.ts：应用层播放 controller。
• PlaybackStore.ts：播放状态 store。
• domain/PlaybackQueue.ts：播放队列和播放模式逻辑。
• service/PlaybackService.ts：播放服务 facade。
• service/AudioEngineAdapter.ts：Web Audio / WASAPI 切换适配。
• service/audioEngine/webAudio/：Web Audio 实现。
• service/audioEngine/wasapi/WasapiEngine.ts：WASAPI renderer adapter。
• ui-bindings/：播放器、列表等 UI 事件绑定。

播放状态变化通过事件和 store 同步到播放器 UI、歌词、桌面歌词和插件 API。

样式结构

样式入口：

• styles/main.scss：主窗口样式入口。
• styles/DesktopLyrics.scss：桌面歌词窗口样式入口。

样式目录按用途拆分：

• base/：reset、loading。
• layout/：app、content、navbar、sidebar。
• components/：按钮、表单、播放器、列表等。
• pages/：页面级样式。
• features/：均衡器、迷你模式、插件、网络磁盘、快捷键等功能样式。
• dialogs/：对话框样式。
• theme/：设计 token。

新增 renderer 代码检查清单

• 是否放在 canonical 目录，而不是 deprecated core/ / services/。
• 是否通过 gateway 访问 preload API。
• 是否把跨模块依赖显式注入到组合根或端口对象。
• 是否清理 DOM listener、API listener、timer、plugin disposable。
• 是否运行 npm run typecheck:renderer。
• 是否运行 cd src/renderer && npm run lint。