aa892e17fb
All checks were successful
continuous-integration/drone/push Build is passing
主要改进： - 使用 dataclass 替代字典存储比赛数据，提高类型安全性 - 实现自动重试机制，添加指数退避 - 使用 Python logging 模块，支持多级别日志 - 拆分大函数为多个专门的方法，提高可维护性 - 实现优雅降级，单个失败不影响整体流程 - 将 v3 版本移至 legacy 目录存档 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
150 lines
5.2 KiB
Markdown
150 lines
5.2 KiB
Markdown
# Dota 2 Calendar Sync v4.0
|
||
|
||
自动从 Liquipedia 获取 Dota 2 Tier 1 比赛信息并同步到 Google Calendar，支持自动更新比赛结果、时间变更、智能管理TBD占位事件、自动清理过期和重复比赛。
|
||
|
||
**v4.0 新特性**：
|
||
- 🏗️ 代码结构重构：使用 dataclass 替代字典，提高类型安全性
|
||
- 🔄 增强错误处理：添加自动重试机制（指数退避）
|
||
- 📝 专业日志系统：使用 Python logging 模块，支持多级别日志
|
||
- 🛡️ 优雅降级：部分失败不影响整体同步流程
|
||
- ⚡ 代码模块化：拆分大函数，提高可维护性
|
||
|
||
## 功能
|
||
|
||
- 自动获取 Liquipedia 上的 Tier 1 级别 Dota 2 比赛
|
||
- 包括 The International、Major、Premier 级别赛事
|
||
- 自动创建 Google Calendar 事件
|
||
- **自动更新已完成比赛的结果和比分**
|
||
- **检测并更新比赛时间变更**（赛程调整时自动同步）
|
||
- **智能管理TBD占位事件**（自动更新队伍信息，删除过期和被取代的事件）
|
||
- **自动清理重复比赛**（优先保留已完成的比赛记录）
|
||
- **增强的TBD事件清理**（删除已结束但仍包含TBD的事件，删除与确认比赛同时间的TBD占位符）
|
||
- 避免重复添加已存在的比赛
|
||
- 支持 dry-run 模式进行测试
|
||
|
||
## 前置要求
|
||
|
||
### 1. Google Calendar 设置
|
||
|
||
你需要将你的 Google Calendar 分享给服务账号：
|
||
|
||
1. 打开 Google Calendar
|
||
2. 进入日历设置
|
||
3. 在"与特定人员共享"部分，添加：
|
||
- Email: `calendar-bot@tunpok.iam.gserviceaccount.com`
|
||
- 权限: "进行更改"（Make changes to events）
|
||
|
||
### 2. Python 环境
|
||
|
||
使用 pyenv 和虚拟环境：
|
||
|
||
```bash
|
||
pyenv activate test-venv
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 激活虚拟环境
|
||
source $(pyenv prefix test-venv)/bin/activate
|
||
|
||
# 运行同步（使用默认的 primary 日历）
|
||
python sync_dota2_matches.py
|
||
|
||
# 指定特定的 Google Calendar
|
||
python sync_dota2_matches.py --calendar-id "091325d4ea74ad78387402db1a428390c4779dff573322863b6fca00194da024@group.calendar.google.com"
|
||
|
||
# 使用调试模式查看详细日志
|
||
python sync_dota2_matches.py --log-level DEBUG
|
||
```
|
||
|
||
### Dry Run 模式
|
||
|
||
在实际添加事件之前，先测试看看会添加哪些比赛：
|
||
|
||
```bash
|
||
python sync_dota2_matches.py --dry-run
|
||
```
|
||
|
||
### 命令行参数
|
||
|
||
- `--calendar-id`: Google Calendar ID 或邮箱地址（默认: primary）
|
||
- `--dry-run`: 只显示将要添加的比赛，不实际创建事件
|
||
- `--no-results`: 跳过更新已完成比赛的结果
|
||
- `--no-time-updates`: 跳过更新比赛时间变更
|
||
- `--credentials`: 服务账号凭据文件路径（默认: credentials.json）
|
||
- `--log-level`: 设置日志级别 (DEBUG, INFO, WARNING, ERROR)
|
||
|
||
## 文件说明
|
||
|
||
- `sync_dota2_matches.py`: 主同步脚本（v4版本 - 优化版）
|
||
- `legacy/`: 历史版本脚本存档
|
||
- `credentials.json`: Google 服务账号凭据（需要自行添加）
|
||
- `requirements.txt`: Python 依赖包
|
||
- `run_sync.sh`: 便捷运行脚本
|
||
- `TIMEZONE_INFO.md`: 时区转换说明
|
||
- `CHANGELOG.md`: 版本更新历史
|
||
- `legacy/`: 旧版本脚本存档
|
||
|
||
## 功能特点
|
||
|
||
1. **智能匹配识别**：
|
||
- 自动识别 Tier 1、Premier、Major 级别赛事
|
||
- 支持 The International (TI) 赛事
|
||
- 提取比赛格式（Bo1、Bo3、Bo5）
|
||
- **智能去重**：相同时间、相同轮次的 TBD 比赛只保留一个代表
|
||
- **TBD比赛保护**：确保TBD vs TBD的比赛不会被错误标记为已完成
|
||
- **改进的TBD匹配**：1小时时间窗口匹配，更好处理赛程调整
|
||
- **重复比赛清理**：自动检测并删除同队伍的重复事件
|
||
- **TBD事件自动删除**：当队伍确定后自动删除对应的TBD占位符
|
||
- **增强的过期事件清理**：自动删除已结束但仍包含TBD的事件
|
||
- **智能TBD vs TBD处理**：删除与确认比赛在同一时间段的TBD vs TBD占位符
|
||
|
||
2. **日历事件管理**：
|
||
- 自动设置比赛时长（根据 Bo 格式估算）
|
||
- 添加 30 分钟提醒
|
||
- 使用蓝色标记 Dota 2 事件
|
||
- 避免重复添加
|
||
- **自动更新已完成比赛的结果**
|
||
- **在标题添加完成标记（✓ + 比分）**
|
||
- **TBD 比赛队伍确定后自动更新**
|
||
- **自动清理过期的TBD占位事件**
|
||
|
||
3. **错误处理**：
|
||
- 网络请求超时处理
|
||
- API 错误重试
|
||
- 详细的错误日志
|
||
- **改进的比分解析**：避免将时间(19:00)误识别为比分
|
||
|
||
## 定时运行
|
||
|
||
可以设置 cron job 定期运行同步：
|
||
|
||
```bash
|
||
# 编辑 crontab
|
||
crontab -e
|
||
|
||
# 每天早上 9 点运行同步
|
||
0 9 * * * cd /Users/ching/develop/dota2-calendar && /Users/ching/.pyenv/versions/3.10.14/envs/test-venv/bin/python sync_dota2_matches.py --calendar-id your-email@gmail.com
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. 确保已经将日历分享给服务账号邮箱
|
||
2. 首次运行建议使用 `--dry-run` 测试
|
||
3. Liquipedia 页面结构可能会变化，如果解析失败需要更新解析逻辑
|
||
|
||
## 故障排查
|
||
|
||
如果没有找到比赛：
|
||
1. 检查 Liquipedia 页面是否可以访问
|
||
2. 运行 `python fetch_liquipedia.py` 查看页面结构
|
||
3. 确认是否有正在进行的 Tier 1 赛事
|
||
|
||
如果无法添加到日历：
|
||
1. 确认已经正确分享日历给服务账号
|
||
2. 检查 credentials.json 文件是否有效
|
||
3. 确认使用了正确的 calendar-id |