新增資料庫架構

2025-07-19 02:12:37 +08:00
parent e3832acfa8
commit 924f03c3d7
45 changed files with 12858 additions and 324 deletions
--- a/SUPABASE-COMPLETE-SETUP.md
+++ b/SUPABASE-COMPLETE-SETUP.md
@@ -0,0 +1,369 @@
+# 🚀 心願星河 - Supabase 完整建置指南
+
+## 📋 目錄
+- [前置準備](#前置準備)
+- [Supabase 項目設置](#supabase-項目設置)
+- [本地環境配置](#本地環境配置)
+- [數據庫建置](#數據庫建置)
+- [存儲服務設置](#存儲服務設置)
+- [安全政策配置](#安全政策配置)
+- [測試驗證](#測試驗證)
+- [數據遷移](#數據遷移)
+- [部署準備](#部署準備)
+- [故障排除](#故障排除)
+
+---
+
+## 🎯 前置準備
+
+### 系統需求
+- Node.js 18+ 
+- npm 或 yarn
+- 現代瀏覽器
+- Supabase 帳號
+
+### 預估時間
+- 初次設置：30-45 分鐘
+- 數據遷移：5-10 分鐘
+- 測試驗證：10-15 分鐘
+
+---
+
+## 🏗️ Supabase 項目設置
+
+### 1. 創建新項目
+1. 前往 [Supabase Dashboard](https://supabase.com/dashboard)
+2. 點擊 **"New Project"**
+3. 填寫項目資訊：
+   \`\`\`
+   Name: wish-pool-production
+   Organization: [選擇你的組織]
+   Database Password: [設置強密碼，請記住！]
+   Region: [選擇最近的區域，建議 ap-southeast-1]
+   \`\`\`
+4. 點擊 **"Create new project"**
+5. 等待 2-3 分鐘完成初始化
+
+### 2. 獲取項目配置
+項目創建完成後：
+1. 進入項目 Dashboard
+2. 左側選單 → **Settings** → **API**
+3. 複製以下資訊：
+   \`\`\`
+   Project URL: https://[your-project-id].supabase.co
+   anon public key: eyJ... (很長的字串)
+   service_role key: eyJ... (僅在需要管理員功能時使用)
+   \`\`\`
+
+---
+
+## ⚙️ 本地環境配置
+
+### 1. 安裝依賴
+\`\`\`bash
+# 安裝 Supabase 客戶端
+npm install @supabase/supabase-js
+
+# 如果需要圖片處理功能
+npm install sharp
+\`\`\`
+
+### 2. 環境變數設置
+1. 複製環境變數範本：
+   \`\`\`bash
+   cp .env.local.example .env.local
+   \`\`\`
+
+2. 編輯 `.env.local`：
+   \`\`\`env
+   # Supabase 配置
+   NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
+   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
+   
+   # 可選：管理員功能（謹慎使用）
+   SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+   
+   # 應用配置
+   NEXT_PUBLIC_APP_URL=http://localhost:3000
+   \`\`\`
+
+### 3. 驗證連接
+\`\`\`bash
+# 啟動開發服務器
+npm run dev
+
+# 檢查控制台是否有 Supabase 連接錯誤
+\`\`\`
+
+---
+
+## 🗄️ 數據庫建置
+
+### 執行順序很重要！請按照以下順序執行 SQL 腳本：
+
+### 步驟 1: 創建基礎表格
+1. 進入 Supabase Dashboard
+2. 左側選單 → **SQL Editor**
+3. 點擊 **"New Query"**
+4. 複製並執行 `scripts/01-create-tables.sql`
+5. 確認執行成功（無錯誤訊息）
+
+### 步驟 2: 創建索引和觸發器
+1. 新建查詢
+2. 複製並執行 `scripts/02-create-indexes.sql`
+3. 確認所有索引創建成功
+
+### 步驟 3: 創建視圖和函數
+1. 新建查詢
+2. 複製並執行 `scripts/03-create-views-functions.sql`
+3. 確認視圖和函數創建成功
+
+### 步驟 4: 設置存儲服務
+1. 新建查詢
+2. 複製並執行 `scripts/04-setup-storage.sql`
+3. 檢查 Storage → Buckets 是否出現新的桶
+
+### 步驟 5: 配置安全政策
+1. 新建查詢
+2. 複製並執行 `scripts/05-setup-rls.sql`
+3. 確認 RLS 政策設置完成
+
+---
+
+## 📁 存儲服務設置
+
+### 存儲桶說明
+- **wish-images**: 主要圖片存儲（5MB 限制）
+- **wish-thumbnails**: 縮圖存儲（1MB 限制）
+
+### 支援格式
+- JPEG, JPG, PNG, WebP, GIF
+- 自動壓縮和優化
+- CDN 加速分發
+
+### 存儲政策
+- 公開讀取：所有人可查看圖片
+- 限制上傳：防止濫用
+- 自動清理：定期清理孤立圖片
+
+---
+
+## 🔒 安全政策配置
+
+### Row Level Security (RLS)
+所有表格都啟用了 RLS，確保數據安全：
+
+#### wishes 表格
+- ✅ 公開困擾案例：所有人可查看
+- ✅ 私密困擾案例：僅統計使用
+- ✅ 插入權限：所有人可提交
+
+#### wish_likes 表格
+- ✅ 查看權限：用於統計顯示
+- ✅ 插入權限：所有人可點讚
+- ✅ 防重複：同一用戶不可重複點讚
+
+#### user_settings 表格
+- ✅ 個人設定：用戶只能管理自己的設定
+- ✅ 會話隔離：基於 session ID 區分用戶
+
+---
+
+## 🧪 測試驗證
+
+### 1. 數據庫連接測試
+\`\`\`sql
+-- 在 SQL Editor 中執行
+SELECT 'Database connection successful!' as status;
+\`\`\`
+
+### 2. 表格結構驗證
+\`\`\`sql
+-- 檢查所有表格是否存在
+SELECT table_name 
+FROM information_schema.tables 
+WHERE table_schema = 'public'
+ORDER BY table_name;
+\`\`\`
+
+### 3. 存儲服務測試
+1. 進入 Storage → wish-images
+2. 嘗試上傳一張測試圖片
+3. 確認可以正常預覽
+
+### 4. 功能測試清單
+- [ ] 提交新的困擾案例
+- [ ] 上傳圖片附件
+- [ ] 點讚功能
+- [ ] 查看統計數據
+- [ ] 背景音樂設定保存
+- [ ] 響應式設計正常
+
+---
+
+## 🔄 數據遷移
+
+### 自動遷移流程
+1. 啟動應用程式
+2. 如果檢測到本地數據，會自動顯示遷移對話框
+3. 點擊 **"開始遷移"** 
+4. 等待遷移完成
+5. 驗證數據完整性
+
+### 手動遷移（如需要）
+\`\`\`javascript
+// 在瀏覽器控制台執行
+console.log('Local wishes:', JSON.parse(localStorage.getItem('wishes') || '[]'));
+console.log('Local likes:', JSON.parse(localStorage.getItem('wishLikes') || '{}'));
+\`\`\`
+
+### 遷移後清理
+\`\`\`javascript
+// 確認遷移成功後，清理本地數據
+localStorage.removeItem('wishes');
+localStorage.removeItem('wishLikes');
+localStorage.removeItem('userLikedWishes');
+\`\`\`
+
+---
+
+## 🚀 部署準備
+
+### 1. 環境變數設置
+在部署平台（Vercel/Netlify）設置：
+\`\`\`
+NEXT_PUBLIC_SUPABASE_URL=your-production-url
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-production-key
+\`\`\`
+
+### 2. 生產環境優化
+\`\`\`sql
+-- 執行生產環境優化
+SELECT optimize_database_performance();
+\`\`\`
+
+### 3. 備份設置
+1. 進入 Supabase Dashboard
+2. Settings → Database → Backups
+3. 確認自動備份已啟用
+
+---
+
+## 🔧 故障排除
+
+### 常見問題
+
+#### 1. 連接失敗
+**症狀**: `Failed to connect to Supabase`
+**解決方案**:
+- 檢查環境變數是否正確
+- 確認 Supabase 項目狀態正常
+- 檢查網路連接
+
+#### 2. RLS 政策錯誤
+**症狀**: `Row Level Security policy violation`
+**解決方案**:
+\`\`\`sql
+-- 檢查 RLS 政策
+SELECT * FROM pg_policies WHERE tablename = 'wishes';
+\`\`\`
+
+#### 3. 存儲上傳失敗
+**症狀**: 圖片上傳失敗
+**解決方案**:
+- 檢查檔案大小（<5MB）
+- 確認檔案格式支援
+- 檢查存儲桶政策
+
+#### 4. 性能問題
+**症狀**: 查詢速度慢
+**解決方案**:
+\`\`\`sql
+-- 檢查索引使用情況
+EXPLAIN ANALYZE SELECT * FROM wishes_with_likes LIMIT 10;
+\`\`\`
+
+### 日誌檢查
+1. Supabase Dashboard → Logs
+2. 查看 Database、API、Storage 日誌
+3. 過濾錯誤和警告訊息
+
+### 性能監控
+\`\`\`sql
+-- 檢查數據庫性能
+SELECT * FROM get_performance_stats();
+\`\`\`
+
+---
+
+## 📊 維護建議
+
+### 定期維護任務
+
+#### 每週
+- [ ] 檢查錯誤日誌
+- [ ] 監控存儲使用量
+- [ ] 清理孤立圖片
+
+#### 每月
+- [ ] 分析查詢性能
+- [ ] 檢查備份完整性
+- [ ] 更新統計數據
+
+#### 每季
+- [ ] 檢查安全政策
+- [ ] 優化數據庫索引
+- [ ] 評估擴展需求
+
+### 清理腳本
+\`\`\`sql
+-- 清理 30 天前的孤立圖片
+SELECT cleanup_orphaned_images();
+
+-- 更新統計數據
+REFRESH MATERIALIZED VIEW wishes_stats_cache;
+\`\`\`
+
+---
+
+## 🎉 完成檢查清單
+
+設置完成後，請確認以下項目：
+
+### 基礎設置
+- [ ] Supabase 項目創建成功
+- [ ] 環境變數配置正確
+- [ ] 所有 SQL 腳本執行成功
+- [ ] 存儲桶創建完成
+
+### 功能測試
+- [ ] 可以提交新困擾案例
+- [ ] 圖片上傳功能正常
+- [ ] 點讚功能運作正常
+- [ ] 統計數據顯示正確
+- [ ] 用戶設定保存成功
+
+### 安全檢查
+- [ ] RLS 政策生效
+- [ ] 無法訪問他人私密數據
+- [ ] 存儲權限設置正確
+
+### 性能驗證
+- [ ] 頁面載入速度正常
+- [ ] 圖片載入速度快
+- [ ] 查詢響應時間合理
+
+---
+
+## 📞 支援資源
+
+- **Supabase 官方文檔**: https://supabase.com/docs
+- **Next.js 整合指南**: https://supabase.com/docs/guides/getting-started/quickstarts/nextjs
+- **故障排除指南**: https://supabase.com/docs/guides/platform/troubleshooting
+
+---
+
+**🌟 恭喜！你的心願星河已經成功整合 Supabase！**
+
+現在你可以享受雲端數據存儲、圖片管理、實時同步等強大功能。如果遇到任何問題，請參考故障排除章節或聯繫技術支援。
+\`\`\`