# 专注

**Repository Path**: cloud-lumiere/focus

## Basic Information

- **Project Name**: 专注
- **Description**: 一个面向大学生的 Web 应用，帮助提升注意力、管理任务与时间。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 专注辅助程序 (Focus Assistant)

一个面向大学生的 Web 应用，帮助提升注意力、管理任务与时间。

## 功能特性

- **自由计时器** — 点击开始/停止记录专注时长，可关联当前任务，实时显示计时
- **任务管理** — 创建、编辑、删除任务，支持截止日期和进度跟踪（过期高亮警告）
- **数据看板** — 使用 Chart.js 展示四个可视化：每日专注时长（柱状图）、每周趋势（折线图）、时段分布（环形图）、专注时间轴（按天展示各时段分布）
- **数据管理** — 导出/导入 JSON 备份、清除全部数据、浏览和删除单条专注记录
- **SQLite 存储** — 零配置，单文件数据库

## 技术栈

| 层级     | 技术                          |
| -------- | ----------------------------- |
| 后端     | Python Flask + Flask-SQLAlchemy |
| 前端     | HTML / CSS / JavaScript       |
| UI 框架  | Bootstrap 5 (CDN)             |
| 图表     | Chart.js 4 (CDN)              |
| 数据库   | SQLite                        |

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 运行应用

```bash
python app.py
```

### 3. 访问

打开浏览器访问 `http://127.0.0.1:5000`

## 项目结构

```
专注/
├── app.py              # Flask 应用入口（路由、模型、API）
├── requirements.txt    # Python 依赖
├── README.md           # 本文件
├── focus.db            # SQLite 数据库（首次运行自动生成）
└── templates/
    ├── base.html       # 基础模板（导航栏、页脚、CDN 引用）
    ├── index.html      # 首页 / 计时器页面
    ├── tasks.html      # 任务管理页面
    ├── dashboard.html  # 数据看板页面（含时间轴）
    └── data.html       # 数据管理页面（导出/导入/清除/记录列表）
```

## API 接口

### 任务

| 方法   | 路径                | 说明         |
| ------ | ------------------- | ------------ |
| GET    | `/api/tasks`        | 获取所有任务 |
| POST   | `/api/tasks`        | 创建任务     |
| PUT    | `/api/tasks/<id>`   | 更新任务     |
| DELETE | `/api/tasks/<id>`   | 删除任务     |

### 专注记录

| 方法   | 路径                           | 说明                 |
| ------ | ------------------------------ | -------------------- |
| GET    | `/api/focus/sessions`          | 获取所有专注记录     |
| POST   | `/api/focus/sessions`          | 记录一次专注会话     |
| DELETE | `/api/focus/sessions/<id>`     | 删除单条专注记录     |

### 数据分析

| 方法 | 路径                             | 说明                           |
| ---- | -------------------------------- | ------------------------------ |
| GET  | `/api/focus/today`               | 今日专注总分钟数               |
| GET  | `/api/focus/daily`               | 最近 7 天每日专注分钟数         |
| GET  | `/api/focus/weekly`              | 最近 4 周每周专注分钟数         |
| GET  | `/api/focus/period-distribution` | 六大时段专注分钟数分布           |
| GET  | `/api/focus/week-summary`        | 本周专注总时长概览              |
| GET  | `/api/focus/timeline?days=7`     | 专注时间轴（按天分组）          |

### 数据管理

| 方法   | 路径                     | 说明                 |
| ------ | ------------------------ | -------------------- |
| GET    | `/api/data/export`       | 导出全部数据为 JSON  |
| POST   | `/api/data/import`       | 从 JSON 文件导入     |
| DELETE | `/api/data/clear`        | 清除全部数据         |

## 数据模型

**Task（任务）**
- `id` — 主键
- `name` — 名称（必填）
- `deadline` — 截止日期（可选）
- `progress` — 进度 0–100%
- `created_at` — 创建时间

**FocusSession（专注会话）**
- `id` — 主键
- `start_time` — 开始时间
- `end_time` — 结束时间
- `duration_seconds` — 专注时长（秒）
- `task_id` — 关联任务 ID（外键，可空）

## 注意事项

- 请使用 Python 3.8 或更高版本
- 所有数据存储在项目根目录的 `focus.db` 文件中
- 删除任务时，相关专注记录不会删除，仅解除关联
- 数据导入支持两种模式：`replace`（替换全部）和 `merge`（合并追加）