LagZero/docs/module-usage.md

模块说明与使用方法

1. 通用调用链

在 LagZero 中，推荐遵循下面这条调用链：

flowchart LR
  A["View / Component"] --> B["Store / Composable"]
  B --> C["src/api"]
  C --> D["window.*"]
  D --> E["Electron IPC"]
  E --> F["Service / Database / System"]

原则上：

• 组件负责展示与交互
• store 负责跨页面业务状态
• composable 负责可复用逻辑
• src/api 是渲染进程调用主进程的薄封装
• preload 是唯一允许暴露主进程能力给渲染进程的地方

2. 前端模块

2.1 游戏模块

相关文件：

• src/views/library/index.vue
• src/views/dashboard/index.vue
• src/stores/games.ts
• src/utils/singbox-config.ts

职责：

• 管理游戏库、当前选中游戏、运行状态、延迟与加速时长
• 负责游戏加速的启动与停止
• 根据节点与设置生成 sing-box 配置
• 在进程模式下协调 proxyMonitor

常用方法：

• init(): 初始化游戏库
• setCurrentGame(id): 切换当前游戏
• addGame(game), updateGame(game), removeGame(id): 游戏 CRUD
• startGame(id): 启动加速
• stopGame(id): 停止加速
• matchRunningGames(processNames): 根据进程名回填运行状态
• applySessionNetworkTuningChange(): 当前正在加速时重启应用配置

示例：

<script setup lang="ts">
import { useGameStore } from '@/stores/games'

const gameStore = useGameStore()

async function onStart(gameId: string) {
  await gameStore.startGame(gameId)
}

async function onStop(gameId: string) {
  await gameStore.stopGame(gameId)
}
</script>

使用建议：

• 如果只是编辑游戏资料，用 addGame / updateGame
• 如果涉及启停 sing-box，一律走 startGame / stopGame
• 修改加速规则时，优先检查 generateSingboxConfig() 是否也要更新

2.2 节点模块

相关文件：

