專案介紹
香譜是一款香水收藏與試香紀錄工具。去專櫃試了好幾支,隔週就忘了哪支喜歡;收藏越來越多,每天出門前也不知道該噴哪一支。香譜把試香感想、收藏檔案跟每日使用紀錄放在一起,讓這些紀錄反過來幫你挑今天的香水。
整個服務跑在 Cloudflare Workers 上,搭配 D1、R2、KV 跟 Durable Objects,可以安裝成 PWA,在沒有網路的專櫃也能先記下來,回到線上再自動同步。
隨著公共香水庫增加,我把資料讀取拆成兩條路線:大家共用的產品資訊發布成可快取的資料包,自己的評分、心得跟使用紀錄則走會員同步。同一份香水資料能在收藏、圖鑑跟試香畫面重用,也減少每次開頁面或搜尋時對資料庫的重複讀取。
核心功能
技術架構
前端
以 Hono JSX 產生頁面外殼,互動區塊用 React 19 islands 掛載,搭配 Tailwind CSS v4、Base UI 跟 Framer Motion 處理抽屜、分頁等手機原生感的操作。
後端
執行於 Cloudflare Workers。D1 保存公共香水主檔、審核資料跟會員私人紀錄;公共目錄另外發布到 R2,透過邊緣快取提供讀取。圖片也放在 R2,KV 則依會員跟 D1 版本快取可丟棄的 API 回應。
認證系統
使用 WorkOS AuthKit 登入,Worker 處理 PKCE、callback 跟 Session 更新。密封後的 Session 放在 HttpOnly Cookie,HTTPS 環境使用 __Host- 前綴,瀏覽器只拿得到會員基本資料。
離線同步
IndexedDB 分開保存公共目錄、會員資料快照跟離線操作佇列(outbox),恢復連線後依序送出私人操作。Durable Objects 透過 WebSocket 通知同一會員的其他裝置檢查版本、同步有變動的資料,前景每五分鐘再補查一次會員版本。公共目錄則自行檢查版本、下載快照。
公共香水庫跟私人資料的雙線路架構
產品資料整理一次,讓不同紀錄共用
品牌、品名、濃度、調香師跟香調等產品資訊集中在公共香水庫維護。會員的收藏、試香跟使用紀錄透過 catalogId 連結同一個品項,顯示時再補上公共欄位;評分、心得、購買資訊跟私人圖片則各自保存。
公共線路:主檔發布成快照,再分發到裝置
D1 保留公共主檔跟審核依據,通過公開條件的欄位才會寫進 R2 的版本化 JSON 快照。裝置先讀取小型版本清單,版本改變才下載資料包,並透過 CDN 邊緣快取重用同一份內容。一般公共目錄讀取不必查詢 D1,也不用每次重算哪些欄位可以公開。
私人線路:沿用會員 API 跟 D1 同步
個人紀錄經過登入驗證後,由會員 API 讀寫 D1。所有私人查詢都經過同一個資料存取層,從已驗證的會員身分產生查詢範圍;資料庫 triggers 再檢查跨表關聯的擁有者。私人資料各自同步,不會進入公共快照或共享快取。
在本機組合跟搜尋
公共目錄下載後保存在 IndexedDB,前端將它跟會員私人紀錄組合,搜尋也優先使用這份本機資料。私人圖片優先於公共圖片;品項下架或公共欄位撤回時,則回到會員保留的私人副本。離線時可以繼續使用最後一份目錄,下載新版失敗也保留舊資料。
公共版本跟私人版本分開更新
公共香水庫更新,不再連帶讓收藏、試香跟使用紀錄的快取失效,裝置只需更新公共快照。私人紀錄有變動時,才走原本的會員同步;推薦跟部分伺服器頁面仍會讀取 D1 的完整資料,推薦版本也會隨公共欄位變動。
把重複讀取集中到發布時處理
排程每五分鐘檢查公共目錄變動,平常只重讀有修改的品項,修補後發布成新版本;另外保留完整重建跟每日校驗。這樣能把公共目錄的資料庫工作集中在內容更新時,減少隨瀏覽、搜尋次數增加的重複讀取。裝置定期檢查版本後才會套用新版,離線裝置則在重新連線後更新。
公共香水庫的收錄流程
共用目錄需經審核
找不到的香水只要填品牌跟名稱,就能先建立自己的紀錄,同時提出收錄申請。管理員逐欄核實來源跟使用範圍後才會公開;審核通過會自動連結共用資料,個人的評價、紀錄跟私人圖片都保留。
不批次爬取
來源整理預設不啟用任何網站,需要先記錄網域的讀取依據,再逐筆讀取產品頁的結構化資料。只保存待核實的欄位建議,不複製圖片、介紹文案或評論。
推薦機制
推薦不呼叫生成式 AI,而是用規則計算:個人偏好標籤、評分、適合的場合跟天氣、近期使用紀錄,再加上選填的即時天氣(體感溫度、濕度、降雨機率)。每一支推薦都會附上理由,例如「偏熱友善:清新,個人天氣:多雲」,讓你知道它為什麼被選出來。






