計畫目標：根據「NIR即時看板」開發計畫的內容，建置client-server存取與運算軟體
計畫設計：Google Gemine Pro

壹、 系統總覽 (System Overview)
本系統旨在推廣「光健康」與「光維他命」概念。透過串接台灣官方開放資料庫（氣象、空汙、紫外線），並結合專業的大氣光譜物理模型，即時計算全台 19 個主要縣市的「近紅外光 (NIR)」輻射強度，並與「紫外線 (UV)」指數進行對照。協助民眾尋找「高 NIR、低 UV」的黃金日曬時機，並以直覺的燈號與地圖提供具體的戶外活動建議。

貳、 系統架構與使用技術 (Architecture & Tech Stack)
本系統採用現代化的「前後端分離 (Decoupled Architecture)」設計，確保網頁載入速度與後端運算互不干擾。
• 後端 API 引擎 (Backend):
o 程式語言： Python 3
o 網頁框架： FastAPI (提供高效能、異步的 RESTful API 服務)
o 部署環境： Render 雲端平台 (PaaS)
o 跨域處理： 啟用 CORS Middleware 允許前端跨域請求。
• 前端網頁展示 (Frontend):
o 執行環境： WordPress (搭配 Elementor HTML 小工具)
o 核心技術： HTML5, CSS3, 原生 JavaScript (ES6+ async/await Fetch API)
o 資料視覺化： D3.js (用於繪製全台地理拓撲熱力圖)
• 效能優化層 (Caching Layer):
o 記憶體快取： Python 全域變數暫存 (In-Memory Cache)。
o HTTP 快取： 伺服器回傳 Cache-Control: public, max-age=1800，強制瀏覽器與 CDN 進行 30 分鐘快取。

參、 核心大氣物理模型 (Core Physics Models)
本系統的核心運算引擎依賴開源太陽能物理套件 pvlib-python。
將原始氣象數據轉換為 NIR 強度的數學與物理過程如下：

1. 可降水量計算 (Precipitable Water, PWV)：
   使用 Gueymard (1994) 模型，將地面溫度與相對濕度轉換為大氣整層水氣含量。水氣是吸收近紅外光最主要的變數。
2. 太陽位置與天頂角 (Solar Zenith Angle)：
   透過精確的經緯度與 UTC+8 時間，計算太陽當下在天空的絕對位置。若天頂角 > 90^。 (日落)，則輻射直接歸零。
3. 相對大氣質量 (Relative Air Mass)：
   計算太陽光穿透大氣層的厚度。
4. 晴天光譜輻射模型 (BIRD Simple Spectral Model – spectrl2)：
   輸入上述參數及空汙數據，模擬出到達地面的太陽光譜分布 (Wavelength vs. Irradiance)。
5. 微積分數值積分 (Numerical Integration)：
   光譜產出後，系統使用梯形積分法 (numpy.trapezoid)，針對近紅外光波段 700 nm 至 2500 nm 的直射法向輻射 (DNI) 進行面積加總，得出 NIR 總能量：
   

肆、 外部資料庫與數據調取 (Data Sources)
系統每 30 分鐘向以下三大公開資料庫發起請求，進行數據融合：

資料來源單位	API / 資料集名稱	調取參數 / 內容	系統用途
中央氣象署 (CWA)	自動氣象站 (O-A0001-001)	氣溫、濕度、天氣描述、即時降雨	提供物理模型基礎參數，以及雲量衰減判斷。
環境部 (MOENV)	空氣品質指標 (aqx_p_432)	各縣市即時 PM2.5 濃度	轉換為林克大氣混濁係數 (Turbidity)，模擬空汙對陽光的遮蔽。
環境部 (MOENV)	紫外線指數 (uv_s_01)	各縣市即時 UVI 數值	提供前端健康對照指標與防曬警告。
g0v 開源社群	台灣縣市邊界 GeoJSON	2010 年版台灣縣市經緯度座標點	提供 D3.js 於前端動態繪製台灣地理熱力圖。

伍、 關鍵參數設定與假設條件 (Parameters & Assumptions)
為了讓理想物理模型貼近台灣真實環境，系統導入了以下動態補償機制：
• 雲層透光率折扣 (Cloud Transmissivity)：
• 以氣象署「天氣描述」與「降雨量」作為雲量 Proxy：
o 有雨 或 降雨量 > 0 : NIR 能量剩餘 25%
o 天氣 陰 : NIR 能量剩餘 45%
o 天氣 多雲 : NIR 能量剩餘 75%
o 其餘 (晴天) : NIR 能量 100%
• 動態大氣混濁度 (Aerosol Turbidity)：
• 公式：0.1 + (PM2.5* 0.005)。並將極限值鎖定在 0.05 – 0.8 之間。
• 地表反射率 (Albedo) 精細化：
• 依據各縣市都市化程度與地貌手動賦予：
o 水泥都會區 (北北基宜、新竹)：0.15
o 水體埤塘多 (桃園)：0.12
o 農業與空曠區 (中南部、外島)：0.18 – 0.20
• 異常值防護網：
• 若氣象署回傳 -99.0 (儀器維護)，系統會自動以 25^。 C 作為物理替代運算值，前端則顯示「維護中」，確保系統不崩潰。

陸、 評級標準與視覺化策略 (Classification & UI)
系統定義了光健康的 5 級指標，於前端轉換為顏色與建議：

1. NIR 光補給指標 (近紅外光能量)：
   • 無光 (灰)： < 10 W/m² : 太陽休息中，建議室內休息。
   • 偏弱 (藍灰)： 10 – 150 W/m² :吸收緩慢，適合長時間散步。
   • 溫和 (黃)： 150 – 300 W/m² : 溫和補充，適合一般戶外活動。
   • 良好 (橘)： 300 – 400 W/m² : 強烈建議日曬！(20-30分)。
   • 極佳 (紅)： > 400 W/m² : 高效快充 🔋 (10-15分，需防曬)。
2. 前端展示版本：
   • 版本 A (六都對照表)： 著重精確數據與 UV 雙向對照。
   • 版本 B (真實地理圖)： D3.js 繪製，適合大版面戰情室，具備浮動提示卡。
   • 版本 C (全省方格圖)： 現代化 UI，適合手機版與側邊欄，空間利用率極高。

柒、 系統效能與節能機制 (Performance & Energy Saving)
• 自動夜間休眠： 每日 21:00 至隔日 04:59，API 直接中止外部連線與微積分運算，回傳夜間狀態，保護雲端主機額度。
• 自動快取防護： 後端 30 分鐘緩存機制，阻擋了頻繁重整造成的 API 呼叫過載，達成前端 0.01 秒秒開體驗。

捌、 流程圖 (Flow Chart)