199 lines
5.2 KiB
Markdown
199 lines
5.2 KiB
Markdown
|
# 會員系統（Members）功能說明
|
|||
|
|
|
|||
|
|
> 此文件記錄會員系統的設計決策與功能說明，供開發與維護時參閱。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
會員系統用於智能販賣機商城，支援消費者透過多種社群管道（Line、Google、Facebook）加入會員。
|
|||
|
|
|
|||
|
|
**重要區分**：
|
|||
|
|
- `users` 表：後台管理員登入帳號
|
|||
|
|
- `members` 表：前台消費者會員帳號
|
|||
|
|
|
|||
|
|
兩者**完全獨立**，無關聯。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 資料表
|
|||
|
|
|
|||
|
|
### 1. `members` - 會員資料
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `id` | bigint | 主鍵 |
|
|||
|
|
| `uuid` | string | 唯一識別碼（對外使用） |
|
|||
|
|
| `name` | string | 姓名 |
|
|||
|
|
| `email` | string | 電子郵件（可空） |
|
|||
|
|
| `phone` | string | 手機號碼（可空） |
|
|||
|
|
| `password` | string | 密碼（社群登入可空） |
|
|||
|
|
| `birthday` | date | 生日 |
|
|||
|
|
| `gender` | enum | 性別 |
|
|||
|
|
| `avatar` | string | 頭像 URL |
|
|||
|
|
| `is_active` | boolean | 是否啟用 |
|
|||
|
|
| `email_verified_at` | timestamp | Email 驗證時間 |
|
|||
|
|
|
|||
|
|
### 2. `social_accounts` - 社群帳號
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `id` | bigint | 主鍵 |
|
|||
|
|
| `member_id` | bigint | 關聯會員 |
|
|||
|
|
| `provider` | enum | line / google / facebook |
|
|||
|
|
| `provider_id` | string | 社群平台用戶 ID |
|
|||
|
|
| `access_token` | text | 存取令牌 |
|
|||
|
|
| `refresh_token` | text | 刷新令牌 |
|
|||
|
|
| `profile_data` | json | 社群個人資料 |
|
|||
|
|
| `token_expires_at` | timestamp | 令牌到期時間 |
|
|||
|
|
|
|||
|
|
### 3. `member_wallets` - 會員錢包
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `member_id` | bigint | FK，唯一 |
|
|||
|
|
| `balance` | decimal | 儲值餘額 |
|
|||
|
|
| `bonus_balance` | decimal | 回饋金餘額 |
|
|||
|
|
|
|||
|
|
### 4. `wallet_transactions` - 錢包交易
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `type` | enum | deposit/consume/refund/bonus/adjust |
|
|||
|
|
| `amount` | decimal | 異動金額 |
|
|||
|
|
| `balance_after` | decimal | 異動後餘額 |
|
|||
|
|
| `reference_type/id` | | 關聯訂單或活動 |
|
|||
|
|
|
|||
|
|
### 5. `deposit_bonus_rules` - 儲值回饋規則
|
|||
|
|
|
|||
|
|
設定儲值達指定金額可獲得的回饋（固定金額或百分比）。
|
|||
|
|
|
|||
|
|
### 6. `member_points` - 點數帳戶
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `available_points` | int | 可用點數 |
|
|||
|
|
| `pending_points` | int | 待生效點數 |
|
|||
|
|
| `expired_points` | int | 已過期（統計） |
|
|||
|
|
| `used_points` | int | 已使用（統計） |
|
|||
|
|
|
|||
|
|
### 7. `point_transactions` - 點數異動
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `type` | enum | earn/use/expire/gift/adjust |
|
|||
|
|
| `points` | int | 異動點數 |
|
|||
|
|
| `expires_at` | datetime | **此筆點數到期日** |
|
|||
|
|
|
|||
|
|
> 每筆獲得點數都記錄 `expires_at`，排程任務定期處理過期。
|
|||
|
|
|
|||
|
|
### 8. `point_rules` - 點數規則
|
|||
|
|
|
|||
|
|
設定消費/儲值/註冊等行為可獲得的點數及有效天數。
|
|||
|
|
|
|||
|
|
### 9. `membership_tiers` - 會員等級
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `name` | string | 等級名稱 |
|
|||
|
|
| `annual_fee` | decimal | 年費（0=免費） |
|
|||
|
|
| `discount_rate` | decimal | 折扣比例 |
|
|||
|
|
| `point_multiplier` | decimal | 點數倍率 |
|
|||
|
|
|
|||
|
|
### 10. `member_memberships` - 會員等級紀錄
|
|||
|
|
|
|||
|
|
記錄會員的等級歸屬及有效期間。
|
|||
|
|
|
|||
|
|
### 11. `gift_definitions` - 禮品定義
|
|||
|
|
|
|||
|
|
| 欄位 | 類型 | 說明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| `type` | enum | points/coupon/product/discount/cash |
|
|||
|
|
| `trigger` | enum | register/birthday/annual/upgrade/manual |
|
|||
|
|
|
|||
|
|
### 12. `member_gifts` - 禮品發放紀錄
|
|||
|
|
|
|||
|
|
記錄發放給會員的禮品及領取狀態。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ER 關係圖
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
members
|
|||
|
|
├── social_accounts (1:N)
|
|||
|
|
├── member_wallets (1:1)
|
|||
|
|
│ └── wallet_transactions (1:N)
|
|||
|
|
├── member_points (1:1)
|
|||
|
|
│ └── point_transactions (1:N)
|
|||
|
|
├── member_memberships (1:N)
|
|||
|
|
│ └── membership_tiers
|
|||
|
|
└── member_gifts (1:N)
|
|||
|
|
└── gift_definitions
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 登入流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
使用者選擇社群登入
|
|||
|
|
↓
|
|||
|
|
取得 provider + provider_id
|
|||
|
|
↓
|
|||
|
|
查詢 social_accounts
|
|||
|
|
↓
|
|||
|
|
┌────┴────┐
|
|||
|
|
已綁定 未綁定
|
|||
|
|
↓ ↓
|
|||
|
|
取得 member 建立新 member + social_account
|
|||
|
|
↓ ↓
|
|||
|
|
完成登入
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Email 驗證（可選功能）
|
|||
|
|
|
|||
|
|
若需要 Email 驗證，需設定 `.env` 的 SMTP 並讓 `Member` Model 實作 `MustVerifyEmail`。
|
|||
|
|
|
|||
|
|
社群登入時自動標記 `email_verified_at`，僅對手機/密碼註冊要求驗證。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## API 端點
|
|||
|
|
|
|||
|
|
| Method | Endpoint | 說明 | 認證 |
|
|||
|
|
|--------|----------|------|------|
|
|||
|
|
| POST | `/api/members/register` | 註冊會員 | 否 |
|
|||
|
|
| POST | `/api/members/login` | 登入 | 否 |
|
|||
|
|
| POST | `/api/members/social-login` | 社群登入 | 否 |
|
|||
|
|
| GET | `/api/members/profile` | 取得個人資料 | 是 |
|
|||
|
|
| PUT | `/api/members/profile` | 更新個人資料 | 是 |
|
|||
|
|
| POST | `/api/members/logout` | 登出 | 是 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Postman 測試
|
|||
|
|
|
|||
|
|
匯入：`docs/postman/Star_Cloud_Members_API.postman_collection.json`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 社群登入實測
|
|||
|
|
|
|||
|
|
訪問 `/test/social-login` 測試 Google/Line 登入。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 開發進度
|
|||
|
|
|
|||
|
|
| 日期 | 項目 | 狀態 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 2026-01-12 | 會員核心 (members, social_accounts) | ✅ 完成 |
|
|||
|
|
| 2026-01-12 | 錢包系統 (3 表 + 3 Model) | ✅ 完成 |
|
|||
|
|
| 2026-01-12 | 點數系統 (3 表 + 3 Model) | ✅ 完成 |
|
|||
|
|
| 2026-01-12 | 年度會員 (2 表 + 2 Model) | ✅ 完成 |
|
|||
|
|
| 2026-01-12 | 贈送機制 (2 表 + 2 Model) | ✅ 完成 |
|
|||
|
|
|