架构文档

深入了解 TimeLens 的系统架构、模块划分、数据流设计及关键技术决策。

系统概览

TimeLens 是一款基于 Tauri 2.x 构建的桌面应用，采用 Rust + React 双层架构。Rust 层负责系统级交互（窗口监控、数据库、系统托盘），React 层负责所有用户界面。

核心设计原则

数据主权：所有使用数据存储在本地 SQLite，不上传云端。
零运行时依赖：除操作系统自带组件外，不需要额外安装任何服务。
模块化 Command：每个功能域拥有独立的 Rust command 模块，便于维护和扩展。
状态集中管理：前端使用 Zustand 进行全局状态管理，避免 props drilling。

Rust 后端层

lib.rs — 应用生命周期

src-tauri/src/lib.rs 是整个 Rust 层的入口，负责以下初始化流程：

初始化 env_logger 日志系统。
注册 Tauri 插件（shell、global-shortcut、notification、updater、dialog）。
setup 回调中：
- 打开/创建 SQLite 数据库
- 将数据库连接注册为共享状态（DbState）
- 恢复上次会话的小组件窗口
- 创建系统托盘图标和菜单
- 启动后台监控任务（tokio）

monitor/ — 前台窗口监控

后台 tokio 任务，以固定间隔（默认 1 秒）轮询当前前台窗口信息。

平台	实现方式
Windows	Win32 API（`GetForegroundWindow`、`GetWindowThreadProcessId`、`GetModuleBaseName`）
macOS	AppleScript / Accessibility API

监控模块检测到窗口切换时，将旧窗口的使用时长写入数据库，并开始记录新窗口。同时通过 Tauri 事件通道向前端广播 active-window-changed 事件。

db/ — SQLite 数据层

所有数据库操作集中在 db/mod.rs，包含以下核心表：

表名	用途
`app_usage`	每条记录 = 一个应用在某日的一个使用片段（含窗口标题、活跃秒数）
`app_categories`	应用 → 分类映射规则
`usage_goals`	用户设置的使用目标（每日/每周、至少/至多）
`focus_sessions`	专注模式会话记录
`todos`	待办事项数据
`widget_configs`	小组件窗口位置、尺寸、透明度等配置
`settings`	应用级设置（启动项、快捷键、语言等）
`browser_sessions`	浏览器扩展同步的网页访问记录
`browser_domain_limits`	网页域名使用限额

commands/ — IPC 接口层

Rust command 模块按功能域拆分：

文件	职责
`monitor_cmd.rs`	监控状态查询、暂停/恢复追踪
`storage_cmd.rs`	所有数据查询、统计计算、导入导出
`widget_cmd.rs`	创建/打开/关闭小组件窗口
`app_cmd.rs`	应用设置、系统通知、安装渠道检测
`browser_cmd.rs`	浏览器扩展数据、域名统计与限额
`productivity_cmd.rs`	生产力评分、中断时段分析
`widget_permissions.rs`	第三方小组件权限管理

React 前端层

窗口路由

TimeLens 不是单页应用，而是多窗口应用。src/App.tsx 根据 Tauri 窗口标签决定渲染内容：

窗口标签	渲染组件	说明
`main`	`MainApp`	主仪表盘，包含 HashRouter
`clock-*`	`WidgetWindow`	时钟小组件
`todo-*`	`WidgetWindow`	待办小组件
`timer-*`	`WidgetWindow`	计时器小组件
`note-*`	`WidgetWindow`	笔记小组件
`status-*`	`WidgetWindow`	状态小组件

页面结构

主应用（MainApp）使用 HashRouter，包含以下页面：

Dashboard — 今日概览、应用排行、热力图、生产力评分、目标进度
HomeCustomize — 仪表盘布局自定义（拖拽排序卡片）
WidgetCenter — 小组件管理中心（创建、配置、权限）
Limits — 应用使用限额设置
BrowserUsage — 浏览器使用统计（需配合浏览器扩展）
Categories — 应用分类管理与智能推荐
Goals — 使用目标设定与追踪
FocusMode — 专注模式开关与历史
Settings — 全局设置（语言、主题、快捷键等）

状态管理

使用 Zustand 创建了 4 个全局 store：

Store	数据	持久化
`statsStore`	今日/本周/历史使用数据、监控状态	否（实时从 Rust 获取）
`widgetStore`	小组件配置列表、可见性状态	Rust DB
`settingsStore`	主题、语言、监控设置等	Rust DB + localStorage 缓存
`dashboardLayoutStore`	仪表盘卡片顺序、显隐	localStorage

数据流设计

监控数据流

OS 前台窗口
    ↓ (每秒轮询)
monitor/mod.rs
    ↓ (聚合 + 写入)
SQLite (app_usage 表)
    ↓ (前端主动查询 / 事件推送)
React Frontend
    ↓ (Zustand store)
Dashboard Charts & Lists

事件流

Tauri 提供了两种前后端通信方式：

invoke — 前端调用 Rust command，同步/异步请求-响应模式。
emit / listen — 事件广播模式，用于监控状态变更、窗口切换通知等实时推送。

小组件是 TimeLens 的特色功能。每个小组件都是一个独立的 Tauri 窗口，拥有独立的 WebView 实例。

官方内置小组件

类型	功能
Clock	模拟/数字时钟，支持自定义格式
Todo	待办列表，支持拖拽排序、完成标记
Timer	多模式计时器（番茄钟 / 倒计时 / 正计时）
Note	便签小组件，支持文本编辑
Status	系统状态展示（当前应用、今日总时长）

第三方小组件

TimeLens 支持加载第三方 JavaScript 小组件。详细开发指南参见小组件开发指南。

国际化架构

使用 i18next + react-i18next 实现多语言支持。

翻译文件位于 src/i18n/locales/{lang}/
按功能域拆分 JSON 文件：common.json、dashboard.json、widgets.json、settings.json 等
新增语言仅需翻译 JSON 并在 config.ts 注册即可

安全模型

TimeLens 使用 Tauri v2 的 Capability 系统进行权限控制：

capabilities/default.json 定义了主窗口和各类小组件窗口的权限集合。
第三方小组件通过权限系统（widget_permissions.rs）进行沙箱隔离，按需授予 screen-time:read 等权限。
所有 Rust command 参数均经过类型校验，SQL 查询使用参数化防止注入。

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