Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,12 @@ jobs:

- name: Build app
run: npm run build

- name: Run Electron end-to-end smoke
run: npm run test:e2e

- name: Package Windows artifacts
run: npm run package

- name: Run packaged executable smoke
run: npm run test:package-smoke
35 changes: 32 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

- 项目名:`FocusFlow`
- 定位:本地优先的 Windows 桌面番茄钟客户端,核心场景是个人专注、任务绑定、本地统计。
- 技术栈:Electron 34、electron-vite 5、React 19、TypeScript 5、SQLite via `sql.js`、electron-log、Vitest。
- 技术栈:Electron 41.3.0、electron-builder 26.15.3、electron-vite 5、Vite 7.3.6、React 19、TypeScript 5、SQLite via `sql.js`、electron-log、Vitest 4.1.10、Playwright 1.61.1。
- 包管理器:`npm`
- 源码目录:`core/`、`main/`、`preload/`、`renderer/`、`shared/`
- 构建产物:`output/build/`
Expand All @@ -18,7 +18,9 @@

- 不要把业务规则塞回 React 组件;计时、统计、任务等规则优先放在 `core/` 或 `main/services/`。
- Renderer 只能通过 preload 暴露的 `window.focusFlow` API 访问桌面能力,不直接触碰 Electron 主进程对象。
- Preload 必须保持 sandbox 兼容,并以 CommonJS 输出到 `output/build/preload/index.cjs`。
- IPC channel、shared types、数据库 schema、打包产物命名都是稳定边界,改动前必须确认影响面。
- IPC 入参在主进程边界做运行时校验;不要把 TypeScript 类型当作不可信 renderer 数据的运行时保证。
- 当前是 Windows / PowerShell 语义;不要用 bash 风格 `&&` 串命令。
- 编辑 `md / ts / tsx / json / html / yml` 时优先用 `apply_patch` 或 UTF-8 安全写法,避免 PowerShell 编码问题。

Expand All @@ -32,6 +34,7 @@
- 默认设置定义在 `shared/defaults.ts`。
- 小窗尺寸常量定义在 `shared/windowMetrics.ts`。
- 如需新增或修改跨进程 API,必须同步更新 `shared/contracts.ts`、`preload/index.ts`、`main/ipc/registerIpcHandlers.ts` 和相关测试。
- IPC 请求校验集中在 `main/ipc/requestValidation.ts` 和 `main/ipc/settingsUpdateRequest.ts`;新增带 payload 的 channel 时必须补对应运行时校验。

当前 IPC 分组:

Expand All @@ -41,12 +44,22 @@
- `stats`:总体统计和月历统计。
- `system`:主题、主窗口、小窗、拖拽、缩放、最小化、最大化、关闭、退出。

### Electron 安全边界

- BrowserWindow 使用 `contextIsolation: true`、`nodeIntegration: false`、`sandbox: true`、`webviewTag: false`。
- `main/security.ts` 统一拒绝 renderer 新开窗口、页面跳转和权限请求。
- Renderer 中不应存在可用的 Node.js `process`、`require` 或 Electron API;唯一桌面桥接是 `window.focusFlow`。
- 改窗口创建、preload 或 IPC 时,至少同步检查 `main/security.test.ts`、`main/ipc/requestValidation.test.ts` 和真实 Electron E2E。

### 数据库

