一個冒險主題的日本購物清單管理應用，專為「村民A」和「村民B」設計，讓購物變成一場冒險遊戲！
選擇你的冒險身份 —「村民A」或「村民B」
瀏覽所有待購商品，依分類或店舖篩選
旅遊攻略據點一覽，規劃你的冒險路線
即時新增或編輯商品資訊
所有商品收集完畢，冒險成功！
- 📋 商品管理 - 60+ 種精選日本必買商品，含化妝品、保養品、藥品、生活用品、小物等
- ➕ 新增 / 編輯商品 - 可即時新增或修改商品資訊（品名、分類、店舖、描述、圖片連結）
- 🔍 智能搜尋 - 快速找到想要的商品
- 🏷️ 雙模式篩選 - 依「分類」或「店舖」篩選商品，附已完成篩選
- 👥 雙人進度追蹤 - 村民A 與村民B 分別標記已購買商品，進度條呈現各自貢獻
- 📸 商品圖片 - 透過 Google Drive 連結顯示商品照片
- 🔎 Google 搜圖 - 一鍵開啟 Google 圖片搜尋
- 📍 據點管理 - 購物、動漫、遊玩、餐廳、伴手禮等分類的旅遊攻略
- ➕ 新增 / 編輯據點 - 即時新增或修改攻略據點（地點、描述、分類、行動、連結）
- ✅ 完成追蹤 - 標記已造訪的據點
- 🔗 外部連結 - 支援附加相關連結（Instagram、Google Maps 等）
- 🌿 沉浸式冒險主題設計，深綠色調搭配金色漸層
- 🐾 背景腳印、樹葉等裝飾元素
- ✨ 動態進度條與動畫效果
- 📱 行動裝置優先的響應式設計
- 🔥 Firebase Firestore - 即時雲端同步，多裝置即時更新
- 📊 Google Sheets 雙向同步 - 從 Google Sheets 匯入 / 匯出資料
| 技術 | 用途 |
|---|---|
| React 18 | UI 框架 |
| TypeScript | 類型安全 |
| Vite | 開發建置工具 |
| TailwindCSS | 樣式框架 |
| Lucide React | 圖示庫 |
| Firebase Firestore | 即時雲端資料庫 |
| Google Sheets API | 資料匯入匯出 |
japan-shiba-rb/
├── docs/
│ └── screenshots/ # 應用程式畫面截圖
├── src/
│ ├── App.tsx # 主應用程式（含用戶選擇、頁籤管理）
│ ├── main.tsx # 入口點
│ ├── index.css # 全域樣式
│ ├── firebase.ts # Firebase 初始化設定
│ ├── components/
│ │ ├── Header.tsx # 頂部導航（搜尋、篩選、雙人進度條）
│ │ ├── ItemList.tsx # 商品列表容器
│ │ ├── ItemCard.tsx # 商品卡片（含完成者標記）
│ │ ├── ItemModal.tsx # 商品詳情彈窗
│ │ ├── ItemFormModal.tsx # 商品新增/編輯表單
│ │ ├── TravelTips.tsx # 旅遊攻略列表
│ │ ├── TipFormModal.tsx # 攻略新增/編輯表單
│ │ ├── BottomNav.tsx # 底部導航（任務/冒險頁籤）
│ │ ├── FilterChips.tsx # 篩選器標籤
│ │ └── AdventureDecor.tsx # 冒險主題背景裝飾
│ ├── data/
│ │ ├── items.ts # 商品初始資料（60 項）
│ │ ├── travelTips.ts # 攻略據點初始資料
│ │ └── imageMap.ts # 圖片 ID 映射
│ ├── hooks/
│ │ ├── useItems.ts # 商品狀態管理（含 Firestore 同步）
│ │ └── useTravelTips.ts # 攻略狀態管理（含 Firestore 同步）
│ ├── services/
│ │ └── itemsService.ts # Firestore CRUD 服務模組
│ ├── utils/
│ │ └── imageUtils.ts # 圖片工具函式
│ └── types/
│ └── index.ts # TypeScript 類型定義
├── scripts/
│ ├── syncFromSheet.js # Google Sheets → Firestore 同步
│ ├── syncToSheet.js # Firestore → Google Sheets 同步
│ └── verify-firebase.js # Firebase 連線驗證工具
├── sa/ # Google Service Account 金鑰（不含入版控）
├── .env.example # 環境變數範本
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
└── postcss.config.js
- 前往 Firebase Console
- 點擊「新增專案」，輸入專案名稱
- 可停用 Google Analytics（簡化設定）
- 點擊「建立專案」
- 在專案首頁點擊「網頁」圖示 (
</>) - 輸入應用程式暱稱，點擊「註冊應用程式」
- 📋 複製顯示的
firebaseConfig設定值
- 左側選單：「Build」→「Firestore Database」
- 點擊「建立資料庫」
- 選擇「正式模式」
- 選擇位置（建議：
asia-east1台灣）
在 Firestore → 「規則」頁籤，暫時使用：
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /items/{itemId} {
allow read, write: if true;
}
match /travel_tips/{tipId} {
allow read, write: if true;
}
}
}
⚠️ 注意：上述規則允許任何人讀寫，上線前請加入適當的驗證規則。
複製 .env.example 為 .env，填入 Firebase 設定值：
VITE_FIREBASE_API_KEY=AIzaSy...
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abc123如需使用 Google Sheets 雙向同步功能：
- 建立 Google Cloud Service Account，取得 JSON 金鑰檔案
- 將金鑰檔案放至
sa/sa.json - 在
.env中加入 Google Sheets URL：G_SHEET_URL=https://docs.google.com/spreadsheets/d/YOUR_SHEET_ID/edit
- 確保 Google Sheet 中有以下工作表：
Shopping_List- 匯入商品資料用Travel_Tips- 匯入攻略資料用Shopping_List_Pull- 匯出商品資料用Travel_Tips_Pull- 匯出攻略資料用
# Google Sheets → Firestore（匯入）
npm run syncFromSheet
# Firestore → Google Sheets（匯出）
npm run syncToSheet- Node.js 18+
- npm
-
Clone 專案
git clone <repository-url> cd japan-shiba-rb
-
安裝依賴
npm install
-
設定環境變數（參考上方 Firebase 設定章節）
-
啟動開發伺服器
npm run dev
開發伺服器會自動開啟 http://localhost:5173
# 建置生產版本
npm run build
# 預覽生產版本
npm run preview- 選擇身份 - 開啟應用後選擇「村民A」或「村民B」
- 瀏覽商品 - 在「任務」頁籤瀏覽所有待購商品
- 篩選商品 - 點擊頂部標籤依分類篩選，或切換至店舖模式
- 搜尋商品 - 使用搜尋欄快速找到特定商品
- 查看詳情 - 點擊商品卡片開啟詳情視窗
- 標記已買 - 點擊打勾按鈕標記為已收集，系統會記錄是誰完成的
- 搜尋圖片 - 在詳情視窗點擊「在 Google 搜尋圖片」
- 新增商品 - 點擊「+」按鈕新增自訂商品
- 編輯商品 - 點擊編輯圖示修改商品資訊
- 旅遊攻略 - 切換至「冒險」頁籤查看、新增、編輯攻略據點
祝購物愉快！🛍️✨