行動儀表板受控網址設定（IT）¶

行動儀表板有兩條送達通道：

寄信附件——排程把行動版 HTML 當附件寄給主管。不需要本頁的任何設定，掛好排程即可。
受控網址——排程把「最新一份行動版」推上一個受保護的網址，主管開網址即看、可加到手機主畫面。

本頁只講第二條：受控網址的一次性建置與維運，對象是 IT／系統管理員。管理員在 ERP 端要做的（格式勾 HTMLMOBILE、參數 發布網址=Y）見排程作業 · 發布到受控網址；主管端的閱讀方式見行動儀表板。

為什麼要「受控」：這是財報，不是公開網頁

行動版內容是營運與財務數字。公司既有的公開手冊站絕不可共用同一個發布目的地；受控網址必須掛存取控管（Email 白名單驗證），只有名單內的信箱通過驗證才進得去。

運作方式¶

flowchart LR
    EVT[行事曆事件<br/>發布網址=Y] --> DECK[排程任務<br/>Customdash_ScheduledDeck]
    DECK --> FILE[產出 *_mobile.html]
    FILE --> MAIL[寄信附件<br/>主通道]
    FILE --> PUB[子行程呼叫<br/>tools/dash-publish.ps1]
    PUB --> ARCH[本機歷史夾<br/>%ProgramData%\TsERP\dash-archive]
    PUB --> CF[(受保護的靜態網站<br/>Email 白名單存取控管)]

重點行為：

發布只在寄信入列成功之後執行，且發布失敗只記 log、不影響寄信（主管仍收得到附件）。
子行程逾時上限 5 分鐘，逾時即放棄本次發布。
每次發布是整站替換：腳本會把「最新一份 → index.html」＋「本機歷史夾內的所有既往期別」＋「history.html 期別清單頁」整包上傳，因此首頁永遠是最新一期，右下角浮動鈕可翻歷史。
歷史檔累積在發布主機本機（預設 %ProgramData%\TsERP\dash-archive\<專案名>\，檔名含期間，同期重發覆蓋）。清掉本機歷史夾＝線上歷史頁跟著只剩最新一期。

前置需求¶

項目	說明
靜態網站託管帳號	目前實作以 Cloudflare Pages ＋ Cloudflare Access（Email OTP 白名單）為部署目標；帳號與方案由 IT 準備
API Token 與 Account ID	Token 權限需含 Cloudflare Pages → Edit；Account ID 必備（多帳號情況下缺它會讓上傳指令在無人值守環境等待輸入而卡住）
發布主機可執行 wrangler	腳本優先使用已安裝的 `wrangler`，否則以 `npx wrangler@3` 執行——後者需要該主機可用 Node/npx 並能連外
腳本存在於發布主機	`tools\dash-publish.ps1`；排程端會從執行目錄逐層往上找，找不到時可用環境變數 `DASH_PUBLISH_SCRIPT` 指定完整路徑
排程作業已可正常寄送	受控網址是排程報表的延伸，請先確認排程報表自動寄送本身已跑通

環境變數（設在排程服務帳號的環境）¶

腳本一律從環境變數取用機密，任何 token 都不寫進 repo 或設定檔。

變數	必要	用途
`CLOUDFLARE_API_TOKEN`	✔	上傳用 API Token
`CLOUDFLARE_ACCOUNT_ID`	✔	目標帳號 ID
`DASH_ACCESS_CONFIRMED`	✔（真實數據）	安全閘：值為 `Y` 才允許上傳帶真實數據的報表
`DASH_PUBLISH_SCRIPT`	—	指定 `dash-publish.ps1` 的完整路徑（自動尋找失敗時才需要）

環境變數要設在排程實際執行的身分底下

排程作業通常以服務帳號執行。變數若只設在你自己的登入工作階段，排程跑起來會讀不到（症狀：信正常寄出、網址卻永遠沒更新，log 顯示缺 token）。

一次性建置流程¶

順序不可調換——先把站建起來並掛好存取控管，確認擋得住，最後才打開真實數據的閘門。

用佔位頁建站（零營運數據）：
```
./tools/dash-publish.ps1 -Placeholder
```
這會建立 Pages 專案（預設名稱 tserp-dash）並發布一頁「尚未發布內容」。想先驗證打包結果不上傳，可加 -DryRun。
掛存取控管（Email 白名單）：到託管平台後台為該專案啟用 Access 政策。腳本提示的路徑為 Pages 專案 → Settings → General → Access policy；實際選單位置與白名單維護方式由 IT 依當前後台版本與公司政策設定，本手冊不逐步截圖。