- SQLite schema 在 `main/adapters/sqlite/schema.ts`。
- 数据库初始化在 `main/adapters/sqlite/sqliteDatabase.ts`。
- 主进程启动时在 `main/index.ts` 调用 `createSqliteAppDatabase(join(app.getPath('userData'), 'focusflow.sqlite'))`。
- 如果 `focusflow.sqlite` 不存在,`sql.js` 会创建空数据库,执行 schema,并立即 flush 到磁盘。
- 数据库写入通过临时文件和原子替换落盘,并维护 `focusflow.sqlite.bak`;启动时会依次尝试临时文件、主文件和备份文件恢复。
- 写操作串行化;顶层事务负责 `BEGIN / COMMIT / ROLLBACK` 和统一落盘,嵌套事务复用当前事务上下文。
- schema 迁移版本记录在 `PRAGMA user_version`,当前版本是 `2`;遇到高于当前版本或非法版本时拒绝启动迁移。
- Windows 常见路径:`%APPDATA%/focusflow/focusflow.sqlite`。
- 安装版、`focusflow-single.exe` 单文件便携版、`output/release/focusflow-appx.appx` 安装出的 AppX 版本、`win-unpacked/focusflow.exe` 展开版默认共享同一个用户级 `userData` 数据库位置。
- `focusflow-single.exe` 是程序分发形态,不是数据便携形态;数据库不会放在 exe 同目录。
Expand Down Expand Up @@ -98,7 +111,9 @@ Electron 主进程层,负责应用启动、服务装配、窗口、托盘、
- `main/adapters/`:桌面能力、SQLite、通知帮助函数。
- `main/ports/`:仓储接口与桌面接口。
- `main/ipc/settingsUpdateRequest.ts`:`settings.update` 请求形状校验 helper。
- `main/ipc/requestValidation.ts`:计时、任务、统计和窗口相关 IPC payload 的运行时校验。
- `main/ipc/registerIpcHandlers.ts`:IPC handler 注册。
- `main/security.ts`:BrowserWindow webPreferences 与导航、弹窗、权限策略。
- `main/timerSnapshotBroadcast.ts`:主进程计时快照广播 wiring 与 tick runner helper。
- `main/assets/`:主进程运行时资源,打包后复制到 `app-assets/`。

Expand All @@ -109,6 +124,7 @@ Electron 主进程层,负责应用启动、服务装配、窗口、托盘、
安全桥接层。

- `preload/index.ts` 通过 `contextBridge` 暴露 `window.focusFlow`。
- 构建配置强制输出 sandbox 兼容的 CommonJS 文件 `output/build/preload/index.cjs`;主进程窗口必须加载这个路径。
- 这里是 renderer 唯一能访问主进程能力的入口。

适合放:IPC invoke/send/on 的最小封装,不放业务规则。
Expand Down Expand Up @@ -149,18 +165,24 @@ React 渲染层。
npm run dev
npm run build
npm test
npm run test:e2e
npm run preview
npm run package
npm run test:package-smoke
npm run package:appx:dev
```

- `npm run dev`:启动 `electron-vite dev --watch`,用于完整 Electron 开发态。
- `npm run build`:执行 `tsc --noEmit && electron-vite build`,输出到 `output/build/`。
- `npm test`:运行 `vitest run`。
- `npm test`:运行 `vitest run`;当前基线是 32 个测试文件、185 个测试。
- `npm run test:e2e`:先构建,再启动真实 Electron,验证 renderer 沙箱与弹窗拦截、IPC 入参校验、任务创建与绑定、计时启动/暂停和重启持久化。
- `npm run preview`:预览构建后的 Electron 应用。
- `npm run package`:默认 Windows 发布链路;先构建,再通过 `package-win.mjs` 预热 Windows 打包兼容层,最后生成 `nsis + portable`,输出到 `output/release/`。
- `npm run test:package-smoke`:检查安装包、便携版和 `latest.yml` 相对 `win-unpacked` 的新鲜度,验证发布元数据,并启动打包态应用检查 preload API。
- `npm run package:appx:dev`:唯一 AppX 打包入口;内部会自动准备或复用开发证书、在需要时拉起管理员导入机器级信任、执行构建,并通过 `package-win.mjs appx` 产出当前机器可直接安装的签名 `appx`。

运行 `npm run package` 前必须退出所有从 `output/release/` 启动的 FocusFlow 实例,尤其是 `output/release/win-unpacked/focusflow.exe`。运行中的 exe 会锁定该目录,导致 electron-builder 以 `EBUSY` 失败。

直接在普通浏览器打开 `http://localhost:5173/` 时,只会看到 renderer 的浏览器态提示页。要验证完整交互、托盘、窗口控制和 preload API,请使用 `npm run dev` 拉起 Electron。

