Development Record
Formosa ESG 2026
Formosa ESG 2026
白沙屯媽祖進香 GPS 追蹤系統 — 專案開發紀錄
從概念驗證到萬人系統：簡述開發歷程
版本 1.2
涵蓋期間：2026/03/23 — 2026/04/17
更新日期：2026/04/17
Formosa ESG 專案團隊
6
開發階段
5
Pre-Launch Audit 輪次
179+
已解決問題
4
支持語言
1. 專案概述
"Formosa ESG 2026 白沙屯媽祖進香 GPS 追蹤系統"是一個結合 GPS 定位、碳足跡估算和社區互動的進香追蹤服務。香客通過 LINE 登錄，使用手機進行實時打卡，累積里程數，查看等級進度，並可生成並分享個人成就卡。系統還為管理員提供實時地圖儀表板、推送通知、用戶管理等後端功能。
技術架構採用 Astro（前端靜態生成）+ Cloudflare Pages + Workers + D1（SQLite）+ KV（緩存和緩衝），結合 LINE LIFF SDK 進行登錄和分享集成。系統設計可處理 10,000 併發用戶。
活動日期
2026/04/12 出發
活動週期
~8-9 天（媽祖意願）
容量目標
10,000 併發用戶
支持語言
zh-Hant / en / ja / zh-Hans
前端框架
Astro + Cloudflare Pages
後端架構
Workers + D1 + KV
2. 開發階段總覽
| 階段 | 日期 | 核心目標 | 狀態 |
|---|---|---|---|
| 階段 0 | 03/23 | PoC：EXIF GPS 讀取、D1 寫入可行性 | 完成 |
| 階段 0.5 | 03/24 | MVP：16 問卷 + GPS 打卡 + 碳足跡 + 成就卡 + LINE webhook | 完成 |
| 階段 1 | 03/25 | UX 優化：逐問設計卡 + 9 級等級 + LIFF + 分享卡 + 儀表板 | 完成 |
| 階段 1.5 | 03/25–26 | 安全加固 + 儀表板 + LIFF 已發佈 + Workers 付費升級 | 完成 |
| 階段 2 | 03/25–26 | 4 輪壓力測試 + D1 瓶頸分析 + KV 緩衝架構設計 | 完成 |
| 階段 3 | 03/27–30 | GPS 管線修復 GP-1~GP-9 + 隱私機制 + 文檔 + 高級功能 | 完成 |
| 階段 4 | 03/31–04/07 | 問卷優化 Q16→Q10 + 權限系統 + 成本優化 Plan A + 上線前檢查 | 完成 |
| 階段 5 | 04/08–11 | Pre-Launch Audit 五輪完成 + 分眾推播 + Issue #155 自動同步儀表板 | 完成 |
| 活動期 | 04/12– | 起駕上線運維：熱修 #168/#171/#172 + 治理 v4.8→v4.12 + post-event branch 隔離 | 進行中 |
3. 逐日開發紀錄
| 日期 | 階段 | 交付內容 | 狀態 |
|---|---|---|---|
| 03/23 第 1 天 |
階段 0 | 專案頁面框架（Astro SSG + Cloudflare Pages） | 完成 |
| 03/24 第 2 天 |
階段 0.5 | 16 問 ESG 問卷（逐問設計卡工作流） | 完成 |
| 階段 0.5 | GPS 打卡功能 + 碳足跡計算引擎 | 完成 | |
| 階段 0.5 | 成就卡系統（打卡點位可視化） | 完成 | |
| 階段 0.5 | LINE Bot webhook 集成（消息 API） | 完成 | |
| 階段 0.5 | Cloudflare Workers CORS 修復 + 部署驗證 | 完成 | |
| 03/25 第 3 天 |
階段 1 | UX 優化：逐問設計 + 直線進度條 + 滑動動畫 | 完成 |
| 階段 1 | 9 級香客等級系統（修煉→飛昇），雙條件：km + 打卡數 | 完成 | |
| 階段 1 | 9 張 AI 生成吉祥物圖（替代表情圖標） | 完成 | |
| 階段 1 | LINE LIFF SDK 集成（登錄頻道 + 初始化） | 完成 | |
| 階段 1 | 分享卡（縱向佈局 + 地圖 + 二維碼 + 吉祥物 + 統計） | 完成 | |
| 階段 2 | 壓力測試 R1：HTTP 層 C-10K ~ C-100K 全部通過 | 完成 | |
| 03/26 第 4 天 |
階段 1.5 | 儀表板：熱力圖 + 聚類標記 + 前後段 + 3 種模式切換 | 完成 |
| 階段 1.5 | 安全加固：認證網關 + 管理 Token API 驗證 | 完成 | |
| 階段 2 | 壓力測試 R2：800 VU 最優點確認（99.99% 成功率） | 完成 | |
| 階段 2 | 壓力測試 R3：D1 寫入瓶頸驗證（SQLite 單寫者鎖） | 完成 | |
| 階段 2 | 壓力測試 R4：真實場景模擬（CF-800 通過 / RW-500 數據 API 瓶頸） | 完成 | |
| 03/27–28 第 5–6 天 |
階段 3 | 碳足跡每日報告前端 + 動態生成 OG 圖片 | 完成 |
| 階段 3 | 吉祥物圖 4 倍分辨率升級 + 儀表板認證修復 | 完成 | |
| 階段 3 | 7 項 UX 修復（照片縮略圖 / FB 分享 / GPS 持久化等） | 完成 | |
| 階段 3 | 功能盤點：23 項完成清單編制 | 完成 | |
| 03/29 第 7 天 |
階段 3 | 隱私同意機制（P0）+ 暫停/完成狀態 | 完成 |
| 階段 3 | 碳足跡簡化為 2 層結構（零排放 vs 機動交通） | 完成 | |
| 階段 3 | 二維碼替換為 NET-ZERO 徽標 + FB OG 圖片修復 | 完成 | |
| 階段 3 | 用戶指南轉換為網頁（香客版 + 管理員版） | 完成 | |
| 階段 3 | LINE Bot 指導鏈接集成 | 完成 | |
| 階段 3 | 活動照片歸檔功能 + FB 分享 fbclid 修復 | 完成 | |
| 03/30 第 8 天 |
階段 3 | 活動照片歸檔按鈕 UX 改進（清晰保存按鈕） | 完成 |
| 階段 3 | 個性化 FB OG 圖片實現 | 完成 | |
| 階段 3 | 測試模式橫幅 + 照片保存 bug 修復 | 完成 | |
| 03/31 第 9 天 |
階段 3 | 完整 GPS 數據管線修復 GP-1 ~ GP-9（commit 8f08e5d） | 已部署 |
| 階段 3 | KV 緩衝架構實現：打卡 → KV → Cron 批量插入 D1 | 已部署 | |
| 階段 3 | 住宿碳係數更新：12.5 → 8.85 kgCO₂e/晚 | 完成 | |
| 04/01–02 第 10–11 天 |
階段 4 | 問卷優化 Q16 → Q10（減少 6 問 + 重新編號） | 已部署 |
| 階段 3 | 三層權限系統上線：擁有者 / 經理 / 志工 | 已部署 | |
| 階段 3 | 儀表板訪問日誌（即發即棄 KV 日誌） | 完成 | |
| 階段 4 | 成就卡門檻：打卡 ≥3 次 + 完成問卷 + 留電話 | 完成 | |
| 04/03–04 第 12–13 天 |
階段 3 | mazu.today 自有域名上線（Worker 路由 + DNS） | 已部署 |
| Ops | RFC #100：HealthAlert + Service Worker + 離線回退驗證 | 已部署 | |
| Ops | Issue #99：8 項彈性改進（Promise.allSettled、localStorage 回退等） | 已部署 | |
| Ops | Issue #102：雙認證系統對齊（KV 邀請碼 + Worker 密鑰統一） | 已部署 | |
| 階段 3 | LIFF 頻道 → 已發佈（所有用戶可用） | 已部署 | |
| 04/05 第 14 天 |
Ops | Issue #103：碳機動交通係數修正 0.47515 → 0.12013 kg CO₂e/人·km | 已部署 |
| Ops | Issue #105：推送支持圖片 + 圖片+文本格式（commit 35945cd） | 已部署 | |
| Ops | Issue #106：志工可視範圍修正（僅隱藏推送 + 用戶列表） | 已部署 | |
| Ops | Worker 全面部署確認（版本 342af8b0） | 已部署 | |
| 階段 4 | Cloudflare 成本分析：$44.63/月，KV 操作佔 84% | 完成 | |
| 04/06–07 第 15–16 天 |
階段 4 | KV 成本優化 Plan A：移除 TICKER_KV.delete()（commit a4b6fd2） | 已部署 |
| 階段 4 | 上線前驗收清單生成（7 類別、34 項） | 完成 | |
| 階段 4 | 完整技術文檔清單 + 公開部署計劃（/docs/ + /verification/） | 完成 | |
| 階段 4 | mazu.today 重定向規則偵察完成（Cloudflare 儀表板方案確認） | 完成 | |
| 04/08–09 第 17–18 天 |
階段 4 | Issue #141：分眾推送 + LIFF OA 引導 + Secrets 盤點 | 已部署 |
| 階段 4 | Issue #120：推送圖片上傳（R2 存儲）+ Wiki Phase 3–4A | 已部署 | |
| Ops | 儀表板遷移至 GitHub Issue #155 + sync-dashboard Action 自動同步 | 完成 | |
| 04/10 第 19 天 |
Ops | Pre-Launch Audit R3：數據質量 + 防禦韌性（computeFilteredKm + VALID_SOURCES 修復，Worker deploy 174bace0） | 已部署 |
| Ops | Issue #162：今日善足跡 API 驗證通過 | 完成 | |
| Ops | CI/CD 盤查 + 治理框架 Phase 1–2.5 完成（Dashboard + API + KV seed） | 已部署 | |
| 04/11 第 20 天 |
Ops | Pre-Launch Audit R4：用戶旅程 + 邊界人物 + 運維韌性（P0=0, P1=4 全修, Worker deploy 876dddbd） | 已部署 |
| Ops | Issue #163：GPS 漂移 + 直線軌跡修復（speed outlier filter + accuracy 過濾） | 已部署 | |
| Ops | Issue #161：分享足跡鏈接修復（race condition — lineUserId 在 LIFF async 前為 null） | 已部署 | |
| Ops | Pre-Launch Audit R5：全面代碼健康檢查 + 修復完成（P0×2 + P1×6 全修，commit 9fa6c9d） | 完成 | |
| Ops | 五輪 Pre-Launch Audit 全部完成 ✅ — 核心打卡路徑穩固、離線機制完整、無死路由 | 完成 | |
| 04/12 第 21 天 — 起駕 |
Ops | 🎉 白沙屯拱天宮起駕，系統正式上線運行（Worker 版本 8148bac5） | 已部署 |
| Ops | 起駕日清場：D1 測試資料全清（users 143→0, gps 1140→0, surveys 20→0）+ KV gps: buffer 9,255 key bulk delete | 完成 | |
| Ops | Feedback 治理 Phase A 完成：formosa-feedback skill 新增 Step 6.5 exit gate + session-handoff v4.4 reconciliation + 7 筆舊 triaging 全部 PATCH fixed | 已部署 | |
| Ops | Phase B batch-update.yml 上線：file-based trigger 方案（Chat 研究→Cowork 說帖→Code 實作→Cowork 驗收），commit 57024b2 | 已部署 | |
| 04/13 第 22 天 |
Ops | Issue #168 GPS 幽靈里程修復（commit 9160a69）— /track/sync 加 geofence + WHERE source != 'remote' 過濾；催生護欄 #13（新 endpoint 防護繼承）、session-handoff 升級 v4.8 | 已部署 |
| 04/14 第 23 天 |
Ops | Issue #170 pushHours 幽靈部署事故：跨 repo 真相驗證失誤；催生護欄 #14 + Code 完成三態宣告規範，session-handoff 升級 v4.9 | 完成 |
| Ops | Issue #171 個人足跡頁碳欄位修復（commit 93fb621）— 綁錯 carbon_kg 欄位，已部署待 LIFF 實測 | 已部署 | |
| Ops | 治理框架 Code-First 審計落地：session-handoff v4.9 整併 Code / Cowork 三態宣告、延遲觸發行為驗證 | 完成 | |
| 04/15 第 24 天 |
Ops | Issue #172 網頁版/LINE 雙等級不同步修復（commit a389dd6）— 根因：localStorage 跨瀏覽器隔離 + Stats API fallback 陷阱（Math.max(len, 1) 對空陣列回 1）；衍生 #174 AuthGate bypass + #175 auto-close.yml injection | 已部署 |
| Ops | Feedback 三筆直接回報分流：#177 GPS 彰化以南未記錄 / #178 LIFF 常駐影響 LINE 群+來電 / #179 拍照入口+我的相簿 — 全部 post-event label；確立活動期原則：靜默修復優於警示、門檻 = 純後台且零體感副作用才動 | 排程中 | |
| 04/16 第 25 天 |
Ops | Cowork 巡查 + Code Formosa post-event batch fix：Batch 1 (#175 auto-close.yml injection) 進 main (0aeb496)；Batch 2+3 (#177/#178/#173/#174/#179) 於 fix/formosa-post-event branch 隔離，待活動後 merge+deploy | 隔離中 |
| Ops | Impact Fence（活動期程式碼圍籬）建立：🟢 Safe Zone（CI/CD）直接進 main / 🔴 Live Zone（前端+Worker）fix/formosa-post-event 隔離 | 完成 | |
| 04/17 第 26 天 |
Ops | CI race condition 系統性修復（commit 70173b2）：seo-index.yml + ai-ready-opt.yml 加 concurrency group + 3-retry pull --rebase loop，根治 workflow_run 串連自我 race | 已部署 |
| Ops | Cowork 治理 v4.12 落地：儀表板載體正名（Apple Notes→Issue #155 單一載體）；新增 Phase 版本沿革 v4.7→v4.12 + 護欄 #12–#14 沿革 | 完成 |
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 全部通過；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 單寫者鎖；實時成功率 42%；延遲 +51% |
| R4 | 03/26 | 真實場景模擬 | 500–800 | CF-800（直接 D1 寫）100% 通過；RW-500（混合負載）60% 失敗 = 數據 API 瓶頸 |
根本原因與解決方案
R3-R4 測試確認根本原因是 D1 SQLite 的單寫者鎖，在高併發下造成序列化瓶頸。解決方案採用 KV 緩衝架構：
方案 1 — KV 緩衝
將打卡寫入 KV（非 D1），key = gps:{ts}:{userId}:{randomId}
方案 2 — Cron 刷新
每 5 分鐘批量刷新 KV → D1，INSERT OR IGNORE 防止重複
方案 3 — 數據 API 緩存
統計先檢查 KV 緩存（TTL 60s），未命中再查 D1
所有三項方案已在 2026/03/29 部署並驗證。
5. GPS 數據管線修復
2026/03/31 進行了完整的 GPS 數據管線修復（commit 8f08e5d），涵蓋 9 項改進：
| 專案 | 修復項 | 說明 |
|---|---|---|
| GP-1 | 自動追蹤持久化 | localStorage 狀態跨會話保持 |
| GP-2 | 批量上傳 | 離線累積打卡批量上傳 |
| GP-3 | 同步端點 | 前端 ↔ Worker 數據同步 API |
| GP-4 | GPS 精度過濾 | 精度 > 閾值自動跳過 |
| GP-5 | 速度檢測 | ≤15 km/h 零排放 / >15 km/h 機動交通 |
| GP-6 | 距離計算修復 | Haversine 公式 + 里程累積 |
| GP-7 | 時間戳標準化 | UTC → ISO 8601 統一格式 |
| GP-8 | 重複打卡保護 | 時間間隔 + 位置距離雙重檢查 |
| GP-9 | 錯誤恢復 | 網絡中斷自動重試 + 錯誤上報 |
6. 碳足跡模型
碳足跡使用 GPS 速度自動檢測將進香運動分為零排放（步行/騎行）和機動交通。機動交通碳係數使用 ecoinvent"公交車市場"數據集進行學術修正。
零排放（≤15 km/h）
0 kg CO₂e / 人·km
機動交通（>15 km/h）
0.12013 kg CO₂e / 人·km
住宿碳排
8.85 kg CO₂e / 晚
數據來源
ecoinvent — 公交車（人·km）
碳數據包含"估算"標註和免責聲明，作為用戶參考提供，但並非官方碳會計。碳係數在 Issue #103 中修正（舊值 0.47515 kg CO₂e/km 是車·km 基礎，語義不正確）。
7. 基礎設施與運維
mazu.today 獨立域名
2026/04/03–04 mazu.today 自有域名上線，通過 Cloudflare Workers 反向代理到 paulkuo.tw/projects/formosa-esg-2026/。涵蓋 DNS 設置、Worker 路由、i18n 路徑映射、webhook URL 遷移等。所有 LINE 推送鏈接現已使用 mazu.today。
權限系統
三層角色權限：擁有者（完整管理權限）、經理（推送 + 用戶管理）、志工（僅查看儀表板地圖和統計，無推送或用戶列表）。通過 KV 邀請碼機制分配邀請碼，與 Worker 密鑰統一驗證。
Cloudflare 成本分析
月度成本（03/05–04/04）
$44.63 USD
最大專案
KV 操作佔 84%
10K 用戶預估
~$46/月（可控）
優化後預估
~$27/月（Plan A 移除刪除操作）
其他基礎設施
Workers 付費計劃升級（$5/月），移除 100K/天請求限制。LIFF 頻道已發佈。LINE OA 升級至中等級（3,000 消息/月）。儀表板推送支持文本、模板和圖片格式。
8. 關鍵問題追蹤
| Issue | 標題 | 風險 | 狀態 |
|---|---|---|---|
| #99 | 8 項系統彈性改進（錯誤處理、Promise.allSettled、localStorage 回退） | L1 | 已部署 |
| #100 | RFC — HealthAlert + Service Worker + 離線回退 | L2 | 已部署 |
| #101 | _redirects 雙域名重定向循環（緊急回退） | L3 | 已回退 |
| #102 | 雙認證系統對齊（KV 邀請碼 + Worker 密鑰） | L2 | 已部署 |
| #103 | 碳機動交通係數修正（ecoinvent 人·km 基礎） | L2 | 已部署 |
| #105 | 推送支持圖片 + 圖片+文本格式 | L1 | 已部署 |
| #106 | 志工可視範圍修正 | L1 | 已部署 |
| #107 | /verification/ 驗證頁面 | L1 | 已部署 |
| #108 | /docs/ 文檔中心 + Footer 擴展 | L1 | 已部署 |
| #120 | 推送圖片上傳（R2 存儲） | L1 | 已部署 |
| #141 | 分眾推送 + LIFF OA 引導 | L2 | 已部署 |
| #161 | 分享足跡鏈接 race condition 修復 | L2 | 已部署 |
| #162 | 今日善足跡 API 驗證 | L1 | 完成 |
| #163 | GPS 漂移 + 直線軌跡修復 | L2 | 已部署 |
| #168 | GPS 幽靈里程（靜止用戶累積假 km）— geofence + source filter | L2 | 已部署 |
| #170 | pushHours 幽靈部署事故 — 跨 repo 真相驗證（催生護欄 #14） | L2 | 完成 |
| #171 | 個人足跡頁 carbon_kg 欄位綁錯修復 | L1 | 已部署 |
| #172 | 網頁版／LINE 雙等級不同步（localStorage 隔離 + fallback 陷阱） | L2 | 已部署 |
| #173 | Dashboard 媽祖定位缺席 | L1 | post-event branch |
| #174 | AuthGate bypass 疑似 | L2 | post-event branch |
| #175 | auto-close.yml Expression injection — gh api 取代 shell heredoc | L1 | 已部署 |
| #177 | GPS 彰化以南未記錄（Vivo OriginOS 節電策略假說） | L1 | post-event branch |
| #178 | LIFF 常駐影響 LINE 群+來電 | L1 | post-event branch |
| #179 | 照片上傳找不到拍照入口 + 缺少我的相簿 | L1 | post-event branch |
9. 交付文檔
| 文檔名稱 | 版本 | 目的 | 狀態 |
|---|---|---|---|
| 香客用戶指南 | v0.4 | 通用用戶操作指南 | 已上線 |
| 管理員用戶指南 | v0.5 | 儀表板操作 + 推送通知 + 用戶管理 | 已上線 |
| 常見問題 | v1.0 | 用戶自助故障排查 | 已上線 |
| 隱私政策 | v1.0 | 數據收集和隱私 | 已上線 |
| 上線前驗收清單 | v1.0 | 合作伙伴 / 贊助商參考 | 完成 |
| 專案開發紀錄（本文檔） | v1.0 | 完整開發歷程記錄 | 完成 |
| 志工用戶指南 | — | 志工操作指南 | 已上線 |
10. 開發里程碑
03/23 — 專案啟動
PoC 完成，EXIF GPS 讀取 + D1 寫入可行性確認
03/24 — MVP 上線
問卷 + GPS 打卡 + 碳足跡 + 成就卡 + LINE Bot，24 小時從零到功能
03/25 — 重大 UX 優化
逐問設計卡工作流、9 級等級系統、LIFF 集成、分享卡、儀表板地圖。同日完成壓力測試 R1
03/26 — 壓力測試完成
R2-R4 完成，確認 D1 瓶頸和 KV 緩衝方案方向
03/29 — KV 緩衝驗證
三項方案全部部署並驗證：KV 緩衝、Cron 刷新、數據 API 緩存
03/31 — GPS 管線修復
GP-1 ~ GP-9，9 項修復部署，數據質量顯著提升
04/03 — mazu.today 上線
獨立域名上線，品牌認可度提升，所有 LINE 鏈接已遷移
04/05 — 全面部署
RFC #100 + Issues #99 / #102 / #103 / #105 / #106 一同部署。未解決問題已解決
04/07 — 上線前評審
驗收清單完成、技術文檔清單、成本優化 Plan A 部署。距起駕 5 天
04/08–09 — 功能完善 + 治理框架
分眾推送上線、推送圖片 R2 存儲、儀表板遷移至 GitHub Issue #155 自動同步
04/10 — R3 審計 + 修復
數據質量 + 防禦韌性審計，computeFilteredKm + VALID_SOURCES 修復部署，治理框架上線
04/11 — 五輪審計全部完成 ✅
R4 + R5 審計 + 修復完成，Issue #161/#163 關閉。核心路徑穩固，距起駕 1 天
04/12 — 起駕日
白沙屯拱天宮出發。系統正式上線（Worker 版本 8148bac5）。同日完成起駕清場（D1 + KV 歸零）與 Feedback 治理 Phase A + B。
04/13 — Issue #168 GPS 幽靈里程修復
靜止用戶累積假 km 修復（geofence + source filter），催生護欄 #13、skill 升至 v4.8
04/14 — Issue #170 事故與治理升級
pushHours 幽靈部署事故，催生護欄 #14「跨 repo 真相驗證」+ Code 三態宣告；session-handoff 升至 v4.9
04/15 — Issue #172 雙等級根因釐清
localStorage 跨瀏覽器隔離 + fallback 陷阱修復；確立活動期兩條原則（靜默修復優於警示、部署門檻 = 純後台零體感副作用）
04/16 — post-event branch 隔離
Impact Fence 建立：🟢 Safe Zone 直接 main / 🔴 Live Zone 於 fix/formosa-post-event 隔離五項修復（#173/#174/#177/#178/#179）
04/17 — 活動期運維穩定
CI race condition 系統性修復（concurrency group + pull --rebase retry）；Cowork 治理 v4.12 落地，儀表板載體正名為 Issue #155 單一事實來源