架構與工作流程說明書

問題與修復

資料補強與來源

新增研究路徑、安置與解除安置差異、機構委託查證步驟、臨時安置概念流程及引用原則。法律流程以勞動部作業要點為依據；103 人的公告來源為移民署 2026 研討會公告。機構卡片額外顯示證據能支持的範圍；未逐筆確認所有現行契約。

系統邊界與尚存風險

• KV 為最終一致儲存，並行讀取後加一可能互相覆蓋；本版未改用新資料庫，統計仍是約略值，不能用於稽核、請款或精確人數報告。
• 來源檢查與機器人字串不是完整的流量防護；蓄意偽造請求仍需 Cloudflare 平台流量控管。未以此宣稱通過正式滲透測試。
• 正式站設定獨立隨機 VISIT_SALT，值不存入專案與前端；缺少此值時停止新增計數。雜湊是短期假名化資料，不等於完全匿名；應用程式不將原始 IP 存入 KV，託管業者仍處理連線資訊。
• script-src 已限制行內程式；為保留圖表與設定的動態樣式，style-src 仍允許行內樣式。
• 本機自動化與裝置尺寸模擬不能取代實體裝置、Safari、輔助科技、真實網路及長期負載測試。

維護檔案

新增 assets/refinement.v41.css、assets/docs.v41.js 及 hero-v41-640／960／1440.webp。既有 app.v4.js 檔名保留以維持工具相容，實際產品版本以 version.json 與部署記錄為準。不要只複製首頁，必須整包部署。

發布與回復流程

先基本檢查 → 本機回歸 → 資安與離線情境 → 人工視覺檢查 → 備份 → 批次部署 → 正式站核對。需要回復時先確認版本，再使用 Cloudflare 成功部署紀錄回復；本機備份還原會覆蓋檔案，應在執行前另行確認。

技術依據：Cloudflare KV 寫入與併發限制、Pages 安全標頭、CSP 原則。

設計目標

以細緻寫實的情境插畫搭配編輯式排版，讓讀者先找到研究方向，再按需要展開文章。原有七個分頁、搜尋、下載、友善模式及訪客統計皆保留。

架構與檔案

閱讀流程

首頁研究入口 → 選擇數據、機構或法規 → 篩選主題 → 展開文章／原始數據表 → 核對來源。首頁深入內容預設收合，搜尋結果會連同外層文章一起展開；列印時也會自動展開並在結束後恢復。

圖表分析原則

五張互動圖表依「移工規模」「被害人保護」切換。2025 年底規模、年度增加、十年變化與許可失效占比均從同一份原始陣列計算。年增率＝（本年／上年－1）×100%；許可失效占比＝（總計－產業有效許可－社福有效許可）／總計。數值不代表安置需求，也不把 2026 年部分月份直接與全年比較。

批次檔上傳

1. 編輯並儲存內容，先在本機預覽。
2. 雙擊「更新上傳.bat」，以現有 Wrangler 登入檢查檔案。
3. 腳本備份本次部署前的網站與版本資訊，再寫入台灣時間。
4. 上傳 Cloudflare Pages；遇到錯誤即停止，不宣告成功。
5. 開啟 shelter.wen8604.org，核對版本、數據頁與說明書。

快取與回復

頁面採網路優先；拆分的樣式與程式使用必須重新驗證的 HTTP 快取，Service Worker 升級為 msr-v41-20261028。線上更新不必手動清除所有瀏覽器快取。需要回復時，可在 Cloudflare 選擇前一次成功部署；本機還原涉及覆蓋，應先確認欲回復的備份。

提供可查證的移工安置制度與機構研究索引，回答「誰設立、誰承接、誰出錢、誰監督」。它不是即時庇護所名錄，也不是緊急轉介入口。

• 區分一般臨時安置、人口販運庇護、駐台代表處安置、婦幼特殊安置與仲介住宿，不虛構全國總數。
• 歷史安置紀錄不等於現在仍在營運或持有政府契約。
• 不收集個資、不提供上傳、不公開受庇護者非公開位置。

配色（依 wen8604 設計規範 v1.0）

內文對比 ≥ 4.5:1；金色只用於深色底或當底色配黑字。插圖顏色全部以 CSS 變數控制，深色模式自動轉為夜景（月亮、星星、窗戶亮燈）。

三種裝置版型

友善模式細部設定

• 內容 HTML、同站 CSS 與 JavaScript 分離；不請求第三方字型或套件，使用系統中文字型。
• 圖示改為內嵌 SVG sprite（<symbol> + <use>），插圖為向量，不需載入任何圖片。
• 分頁切換只切換顯示，不重新請求；資料卡片用 DocumentFragment 式建立，搜尋加防抖。
• 訪客統計延後到瀏覽器閒置時才呼叫（requestIdleCallback），不影響首屏。
• Cloudflare 自動 Brotli 壓縮、HTTP/3 與全球節點；HTML 每次重新驗證，確保更新立即生效。
• 非首頁分頁延遲建立、裝飾動畫延後到頁面穩定才啟動，首屏不搶主執行緒。
• 首屏依網址先顯示對應分頁，避免版面跳動（CLS 0）。
• 舊版 Lighthouse 數字不沿用至本版；本版以實測報告為準。

