# FocusFlow

**Repository Path**: li-shaoting/focus-flow

## Basic Information

- **Project Name**: FocusFlow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-04-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FocusFlow

专注时间追踪工具 — 记录每一刻的专注与成长。

## 功能特性

- **专注计时器** — 支持开始、暂停、继续、结束，实时显示翻牌式计时
- **任务分类** — 内置工作、学习、运动、娱乐四大类别，各自配色与图标
- **今日时间轴** — 可视化展示当日专注记录的时间分布
- **每日统计** — 总时长、专注次数、最长连续、分类占比一目了然
- **周报统计** — Canvas 绘制柱状图与环形图，分析一周专注趋势
- **历史记录** — 按日期分组浏览、按日期筛选、支持删除
- **深色模式** — 支持 light/dark 主题切换，兼容 iframe 嵌入场景
- **数据持久化** — SQLite 后端存储，自动迁移旧版 localStorage 数据
- **一键部署** — 构建产物由 Express 直接托管，PM2 管理进程

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端 | React 18 · TypeScript · Tailwind CSS · Framer Motion · Recharts · Lucide Icons |
| 路由 | React Router DOM (HashRouter) |
| 后端 | Express 5 · better-sqlite3 · CORS |
| 构建 | Webpack 5 · Babel · PostCSS |
| 部署 | PM2 · Nginx (可选) |

## 项目结构

```
FocusFlow/
├── server.js              # Express 后端（API + 静态文件托管）
├── index.html             # HTML 模板（含主题防闪烁脚本）
├── webpack.config.js      # Webpack 配置
├── tailwind.config.js     # Tailwind CSS 配置
├── postcss.config.js      # PostCSS 配置
├── tsconfig.json          # TypeScript 配置
├── package.json
├── src/
│   ├── index.tsx           # 入口文件
│   ├── App.tsx             # 根组件（路由、页面布局）
│   ├── types/
│   │   └── index.ts        # 类型定义（TaskCategory, TimeRecord, DailyStats, WeeklyStats）
│   ├── hooks/
│   │   ├── useStorage.tsx  # 数据层 Hook（CRUD、统计、localStorage 迁移）
│   │   └── useTheme.ts     # 主题 Hook（light/dark 切换、iframe 消息监听）
│   ├── components/
│   │   ├── Timer.tsx       # 计时器（翻牌数字、分类选择、开始/暂停/结束）
│   │   ├── Timeline.tsx    # 今日时间轴
│   │   ├── StatsCards.tsx  # 每日统计卡片
│   │   ├── WeeklyReport.tsx# 周报（Canvas 柱状图 + 环形图）
│   │   ├── History.tsx     # 历史记录（日期筛选、分组、删除）
│   │   └── Sidebar.tsx     # 侧边导航栏
│   └── styles/
│       └── index.css       # 全局样式 + CSS 变量
├── DEPLOY.md               # 详细部署指南
└── LICENSE                 # MIT License
```

## 页面路由

| 路径 | 页面 | 说明 |
|------|------|------|
| `/` | 仪表盘 | 计时器 + 时间轴 + 统计卡片 |
| `/report` | 周报 | 本周专注数据可视化 |
| `/history` | 历史 | 全部记录浏览与管理 |

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/records` | 获取所有记录 |
| `POST` | `/api/records` | 新增记录 |
| `PUT` | `/api/records/:id` | 更新记录 |
| `DELETE` | `/api/records/:id` | 删除记录 |
| `POST` | `/api/migrate` | 迁移 localStorage 数据 |

## 快速开始

### 环境要求

- Node.js >= 16
- npm >= 8

### 安装与开发

```bash
# 安装依赖
npm install

# 启动开发环境（前端 :3266 + 后端 :3267）
npm start

# 或分别启动
npm run dev      # 前端开发服务器 (port 3266)
npm run server   # 后端 API 服务器 (port 3267)
```

开发模式下，前端 devServer 自动将 `/api` 请求代理到后端 `http://localhost:3267`。

### 构建与部署

```bash
# 构建生产版本
npm run build

# 使用 PM2 启动（生产模式自动托管 dist/ 静态文件）
pm2 start server.js --name focusflow
```

详细部署步骤请参考 [DEPLOY.md](./DEPLOY.md)。

## 数据存储

- **后端**：SQLite 数据库（`focusflow.db`），WAL 模式，含 `startTime` 和 `categoryId` 索引
- **迁移**：首次启动时自动检测 `localStorage_backup.json` 或浏览器 localStorage 中的旧数据并迁移至 SQLite
- **字段**：`id` (TEXT PK) · `categoryId` (TEXT) · `startTime` (INTEGER) · `endTime` (INTEGER NULL) · `duration` (INTEGER)

## 主题支持

- 通过 CSS class (`light` / `dark`) 和 `data-theme` 属性控制主题
- iframe 嵌入场景下，监听父窗口 `postMessage` 实现主题同步
- HTML 内联脚本确保首次渲染无闪烁

## License

[MIT](./LICENSE) © 2026 李少庭