# 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
- 生产环境注意备份数据库
- 不要提交敏感配置到仓库

## 运行命令
```bash
cd ~/develop/din
source ~/develop/.venv/bin/activate
python app.py
# 访问 http://localhost:5000
```

## 常见任务

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

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

### 备份数据
```bash
cp din.db din.db.backup.$(date +%Y%m%d)
```

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