1. 頁面載入後閒置時：若是本工作階段第一次造訪送 POST /api/visit，之後只送 GET 讀取。
2. 邊緣函式判斷：排除爬蟲、無頭瀏覽器與 Cloudflare 判定的機器人；拒絕跨網域 POST。
3. 去重：以「IP＋瀏覽器＋日期＋鹽」做 SHA-256，存 48 小時後自動刪除；同一人同一天只算一次。
4. 累加：total 與 d:YYYY-MM-DD 兩個計數器各加一，回傳累計與今日人次。
5. 顯示：頁尾「累計造訪 N 人次・今日 n」；若 API 失敗或數字為 0，整塊隱藏。

更新時間：每次執行 deploy.ps1 會把當下時間寫入兩個頁面的 build-time 與 version.json，並在 deploy-log.txt 記一筆。

{
  "id": "organization-001",
  "name": "組織名稱",
  "category": "government | shelter | education",
  "shelter_contract_status": "documented | unverified",
  "description": "已查得服務與限制",
  "source_ids": ["S01"],
  "reference_year": 2022,
  "last_verified_at": "2026-10-27",
  "operating_status": "unknown",
  "reviewer": "待指派",
  "revision_notes": "需取得正式函覆"
}

同一團體可有多種服務類型；正式資料庫應以多對多關聯表（organizations、services、facilities、contracts、grants、evidence、revisions）處理。設施與法人分開，避免重複計算。

1. 提案：建立待查問題，明確統計期間與定義。
2. 取證：法規、標案、審計報告、官方年報優先；保存網址、發布日、擷取日。
3. 分級：官方直接證實／歷史有據／尚待驗證／已更正／已撤回。
4. 核對：高風險資訊至少兩位編輯交叉覆核；涉及機構聲譽須給予回應機會。
5. 去重：依法人識別碼、設施識別碼、契約案號與年度比對。
6. 審核：法規適用、統計單位、推論限制、個資遮蔽、中性用詞與來源連結。
7. 發布：更新資料陣列 → 執行 deploy.ps1，自動記錄更新時間與摘要。
8. 勘誤：公布錯誤位置、來源與更正日期；不默默改寫重要結論。

第一次設定（約 5 分鐘）

1. 安裝 Node.js LTS（nodejs.org）。
2. 雙擊 deploy.bat。第一次會開啟瀏覽器，請登入 Cloudflare 並按「Allow」授權。
3. 腳本會自動建立 KV「VISITS」、填入 wrangler.toml、建立 Pages 專案 migrant-shelter-research 並上傳。
4. 完成後網址為 https://migrant-shelter-research.pages.dev；可在 Cloudflare 後台 Pages → 自訂網域 綁定自己的網域。

日常更新

# 1. 修改 site\assets\app.v4.js 內的資料陣列，或 index.html 的文章文字
# 2. 本機預覽（含統計 API）
preview.bat                      # 開啟 http://localhost:8788
# 3. 上傳（可附更新說明）
.\deploy.ps1 -Message "新增 2026 年勞動部安置名冊"

回復上一版

Cloudflare 後台 → Workers & Pages → 本專案 → 部署 → 找到上一個成功版本 →「Rollback to this deployment」，生效時間依 Cloudflare 狀態而定；KV 歷史值保留，但不同版本的去重方式可能影響約略統計。

• 六分頁單頁應用、滑順切換、舊網址相容
• 手機底部列／平板滑動分頁／桌機分頁指示器
• 重新繪製的主視覺插圖（串燈、窗台花、門牌、盆栽）、分頁插圖與 47 個圖示，深色模式夜景
• 文章與說明全面可收合，含全部展開／收合
• 深色模式＋友善模式 8 項細部設定，跨站共用設定
• 網站更新時間自動寫入、獨立訪客統計（排除機器人）
• Cloudflare 安全標頭、一鍵部署、本機預覽
• v3：數據分析分頁 5 張官方統計圖表、全站搜尋、離線快取、閱讀進度條
• v3：自動化測試 209 項（3 種裝置 × 淺／深色），axe 無障礙無嚴重問題
• 全台政府安置名冊與委託契約逐筆去重
• 機構狀態正式函覆、印尼據點精確開設日期
• 真機 WCAG 2.2 AA 稽核與螢幕閱讀器實測
• 公開勘誤紀錄頁與資料版本差異

角色：資料研究員收集來源；主編審核推論與措辭；法務／資安審查敏感內容；工程師管理程式、部署、備份與監測。任何人都不應在缺乏原始資料時自行更改數字或指控機構。

設計規則

• 標題就是結論：例如「十年增加 27.8 萬人」，副標說明範圍與單位。
• 配色經驗證：類別色 #13846D／#D45F28／#3473BD（深色 #24A086／#E2703A／#4D8FD8）通過色盲分離、亮度帶與 3:1 對比檢查；「許可失效」用灰色退居背景。
• 細線與留白：直條最寬 24px、頂端 4px 圓角、堆疊間 2px 間隙；格線為實線細線；只標重點數值，不在每個點上寫數字。
• 不使用雙 Y 軸：人數與占比分開呈現（占比放在提示框與數據表）。
• 互動不設門檻：滑鼠、觸控、鍵盤（Tab 進入、左右鍵逐年）都能看提示框；每張圖都有「顯示數據表」。
• 純 SVG 自繪：不載入圖表套件，寬度改變才重繪，切換深色模式自動換色。

既有回歸套件包含 209 項自動化檢查，本版結果請見測試報告。測試在本機以與 Cloudflare 相同的統計函式模擬執行；外部政府網站連結因測試環境無法連外，需上線後人工點開確認。