### Windows / PowerShell
Expand All @@ -176,6 +198,7 @@ npm run package:appx:dev
- 打包工具:`electron-builder`
- Windows targets:`nsis`、`portable`、`appx`
- 默认 `npm run package` 仍只打 `nsis + portable`
- GitHub Release 仍由人工创建和上传产物;项目当前没有 publish 自动化,也没有应用内自动更新。
- `package.json > build.win.icon`:`main/assets/focusflow-icon.ico`
- `package.json > build.win.executableName`:`focusflow`
- `package.json > build.nsis.oneClick`:`false`,保持 `focusflow-setup.exe` 为标准辅助安装向导,而不是一键安装。
Expand Down Expand Up @@ -328,19 +351,24 @@ npm run package:appx:dev
- 打包配置:跑 `npm test -- main/packageConfig.test.ts`。
- 构建路径、alias、资源路径:跑 `npm run build`。
- Windows 发布产物:跑 `npm run package`,检查 `output/release/` 中安装包、单文件便携版、`win-unpacked/` 和 `latest.yml`。
- 真实 Electron 安全与主流程:跑 `npm run test:e2e`,覆盖沙箱、新窗口拒绝、IPC 校验、任务计时和重启持久化。
- 已打包产物:在 `npm run package` 成功后跑 `npm run test:package-smoke`,覆盖产物新鲜度、元数据、打包态启动和 preload API。
- AppX 打包链路:统一跑 `npm run package:appx:dev`,并检查 `output/release/` 中 `.appx` 产物与 `output/dev-cert/` 证书导出文件。
- 启动烟测:用 `output/release/focusflow-single.exe` 和 `output/release/win-unpacked/focusflow.exe` 分别验证;注意单文件版会自解包到 `%TEMP%`,可能受单实例锁影响。

当前测试框架:`vitest`
当前测试框架:`Vitest 4.1.10`(单元/组件)与 `Playwright 1.61.1`(真实 Electron E2E 和打包烟测)。当前 Vitest 基线是 32 个测试文件、185 个测试。

重点测试文件:

- `core/timer/timerState.test.ts`
- `core/stats/statsAggregator.test.ts`
- `main/repositories/sqliteRepositories.test.ts`
- `main/adapters/sqlite/sqliteDatabase.test.ts`
- `main/timerSnapshotBroadcast.test.ts`
- `main/ipc/registerIpcHandlers.test.ts`
- `main/ipc/requestValidation.test.ts`
- `main/ipc/settingsUpdateRequest.test.ts`
- `main/security.test.ts`
- `main/services/timerService.test.ts`
- `main/services/taskService.test.ts`
- `main/services/taskBoardService.test.ts`
Expand All @@ -356,6 +384,7 @@ npm run package:appx:dev
- `renderer/windowMode.test.ts`
- `renderer/views/*.test.tsx`
- `renderer/components/*.test.tsx`
- `tools/packaged-smoke.test.mjs`

## 工作区纪律

Expand Down
52 changes: 39 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# FocusFlow

