din/AGENTS.md

din - AGENTS.md

项目简介

din (Do It Now) - 一个极简的「想到就做」记录器，PWA 应用，支持离线使用。

技术栈

• 后端: Python + Flask + SQLite
• 前端: 原生 HTML/CSS/JS (PWA)
• 时区: 东八区 (Asia/Shanghai)
• 仓库: https://git.tunpok.com/ching/din

项目结构

din/
├── app.py              # Flask 后端
├── achievements.json   # 成就配置（可自由扩展）
├── requirements.txt    # Python 依赖
├── README.md
└── static/             # 前端文件
    ├── index.html      # 主页面
    ├── style.css       # 样式
    ├── app.js          # 前端逻辑
    ├── manifest.json   # PWA 配置
    ├── sw.js           # Service Worker
    └── icon-*.png      # PWA 图标

开发规范

时区处理

重要: 所有时间必须使用东八区 (Asia/Shanghai)

• 后端使用 now_tz() 函数获取当前时间
• 数据库中存储带时区信息的时间字符串
• 成就统计中早晚判断必须使用东八区小时数

成就系统扩展

成就配置在 achievements.json，支持以下类型:

• total - 累计数量 (如: {"type": "total", "min": 100})
• streak - 连续天数 (如: {"type": "streak", "min": 7})
• day_max - 单日最高 (如: {"type": "day_max", "min": 10})
• content_count - 有描述的记录数
• early_time - 早起记录 (6点前)
• late_time - 晚睡记录 (23点后)

添加新成就只需编辑 JSON，无需修改代码。

Git 提交

• 每次功能完成后提交
• 提交信息用中文简要描述变更
• 先提交到本地，再推送到 origin

数据安全

• SQLite 数据库文件 din.db 已加入 .gitignore
• 生产环境注意备份数据库
• 不要提交敏感配置到仓库

运行命令

cd ~/develop/din
source ~/develop/.venv/bin/activate
python app.py
# 访问 http://localhost:5000

常见任务

添加新成就

1. 编辑 achievements.json
2. 添加新的成就对象
3. 重启服务生效

修改前端

1. 编辑 static/ 下的文件
2. 刷新浏览器（PWA 可能需要清除缓存）
3. 测试功能正常

备份数据

cp din.db din.db.backup.$(date +%Y%m%d)

注意事项

• PWA 缓存策略：Service Worker 会缓存静态资源
• 离线模式：IndexedDB 存储待同步记录
• 浏览器调试：Application 标签可查看 SW 和缓存