# DaydreamLab DDDream

一個功能豐富的 Laravel 套件，提供電商、預約系統、會員管理等完整的商業應用解決方案。

## 專案概述

DDDream 是 DaydreamLab 開發的企業級 Laravel 套件，專為多商戶電商平台設計。該套件包含了完整的商戶管理、產品管理、訂單處理、預約系統、會員系統等功能模組。

## 主要功能

### 🏪 商戶管理
- 多商戶支援
- 商戶權限管理
- 商戶資料管理
- 商戶日誌記錄

### 🛒 電商功能
- 產品管理
- 購物車系統
- 訂單管理
- 庫存管理
- 優惠券系統

### 📅 預約系統
- 排程管理
- 服務預約
- 時間管理
- 預約通知

### 👥 會員系統
- 會員註冊與管理
- 會員等級
- 會員標籤
- 預付卡系統

### 📱 通知系統
- 推播通知 (APNS)
- 簡訊通知
- Email 通知
- LINE Bot 整合

### 💰 金流整合
- NewebPay 藍新金流
- EzPay 簡單付
- 分期付款
- 退款處理

## 系統需求

- PHP >= 7.4
- Laravel >= 8.0
- MySQL >= 5.7
- Redis (推薦)

## 安裝指南

### 1. 透過 Composer 安裝

```bash
composer require daydreamlab/dddream:dev-master
```

### 2. 發佈設定檔

```bash
# 發佈常數設定
php artisan vendor:publish --tag=dddream-constants

# 發佈套件設定
php artisan vendor:publish --tag=dddream-configs

# 發佈 Email 樣板
php artisan vendor:publish --tag=emails-template
```

### 3. 執行資料庫遷移

```bash
php artisan migrate
```

### 4. 執行安裝指令

```bash
# 基礎安裝
php artisan dddream:install

# V3 版本安裝
php artisan dddream:v3:install

# 特定功能安裝
php artisan dddream:install:plan
php artisan dddream:install:merchant-member-tag
php artisan dddream:install:super-admin
```

## 環境變數設定

在你的 `.env` 檔案中添加以下設定：

```env
# 預設商戶
DEFAULT_MERCHANT=your-default-merchant

# APNS 推播設定
APNS_KEY_ID=your-apns-key-id
APNS_TEAM_ID=your-apns-team-id
APNS_BUNDLE_ID=your-bundle-id
APNS_URL=https://api.push.apple.com

# TOTP 驗證
TOTP_SECRET_KEY=your-totp-secret-key
```

## 專案結構

```
src/
├── Commands/           # Artisan 指令
├── Controllers/        # 控制器
├── Models/            # Eloquent 模型
├── Services/          # 服務層
├── Repositories/      # 資料存取層
├── Helpers/           # 輔助函數
├── Middlewares/       # 中介層
├── Events/            # 事件
├── Listeners/         # 事件監聽器
├── Notifications/     # 通知
├── Jobs/              # 佇列任務
├── Rules/             # 驗證規則
├── Traits/            # 特性
├── database/          # 資料庫相關
│   ├── migrations/    # 資料庫遷移
│   ├── seeds/         # 資料填充
│   └── factories/     # 模型工廠
└── routes/            # 路由定義
```

## 可用指令

### 安裝指令
```bash
# 主要安裝指令
php artisan dddream:install
php artisan dddream:v2:install
php artisan dddream:v3:install

# 功能模組安裝
php artisan dddream:install:plan-module
php artisan dddream:install:plan-component
php artisan dddream:install:product-price-inventory
php artisan dddream:install:merchant-member-tag
```

### 資料管理指令
```bash
# 清空資料
php artisan dddream:truncate

# 恢復資料
php artisan dddream:v3:recover

# 更新指令
php artisan dddream:v3:update-merchant
php artisan dddream:v3:update-merchant-payment-history
php artisan dddream:v3:update-sms-history
```

### 特殊功能指令
```bash
# Jtails 相關
php artisan dddream:jtails:install
php artisan dddream:jtails:import-data
php artisan dddream:jtails:clean-prepaid-order

# iPetBooking 相關
php artisan dddream:ipetbooking:install
php artisan dddream:ipetbooking:demo:install
```

## API 文件

### 📚 分類文件
- **Site API (前台)**: [API_SITE_DOCUMENTATION.md](API_SITE_DOCUMENTATION.md)
- **Admin API (後台)**: [API_ADMIN_DOCUMENTATION.md](API_ADMIN_DOCUMENTATION.md)

### 主要 API 端點

#### 前台 API
- **會員系統**: 登入、註冊、資料管理
- **預約服務**: 服務搜尋、預約、日曆查看
- **購物車**: 商品管理、結帳流程
- **訂單管理**: 訂單查詢、狀態追蹤
- **包套方案**: 方案購買、使用記錄
- **儲值金**: 儲值、使用、餘額查詢
- **優惠券**: 可用券查詢、使用驗證
- **寵物管理**: 寵物資料建檔、疫苗記錄

