# 日期功能說明
## 📅 功能概述
`viz` 和 `raw` 命令現在支援指定日期查詢，讓您可以查看過去或未來特定日期的天氣數據。
## 🚀 使用方法
### 互動模式
#### viz 命令
```bash
# 查看今天的天氣（預設）
viz Tokyo
# 查看昨天的天氣
viz Tokyo 2025-10-01
# 查看明天的天氣
viz Paris 2025-10-03
# 查看過去某天的天氣
viz London 2025-09-25
```
#### raw 命令
```bash
# 查看今天的原始數據（預設）
raw Tokyo
# 查看昨天的原始數據
raw Tokyo 2025-10-01
# 查看明天的原始數據
raw Paris 2025-10-03
# 查看未來某天的原始數據
raw Berlin 2025-10-10
```
### 命令列模式
```bash
# 查看今天的天氣視覺化
python main.py --mode viz --city Tokyo
# 查看昨天的天氣視覺化
python main.py --mode viz --city Tokyo --date 2025-10-01
# 查看明天的天氣視覺化
python main.py --mode viz --city Paris --date 2025-10-03
# 自訂小時數
python main.py --mode viz --city London --date 2025-10-02 --hours 12
```
## 📊 功能特性
### 智能小時數計算
系統會根據日期自動調整顯示的小時數：
- **今天**：從午夜 00:00 到當前時間
- **其他日期**：完整的 24 小時
您也可以使用 `--hours` 參數手動指定小時數。
### 日期範圍
- **歷史數據**：最多支援 92 天前
- **預測數據**：最多支援 16 天後
- **日期格式**：`YYYY-MM-DD`（例如：2025-10-01）
### 自動計算參數
系統會自動判斷日期並計算所需參數：
| 日期 | 自動設定 |
|------|---------|
| 昨天 (2025-10-01) | `past_days=1, forecast_days=1` |
| 今天 (2025-10-02) | `past_days=0, forecast_days=1` |
| 明天 (2025-10-03) | `past_days=0, forecast_days=2` |
## 💡 使用範例
### 範例 1：比較昨天和今天的天氣
```bash
# 互動模式
viz Tokyo 2025-10-01 # 昨天
viz Tokyo # 今天
```
### 範例 2：查看未來一週的天氣預測
```bash
# 查看不同日期
viz Paris 2025-10-03 # 明天
viz Paris 2025-10-04 # 後天
viz Paris 2025-10-09 # 一週後
```
### 範例 3：獲取原始數據進行分析
```bash
# 取得昨天的原始數據
raw London 2025-10-01
# 取得今天的原始數據
raw London
# 取得明天的原始數據
raw London 2025-10-03
```
## 📁 輸出檔案
### 視覺化圖表
圖表檔案會根據城市和日期命名：
```
weather_Tokyo_2025-10-01.png # 昨天東京天氣
weather_Tokyo_today.png # 今天東京天氣
weather_Paris_2025-10-03.png # 明天巴黎天氣
```
## 🔍 日誌記錄
所有查詢都會記錄在 `mcp_server.log`，顯示自動計算的參數：
```
🌤️ get_weather(lat=35.6895, lon=139.69171, hours=24, target_date='2025-10-01', calculated: past_days=1, forecast_days=1)
🌤️ get_weather(lat=48.85341, lon=2.3488, hours=24, target_date='2025-10-03', calculated: past_days=0, forecast_days=2)
```
## ⚠️ 注意事項
1. **日期格式**：必須使用 `YYYY-MM-DD` 格式
2. **API 限制**：
- 歷史數據：最多 92 天前
- 預測數據：最多 16 天後
3. **不提供日期**：系統會自動使用今天的日期
## 🧪 測試腳本
執行測試腳本驗證功能：
```bash
python examples/test_date_feature.py
```
## 📚 相關文件
- [HISTORICAL_WEATHER.md](HISTORICAL_WEATHER.md) - 歷史天氣查詢詳細說明
- [MULTI_DAY_FORECAST.md](MULTI_DAY_FORECAST.md) - 多日預報功能
- [README.md](../README.md) - 專案主要文件
---
**更新日期**: 2025-10-02
**版本**: v3.1.0
