开发指南

本文档涵盖 TimeLens 完整开发环境搭建、项目架构理解、日常调试技巧及脚本参考。无论你是初次接触 Tauri 还是经验丰富的 Rust 开发者，都能在这里找到所需信息。

前置条件

工具	最低版本	安装方式
Node.js	18	nodejs.org
Rust	1.77	rustup.rs
Tauri CLI	2.x	`cargo install tauri-cli --version "^2"`
WebView2 (Windows)	任意	Windows 11 已内置；Win10 独立安装包
Xcode CLI Tools (macOS)	最新稳定版	`xcode-select --install`

验证安装

node --version   # v18.x.x
npm --version    # 9.x.x
rustc --version  # 1.77.x
cargo --version  # 1.77.x

项目初始化

# 1. 克隆仓库
git clone https://github.com/PythonSmall-Q/TimeLens.git
cd TimeLens

# 2. 安装前端依赖（package.json）
npm install

# 3. 安装浏览器扩展依赖（可选）
cd browser-extension && npm install && cd ..

开发模式

TimeLens 使用 Tauri 开发模式，该模式会同时启动 Vite 开发服务器和 Tauri 桌面窗口。

# 启动完整开发环境（推荐）
npm run tauri:dev

# 仅启动 Vite 前端服务器（用于纯 UI 调试，无后端）
npm run dev

开发服务器默认运行在 http://localhost:1420。热模块替换（HMR）对所有前端代码生效；Rust 代码修改需要完整重启。

开发时常见问题

窗口白屏：检查 WebView2 是否已安装，或尝试刷新页面（F5 或 Ctrl+R）。
Rust 编译错误：确保已安装 cargo install tauri-cli --version "^2"。
端口被占用：Vite 会自动寻找下一个可用端口，Tauri 配置中的 URL 需同步更新。

架构概览

TimeLens 采用经典的双层架构：Rust 后端负责系统级操作和数据持久化，React 前端负责用户界面和状态管理。

┌─────────────────────────────────────────────────┐
│  Tauri Process (Rust)                            │
│                                                  │
│  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  monitor/    │  │  db/ (SQLite)            │  │
│  │  (tokio task)│  │  app_usage               │  │
│  │  Win32/      │  │  todos                   │  │
│  │  AppleScript │  │  widget_configs          │  │
│  └──────┬───────┘  └──────────┬───────────────┘  │
│         │  emit events        │ queries          │
│  ┌──────▼───────────────────┐ │                  │
│  │  commands/ (invoke)      ◄─┘                  │
│  │  monitor_cmd.rs          │                    │
│  │  storage_cmd.rs          │                    │
│  │  widget_cmd.rs           │                    │
│  └──────┬───────────────────┘                    │
└─────────│───────────────────────────────────────┘
          │ IPC (invoke / emit)
┌─────────▼────────────────────────────────────────┐
│  React Frontend (WebView)                         │
│                                                   │
│  App.tsx → 窗口标签检测                            │
│    "main"    → MainApp (HashRouter)               │
│    "clock-*" → WidgetWindow                │
│    "todo-*"  → WidgetWindow                 │
│    "timer-*" → WidgetWindow                │
│                                                   │
│  stores/  → Zustand (statsStore, widgetStore,     │
│             settingsStore)                        │
│  services/ → tauriApi.ts wrappers                │
└───────────────────────────────────────────────────┘

关键文件速查

文件	职责
`src-tauri/src/lib.rs`	应用初始化、数据库初始化、系统托盘、监控启动、窗口恢复
`src-tauri/src/monitor/mod.rs`	后台窗口轮询 + 数据库写入
`src-tauri/src/db/mod.rs`	SQLite 表结构定义与所有查询
`src/App.tsx`	窗口标签路由（main vs widget）
`src/MainApp.tsx`	主仪表盘壳 + 全局事件监听
`src/services/tauriApi.ts`	所有 invoke 调用的前端封装
`src/i18n/config.ts`	i18next 初始化配置、语言列表

调试技巧

Rust 日志

设置 RUST_LOG 环境变量以查看详细日志：

# Windows PowerShell
$env:RUST_LOG = "debug"; npm run tauri:dev

# macOS / bash / zsh
RUST_LOG=debug npm run tauri:dev

前端 DevTools

在任意 Tauri 窗口中按 F12 即可打开 Chromium DevTools（仅开发构建）。

SQLite 数据库检查

数据库文件位置：

Windows: %APPDATA%\com.timelens.app\timelens.db
macOS: ~/Library/Application Support/com.timelens.app/timelens.db

可使用 DB Browser for SQLite 等工具直接打开查看。

小组件窗口不显示

检查 capabilities/default.json 中窗口标签模式是否匹配（clock-*、todo-*、timer-*）。

脚本速查

命令	说明
`npm run dev`	仅启动 Vite 前端开发服务器
`npm run build`	前端生产构建
`npm run tauri:dev`	完整 Tauri 开发模式（推荐）
`npm run tauri:build`	完整生产构建（输出安装包）
`npm run lint`	ESLint 检查
`npm run typecheck`	TypeScript 类型检查（不输出文件）
`npm run format`	Prettier 格式化
`npm run test`	Vitest 单元测试

添加测试

前端测试放置于 src/__tests__/，使用 Vitest + @testing-library/react。

Rust 单元测试与模块并存：

// Rust 测试示例
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_format_seconds() {
        assert_eq!(format_seconds(3661), "1h 1m");
        assert_eq!(format_seconds(59), "0m");
    }
}

发布流程

# 1. 先推送 master（仓库约定）
git push origin refs/heads/master:refs/heads/master

# 2. 创建并推送版本标签
git tag -a v1.1.0 -m "release: v1.1.0"
git push origin v1.1.0

推送 v* 标签会自动触发 .github/workflows/release.yml 工作流，构建并发布各平台安装包。

贡献代码

我们欢迎所有形式的贡献！在提交 PR 前，请：

阅读 CONTRIBUTING.md
确保代码通过 npm run lint 和 npm run typecheck
保持提交信息简洁清晰（推荐遵循 Conventional Commits）
为重大变更更新相关文档

最后更新：2025-05-03 · TimeLens v1.1.0