# 📊 Google Apps Script 專案說明：中油油價通知推播系統

> 這份筆記幫助任何人——即使是不會寫程式的使用者，也能理解這份程式在做什麼、為什麼這樣寫。

---

## 🚀 系統功能概覽

這個 GAS 專案的目的是：
- 每週自動從中油網站抓取下週油價與新聞稿
- 組裝成漂亮的 LINE Flex Message 卡片
- 發送給事先定義的 LINE 使用者群組
- 並將整個過程紀錄到 Google 試算表中備查

---

## 🔧 基本設定區

const LOG_SHEET_ID = '...'; // Google Sheet 的 ID
const LOG_SHEET_NAME = '每周油價log';
const LINE_CHANNEL_ACCESS_TOKEN = '...'; // LINE Bot 金鑰（請勿外洩）
const RECIPIENTS = ['LINE使用者ID1', 'LINE使用者ID2'];

> 建議將這些參數移至 Google Apps Script 的專案屬性（PropertiesService）中集中管理。

---

## 🧠 系統主程式 `main()` 解說

- **主要邏輯**：
1. 計算今天與明天日期
2. 自動嘗試抓取明日油價（最多重試三次）
3. 自動嘗試抓取今日新聞稿（最多重試三次）
4. 如果油價或新聞任一失敗則中止
5. 組裝成 Flex Message 並發送至 LINE 群組
6. 所有流程記錄寫入 Google 試算表

function main() {
  try {
    const today = new Date();
    today.setHours(0, 0, 0, 0);
    const tomorrow = new Date(today);
    tomorrow.setDate(today.getDate() + 1);
    ...
  } catch (error) {
    log('錯誤', '執行失敗', error.stack);
  } finally {
    flushLogs();
  }
}

---

## 🔁 重試機制 `fetchWithRetries()`

這是一個萬用小幫手，任何你要去網路抓資料的地方都能用上它：

function fetchWithRetries(fetchFunction, resourceName, maxRetries, delay)

- `fetchFunction`：真正去抓資料的函式
- `resourceName`：這次要抓的資源名稱（油價/新聞）
- `maxRetries`：最多可以失敗幾次
- `delay`：每次失敗後要等多久（單位是毫秒）

---

## ⛽ 油價資料取得 `fetchPrice(date)`

這支函式會從中油油價歷史頁面抓資料，並解析當週與上週價格做出差異比較。

---

## 📰 新聞標題取得 `fetchNews(date)`

這支函式會從中油的開放資料 XML 抓取新聞稿清單，挑出與今日相符的標題。

---

## 💌 推播訊息 `pushMulticastMessage()`

這支會用 LINE Bot 的 Multicast API 一次性發送 Flex Message 給所有使用者。

---

## ✨ Flex 卡片設計 `buildFlexMessage(data)`

這支函式會根據油價與新聞組裝出一個漂亮的 Flex Message。
- 顯示各種油品價格
- 顯示漲跌符號與顏色
- 顯示新聞稿標題

---

## 📝 日誌紀錄：`log()` 與 `flushLogs()`

透過 `log()` 記錄每一步的狀態，透過 `flushLogs()` 最後統一寫入 Google Sheet。

---

## ⏰ 自動排程 `createTimeDrivenTriggers()`

建立一個定時觸發器，讓主程式自動在每週日 12:15 執行一次。

---

## 🧪 測試用 `test()`

提供測試訊息與畫面用的測試函式（不含實際資料）。

---

## 📆 民國轉西元 `twToAD()`

把中油的民國格式日期轉成 JavaScript 的 Date 物件。

---

> 📌 如果你是第一次使用這份腳本，請務必依序確認：
> - LINE Bot 是否有對應權限
> - Google Sheet 權限與格式是否正確
> - 定時觸發器是否正確註冊
> - 所有參數是否已設定於專案屬性

---

🧾 編寫日期：2025-06-15｜最後更新：ChatGPT 自動產出
🧑‍💻 作者：你自己（或 ChatGPT）