一、项目概览

FocusTrack 是一个全功能番茄钟桌面应用，将番茄工作法计时器、AI专注预测、习惯追踪、目标管理、待办事项五大模块融合。

---

二、架构设计

┌─────────────────────────────────────────────────────────┐
│                    main.py (834行)                       │
│  ┌──────────────┐    ┌──────────────────────────────┐   │
│  │  TimerState  │    │     FocusTrackApp (GUI)       │   │
│  │  - running   │    │  ┌──────┐ ┌──────┐ ┌──────┐ │   │
│  │  - tick()    │    │  │Stats │ │Charts│ │  AI  │ │   │
│  │  - skip()    │    │  ├──────┤ ├──────┤ ├──────┤ │   │
│  │  - _next_mode│    │  │Todo  │ │Habits│ │Goals │ │   │
│  └──────────────┘    │  └──────┘ └──────┘ └──────┘ │   │
│                      └──────────────────────────────┘   │
├─────────────────────────────────────────────────────────┤
│                 promodo_ai.py                    │
│  ┌──────────────────┐  ┌─────────────────┐             │
│  │ PomodoroPredictor │  │  TodoManager     │             │
│  │  - predict()      │  │  - add/toggle/   │             │
│  │  - answer()  ←──规则引擎AI              │             │
│  │  - forecast_summary│  │    delete()     │             │
│  └──────┬───────────┘  └─────────────────┘             │
├─────────┼───────────────────────────────────────────────┤
│         │         predictor.py                    │
│         │   ┌─────────────────────────┐                 │
│         └──→│ _linear_trend() 线性回归 │                 │
│             │ 混合预测: 70%近期均值    │                 │
│             │        + 30%趋势外推    │                 │
│             └─────────────────────────┘                 │
├─────────────────────────────────────────────────────────┤
│               study_tracker.py                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │Sessions  │ │  Todos   │ │ Habits   │ │  Goals   │  │
│  │JSON CRUD │ │JSON CRUD │ │JSON CRUD │ │JSON CRUD │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────┘

---

三、核心模块详解

1. TimerState — 番茄钟状态机（main.py）

状态转换逻辑:
  work ──完成──→ short_break (每N个→long_break)
  short_break/long_break ──完成──→ work
  
关键属性:
  - running / seconds_left / total_seconds
  - mode ∈ {work, short, long}
  - session_num / completed (完成的工作session数)
  - display: "MM:SS" 格式
  - progress: 0.0~1.0 进度比例

每次工作 session 完成时自动调用 add_session() 持久化记录。

2. predictor.py — 专注时间预测引擎

这是整个项目的 AI 核心，使用纯数学方法（无需外部模型）：

步骤	方法	说明
数据加载	_daily_minutes(30)	从 sessions.json 汇总过去30天每天的专注分钟
趋势拟合	_linear_trend()	最小二乘法线性回归，计算斜率(slope)和截距(intercept)
混合预测	0.7×近期均值 + 0.3×趋势外推	平衡近期表现与长期趋势，避免过拟合
等级评定	get_level()	≥120min Excellent, ≥75 Bon, ≥40 Modéré, <40 Faible
格式化	fmt_minutes()	60→"1h00m", 45→"45m"

预测公式：

raw_pred[i] = intercept + slope × (30 + i)     # 线性外推
blended[i]  = 0.7 × avg(last_7_days) + 0.3 × raw_pred[i]

3. PomodoroPredictor — AI 助手层（promodo_ai.py:25-83）

这是一个基于规则的 NLP 引擎，通过关键词匹配理解用户意图：

关键词	触发功能	返回内容
predict/forecast/next week	7天预测	每天预测值 + 等级 + 趋势
streak/consecutive	连续打卡	当前连续天数
today/so far	今日统计	今日分钟数 + session数
week/weekly	本周统计	本周总分钟数
tip/advice/improve	每日建议	基于日期哈希的随机专注建议
默认	综合摘要	今日/本周/连续/预测汇总

Tips 池（5条）：

1. 每天第一个 session 处理最难的任务
2. 工作时把手机放另一个房间
3. session 间散步5分钟提升记忆保持
4. 将浅层任务批量处理到下午一个 block
5. 固定开始时间训练大脑更快进入专注

4. study_tracker.py — 数据持久化层

四套完整的 CRUD 操作，对应四个 JSON 文件：

模块	文件	数据结构	核心操作
Sessions	sessions.json	{date, start, duration, type, completed}	add_session(), get_today_stats(), get_week_stats(), get_streak()
Todos	todos.json	{text, done, created}	add_todo(), toggle_todo(), delete_todo()
Habits	habits.json	{name, streak, last_done}	add_habit(), check_habit(), delete_habit()
Goals	goals.json	{name, target, current, unit, created}	add_goal(), progress_goal(), delete_goal()

Streak 算法（get_streak()）：从今天开始倒推，统计连续有工作 session 的天数，直到遇到中断。

---

四、UI 设计

CSS 变量风格

变量	色值	用途
BG	#080b10	主背景（极深蓝黑）
SURF	#0e1118	卡片/面板表面
SURF2	#141820	次级表面
SURF3	#1a2030	三级表面（按钮、进度条背景）
BORDER	#1f2535	边框
ACCENT	#ff6b35	主色调（橙）- Work 模式、主按钮
ACCENT2	#3d8bff	蓝色 - 图表、Todo
ACCENT3	#36d9a0	绿色 - Short Break、Habits
ACCENT4	#c87fff	紫色 - Long Break、Goals
TEXT	#e8eaf2	主文字
MUTED/MUTED2	#4a5268/#6b7591	次要文字

布局结构

┌────────────┬──────────────────────────────────────┐
│ LEFT 280px │           RIGHT (flex)                │
│            │ ┌──────┬──────┬──────┬──────┬──────┐ │
│ BRAND  │ │Stats │Charts│  AI  │ Todo │Habits│Goals│
│            │ ├──────┴──────┴──────┴──────┴──────┤ │
│  MODE BADGE│ │                                   │ │
│            │ │         CONTENT AREA              │ │
│  25:00     │ │   (tab切换通过 lift/lower)        │ │
│            │ │                                   │ │
│  Session   │ │                                   │ │
│  ████░░░░  │ │                                   │ │
│            │ │                                   │ │
│ [START][⏭][↺]│                                   │ │
│            │ │                                   │ │
│ ⚙ SETTINGS │ │                                   │ │
└────────────┴──────────────────────────────────────┘

字体系统

• Courier New 10pt — 正文等宽
• Courier New 60pt bold — 计时器大数字
• Segoe UI 10pt — 辅助文字

---

五、数据流

用户点击 START
    ↓
TimerState.toggle() → running=True
    ↓
_tick() 每1000ms → tick() → seconds_left--
    ↓
seconds_left == 0 → _next_mode()
    ↓
mode=="work"? → add_session(duration) 写入 sessions.json
    ↓                    ↓
completed++, 切换到break   切换到work
    ↓
_update_timer_display() 更新UI
    ↓
用户切换tab → _switch_tab() → _draw_bars()/_draw_predictions()
    ↓
用户Ask AI → _ask_ai() → PomodoroPredictor.answer() → 读取 sessions.json → predictor.predict() → 返回文字+图表