開発記録
Formosa ESG 2026
Formosa ESG 2026
白沙屯媽祖巡礼 GPS トラッキングシステム — プロジェクト開発記録
概念実証から万人対応システムへ：開発経緯の概要
バージョン 1.0
対象期間：2026/03/23 —
更新日：2026/04/07
Formosa ESGプロジェクトチーム
5
開発フェーズ
4
負荷テスト回数
106+
Issues 対応数
4
対応言語数
1. プロジェクト概要
「Formosa ESG 2026 白沙屯媽祖巡礼 GPS トラッキングシステム」は、GPS 定位、カーボンフットプリント推定、ソーシャルインタラクションを統合した巡礼トラッキングサービスです。巡礼者は LINE で LOGIN し、スマートフォンでリアルタイムチェックイン、走行距離の蓄積、ランクアップの進捗確認、パーソナライズされたアチーブメントカードの共有が可能です。システムはまた管理者ダッシュボードを提供し、リアルタイムマップ、プッシュ通知、ユーザー管理などのバックエンド機能を含みます。
技術アーキテクチャは Astro（フロントエンド SSG）+ Cloudflare Pages + Workers + D1（SQLite）+ KV（キャッシュとバッファ）を採用し、LINE LIFF SDK と統合してログインと共有機能を実現しています。システムは 1 万人同時利用を想定して設計されています。
イベント日
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 + 共有カード + ダッシュボード | 完了 |
| Phase 1.5 | 03/25–26 | セキュリティ強化 + ダッシュボード + 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段階巡礼者ランクシステム（初心者→飛升），2つの条件：km + チェックイン回数 | 完了 | |
| Phase 1 | 9枚の AI 生成キャラクター画像（絵文字ランクアイコン代替） | 完了 | |
| Phase 1 | LINE LIFF SDK 統合（Login channel + init） | 完了 | |
| Phase 1 | 共有カード（縦レイアウト + 地図 + QR + キャラクター + 統計） | 完了 | |
| Phase 2 | 負荷テスト R1：HTTP 層 C-10K ~ C-100K 全 PASS | 完了 | |
| 03/26 Day 4 |
Phase 1.5 | ダッシュボード：ヒートマップ + クラスタリングマーカー + フロント/テール + 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 修正（写真サムネイル / Facebook 共有 / 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 | Facebook パーソナライズ 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 バッチ 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 | ダッシュボード アクセスログ（fire-and-forget KV ログ） | 完了 | |
| 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：ボランティア可視範囲修正（プッシュ通知 + ユーザーリストのみ非表示） | デプロイ済 | |
| 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 シングルライター制限確認；即時成功率 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 | 距離計算修正 | ハバーサイン公式 + 累積走行距離 |
| GP-7 | 期間戳標準化 | UTC → ISO 8601 統一格式 |
| GP-8 | 重複打卡防護 | 期間間隔 + 位置距離雙重檢查 |
| GP-9 | エラーリカバリー | 網路中斷自動重試 + 錯誤回報 |
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% 占有（開発期間）；1万人想定 ~$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 | ダッシュボード操作 + プッシュ通知 + ユーザー管理 | 已上線 |
| よくある質問（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 — 出発日
白沙屯拱天宮より出発、システム本番稼働開始