#### 後台 API
- **商家管理**: 商家資訊、設定管理
- **會員管理**: 會員搜尋、資料維護、等級管理
- **訂單管理**: 訂單處理、退款、匯出
- **服務管理**: 服務建立、價格設定、庫存管理
- **排程管理**: 人員排班、時間管理
- **數據分析**: 收入分析、銷售報表
- **推播管理**: 通知發送、裝置管理

### API 特色
- **RESTful 設計**: 遵循 REST 架構原則
- **統一驗證**: JWT Token 或 Session 驗證
- **請求驗證**: 基於 Laravel Request 的完整驗證
- **錯誤處理**: 統一的錯誤回應格式
- **分頁支援**: 標準分頁機制
- **中介層**: 權限控制和資料過濾

## 測試

### 執行測試（本機）

```bash
# 執行所有測試
vendor/bin/phpunit

# 執行特定測試套件
vendor/bin/phpunit --testsuite=feature
vendor/bin/phpunit --testsuite=unit

# 執行特定測試檔案
vendor/bin/phpunit tests/Feature/MemberFrontTest.php
vendor/bin/phpunit tests/Unit/Services/Merchant/Admin/GetSelfItem/
```

### Docker 環境執行測試

若主專案使用 Docker 開發環境，請從**主專案根目錄**進入 `docker/dev` 後，在容器內執行測試（`phpunit.xml` 會使用 `DB_HOST=mysql` 連接 Docker 內的資料庫）：

```bash
# 從主專案根目錄執行（例如 dingsomething-admin）
cd docker/dev
docker-compose exec php-fpm sh -c "cd /var/www/html && vendor/bin/phpunit -c vendor/daydreamlab/dddream/phpunit.xml --testsuite unit --testdox"
```

更多 Docker 測試指令（單一檔案、單一方法、Feature 測試等）請見 [TEST.md](TEST.md#docker-環境執行)。

### 測試環境設定

測試會自動使用以下環境變數：
- `SEEDING=1` - 啟用資料填充
- `DB_PORT=33060` - 測試資料庫連接埠（本機）；Docker 環境使用 `DB_HOST=mysql`

## 中介層

套件提供以下中介層：

- `hasMerchant` - 檢查使用者是否擁有商戶權限
- `isMember` - 檢查是否為會員
- `isStaff` - 檢查是否為員工
- `putMember` - 設定會員資訊
- `SuperAdmin` - 超級管理員權限
- `MerchantObserver` - 商戶觀察者
- `CodeScope` - 代碼範圍限制

## API 路由

套件自動載入以下路由：

- `routes/front/api.php` - 前台 API 路由
- `routes/admin/api.php` - 後台 API 路由
- `routes/front/channels.php` - 前台頻道路由
- `routes/admin/channels.php` - 後台頻道路由
- `routes/front/web.php` - 前台網頁路由

## 主要模組

### 商戶模組 (Merchant)
- 商戶註冊與管理
- 商戶會員系統
- 商戶權限控制
- 商戶營運數據

### 產品模組 (Product)
- 產品管理
- 庫存管理
- 價格管理
- 產品分類

### 訂單模組 (Order)
- 訂單建立與管理
- 訂單狀態追蹤
- 付款處理
- 退款機制

### 預約模組 (Schedule/Booking)
- 服務預約
- 時間排程
- 預約通知
- 取消與修改

### 會員模組 (Member)
- 會員註冊
- 會員等級
- 會員標籤
- 會員優惠

## 事件系統

套件使用 Laravel 事件系統，主要事件包括：

- **商戶事件**: 商戶建立、更新、刪除
- **訂單事件**: 訂單建立、付款、完成、取消
- **預付卡事件**: 預付卡建立、使用、退款
- **推播事件**: 推播通知發送
- **通知事件**: 各類通知觸發

## 輔助函數

套件提供的輔助函數：

- `OrderHelper` - 訂單處理輔助
- `ProductHelper` - 產品管理輔助
- `MerchantHelper` - 商戶管理輔助
- `NotificationHelper` - 通知輔助
- `PushNotificationHelper` - 推播輔助
- `SmsHelper` - 簡訊輔助
- `NewebpayHelper` - 藍新金流輔助

## 開發團隊

- **Jordan Tsai** - jordan@daydream-lab.com
- **Alex Yeh** - alex@daydream-lab.com

## 版本管理

專案使用語意化版本控制，當前為開發版本 (`dev-master`)。

## 授權

本專案為 DaydreamLab 私有專案，請遵循公司內部使用規範。

## 支援與回報問題

如有任何問題或建議，請聯繫開發團隊：
- 📧 Email: jordan@daydream-lab.com, alex@daydream-lab.com
- 🏢 公司: DaydreamLab

## 更新日誌

### 最新功能
- ✅ iPetBooking 整合
- ✅ Jtails 系統整合
- ✅ 會員等級系統
- ✅ 服務價格群組
- ✅ 日托服務
- ✅ 商品管理系統

---

*最後更新: 2024年*