# 番茄钟

**Repository Path**: houyunlong1668/pomodoro-timer

## Basic Information

- **Project Name**: 番茄钟
- **Description**: 自己玩玩，不过就是一个简单的玩具
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://ikonwmyself.online/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 番茄钟

**在线版：https://ikonwmyself.online/** — 打开即用，无需注册，数据只存本地。

一个纯本地的番茄工作法计时器：计时、统计、数据自主掌控。基于 Vue 3 + Vite 构建，图表全部手写 SVG，无第三方图表与 UI 组件库。

**没有服务端，没有账号，没有注册。** 数据存在你自己的浏览器里，或者存进你自己指定的一个文件 —— 想放哪、想怎么备份，由你决定。

## 功能

### 计时

- **三种预设** — 专注 25 分钟 / 短休 5 分钟 / 长休 15 分钟，另支持 1–180 分钟自定义时长
- **环形进度条** — SVG 圆环实时展示剩余时间，切换模式时颜色随之变化
- **挂钟校正** — 以 `endTimestamp` 为准而非累加 tick，标签页切到后台也不累积漂移
- **标签页标题同步** — 浏览器标签直接显示剩余时间，归零显示「时间到！」
- **任务标题** — 可为每次专注命名，常用标题自动保存（最多 20 条）并支持搜索、复用、删除
- **提示音** — 默认播放 Web Audio 合成的五音和弦（无需通知权限），也可上传自定义音频（mp3/wav/ogg/m4a）

### 统计

- **月历热力图** — 每日专注强度以颜色深浅呈现，保留日期数字
- **本周专注柱状图** — 选中日期所在周（周一至周日）的每日专注时长，可悬浮查看明细
- **本月趋势 sparkline** — 嵌在柱状图卡片里的迷你折线，附带「选中周高亮段」与「今天点」
- **事项饼图** — 按标题聚合选中日期的专注分布，扇区悬浮放大、图例联动高亮
- **两种口径并存** — 热力图计总时长（含休息），柱状图与趋势线只计专注时长

### 数据（核心特性）

- **默认存在浏览器** — 打开即用，不弹任何引导，数据写进 IndexedDB
- **也可以存进你自己的文件** — Chrome / Edge 桌面端可以指定一个 JSON 文件（如放在网盘同步目录），之后所有改动实时写入该文件；你用编辑器改它、用网盘同步它都生效
- **导出 / 导入** — 随时导出成 JSON 备份；导入时可选择「合并」（按时间/类型/标题/时长去重）或「覆盖」，覆盖会二次确认
- **自动迁移旧数据** — 旧版本留在浏览器里的分日记录会在首次启动时自动并入
- **多标签页同步** — 同时开多个标签页不会互相覆盖
- **不做自动过期** — 数据全部保留，只在数据面板里提供手动清理

> **请务必定期导出备份。** 如果只存在浏览器里，清除浏览器数据就会丢掉全部记录 —— 这是本地优先方案必须接受的代价。

### 其他

- **考研倒计时** — 首页顶部卡片，精确到秒，目标日期可配置
- **三态主题** — 亮色 / 暗色 / 跟随系统，切换带过渡动画，刷新后保持
- **打赏** — 右下角悬浮球展示收款码（静态图片，不含任何支付逻辑）
- **响应式** — 移动端与桌面端分别适配

## 浏览器兼容性

| 浏览器          | 指定数据文件 | 浏览器存储 | 说明                         |
| --------------- | ------------ | ---------- | ---------------------------- |
| Chrome / Edge   | 支持         | 支持       | 完整体验                     |
| Safari 桌面     | 部分支持     | 支持       | 视版本而定，不支持则自动降级 |
| iOS Safari      | 不支持       | 支持       | 只能浏览器存储 + 手动导入导出 |
| Firefox         | 不支持       | 支持       | 同上                         |

不支持文件能力时，「指定数据文件」入口会隐藏，并在面板里说明原因，而不是点了没反应。

## 技术栈

| 类别     | 技术                                                                      |
| -------- | ------------------------------------------------------------------------- |
| 前端框架 | Vue 3（Composition API + `<script setup>`） + Vite 8                      |
| 状态管理 | Pinia 3                                                                   |
| 语言     | TypeScript（`@typescript/native-preview` / tsgo 编译器）                  |
| 路由     | vue-router（hash 模式）                                                   |
| 数据存储 | File System Access API + IndexedDB，**无服务端**                          |
| 图表     | 纯 SVG，零依赖                                                            |
| 音频     | Web Audio API 合成提示音                                                  |
| 测试     | Vitest + @vue/test-utils + jsdom                                          |
| 部署     | EdgeOne Pages（纯静态，含 CSP / HSTS 等安全响应头）                       |
| 包管理   | pnpm 11                                                                   |

**运行时零网络请求。** 构建产物 86 个模块，主包 160.24 kB（gzip 59.22 kB / brotli 51.27 kB）。

## 快速开始

环境要求：Node.js `^20.19.0 || >=22.12.0`，pnpm。

```sh
pnpm install
pnpm dev
```

不需要配置任何环境变量。

## 常用命令

```sh
pnpm dev           # 开发服务器
pnpm build         # 类型检查 + 生产构建 → dist/
pnpm build-only    # 仅构建，跳过类型检查
pnpm type-check    # tsgo --noEmit
pnpm test          # 单次跑全部测试
pnpm test:watch    # 测试监听模式
pnpm lint          # ESLint 自动修复
pnpm lint:check    # ESLint 仅检查
pnpm format        # Prettier 格式化 src/
```

提交前请确保四道门禁全部通过（仓库当前无远程 CI，需本地执行）：

```sh
pnpm lint:check && pnpm type-check && pnpm test && pnpm build
```

## 部署

构建产物是纯静态文件，托管在 EdgeOne Pages。`public/edgeone.json` 定义了安全响应头，其中 CSP 的 `connect-src` 已收紧为 `'self'`。

**关于收款码**：`public/alipay-qr.png` 是打赏功能依赖的唯一静态资源。`.gitignore` 的 `*.png` 规则原本会把它排除，现已加了 `!public/alipay-qr.png` 例外 —— 它是构建产物，缺失会让线上打赏面板显示占位态。

## 项目结构

```
src/
├── main.ts              # 入口（无鉴权初始化）
├── router/              # hash 路由 + 通配回首页
├── stores/              # Pinia：storage（存储后端）、sessions（内存快照）
├── composables/         # usePomodoroEngine / useAudio / useTheme / useTitleDropdown
├── utils/               # localDb / fileStore / backup / date / errors / color
├── components/          # 计时器、图表、弹窗、数据面板
├── views/               # HomeView
├── types/               # 领域类型与校验口径
└── assets/              # 设计 tokens、全局样式
```

## 文档

- [`AGENTS.md`](AGENTS.md) — 面向 AI 编码助手的仓库总览（架构决策、路由表、约定）
- [`docs/glossary.md`](docs/glossary.md) — 领域术语表
- [`docs/adr/`](docs/adr/) — 架构决策记录，特别是 [ADR 0004](docs/adr/0004-local-first-no-backend.md)（为什么去掉服务端）
- [`docs/superpowers/specs/2026-09-12-local-only-storage.md`](docs/superpowers/specs/2026-09-12-local-only-storage.md) — 本地优先改造的完整规格
- `src/*/AGENTS.md` — 各子目录职责卡

## 许可证

见 [LICENSE](LICENSE)。