| name | file-modularization |
| description | Use when adding or refactoring frontend features in this repository and you need to prevent large single-file changes, oversized entry files, mixed responsibilities, or giant App.tsx/Home.tsx style implementations. Apply it when a task risks stuffing UI, state, effects, data access, and helper logic into one file instead of splitting focused components, hooks, services, utils, and types. |
File Modularization
先判断职责，再决定文件。App.tsx 是历史遗留的全局编排接缝，当前已经很大；新功能不要继续堆进它。Home.tsx、PlayerPanel.tsx、AppOverlays.tsx、AppDialogs.tsx 已有相邻的 model/helper 目录，应沿现有边界扩展。
Layer map
- 视图结构：
src/components/*
- app-level 装配和单区域协调：
src/components/app/*
- React 生命周期、异步副作用、可复用交互：
src/hooks/*
- 跨组件共享状态：
src/stores/*
- 请求、解析、provider、播放流程、缓存：
src/services/*
- 纯计算、排序、映射、格式化：
src/utils/*
- 跨层合同：
src/types.ts 或 src/types/*
如果一个文件同时新增 UI、请求、副作用、状态派生、事件处理和类型定义，说明拆分不足。
Current app boundaries
src/components/app/Home.tsx -> components/app/home/*，尤其 buildHomeModel.ts、collection adapters、GridViewOverlayHost.tsx、local/Navi grid views。src/components/app/PlayerPanel.tsx -> components/app/player-panel/*。src/components/app/overlays/AppOverlays.tsx -> components/app/overlays/*。src/components/app/dialogs/AppDialogs.tsx -> components/app/dialogs/*。- 播放恢复、在线回退、缓存 ->
components/app/playback/*。
- 搜索工作台和搜索动作 ->
components/app/search/*。
- 主进程更新通道 ->
electron/updateChannels.cjs；不要把新的 Electron 逻辑都塞回 electron/main.cjs。
Size guardrail
这些是默认警戒值，不是要求机械重写历史文件：
src/index.tsx、新页面根组件、全局 provider 装配文件：尽量不超过 180 行。- 普通容器、页面组件、复杂 hook：尽量不超过 220 行。
- 展示组件、工具、适配器：尽量不超过 160 行。
- 单次需求若要向现有文件追加超过 80 行，先判断是否应新建模块。
src/App.tsx 已经超过入口阈值；触碰相关区域时优先抽到上述 app boundary，不要以“就近”为由继续扩大。
Split order
- 抽离独立视觉区块到
components。
- 把 props 组装、导航映射和展示派生放到相邻
components/app/*/build*.ts 或 create*.ts。
- 把 React 状态和副作用放到
hooks。
- 把请求、缓存、适配放到
services。
- 把纯函数、常量和映射放到
utils 或 types。
- 让原文件只保留传参、组合和必要分支。
Decision signals
- JSX 跨越多个主要视觉区域：拆 component。
- 同类 state/effect 成组且与 UI 弱相关：拆 hook。
- 只服务 Home、PlayerPanel、AppOverlays 或 AppDialogs 的无生命周期组装：拆 app-level builder/helper。
- 包含请求、解析、适配、排序、缓存或序列化：拆 service/util。
- 需要独立测试、可能复用，或让当前文件新增职责：不要留在原文件。
What to avoid
- 在
App.tsx 中直接新增完整功能区、请求函数或大段事件处理。
- 在页面组件中混合 provider 请求、缓存、排序工具和类型声明。
- 把新首页、GridView、集合详情功能塞回旧的
LocalMusicView、local/LocalPlaylistView 或 navidrome/* 路径；当前入口在 components/app/home/*。
- 通过“拆成很多空壳文件”伪装模块化；拆分后职责和依赖方向必须更清楚。
- 为了省一次 import，继续向已有超大 visualizer、
VisPlayground 或 SettingsModal 追加大段实现。
Review checklist
