时间追踪器

支持自定义时区、番茄钟、手动 / 自动排序，为未来上云做好分层准备的时间追踪 TUI 程序。

项目结构

timetracker/
├── run.py                    # 启动入口
└── timetracker/
    ├── __init__.py
    ├── db.py                 # 数据访问层 (SQL only, 所有表带 user_id)
    ├── service.py            # 业务逻辑层 (无 UI, 未来 Web 直接复用)
    ├── tui.py                # TUI 界面 (Textual)
    └── main.py               # 装配入口

为什么这么分？ service.py 不依赖任何 UI 库，未来要上云：

• 把 db.py 换成 SQLAlchemy + PostgreSQL（改一个文件）
• 写一个 api.py（FastAPI 路由），每个路由调用同一个 TimerService 方法
• 前端写 Web / 移动端 UI
• tui.py 可以保留也可以删，互不影响

数据库每张表都有 user_id，本地版固定为 1。上云时改成真实用户 ID 即可，老数据零迁移成本。

安装与运行

pip install textual rich
python run.py

快捷键

计时器

键	功能
n	新建计时器
空格	启动 / 暂停选中计时器（支持多个并行）
r	重命名
d	删除（有确认弹窗）
e	导出会话 CSV 到 ~/timetracker_export_*.csv

排序

键	功能
s	切换排序模式（手动 ↔ 按累计时长降序）
[	手动模式下将当前计时器上移一格
]	手动模式下将当前计时器下移一格

• 手动模式：拖动顺序持久保存到数据库，重启后不变
• 自动模式：按实时计算的累计时长动态降序，只读（[ ] 无效）
• 副标题会实时显示当前排序模式

时区

键	功能
t	打开时区管理（弹窗内 a 添加 / d 删除 / Esc 关闭）

第一个时区（标 ★）是统计周期的基准——「今日 / 本周 / 本月」按它的零点界定。

番茄钟

键	功能
p	启动一个工作番茄
x	取消当前番茄（记录为未完成）
c	番茄钟设置（工作 / 短休 / 长休时长、长休间隔、响铃开关）

其他

键	功能
l	切换语言
q	退出（自动 checkpoint 后关闭）

番茄钟说明

• 独立功能：与普通计时器并行存在，互不影响
• 自定义时长：默认 25 分钟工作 / 5 分钟短休 / 15 分钟长休 / 每 4 个工作番茄后长休一次
• 完成时双重提醒：终端响铃（\a）+ 状态栏通知；响铃可在设置里关掉
• 完成的番茄记录入库：pomodoros 表，可用于后续统计
• 中途取消：记录为 completed=0，不计入今日完成数

时区管理

任意添加 IANA 时区，例如：

Europe/Paris  /  Asia/Shanghai  /  America/New_York  /  Asia/Tokyo  /  UTC

添加时按关键词搜索（不区分大小写），多个匹配项时弹出选择列表。
顶部时钟栏按配置的时区数量自动横向铺开。

数据存储

• 路径：~/.timetracker.db（SQLite）
• 备份：cp ~/.timetracker.db backup.db

表	内容
users	用户表（本地版固定 1 条）
user_prefs	用户偏好（时区列表、番茄钟配置、排序模式，key-value 结构）
timers	计时器主表（含 sort_order 字段用于手动排序）
sessions	计时会话日志（每次启停一条，累计时长从此表实时求和）
pomodoros	番茄钟会话日志

异常恢复

• 每 10 秒自动 checkpoint 所有运行中计时器
• 程序崩溃 / 断电时，最多丢失最后 10 秒进度
• 下次启动自动检测并恢复，状态栏会提示已恢复的计时器
• 停止计时器与写入会话日志在同一事务内完成，不会因崩溃产生数据不一致

统计逻辑说明

• 「今日 / 本周 / 本月」的边界按首选时区的零点计算
• 累计时长从 sessions 表实时求和，不依赖存在截断误差的缓存字段
• 运行中的计时器实时叠加当前会话时长（精确到秒），不等待下一次 checkpoint

上云改造路径（未来参考）

按改动量从小到大：

1. 数据库换 PostgreSQL：改 db.py 的连接和 SQL 方言（推荐 SQLAlchemy，约 200 行）
2. 加 Web API：新增 api.py，FastAPI 路由调用 TimerService 方法，从 JWT 取 user_id 传入
3. 加认证：FastAPI + python-jose 做 JWT，加注册 / 登录路由
4. 前端：任意框架，REST API 均标准
5. Checkpoint 机制改造：改为服务端按「上次心跳」截断，或启停时由客户端调 API 结算

service.py 里的 TimerService 是核心资产，上云时基本不用改业务逻辑——这是分层的最大价值。