• src/views/nodes/index.vue
• src/components/node/*
• src/stores/nodes.ts
• src/utils/protocol.ts

职责：

• 管理节点列表、筛选、排序、分组与多选
• 导入/导出分享链接
• 节点订阅刷新
• 延迟测速与会话统计

常用方法：

• loadNodes(): 从数据库加载节点
• saveNode(node): 保存节点
• addNodes(content): 从分享链接文本导入节点
• removeNode(id), removeNodes(ids): 删除节点
• refreshSubscription(id): 手动刷新订阅
• runScheduledSubscriptions(reason): 按启动或手动场景执行订阅刷新
• checkNode(node, methodOverride?, context?): 测单个节点
• checkAllNodes(): 批量测速

示例：

<script setup lang="ts">
import { useNodeStore } from '@/stores/nodes'

const nodeStore = useNodeStore()

await nodeStore.loadNodes()
await nodeStore.checkAllNodes()

const importedCount = await nodeStore.addNodes(shareLinksText)
console.log('imported:', importedCount)
</script>

使用建议：

• 页面层不要自己解析节点分享链接，统一复用 addNodes
• 订阅刷新默认会做去重，手动导入允许重复
• 如果删除节点会影响当前加速中的游戏，nodes store 已内置停机兜底逻辑

2.3 本地代理模块

相关文件：

• src/stores/local-proxy.ts
• src/main.ts

职责：

• 应用启动时自动拉起本地代理
• 在可用节点中递归探测并选择健康节点
• 节点变更后自动切换或恢复
• 定时做本地代理健康检查

常用方法：

• startLocalProxy(reason?)
• stopLocalProxy()
• recheckLocalProxyHealth()
• handleNodeListChanged()
• applySettingsChange()

示例：

<script setup lang="ts">
import { useLocalProxyStore } from '@/stores/local-proxy'

const localProxyStore = useLocalProxyStore()

async function onProxySettingsChanged() {
  await localProxyStore.applySettingsChange()
}
</script>

使用建议：

• 不要在组件里直接拼测试端口、递归探测等流程，这些都已经封装在 store 中
• 这个模块与游戏加速共用 sing-box 进程，改动前要确认不会破坏 games store 的启停流程

2.4 设置模块

相关文件：

• src/stores/settings.ts
• src/components/settings/*
• src/views/settings/index.vue

职责：

• 持久化语言、主题、窗口关闭行为
• 持久化 DNS、检测方式、本地代理、系统代理与 TUN 相关设置
• 管理全局会话级网络调优参数

常用字段：

• language, theme, themeColor
• windowCloseAction
• checkInterval, checkMethod, checkUrl
• dnsMode, dnsPrimary, dnsSecondary, dnsBootstrap
• localProxyEnabled, localProxyPort
• accelNetworkMode, systemProxyPort, systemProxyBypass
• tunInterfaceName
• sessionNetworkTuning

常用方法：

• resetSessionNetworkTuning()
• applySessionNetworkProfilePreset(profile, options?)

示例：

<script setup lang="ts">
import { useSettingsStore } from '@/stores/settings'

const settingsStore = useSettingsStore()

settingsStore.accelNetworkMode = 'tun'
settingsStore.applySessionNetworkProfilePreset('aggressive', {
  isCurrentNodeVless: true
})
</script>

2.5 游戏扫描模块

相关文件：

• src/composables/useGameScanner.ts
• electron/services/game-scanner.ts
• electron/services/scanners/*.ts

职责：

• 调用主进程扫描本地游戏平台与本地快捷方式
• 自动匹配分类并写入游戏库
• 扫描运行进程并回填游戏运行状态

常用方法：

• scanGames()
• isScanning
• scanProgressText

示例：

<script setup lang="ts">
import { useGameScanner } from '@/composables/useGameScanner'

const { isScanning, scanProgressText, scanGames } = useGameScanner()
</script>

2.6 托盘模块

相关文件：

• src/views/tray/index.vue
• electron/main/tray.ts
• src/layouts/MainLayout.vue

职责：

• 展示当前游戏、延迟、丢包与加速时长
• 提供快速启停、显示主窗口与退出应用操作
• 与主窗口通过托盘状态快照同步

注意点：

• 托盘页走 #/tray
• src/main.ts 对托盘窗口做了特判，不会初始化主窗口的本地代理监听逻辑

3. Electron 主进程模块

3.1 DatabaseService

文件：electron/services/database.ts

职责：

• 初始化 SQLite 数据库
• 管理 nodes、games、categories 等核心数据
• 做数据迁移、默认分类补齐、分类与标签冲突修复

建议：

• 业务数据落库优先经过这个服务
• GameService / NodeService / CategoryService 只是它的 IPC 薄封装

3.2 SingBoxService

文件：electron/services/singbox/index.ts

职责：

• 下载和校验 sing-box 二进制
• 启动、停止、重启 sing-box 进程
• 采集日志并转发到渲染进程
• 处理进程路由规则更新

对应 IPC：

• singbox-start
• singbox-stop
• singbox-restart
• singbox-ensure-core
• singbox-get-install-info

3.3 SystemService

文件：electron/services/system.ts

职责：

• ping / tcpPing
• DNS 刷新
• TUN 网卡重装
• 系统代理设置与恢复
• 本地 HTTP 代理连通性测试
• 主进程代理 HTTP 请求

适用场景：

• 节点测速
• 本地代理健康检查
• 系统代理模式切换
• 网络诊断工具

3.4 ProxyMonitorService

文件：electron/services/proxy-monitor.ts

职责：

• 按游戏进程名轮询进程树
• 找出链式拉起的子进程
• 将新发现的子进程同步给 sing-box 动态代理

适用场景：

• proxyMode = 'process'
• chainProxy = true

3.5 GameScannerService

文件：electron/services/game-scanner.ts

职责：

• 并发调用多个平台扫描器
• 去重安装目录和进程名
• 提供目录扫描能力给“选择文件夹导入进程”功能

当前已接入平台：

• Steam
• Microsoft
• Epic
• EA
• BattleNet
• WeGame
• Local shortcut

3.6 WindowManager 与 TrayManager

文件：

• electron/main/window.ts
• electron/main/tray.ts

职责：

• WindowManager: 主窗口创建、窗口关闭行为管理、开发者工具、主窗口 IPC
• TrayManager: 托盘图标、托盘浮窗、显示主窗口、退出应用

注意点：

• 关闭按钮行为可配置为 ask / minimize / quit
• 托盘浮窗是独立 BrowserWindow，不是原生菜单

4. 渲染进程与主进程之间怎么接

推荐固定模板：

1. electron/services/* 或 electron/main/index.ts 注册 IPC
2. electron/preload/index.ts 通过 contextBridge.exposeInMainWorld 暴露
3. src/api/*.ts 包装成统一调用方法
4. src/stores/* 或 src/composables/* 负责消费
5. src/views/* / src/components/* 只调用上层封装

示例路径：

src/views/nodes/index.vue
  -> src/stores/nodes.ts
  -> src/api/nodes.ts
  -> window.nodes.*
  -> ipcMain.handle('nodes:*')
  -> electron/services/node.ts
  -> electron/services/database.ts

5. 扩展建议

新增一个 IPC 能力

最推荐的文件落点：

• 主进程逻辑：electron/services/xxx.ts
• 桥接层：electron/preload/index.ts
• 渲染进程 API：src/api/xxx.ts
• 业务状态：src/stores/xxx.ts 或 src/composables/useXxx.ts

新增一个共享数据结构

最推荐的文件落点：

• shared/types/*.ts
• 渲染进程 re-export：src/types/index.ts

新增一个系统级功能

优先判断是否属于下面其中一种：

• 文件系统、网络诊断、端口检查、系统代理：加到 SystemService
• sing-box 生命周期和配置校验：加到 SingBoxService
• 业务数据 CRUD：加到 DatabaseService
• 游戏平台扫描：加到 GameScannerService 或 scanners/

6. 维护时最容易踩坑的点

• 直接在组件里调用 window.*，会让调用链分散，后期难维护
• 修改节点结构却忘了同步 shared/types、数据库和协议解析
• 只改游戏加速逻辑，没考虑本地代理复用同一 sing-box 进程
• 给托盘页加主窗口初始化逻辑，导致托盘窗口触发多余副作用
• 在 shared/ 里引入 Electron 或 Vue，导致跨进程复用失败