Development Record
Formosa ESG 2026
Formosa ESG 2026
白沙屯媽祖進香 GPS 追蹤系統 — 專案開發紀錄
從概念驗證到萬人系統：簡述開發歷程
版本 1.0
涵蓋期間：2026/03/23 —
更新日期：2026/04/07
Formosa ESG Project Team
5
開發階段
4
壓力測試輪次
106+
Issues 處理
4
多語系支援
1. 專案概述
「Formosa ESG 2026 白沙屯媽祖進香 GPS 追蹤系統」是一套結合 GPS 定位、碳足跡估算與社群互動的進香追蹤服務。香客透過 LINE 登入，使用手機即時打卡、累積里程、查看等級進度，並可分享個人化的成就卡片。系統同時提供管理者儀表板，含即時地圖、推播通知、用戶管理等後台功能。
技術架構採用 Astro（前端 SSG）+ Cloudflare Pages + Workers + D1（SQLite）+ KV（快取與緩衝），搭配 LINE LIFF SDK 整合登入與分享。系統設計承載目標為萬人同時使用。
活動日期
2026/04/12 起駕
活動期間
約 8-9 天（依媽祖旨意）
承載目標
10,000 人同時使用
支援語系
zh-Hant / en / ja / zh-Hans
前端框架
Astro + Cloudflare Pages
後端架構
Workers + D1 + KV
2. 開發階段總覽
| 階段 | 時間 | 核心目標 | 狀態 |
|---|---|---|---|
| Phase 0 | 03/23 | 概念驗證：EXIF GPS 讀取、D1 寫入可行性 | 完成 |
| Phase 0.5 | 03/24 | MVP：16 題問卷 + GPS 打卡 + 碳足跡 + 獎勵卡 + LINE webhook | 完成 |
| Phase 1 | 03/25 | UX 重構：一題一頁卡片 + 9 級等級 + LIFF + 分享卡片 + Dashboard | 完成 |
| Phase 1.5 | 03/25–26 | 安全強化 + Dashboard + LIFF Published + Workers Paid 升級 | 完成 |
| Phase 2 | 03/25–26 | 壓力測試 4 輪 + D1 瓶頸分析 + KV Buffer 架構設計 | 完成 |
| Phase 3 | 03/27–04/05 | 上線準備：KV Buffer 實作 + GPS 管線修復 + 權限系統 + 推播 + 文件 | 已部署 |
| Phase 4 | 04/01–07 | 功能完善：成就卡規則 + 問卷精簡 + Issue 修復 + 費用優化 | 已部署 |
3. 逐日工作紀錄
| 日期 | 階段 | 工作項目 | 狀態 |
|---|---|---|---|
| 03/23 Day 1 |
Phase 0 | EXIF GPS 座標讀取 PoC（瀏覽器端 EXIF.js） | 完成 |
| Phase 0 | Cloudflare D1 資料庫建立 + Workers API 端點 | 完成 | |
| Phase 0 | 專案頁面框架（Astro SSG + Cloudflare Pages） | 完成 | |
| 03/24 Day 2 |
Phase 0.5 | 16 題 ESG 問卷（一題一頁卡片流程） | 完成 |
| Phase 0.5 | GPS 打卡功能 + 碳足跡計算引擎 | 完成 | |
| Phase 0.5 | 獎勵卡系統（打卡集點視覺化） | 完成 | |
| Phase 0.5 | LINE Bot webhook 串接（Messaging API） | 完成 | |
| Phase 0.5 | Cloudflare Workers CORS 修復 + 部署驗證 | 完成 | |
| 03/25 Day 3 |
Phase 1 | UX 重構：一題一頁 + 線性進度條 + 滑動動畫 | 完成 |
| Phase 1 | 9 級香客等級系統（煉氣→飛升），雙條件：km + 打卡次數 | 完成 | |
| Phase 1 | 9 張 AI 生成公仔圖（取代 emoji 等級圖示） | 完成 | |
| Phase 1 | LINE LIFF SDK 整合（Login channel + init） | 完成 | |
| Phase 1 | 分享卡片（垂直佈局 + 地圖 + QR + 公仔 + stats） | 完成 | |
| Phase 2 | 壓力測試 R1：HTTP 層 C-10K ~ C-100K 全 PASS | 完成 | |
| 03/26 Day 4 |
Phase 1.5 | Dashboard：熱力圖 + 聚類標記 + 前鋒/尾巴 + 3 模式切換 | 完成 |
| Phase 1.5 | 安全強化：AuthGate + Admin Token API 驗證 | 完成 | |
| Phase 2 | 壓力測試 R2：800 VU 甜蜜點確認（99.99% 成功） | 完成 | |
| Phase 2 | 壓力測試 R3：D1 寫入瓶頸驗證（SQLite single-writer lock） | 完成 | |
| Phase 2 | 壓力測試 R4：真實場景模擬（CF-800 PASS / RW-500 Data API 瓶頸） | 完成 | |
| 03/27–28 Day 5–6 |
Phase 3 | 善足跡每日回報前端 + OG Image 動態生成 | 完成 |
| Phase 3 | 公仔圖 4x 解析度升級 + Dashboard AuthGate 修復 | 完成 | |
| Phase 3 | 7 項 UX 修復（照片縮圖 / FB 分享 / GPS 持久化等） | 完成 | |
| Phase 3 | 功能盤點：23 項完成清單彙整 | 完成 | |
| 03/29 Day 7 |
Phase 3 | 隱私同意機制（P0）+ 暫停/完成狀態 | 完成 |
| Phase 3 | 碳足跡簡化為 2 級架構（零排放 vs 搭車） | 完成 | |
| Phase 3 | QR Code 替換為 NET-ZERO logo + FB OG Image 修復 | 完成 | |
| Phase 3 | 使用說明書網頁化（香客版 + 管理者版） | 完成 | |
| Phase 3 | LINE Bot 說明連結整合 | 完成 | |
| Phase 3 | 活動照存檔功能 + FB 分享 fbclid 修復 | 完成 | |
| 03/30 Day 8 |
Phase 3 | 活動照存檔按鈕 UX 改進（明確的儲存按鈕） | 完成 |
| Phase 3 | FB 個人化 OG Image 實作 | 完成 | |
| Phase 3 | 測試模式橫幅 + 照片儲存 Bug 修復 | 完成 | |
| 03/31 Day 9 |
Phase 3 | GPS 資料管線全面修復 GP-1 ~ GP-9（commit 8f08e5d） | 已部署 |
| Phase 3 | KV Buffer 架構實作：Checkin → KV → Cron batch INSERT D1 | 已部署 | |
| Phase 3 | 碳排住宿係數更新：12.5 → 8.85 kgCO₂e/晚 | 完成 | |
| 04/01–02 Day 10–11 |
Phase 4 | 問卷優化 Q16 → Q10（精簡 6 題 + 重新編號） | 已部署 |
| Phase 3 | 三層權限系統上線：Owner / Manager / Volunteer | 已部署 | |
| Phase 3 | Dashboard 存取日誌（fire-and-forget KV logging） | 完成 | |
| Phase 4 | 成就卡門檻定義：打卡 ≥3 次 + 完成問卷 + 留電話 | 完成 | |
| 04/03–04 Day 12–13 |
Phase 3 | mazu.today Custom Domain 上線（Worker 路由 + DNS） | 已部署 |
| Ops | RFC #100：HealthAlert + Service Worker + Offline Fallback 驗證 | 已部署 | |
| Ops | Issue #99：8 項韌性改進（Promise.allSettled、localStorage fallback 等） | 已部署 | |
| Ops | Issue #102：雙 Auth 系統對齊（KV invite code + Worker secret 統一） | 已部署 | |
| Phase 3 | LIFF Channel → Published（所有用戶可使用） | 已部署 | |
| 04/05 Day 14 |
Ops | Issue #103：碳排搭車係數修正 0.47515 → 0.12013 kg CO₂e/person·km | 已部署 |
| Ops | Issue #105：推播支援 image + image+text 格式（commit 35945cd） | 已部署 | |
| Ops | Issue #106：Volunteer 可視範圍修正（只隱藏推播 + 用戶列表） | 已部署 | |
| Ops | Worker 全量部署確認（Version 342af8b0） | 已部署 | |
| Phase 4 | Cloudflare 費用分析：$44.63/月，KV ops 佔 84% | 完成 | |
| 04/06–07 Day 15–16 |
Phase 4 | KV 費用優化 Plan A：移除 TICKER_KV.delete()（commit a4b6fd2） | 已部署 |
| Phase 4 | 上線前驗收清單產出（7 大類 34 項檢核） | 完成 | |
| Phase 4 | 技術文件全盤點 + 公開部署規劃（/docs/ + /verification/） | 完成 | |
| Phase 4 | mazu.today Redirect Rules 偵察完成（Cloudflare Dashboard 方案確認） | 完成 |
4. 壓力測試結果摘要
使用 Grafana k6 進行 4 輪壓力測試（2026/03/25–26），驗證系統在高併發環境下的表現。測試環境為 MacBook Air 本地端 + Cloudflare Workers 生產環境。
| 輪次 | 日期 | 測試重點 | VU 範圍 | 關鍵結果 |
|---|---|---|---|---|
| R1 | 03/25 | HTTP 層極限 | 10K–100K | S-BURST / S-WAVE / S-EXTREME 全 PASS；5,000 VU 91% 成功率 |
| R2 | 03/25 | 容量甜蜜點 | 200–1,200 | 800 VU = 99.99% 成功率（甜蜜點）；1,200+ 開始下降；回復力測試 54% |
| R3 | 03/26 | D1 寫入瓶頸 | 500 | DI-500 確認 D1 SQLite single-writer lock；即時成功率 42%；延遲 +51% |
| R4 | 03/26 | 真實場景模擬 | 500–800 | CF-800（D1 直寫）100% PASS；RW-500（混合負載）60% FAIL = Data API 瓶頸 |
根因與解法
R3-R4 測試確認根因為 D1 SQLite 的 single-writer lock，導致高併發寫入時的序列化瓶頸。解法採用 KV Buffer 架構：
解法 1 — KV Buffer
Checkin 寫 KV（非 D1），key = gps:{ts}:{userId}:{randomId}
解法 2 — Cron Flush
每 5 分鐘批次 flush KV → D1，INSERT OR IGNORE 防重複
解法 3 — Data API Cache
Stats 先查 KV cache（TTL 60s），miss 才查 D1
三項解法已於 2026/03/29 全部部署驗證完成。
5. GPS 資料管線修復
2026/03/31 進行 GPS 資料管線全面修復（commit 8f08e5d），涵蓋 9 項改進：
| 編號 | 修復項目 | 說明 |
|---|---|---|
| GP-1 | Auto-track 持久化 | localStorage 狀態跨 session 保留 |
| GP-2 | Batch 批次上傳 | 離線打卡累積後一次上傳 |
| GP-3 | Sync 同步端點 | 前端 ↔ Worker 資料同步 API |
| GP-4 | GPS 精度過濾 | accuracy > 閥值自動跳過 |
| GP-5 | 速度偵測 | ≤15 km/h 零排放 / >15 km/h 搭車 |
| GP-6 | 距離計算修正 | Haversine 公式 + 累積里程 |
| GP-7 | 時間戳標準化 | UTC → ISO 8601 統一格式 |
| GP-8 | 重複打卡防護 | 時間間隔 + 位置距離雙重檢查 |
| GP-9 | Error Recovery | 網路中斷自動重試 + 錯誤回報 |
6. 碳足跡計算模型
碳足跡採用 GPS 速度自動偵測分級，將進香移動方式分為零排放（步行/自行車）與搭車兩類。搭車碳排係數經學術校正，採用 ecoinvent「market for transport, regular bus」dataset。
零排放（≤15 km/h）
0 kg CO₂e / person·km
搭車（>15 km/h）
0.12013 kg CO₂e / person·km
住宿碳排
8.85 kg CO₂e / 晚
資料來源
ecoinvent — regular bus (person·km)
碳排數據附帶「估算值」標註與免責聲明，提供用戶參考但不做為正式碳盤查依據。碳排係數已於 Issue #103 完成修正並部署（舊值 0.47515 kg CO₂e/km 為 vehicle-km 單位，語義不正確）。
7. 基礎建設與營運
mazu.today 獨立域名
2026/04/03–04 完成 mazu.today Custom Domain 上線，透過 Cloudflare Workers 反向代理至 paulkuo.tw/projects/formosa-esg-2026/。涵蓋 DNS 設定、Worker 路由、i18n 路徑對應、webhook URL 遷移等。所有 LINE 推播連結已統一使用 mazu.today。
權限系統
三層角色權限：Owner（完整管理權限）、Manager（推播 + 用戶管理）、Volunteer（僅查看 Dashboard 地圖與統計，無推播與用戶列表）。透過 KV invite code 機制發放邀請碼，與 Worker secret 統一驗證。
營運成本結構
以下為系統開發與營運期間的實際成本。活動期間隨用戶規模成長，基礎設施與推播費用會相應增加。
| 類別 | 項目 | 費用 | 說明 |
|---|---|---|---|
| AI 開發工具 | Claude Max 20x 訂閱 | $200 USD/月 | 主要開發工具，涵蓋程式撰寫、架構設計、文件產出 |
| Claude Extra Credits | 按量計費 | 高強度開發期間的額外用量，依開發節奏浮動 | |
| Claude 儲值額度 | $250 USD | 預購額度，用於活動期間即時維運 | |
| 基礎設施 | Cloudflare Workers Paid | $5 USD/月 | 解除 100K/天請求上限 |
| Cloudflare KV / D1 用量 | ~$40 USD/月 | KV 操作佔 84%（開發期）；萬人場景預估 ~$46/月，優化後 ~$27/月 | |
| mazu.today 域名 | — | 透過 Cloudflare Workers 反向代理，無額外費用 | |
| 用戶通訊 | LINE OA 進階版 | NT$1,200/月 | 活動期間升級至最高階方案，含 6,000 則推播 |
| LINE 推播超額 | NT$0.2/則 | 超過 6,000 則後按量計費 |
上述費用為持續性支出，隨開發階段與活動狀態動態變化。Cloudflare 費用優化已完成 Plan A（移除冗餘 KV delete 操作），後續將視活動實際流量進一步調整。
8. 關鍵 Issue 追蹤
| Issue | 標題 | 風險 | 狀態 |
|---|---|---|---|
| #99 | 8 項系統韌性改進（error handling, Promise.allSettled, localStorage fallback） | L1 | 已部署 |
| #100 | RFC — HealthAlert + Service Worker + Offline Fallback | L2 | 已部署 |
| #101 | _redirects 雙域名 redirect loop（緊急 revert） | L3 | 已 revert |
| #102 | 雙 Auth 系統對齊（KV invite code + Worker secret） | L2 | 已部署 |
| #103 | 碳排搭車係數修正（ecoinvent person·km 單位） | L2 | 已部署 |
| #105 | 推播支援 image + image+text 格式 | L1 | 已部署 |
| #106 | Volunteer 可視範圍修正 | L1 | 已部署 |
| #107 | /verification/ 驗收清單頁面 | L1 | 進行中 |
| #108 | /docs/ 文件中心 + Footer 擴充 | L1 | 進行中 |
9. 已交付文件
| 文件名稱 | 版本 | 用途 | 狀態 |
|---|---|---|---|
| 香客使用說明書 | v0.4 | 一般用戶操作指南 | 已上線 |
| 管理者使用說明書 | v0.5 | Dashboard 操作 + 推播 + 用戶管理 | 已上線 |
| FAQ 常見問題 | v1.0 | 使用者自助排錯 | 已上線 |
| 隱私權聲明 | v1.0 | 資料收集與使用說明 | 已上線 |
| 上線前驗收清單 | v1.0 | 合作夥伴 / 贊助商參考 | 完成 |
| 專案開發紀錄（本文件） | v1.0 | 完整開發歷程記錄 | 完成 |
| 志工使用說明書 | — | 志工操作指南 | 規劃中 |
10. 開發里程碑
03/23 — 專案啟動
概念驗證完成，EXIF GPS 讀取 + D1 寫入可行性確認
03/24 — MVP 上線
問卷 + GPS 打卡 + 碳足跡 + 獎勵卡 + LINE Bot，24 小時內從零到可用
03/25 — UX 大改版
一題一頁卡片流程、9 級等級系統、LIFF 整合、分享卡片、Dashboard 地圖。同日完成壓力測試 R1
03/26 — 壓力測試完成
R2-R4 完成，確認 D1 瓶頸與 KV Buffer 解法方向
03/29 — KV Buffer 驗證
三項解法全部部署驗證通過：KV Buffer、Cron Flush、Data API Cache
03/31 — GPS 管線修復
GP-1 ~ GP-9 共 9 項修復完成部署，資料品質大幅提升
04/03 — mazu.today 上線
獨立域名正式生效，品牌辨識度提升，所有 LINE 連結遷移完成
04/05 — 全量部署
RFC #100 + Issues #99 / #102 / #103 / #105 / #106 一次部署。Open Issues 歸零
04/07 — 上線前驗收
驗收清單完成、技術文件盤點、費用優化 Plan A 部署。距起駕 5 天
04/12 — 起駕日
白沙屯拱天宮出發，系統正式啟用