[![CI](https://github.com/gis2all/focus-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/gis2all/focus-flow/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/gis2all/focus-flow)](https://github.com/gis2all/focus-flow/releases/latest)
[![License](https://img.shields.io/github/license/gis2all/focus-flow)](LICENSE)

FocusFlow 是一个本地优先的 Windows 桌面番茄钟客户端,面向个人专注、任务绑定和本地统计场景。它把番茄钟、待办任务、专注统计、系统托盘、小窗和 Windows 通知整合在一个轻量桌面应用里。
Expand All @@ -16,12 +17,26 @@ FocusFlow 是一个本地优先的 Windows 桌面番茄钟客户端,面向个
<img src="main/assets/image.png" alt="FocusFlow 主界面" width="860">
</p>

## 快速开始
## 下载与安装

从 [GitHub Releases](https://github.com/gis2all/focus-flow/releases/latest) 下载最新版本:

- `focusflow-setup.exe`:标准安装向导,适合大多数用户。
- `focusflow-single.exe`:无需安装的单文件便携版。

如果 Windows Defender 或 SmartScreen 显示安全提示,请先确认下载地址来自本仓库的 GitHub Releases。

## 开发与验证

开发环境要求:

- Windows 10/11 x64
- Node.js 22(包含 npm)

安装依赖:

```powershell
npm install
npm ci
```

常用命令:
Expand All @@ -30,8 +45,10 @@ npm install
npm run dev
npm run build
npm test
npm run test:e2e
npm run preview
npm run package
npm run test:package-smoke
npm run package:appx:dev
```

Expand All @@ -40,33 +57,42 @@ npm run package:appx:dev
- `npm run dev`:本地开发首选命令,直接启动完整 Electron 应用,适合验证托盘、窗口控制、通知和 preload API。
- `npm run build`:执行 TypeScript 类型检查,并构建 main、preload、renderer 三端产物到 `output/build/`。
- `npm test`:运行 Vitest 测试。
- `npm run test:e2e`:构建并启动真实 Electron,验证沙箱、IPC、任务计时和重启持久化。
- `npm run preview`:预览构建后的 Electron 应用。
- `npm run package`:默认 Windows 发布链路,产出标准安装向导版 `nsis` 安装包和 `portable` 单文件版,输出到 `output/release/`。
- `npm run package`:默认 Windows 发布链路,产出标准安装向导版 `nsis` 安装包和 `portable` 单文件版,输出到 `output/release/`。运行前需要退出从该目录启动的 FocusFlow 实例。
- `npm run test:package-smoke`:启动 `win-unpacked` 中的新打包应用,检查产物、发布元数据和 preload API;需要先成功运行 `npm run package`。
- `npm run package:appx:dev`:唯一 AppX 打包入口,内部会自动准备或复用本地开发证书,并产出当前机器可直接安装的签名 `appx`。

## 技术栈

- 桌面框架:Electron 34
- 桌面框架:Electron 41
- 前端界面:React 19 + TypeScript 5
- 本地数据:SQLite(via `sql.js`)
- 构建工具:electron-vite 5
- 测试:Vitest
- 构建工具:electron-vite 5 + Vite 7
- 测试:Vitest 4 + Playwright 1.61

## 项目结构

```text
core -> services -> adapters -> UI
Renderer -> Preload/IPC -> Main services -> Ports/Adapters
|
Core
```

示意图:

```mermaid
flowchart LR
Core["core/<br/>计时状态机 / 统计聚合"] --> Main["main/<br/>服务装配 / IPC / 窗口 / 托盘 / 数据库"]
Shared["shared/<br/>类型 / IPC 合同 / 默认设置"] --> Main
Shared --> Preload["preload/<br/>contextBridge / window.focusFlow"]
Main --> Preload
Preload --> Renderer["renderer/<br/>React 页面 / 组件 / 视图模型"]
Renderer["renderer/<br/>React 页面 / 组件 / 视图模型"] -->|window.focusFlow| Preload["preload/<br/>contextBridge"]
Preload -->|IPC| Main["main/<br/>启动 / 窗口 / 托盘"]
Main --> Services["main/services/<br/>应用服务"]
Services --> Core["core/<br/>计时状态机 / 统计聚合"]
Services --> Ports["main/ports/<br/>能力接口"]
Adapters["main/adapters + repositories/<br/>Electron / SQLite 实现"] -. implements .-> Ports
Main --> Adapters
Renderer --> Shared["shared/<br/>类型 / IPC 合同 / 默认设置"]
Preload --> Shared
Main --> Shared
```

关键目录:
Expand All @@ -91,7 +117,7 @@ flowchart LR

### 输出目录与发布包

- `output/` 是生成物目录,需要时可删除后通过 `npm run build`、`npm run package` 或 `npm run package:appx:dev` 重新生成。
- `output/` 是生成物目录,需要时可删除后通过 `npm run build`、`npm run package` 或 `npm run package:appx:dev` 重新生成;操作前先退出从 `output/release/` 运行的 FocusFlow。
- `output/build/`:`npm run build` 生成的 Electron main、preload、renderer 构建产物。
- `output/release/focusflow-setup.exe`:Windows 标准安装向导,可选当前用户或所有用户安装,并可修改安装目录。
- `output/release/focusflow-single.exe`:Windows 单文件便携版,双击即可运行。
Expand Down
11 changes: 9 additions & 2 deletions electron.vite.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,16 @@ export default defineConfig({
preload: {
build: {
lib: {
entry: resolve('preload', 'index.ts')
entry: resolve('preload', 'index.ts'),
formats: ['cjs']
},
outDir: buildOutDir('preload')
outDir: buildOutDir('preload'),
rollupOptions: {
output: {
entryFileNames: 'index.cjs',
format: 'cjs'
}
}
},
plugins: [externalizeDepsPlugin()],
resolve: {
Expand Down
113 changes: 113 additions & 0 deletions main/adapters/sqlite/sqliteDatabase.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
import { copyFile, mkdtemp, rename, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, test } from 'vitest'
import {
CURRENT_SCHEMA_VERSION,
createSqliteAppDatabase,
type SqliteAppDatabase
} from './sqliteDatabase'

let database: SqliteAppDatabase | null
let databasePath: string
let tempDirectory: string

beforeEach(async () => {
tempDirectory = await mkdtemp(join(tmpdir(), 'focusflow-database-'))
databasePath = join(tempDirectory, 'focusflow.sqlite')
database = await createSqliteAppDatabase(databasePath)
})

afterEach(async () => {
database?.close()
database = null
await rm(tempDirectory, { recursive: true, force: true })
})

describe('sqlite database durability', () => {
test('records the current schema version', () => {
expect(database?.get<{ user_version: number }>('PRAGMA user_version')?.user_version).toBe(CURRENT_SCHEMA_VERSION)
})

test('rolls back a failed transaction in memory and on disk', async () => {
await expect(
database?.transaction(async () => {
await database?.run(
'INSERT INTO tasks (id, title, sort_order, completed_at, created_at, updated_at) VALUES (?, ?, ?, NULL, ?, ?)',
['rolled-back-task', 'Rolled back', 1, '2026-07-22T09:00:00.000Z', '2026-07-22T09:00:00.000Z']
)
throw new Error('stop transaction')
})
).rejects.toThrow('stop transaction')

expect(database?.get('SELECT id FROM tasks WHERE id = ?', ['rolled-back-task'])).toBeNull()

database?.close()
database = await createSqliteAppDatabase(databasePath)
expect(database.get('SELECT id FROM tasks WHERE id = ?', ['rolled-back-task'])).toBeNull()
})

test('recovers an interrupted atomic write when only the temporary file remains', async () => {
await database?.run(
'INSERT INTO tasks (id, title, sort_order, completed_at, created_at, updated_at) VALUES (?, ?, ?, NULL, ?, ?)',
['recovered-task', 'Recovered', 1, '2026-07-22T09:00:00.000Z', '2026-07-22T09:00:00.000Z']
)
database?.close()
database = null
await rename(databasePath, `${databasePath}.tmp`)

database = await createSqliteAppDatabase(databasePath)

expect(database.get<{ title: string }>('SELECT title FROM tasks WHERE id = ?', ['recovered-task'])?.title).toBe(
'Recovered'
)
})

test('prefers a newer valid temporary file over a stale valid main file', async () => {
await database?.run(
'INSERT INTO tasks (id, title, sort_order, completed_at, created_at, updated_at) VALUES (?, ?, ?, NULL, ?, ?)',
['older-task', 'Older', 1, '2026-07-22T09:00:00.000Z', '2026-07-22T09:00:00.000Z']
)
database?.close()
database = null
const stalePath = join(tempDirectory, 'stale.sqlite')
await copyFile(databasePath, stalePath)

database = await createSqliteAppDatabase(databasePath)
await database.run(
'INSERT INTO tasks (id, title, sort_order, completed_at, created_at, updated_at) VALUES (?, ?, ?, NULL, ?, ?)',
['newer-task', 'Newer', 2, '2026-07-22T09:01:00.000Z', '2026-07-22T09:01:00.000Z']
)
database.close()
database = null
await rename(databasePath, `${databasePath}.tmp`)
await copyFile(stalePath, databasePath)

database = await createSqliteAppDatabase(databasePath)

expect(database.get<{ title: string }>('SELECT title FROM tasks WHERE id = ?', ['newer-task'])?.title).toBe(
'Newer'
)
})

test('falls back to the last valid backup when the main file is corrupt', async () => {
await database?.run(
'INSERT INTO tasks (id, title, sort_order, completed_at, created_at, updated_at) VALUES (?, ?, ?, NULL, ?, ?)',
['backed-up-task', 'Backed up', 1, '2026-07-22T09:00:00.000Z', '2026-07-22T09:00:00.000Z']
)
await database?.run(
'INSERT OR REPLACE INTO settings (key, value, updated_at) VALUES (?, ?, ?)',
['themePreference', '"dark"', '2026-07-22T09:01:00.000Z']
)
database?.close()
database = null
await copyFile(databasePath, `${databasePath}.bak`)
await writeFile(databasePath, Buffer.from('not a sqlite database'))

database = await createSqliteAppDatabase(databasePath)

expect(database.get<{ title: string }>('SELECT title FROM tasks WHERE id = ?', ['backed-up-task'])?.title).toBe(
'Backed up'
)
})
})
Loading
Loading