# qtime

**Repository Path**: sharpguo/qtime

## Basic Information

- **Project Name**: qtime
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QTime - 申请季学生时间管理系统

QTime 是一个专为准备申请大学的高中生设计的时间管理 Web 应用，帮助学生高效管理碎片化时间、跟踪作业截止日期，并为家长提供学习进度监管视图。

## 🌟 功能特色

### 📅 课程表管理
- 添加课程（名称、教师、教室、颜色）
- 周视图课程表展示
- 支持不规则课表（如周一2节课，周二5节课）
- 点击空白格子添加上课时间

### 📝 作业管理
- 添加任务（标题、截止日期、预估时间、类别、优先级）
- 任务类别：作业、考试、项目、SAT、大学申请、其他
- 按截止日期自动排序
- 截止日期提醒（今天、明天、X天后、已过期）
- 一键标记完成
- 多种筛选查看（待完成/已完成/全部）

### ⏰ 时间块规划
- 日视图时间轴（06:00-24:00）
- 显示当天课程安排
- 在空闲时间段添加学习计划
- 关联具体任务
- 标记时间块完成状态

### 🍅 番茄钟计时
- 25分钟专注 + 5分钟休息（可配置）
- 可选择关联任务
- 自动记录学习时长
- 完成提示音
- 今日番茄数统计

### 👨‍👩‍👧‍👦 家长监管视图
- 今日学习进度条（目标 vs 实际）
- 统计卡片：今日番茄、本周完成、待完成、已过期
- 最近7天学习时长图表
- 近期待办任务列表
- 最近活动记录
- 过期任务警告提醒

### 💾 数据管理
- 导出全部数据（JSON备份）
- 导入数据恢复
- 快速批量添加任务（文本格式解析）
- 数据统计概览

## 🛠️ 技术栈

- **前端框架**: React 18 + TypeScript
- **构建工具**: Vite 6
- **样式框架**: Tailwind CSS 3.4
- **图标库**: Lucide React
- **数据存储**: localStorage（纯前端，无后端）

## 🚀 快速开始

### 环境要求
- Node.js 18+ 
- npm

### 安装步骤

1. 克隆项目：
```bash
git clone <repository-url>
cd qtime
```

2. 安装依赖：
```bash
npm install
```

3. 启动开发服务器：
```bash
npm run dev
```

4. 在浏览器中访问 `http://localhost:5173`

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

### 预览构建结果
```bash
npm run preview
```

## 📋 使用流程

### 学生日常使用
1. 每周初：确认/更新课程表
2. 每天：从 PowerSchool 手动同步新作业
3. 每天：在时间规划页安排空闲时间
4. 学习时：使用番茄钟专注
5. 完成后：标记任务完成

### 家长监管
1. 定期查看"进度"页面
2. 关注过期任务警告
3. 查看学习时长趋势
4. 了解近期待办情况

## 📁 项目结构

```
src/
├── components/          # UI 组件
│   ├── Schedule.tsx     # 课程表（课程管理 + 周视图）
│   ├── Assignments.tsx  # 作业管理（CRUD + 筛选 + 截止提醒）
│   ├── TimeBlocks.tsx   # 时间块规划（日视图 + 任务分配）
│   ├── Pomodoro.tsx     # 番茄钟（计时器 + 进度环）
│   ├── ParentView.tsx   # 家长视图（统计 + 趋势图 + 警告）
│   ├── DataImport.tsx   # 数据导入导出
│   └── Settings.tsx     # 设置页
├── hooks/
│   └── useAppData.ts    # 核心状态管理 Hook
├── types/
│   └── index.ts         # TypeScript 类型定义
├── utils/
│   ├── storage.ts       # localStorage 读写
│   └── date.ts          # 日期格式化工具
├── App.tsx              # 主应用（路由 + 布局）
├── main.tsx             # 入口
└── index.css            # Tailwind 入口
```

## 📊 核心数据模型

```typescript
// 课程
interface Course {
  id: string
  name: string
  teacher?: string
  room?: string
  color: string
}

// 课程表时间段
interface ScheduleSlot {
  id: string
  courseId: string
  dayOfWeek: number // 0-6
  startTime: string // "08:00"
  endTime: string
}

// 作业/任务
interface Assignment {
  id: string
  title: string
  courseId?: string
  description?: string
  dueDate: string
  priority: 'high' | 'medium' | 'low'
  status: 'pending' | 'in_progress' | 'completed'
  estimatedMinutes?: number
  actualMinutes?: number
  category: 'homework' | 'exam' | 'project' | 'sat' | 'college' | 'other'
  createdAt: string
  completedAt?: string
}

// 时间块
interface TimeBlock {
  id: string
  date: string
  startTime: string
  endTime: string
  assignmentId?: string
  title?: string
  type: 'study' | 'break' | 'free'
  completed: boolean
}

// 番茄钟会话
interface PomodoroSession {
  id: string
  assignmentId?: string
  startTime: string
  endTime?: string
  duration: number
  completed: boolean
  date: string
}
```

## 🔄 状态管理

使用自定义 Hook `useAppData()` 管理全局状态：
- 数据存储在 `localStorage`，key 为 `qtime_data`
- 所有数据变更自动触发保存
- 提供 CRUD 方法：`addCourse`, `updateAssignment`, `deleteTimeBlock` 等

## 📱 响应式设计

- 移动端优先
- 断点: `md:` (768px)
- 桌面端: 顶部导航
- 移动端: 底部 Tab 导航 + 汉堡菜单

## 🔧 扩展方向

### 可能的增强功能
- 云端同步（多设备）
- 微信/邮件推送提醒
- PowerSchool 数据爬取（需授权）
- 学习数据分析报告
- 目标设定与追踪
- 家长独立账号
- 奖励机制（完成任务换游戏时间）

## 🤝 贡献

欢迎提交 Issue 和 Pull Request 来帮助改进 QTime！

## 📄 许可证

MIT License