活動卡點：好玩的尋寶機制，背後需要可靠的現場系統
園區希望用「尋4大作戰」讓遊客主動探索各區，但活動不能只做一張會開網頁的 QR Code。實際營運需要同時解決：
- 不能重複計點：同一個 QR 重掃只能提示，不能讓累積數失真。
- 不能綁死在同一台手機：遊客清除 Cookie 或換裝置後，仍要有方法找回進度。
- 兌獎必須可控：只有現場工作人員能完成核銷，且同一份進度不能重複領獎。
- 活動要能覆盤：需要知道參加者從廣告、分享、官網或現場何處得知活動。
- 現場網路不一定穩定：高峰掃描、短暫資料庫忙碌與相機辨識速度，都要有明確處理方式。
產品策略：免登入參加，關鍵狀態由系統保護
本專案把遊客端操作壓到最短：開啟頁面、選擇活動來源、掃描 QR、查看進度。帳號註冊被 10 碼恢復編號取代，降低進場摩擦；掃描、計點與核銷則交由後端驗證，避免只靠前端狀態。
核心功能
遊客流程
- 50 組唯一 QR：每個園區點位使用獨立 token，正式重置後與舊 token 完全分離。
- 掃描去重：首次掃描累積進度，重複掃描顯示醒目提示但不重複計算。
- 6 級集點成就：依 8、16、24、32、40、50 個掃描數逐級回饋。
- 恢復編號：建立進度時提供 10 碼編號，換裝置或遺失 Cookie 後可找回。
- 來源問答：記錄 FB、IG、朋友分享、現場或官網等活動來源，留下行銷歸因鉤子。
現場營運
- 工作人員核銷：以受保護的工作人員流程完成兌獎，已核銷狀態不可重複使用。
- 活動日操作手冊：定義開場前測試、常見狀態碼、限流、監控與異常應對。
- 雙掃描引擎：支援原生
BarcodeDetector的裝置優先使用快速辨識，不支援時自動退回 ZXing。 - 可恢復錯誤處理：針對請求過快與資料庫暫時忙碌，前端會依回應延遲重試。
技術亮點
- 後端原子計點：掃描紀錄與參加者計數在同一資料庫交易中處理，避免重送造成重複累積。
- 可辨識模糊提交：資料庫已成功寫入但回應中斷時，利用同次操作時間辨識重播，不把成功誤報為失敗。
- 持久化限流：限流寫入 Cloudflare D1，不依賴單一執行環境的記憶體，活動尖峰下仍能保護掃描與核銷端點。
- QR 密度優化：token 調整為 72-bit 隨機值，QR 由 41 模組降為 37 模組，提高 5 公分印刷品的辨識容錯。
- 正式資料保護：活動資料沒有測試標記時，操作手冊明確禁止依時間直接批次清除，避免誤刪參加者紀錄。
系統架構
遊客開啟活動頁
│
├── 建立免登入 Session ── 取得恢復編號
├── 選擇活動來源 ──────── 留下歸因資料
└── 掃描園區 QR
│
├── token 驗證與持久化限流
├── Cloudflare D1 原子去重與計點
├── 6 級成就與下一階提示
└── 工作人員核銷 ── 防止重複兌獎
技術棧
- 前端與應用框架：Next.js、React、TypeScript
- 部署與執行環境：Cloudflare Workers
- 資料庫：Cloudflare D1、Drizzle ORM
- 掃描能力：BarcodeDetector、ZXing
- 營運資產：50 張 QR PNG、5 頁印刷 PDF、CSV 與部署素材包
驗證證據
- 50 組新 token 與雜湊皆唯一，且與舊雜湊沒有重疊。
- 全新本機 D1 可依序執行完整 migration，資料庫只保留新雜湊。
- 正式環境完成 Session → 來源 → 新 QR → 重複 QR 往返：首次計數為 1，重複掃描仍維持 1。
- 正式 D1 的 50 組新雜湊全數命中，舊雜湊命中數為 0。
- TypeScript、ESLint、production build 與差異格式檢查全數通過。
- 5 頁 QR 印刷 PDF 已逐頁渲染，抽查首頁與末頁沒有裁切。
AI 協作筆記：本專案的活動流程拆解、QR 安全設計、掃描競態處理、D1 限流與現場操作手冊，透過 AI 協作完成設計、實作與逐項驗證；最終規則與上線責任仍由人員確認。