應用程式守護 Watchdog 操作手冊

1. 功能簡介
==================================================

本工具 (Watchdog) 是一個獨立的背景應用程式，其主要功能是：
- 監控主程式：持續檢查指定的應用程式 (.exe) 是否正在執行。
- 自動重啟：如果發現主程式未執行（例如：崩潰、被關閉），Watchdog 會自動嘗試重新啟動它。
- 啟動失敗警報：如果主程式連續多次啟動失敗，Watchdog 可以透過 Email 發送警報通知相關人員。
- 單例執行：確保同一時間只有一個 Watchdog 實例在執行，避免資源浪費和衝突。
- 日誌記錄：記錄所有操作（啟動、重啟、錯誤等），方便追蹤和除錯。
- 系統匣圖示：提供一個系統匣圖示，方便查看狀態、開啟日誌、手動關閉主程式或退出 Watchdog。

2. 檔案結構
==================================================

為了讓 Watchdog 正常運作，請將檔案依以下結構放置：

您的專案資料夾/
├── SchoolBell.exe         <-- (您要監控的主程式)
├── updater.exe            <-- (更新器程式)
├── watchdog.exe           <-- (本守護程式)
├── UAndW_config.json      <-- (共用的設定檔)
└── UAndW.lock             <-- (自動產生的鎖定檔案，請勿手動刪除)

- 日誌檔：Watchdog 啟動後，會自動在同層目錄建立一個 logs 資料夾，並在其中存放日誌檔案。

3. 設定檔說明 (UAndW_config.json)
==================================================

這是 Watchdog 最核心的設定檔，所有行為都由此檔案控制。以下是各項設定的詳細說明：

**重要：**
本系統依賴 `psutil` 和 `portalocker` 函式庫。在執行或打包前，請確保已安裝：
`pip install psutil portalocker`


{
    "version_path": "https://www.winway.tw/UAndW/",
    "main_app_path": "SchoolBell.exe",
    "watchdog_settings": {
        "health_check_interval_seconds": 15,
        "watchdog_app_name": "watchdog.exe",
        "restart_delay_seconds": 5
    },
    "alert_settings": {
        "enabled": true,
        "failure_threshold": 3,
        "email": {
            "smtp_server": "smtp.gmail.com",
            "smtp_port": 587,
            "smtp_user": "pianoszhang@gmail.com",
            "smtp_password": "eiimpblecudlxit",
            "sender_name": "Watchdog Alert",
            "recipient_emails": [
                "winway@winway.tw"
            ]
        }
    },
    "api_settings": {
        "enabled": true,
        "port": 9090
        }
    }
}

- main_app_path (字串):
  - 用途: 指定要監控的主程式執行檔名稱。
  - 範例: "SchoolBell.exe"
  - 注意: 這是最重要的設定，請務必填寫正確的檔名。

- watchdog_settings (物件):
  - health_check_interval_seconds (數字):
    - 用途: Watchdog 每隔幾秒檢查一次主程式的狀態。
    - 範例: 15 代表每 15 秒檢查一次。

  - watchdog_app_name (字串):
    - 用途: 指定 Watchdog 守護程式本身的執行檔名稱。
    - 範例: "watchdog.exe"
    - 注意: 當您將 watchdog.exe 重新命名時（例如：SchoolBell_Guard.exe），必須在此處同步修改，以確保單例執行和更新器能正常運作。

  - restart_delay_seconds (數字):
    - 用途: 當主程式崩潰或關閉後，延遲幾秒再嘗試重新啟動。這可以避免因外部資源問題導致的連續啟動失敗。
    - 範例: 5 代表延遲 5 秒後重啟。設為 0 則立即重啟。

- alert_settings (物件):
  - enabled (布林值):
    - 用途: 是否啟用 Email 警報功能。true 為啟用，false 為停用。
  - failure_threshold (數字):
    - 用途: 當主程式連續啟動失敗達到這個次數時，就發送 Email 警報。
    - 範例: 3 代表連續失敗 3 次就發信。
  - email (物件):
    - smtp_server: 發信的 SMTP 伺服器位址 (例如: "smtp.gmail.com")。
    - smtp_port: SMTP 伺服器的埠號 (例如: 587)。
    - smtp_user: 您的發信用 Email 帳號。
    - smtp_password: 您的 Email 密碼或應用程式專用密碼（注意：使用 Gmail 等服務時，建議產生應用程式密碼以提高安全性）。
    - sender_name: Email 中顯示的寄件人名稱。
    - recipient_emails (陣列):
      - 用途: 要接收警報通知的 Email 地址列表，可以填寫多個。
      - 範例: ["user1@example.com", "user2@example.com"]

- api_settings (物件):
  - enabled (布林值):
    - 用途: 是否啟用 HTTP API 伺服器以供遠端監控。`true` 為啟用，`false` 為停用。
  - port (數字):
    - 用途: 指定 HTTP API 伺服器監聽的網路端口。
    - 範例: 9090
    - 使用方法:
      - **GET /status**: 訪問 `http://<主機IP>:<port>/status` 來獲取 JSON 格式的即時狀態。
      - **POST /restart**: 向 `http://<主機IP>:<port>/restart` 發送 POST 請求，可以遠端觸發主程式的重啟。

4. 系統匣圖示操作
==================================================

Watchdog 啟動後，會在右下角系統匣顯示一個綠色的 "W" 圖示。在圖示上按右鍵會出現選單：
- 狀態 (預設選項): 點擊後會彈出視窗，顯示主程式的執行狀態、PID 和上次啟動時間。
- 查看日誌: 自動用預設的文字編輯器打開最新的日誌檔。
- 關閉主程式: 手動終止正在被監控的主程式。Watchdog 會在下一個檢查週期再次將它啟動。
- 關閉 Watchdog: 退出 Watchdog 程式本身。主程式如果正在執行，會繼續保留。

5. 如何應用於新專案
==================================================

1. 將 watchdog.exe 複製到新的專案資料夾。
2. 將您的主程式 (例如 NewApp.exe) 也放在同一個資料夾。
3. 在該資料夾中建立一個新的 UAndW_config.json 檔案。
4. 複製上方的設定範本，並修改 main_app_path 為您的新程式名稱 (例如 "NewApp.exe")。
5. 根據新專案的需求，調整 watchdog_settings 和 alert_settings 的設定。
6. 執行 watchdog.exe 即可開始守護您的新應用程式。