白名單必須涵蓋預覽網址

每次部署都會另外產生一組 <hash>.<專案>.pages.dev 預覽網址。政策只掛主網域時，真實財報會從預覽網址裸奔。務必確認保護範圍為 *.<專案>.pages.dev（由上述 Access policy 開關建立的 app 即為此範圍）。
實測擋得住：用無痕視窗開該網址，確認會被要求驗證；再用白名單外的信箱試一次，確認被拒絕。
開啟安全閘：確認無誤後，在排程服務帳號的環境設定：
```
$env:DASH_ACCESS_CONFIRMED = 'Y'
```
在 ERP 端啟用：請管理員把該筆排程事件的參數 格式 加入 HTMLMOBILE、發布網址 設 Y（多公司另填 發布專案），見排程作業 · 發布到受控網址。
驗收：等下一次排程執行（或手動觸發一次），確認信件寄出、網址內容更新為當期報表、右下角「歷史報表」可開啟。

安全閘：未確認前拒絕上傳真實數據¶

DASH_ACCESS_CONFIRMED 不是形式上的旗標，而是技術閘：

模式	行為
`-Placeholder`（佔位頁，零數據）	不受限，隨時可發——就是為了先建站設保護用的
帶真實數據（`-SourceHtml`）	`DASH_ACCESS_CONFIRMED ≠ Y` 時直接拒絕上傳並中止，只留 log

排程端遇到發布失敗（含被閘門擋下）一律只記 log，不影響寄信、不讓整筆排程失敗。因此「信有到、網址沒更新」的第一個排查點永遠是這個閘門與 token 環境變數。

事故時的蓋台手段

發現線上內容不該公開時，最快的處置是立刻發一次佔位頁（-Placeholder）覆蓋線上內容——它不帶任何數據，也不會動到本機歷史夾，下次正常發布會自動還原歷史清單。

多公司部署¶

做法	說明
一家公司一個專案	在事件參數 `發布專案` 填該公司的專案名（空白＝預設 `tserp-dash`）
各掛各的白名單	每個專案各自設定 Access 政策，彼此看不到對方的數字
歷史夾自動分開	本機歷史夾為 `%ProgramData%\TsERP\dash-archive\<專案名>\`，per 專案互不干擾

新公司啟用前要先建好專案與保護

新增 發布專案 值之前，請先照上方「一次性建置流程」對該專案跑一遍（佔位頁建站 → 掛 Access → 實測）。直接在事件上填一個尚未設保護的專案名，等於把該公司的報表推到未受保護的站上。

維運¶

工作	做法
加／減白名單成員	在託管平台後台的 Access 政策維護 Email 清單；ERP 端無須改動
輪替 API Token	產生新 Token → 更新環境變數 → 手動跑一次 `-Placeholder -DryRun` 或實際發布驗證
清理歷史期別	刪除本機歷史夾內不再需要的檔案，下次發布後線上清單同步縮短
檢查發布是否成功	看排程作業的 log（成功會記錄「行動版已發布 <檔名> → <專案>」；失敗記錄 exit code 與最後幾行輸出）

疑難排解¶

症狀	可能原因與處置
信正常寄出，網址一直是舊的／佔位頁	① `DASH_ACCESS_CONFIRMED` 未設為 `Y`（安全閘擋下）；② token／Account ID 未設在排程服務帳號環境；③ 該次產出不含行動版（`格式` 沒勾 `HTMLMOBILE`）。三者都只記 log 不報錯
log 顯示「找不到 dash-publish.ps1」	發布主機上缺該腳本，或路徑不在自動尋找範圍內；設 `DASH_PUBLISH_SCRIPT` 指定完整路徑
log 顯示發布逾時	子行程超過 5 分鐘；多為網路或 npx 首次下載造成，改在該主機預先安裝 `wrangler` 可大幅縮短
建立專案失敗	依錯誤訊息到託管平台後台手動建立同名專案後重跑
主管說網址要一直重新驗證	屬存取控管的正常行為（換裝置／清除瀏覽器資料／換帳號）；信箱不在白名單則須由 IT 加入
擔心預覽網址外流	確認 Access 保護範圍為 `*.<專案>.pages.dev`，並以無痕視窗實測預覽網址是否被擋