# yourTimer

**Repository Path**: ma-kuan/your-timer

## Basic Information

- **Project Name**: yourTimer
- **Description**: your-timer
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flow — 任务工时追踪

> 心中有数，游刃有余。一个轻量的桌面工时追踪工具，帮你量化工作、掌控进度。

[![Electron](https://img.shields.io/badge/Electron-28-%2347848f)](https://www.electronjs.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 概述

Flow 是一款基于 Electron 的桌面端工时追踪应用。不同于传统的倒计时番茄钟，Flow 采用 **「先规划，后追踪」** 的方式——你只需为每个子任务填入预估耗时，应用会自动推算结束时间，到期通过桌面通知提醒你。

数据完全存储在本地，无需注册账号。

## 功能特性

- **子任务拆解** — 将复杂任务拆分为可量化的子任务，逐项追踪
- **自动推算** — 根据子任务耗时和开始时间，自动计算每项的预计结束时间
- **即时反馈** — 页面时钟每秒更新，剩余/超时时间一目了然
- **桌面通知** — 子项到期时自动标记完成，并推送系统通知
- **灵活录入** — 直接输入预估耗时，无需开启倒计时
- **定时启动** — 设定未来开始时间，到点自动执行
- **历史记录** — 查看已完成任务，支持提取为模板复用
- **拖拽排序** — 任务卡片和子项均可拖拽调整顺序
- **自定义数据目录** — 支持将数据存储到指定位置

## 界面预览

| 页面 | 说明 |
|---|---|
| 产品介绍页 | 应用启动首页，展示核心功能和入口 |
| 任务面板 | 主仪表盘，管理进行中和已完成任务 |
| 计时视图 | 单任务详情，显示进度、计时和子项列表 |
| 编辑器 | 新建/编辑任务表单，管理子项和时间 |

## 技术栈

| 层级 | 技术 |
|---|---|
| 桌面容器 | Electron 28 |
| 前端 | 原生 HTML + CSS + JavaScript（无框架） |
| 设计系统 | CSS 自定义属性（Design Tokens） |
| 数据持久化 | 本地 JSON 文件（通过 IPC + fs） |
| 通知 | Electron Notification API |
| 打包 | electron-builder + NSIS |

## 快速开始

### 环境要求

- Node.js >= 18
- npm >= 9

### 安装与运行

```bash
# 克隆仓库
git clone https://gitee.com/ma-kuan/your-timer.git
cd your-timer

# 安装依赖
npm install

# 启动开发模式
npm run dev
```

### 构建安装包

```bash
# 构建 Windows 安装包
npm run build

# 构建到目录（不打包）
npm run build:dir
```

构建产物位于 `release/` 目录。

## 项目结构

```
flow-tracker/
├── package.json
├── src/
│   ├── main/
│   │   ├── main.js          # 主进程入口，窗口管理
│   │   ├── ipc.js            # IPC 通道注册
│   │   └── store.js          # JSON 文件持久化
│   ├── preload/
│   │   └── preload.js        # contextBridge API 暴露
│   └── renderer/
│       ├── landing.html       # 产品介绍页
│       ├── app.html           # 任务面板
│       ├── timer.html         # 计时视图
│       ├── editor.html        # 任务编辑器
│       ├── lib/
│       │   ├── utils.js       # 工具函数（时间计算、格式化等）
│       │   └── store.js       # 渲染进程 IPC 封装
│       └── styles/
│           └── tokens.css     # 设计系统 Token
├── designUI/                  # 设计原型（Electron 前身）
├── docs/
│   ├── requirements-analysis.md  # 需求分析文档
│   └── software-design.md        # 软件设计文档
└── release/                   # 构建输出
```

## 数据模型

### 任务

```json
{
  "id": "唯一标识",
  "name": "任务名称",
  "startTime": "ISO 8601 开始时间，或 null",
  "items": [ /* 子任务列表 */ ],
  "completed": false,
  "completedAt": "完成时间戳",
  "currentItemId": "当前进行中的子项 ID",
  "createdAt": "创建时间戳",
  "autoCompleted": false
}
```

### 子任务

```json
{
  "id": "唯一标识",
  "name": "子项名称",
  "durationSeconds": 3600,
  "completed": false,
  "order": 0,
  "autoCompleted": false
}
```

## 架构说明

- **进程模型**：主进程负责窗口管理和系统 API（通知、文件读写）；渲染进程负责 UI；preload 脚本通过 `contextBridge` 安全暴露 API
- **数据流**：渲染进程发起 IPC 请求 → 主进程处理文件读写 → 返回数据 → 渲染进程更新 UI
- **自动完成引擎**：根据子项累计耗时和任务开始时间，自动判断并标记已到期的子项（每秒或每 15 秒轮询）
- **页面路由**：页面间通过 URL 查询参数传递任务 ID，数据共享同一 JSON 文件

## 设计系统

Flow 使用 CSS 自定义属性构建统一的设计语言：

- **主色**：陶土橙 `#c96442`
- **背景**：暖米色 `#f5f4ed`
- **成功**：绿色 `#17a34a`
- **字体**：Serif 展示 + System UI 正文 + Monospace 数字

详细 Token 定义见 `src/renderer/styles/tokens.css`。

## 许可证

MIT License © 2026 makuan