# DDDream Site API 文件

這份文件詳細說明了 DDDream 套件中所有前台 Site API 端點，包括請求參數、驗證規則和回應格式。

## 目錄

- [聯絡我們](#聯絡我們)
- [商家相關](#商家相關)
- [會員系統](#會員系統)
- [預約服務](#預約服務)
- [購物車](#購物車)
- [訂單管理](#訂單管理)
- [包套方案](#包套方案)
- [儲值金](#儲值金)
- [優惠券](#優惠券)
- [寵物管理](#寵物管理)
- [文章模組](#文章模組)
- [其他功能](#其他功能)

---

## 聯絡我們

### POST `/api/contact/post`
提交聯絡表單

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "name": "string|required",
  "email": "email|required", 
  "phone": "string|nullable",
  "subject": "string|required",
  "message": "string|required"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Contact us front create success",
  "data": {
    "contactId": "contact-uuid"
  }
}
```

---

## 商家相關

### GET `/api/merchant`
取得商家資訊

**中介層:** 無 (公開端點)

**查詢參數:**
- `alias`: 商家別名 (由子域名自動取得)

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front get item success",
  "data": {
    "title": "寵物美容店",
    "alias": "pet-salon",
    "i18n": "zh-TW",
    "ga": "UA-123456789-1",
    "logo": "https://example.com/logo.jpg",
    "image": "https://example.com/banner.jpg",
    "images": [
      {
        "path": "https://example.com/image1.jpg",
        "mobilePath": "https://example.com/mobile1.jpg",
        "default": 1
      }
    ],
    "address": "台北市大安區復興南路一段123號",
    "phoneCode": "02",
    "phoneNumber": "12345678",
    "email": "info@petsalon.com",
    "description": "專業寵物美容服務",
    "fbFanpageId": "123456789",
    "lineId": "@petsalon",
    "lineFriendUrl": "https://line.me/R/ti/p/@petsalon",
    "cashflowSetting": 1,
    "paymentMethods": ["Credit", "Atm", "Vacc"],
    "aboutImage": "https://example.com/about.jpg",
    "fbFanpageUrl": "https://facebook.com/petsalon",
    "planAlias": "premium",
    "stores": [
      {
        "alias": "main-store",
        "title": "總店",
        "address": "台北市大安區復興南路一段123號",
        "phoneNumber": "02-12345678"
      }
    ],
    "petCategories": [
      {
        "alias": "dog",
        "title": "狗狗",
        "children": [
          {
            "alias": "small-dog",
            "title": "小型犬"
          },
          {
            "alias": "medium-dog",
            "title": "中型犬"
          }
        ]
      }
    ],
    "depositSetting": {
      "isEnabled": 1,
      "title": "儲值服務",
      "allowNewCustomer": 1,
      "images": [],
      "bannerImages": []
    },
    "prepaidSetting": {
      "isEnabled": 1,
      "title": "預付卡服務",
      "allowNewCustomer": 1,
      "bannerImages": []
    },
    "daycareSetting": {
      "isEnabled": 0,
      "title": "安親服務",
      "allowNewCustomer": 0,
      "bookingTimePeriod": 15
    },
    "levelSetting": {
      "isEnabled": 1,
      "title": "會員等級",
      "images": [],
      "bannerImages": []
    },
    "cosmeticSetting": {
      "isEnabled": 1,
      "title": "美容服務",
      "servicePriceGroupBannerImages": []
    },
    "lineNotifyClientId": "client_id_123",
    "components": ["booking", "prepaid", "deposit"],
    "invoiceSetting": 1,
    "additionalModules": ["advanced_booking"],
    "mixTags": [
      {
        "id": 1,
        "title": "優質服務",
        "type": "service",
        "state": 1
      },
      {
        "id": 2,
        "title": "熱門推薦",
        "type": "product",
        "state": 1
      }
    ]
  }
}
```

### POST `/api/merchant/booking/price`
取得價目表

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "date": "date|required|format:Y-m-d",
  "storeAlias": "string|nullable",
  "categoryAlias": "string|nullable",
  "serviceType": "string|nullable",
  "mixTagIds": [1, 2],
  "types": ["cosmetic", "daycare"]
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Service price front search success",
  "data": {
    "cosmetic": [
      {
        "alias": "basic-grooming",
        "title": "基礎美容",
        "description": "包含洗澡、剪指甲、清耳朵",
        "basePrice": 800,
        "price": 800,
        "serviceTime": 90,
        "bufferTime": 30,
        "categoryTitle": "小型犬",
        "sizeTitle": "3kg以下",
        "storeTitle": "總店",
        "image": "https://example.com/grooming.jpg",
        "mixTags": [
          {
            "id": 1,
            "title": "優質服務",
            "type": "service",
            "state": 1
          }
        ]
      }
    ],
    "daycare": [
      {
        "alias": "half-day-care",
        "title": "半日托",
        "description": "上午8點到下午1點",
        "basePrice": 600,
        "price": 600,
        "serviceTime": 300,
        "bufferTime": 0,
        "categoryTitle": "小型犬",
        "sizeTitle": "3kg以下",
        "storeTitle": "總店"
      }
    ]
  }
}
```

---

## 會員系統

### POST `/api/merchant/member/login`
會員登入

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "phoneCode": "string|required|regex:/^\\+[0-9]+$/",
  "phoneNumber": "string|required", 
  "verificationCode": "string|required"
}
```

**處理邏輯:**
- 自動組合完整電話號碼 (`phoneCode + '-' + phoneNumber`)
- 從子域名取得商家別名

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member login success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "member": {
      "id": "uuid-member-id",
      "fullName": "王小明",
      "phoneCode": "+886",
      "phoneNumber": "0912345678",
      "email": "member@example.com",
      "gender": "male",
      "birthday": "1990-01-01",
      "lineUserId": "line_user_123",
      "level": {
        "id": "level-id",
        "title": "VIP會員",
        "discount": 10
      },
      "depositBalance": 1500.00,
      "bonusBalance": 200.00
    }
  }
}
```

### POST `/api/merchant/member/line/liff/login`
LINE LIFF 登入

**中介層:** 無 (特殊登入端點)

**請求參數:**
```json
{
  "lineUserId": "string|required",
  "idToken": "string|required"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member liff login success",
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "member": {
      "id": "uuid-member-id",
      "fullName": "王小明",
      "phoneCode": "+886",
      "phoneNumber": "0912345678",
      "email": "member@example.com",
      "gender": "male",
      "birthday": "1990-01-01",
      "lineUserId": "line_user_123",
      "level": {
        "id": "level-id",
        "title": "VIP會員",
        "discount": 10
      },
      "depositBalance": 1500.00,
      "bonusBalance": 200.00
    }
  }
}
```

### POST `/api/merchant/member/getCode`
取得驗證碼

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "phoneCode": "string|required|regex:/^\\+[0-9]+$/",
  "phoneNumber": "string|required"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member get code success",
  "data": null
}
```

### GET `/api/merchant/member`
取得會員資訊

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 🔄 自動注入會員資訊到請求中

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member get item success",
  "data": {
    "id": "uuid-member-id",
    "fullName": "王小明",
    "phoneCode": "+886",
    "phoneNumber": "0912345678",
    "email": "member@example.com",
    "gender": "male",
    "birthday": "1990-01-01",
    "lineUserId": "line_user_123",
    "level": {
      "id": "level-id",
      "title": "VIP會員",
      "discount": 10,
      "bonusDiscount": 5
    },
    "depositBalance": 1500.00,
    "bonusBalance": 200.00,
    "totalSpent": 15000.00,
    "totalOrders": 25,
    "joinDate": "2023-01-15T10:30:00Z"
  }
}
```

### POST `/api/merchant/member/store`
更新會員資訊

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 🔄 自動注入會員資訊到請求中

**請求參數:**
```json
{
  "fullName": "string|nullable",
  "gender": "string|nullable|in:male,female",
  "birthday": "date|nullable",
  "email": "email|nullable",
  "address": "string|nullable",
  "emergencyContact": "string|nullable"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member update success",
  "data": {
    "id": "uuid-member-id",
    "fullName": "王小明",
    "phoneCode": "+886",
    "phoneNumber": "0912345678",
    "email": "updated@example.com",
    "gender": "male",
    "birthday": "1990-01-01",
    "address": "台北市大安區復興南路一段123號",
    "emergencyContact": "0987654321",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

### POST `/api/merchant/member/media/upload`
上傳會員媒體檔案

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 📁 限制會員只能管理自己的媒體檔案

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Media front upload success",
  "data": {
    "id": "media-uuid",
    "filename": "pet_photo.jpg",
    "originalName": "小白的照片.jpg",
    "url": "https://example.com/media/pet_photo.jpg",
    "size": 2048576,
    "mimeType": "image/jpeg",
    "uploadedAt": "2024-01-15T10:30:00Z"
  }
}
```

### POST `/api/merchant/member/media/delete`
刪除會員媒體檔案

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 🗑️ 限制會員只能刪除自己的媒體檔案

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Media front delete success",
  "data": null
}
```

### Line 相關功能

#### POST `/api/merchant/member/line/liff/bind`
綁定 LINE LIFF

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 🔗 綁定會員與 LINE 帳號

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Line front bind success",
  "data": {
    "lineUserId": "line_user_123"
  }
}
```

#### POST `/api/merchant/member/line/notify/bind`
綁定 LINE Notify

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 📲 啟用 LINE 通知服務

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Line notify bind success",
  "data": {
    "notifyToken": "notify_token_456"
  }
}
```

#### POST `/api/merchant/member/line/notify/unBind`
解綁 LINE Notify

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 📲 停用 LINE 通知服務

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Line notify unbind success",
  "data": null
}
```


### 認證相關

#### GET `/api/merchant/member/login/check`
檢查登入狀態

**中介層:** 無 (狀態檢查)

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member login check success",
  "data": {
    "isLoggedIn": true,
    "member": {
      "id": "uuid-member-id",
      "fullName": "王小明",
      "phoneNumber": "0912345678"
    },
    "tokenExpiry": "2024-01-16T10:30:00Z"
  }
}
```

#### GET `/api/merchant/member/logout`
會員登出

**中介層:** 無 (登出端點)

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Merchant front member logout success",
  "data": null
}
```

---

## 預約服務

### POST `/api/merchant/booking/search`
搜尋可預約服務

**中介層:** `putMember`
- 🔓 可選會員登入 (未登入也可使用)
- 🔄 嘗試注入會員資訊，影響價格顯示和可預約時段

**請求參數:**
```json
{
  "date": "date|required|format:Y-m-d",
  "storeAlias": "string|nullable",
  "sizeAlias": "string|nullable", 
  "prepaidOrderUuid": "string|nullable",
  "search": "string|nullable",
  "scheduleItemId": "uuid|nullable",
  "servicePriceGroupId": "integer|nullable",
  "types": ["cosmetic", "daycare", "goods"],
  "mixTagIds": [1, 2]
}
```

**處理邏輯:**
- 如果提供 `servicePriceGroupId`，會自動取得該群組內的所有價格 ID
- 自動設定 `state = 1` (啟用狀態)
- 從路由取得 `priceAlias`

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Service price front search success",
  "data": {
    "items": [
      {
        "alias": "basic-grooming",
        "title": "基礎美容",
        "description": "包含洗澡、剪指甲、清耳朵",
        "basePrice": 800,
        "price": 720,
        "memberPrice": 720,
        "serviceTime": 90,
        "bufferTime": 30,
        "categoryTitle": "小型犬",
        "sizeTitle": "3kg以下",
        "storeTitle": "總店",
        "storeAlias": "main-store",
        "image": "https://example.com/grooming.jpg",
        "availableSlots": [
          "09:00", "10:30", "14:00", "15:30"
        ],
        "canUseDeposit": true,
        "canUsePrepaid": true,
        "mixTags": [
          {
            "id": 1,
            "title": "優質服務",
            "type": "service",
            "state": 1
          }
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "total": 15,
      "per_page": 10
    }
  }
}
```

### POST `/api/merchant/booking/{priceAlias}`
取得特定服務詳情

**中介層:** `putMember`
- 🔓 可選會員登入 (未登入也可使用)
- 💰 會員可享有專屬價格或優惠

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Service price front get item success",
  "data": {
    "alias": "basic-grooming",
    "title": "基礎美容",
    "description": "專業寵物美容服務，包含洗澡、剪指甲、清耳朵、造型修剪",
    "content": "詳細服務內容說明...",
    "notice": "請提前30分鐘到店",
    "basePrice": 800,
    "price": 720,
    "memberPrice": 720,
    "serviceTime": 90,
    "bufferTime": 30,
    "categoryTitle": "小型犬",
    "sizeTitle": "3kg以下",
    "storeTitle": "總店",
    "storeAlias": "main-store",
    "images": [
      "https://example.com/grooming1.jpg",
      "https://example.com/grooming2.jpg"
    ],
    "scheduleItems": [
      {
        "id": "schedule-item-uuid",
        "name": "美容師小王",
        "experience": "5年經驗"
      }
    ],
    "addOnServices": [
      {
        "alias": "nail-painting",
        "title": "指甲彩繪",
        "price": 200
      }
    ],
    "mixTags": [
      {
        "id": 1,
        "title": "優質服務",
        "type": "service",
        "state": 1
      }
    ]
  }
}
```

### POST `/api/merchant/booking/price/calendar`
取得預約日曆

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "date": "date|required|format:Y-m-d",
  "priceId": "uuid|required",
  "scheduleItemId": "uuid|nullable",
  "mixTagIds": [1, 2]
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Service price front calendar success",
  "data": {
    "date": "2024-01-15",
    "availableSlots": [
      {
        "time": "09:00",
        "available": true,
        "scheduleItem": {
          "id": "schedule-item-uuid",
          "name": "美容師小王"
        }
      },
      {
        "time": "10:30",
        "available": true,
        "scheduleItem": {
          "id": "schedule-item-uuid",
          "name": "美容師小王"
        }
      },
      {
        "time": "12:00",
        "available": false,
        "reason": "已預約"
      }
    ],
    "serviceInfo": {
      "title": "基礎美容",
      "serviceTime": 90,
      "bufferTime": 30
    }
  }
}
```

---

## 購物車

### GET `/api/cart`
顯示購物車內容

**中介層:** `isMember`
- 🔒 限制只有會員可以查看購物車
- 🛒 確保購物車內容與會員身份關聯

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Cart front get items success",
  "data": {
    "booking": [
      {
        "canPayByDeposit": true,
        "inventoryAlias": "2024-01-15-09-00",
        "merchant": {
          "alias": "pet-salon"
        },
        "param": {
          "alias": "basic-grooming",
          "price": 800,
          "qty": 1,
          "store": {
            "alias": "main-store",
            "title": "總店"
          },
          "title": "基礎美容",
          "serviceTime": 90,
          "bufferTime": 30,
          "categoryTitle": "小型犬",
          "categoryAlias": "small-dog",
          "sizeTitle": "3kg以下",
          "sizeAlias": "under-3kg"
        },
        "add_prices": [],
        "total": 800,
        "prepaid": null,
        "Atm": {
          "Bank": "台灣銀行",
          "BankCode": "004",
          "VACCNo": "1234567890123456",
          "FullName": "寵物美容店"
        },
        "orderExtrafields": [],
        "pet": {
          "id": "pet-id",
          "name": "小白",
          "breed": "貴賓犬"
        },
        "scheduleItems": [
          {
            "id": "schedule-item-id",
            "name": "美容師小王"
          }
        ],
        "availableAddServices": [
          {
            "alias": "nail-trim-add",
            "title": "加購剪指甲",
            "price": 100,
            "serviceTime": 15
          }
        ]
      }
    ],
    "prepaid": [
      {
        "canPayByDeposit": true,
        "Atm": {
          "Bank": "台灣銀行",
          "BankCode": "004",
          "VACCNo": "1234567890123456",
          "FullName": "寵物美容店"
        },
        "prepaid": {
          "title": "美容套餐10次",
          "alias": "grooming-10-pack",
          "groupAlias": "grooming-pack",
          "basePrice": 7200,
          "levelDiscount": 10,
          "levelDiscountType": "percentage",
          "price": 6480,
          "times": 10,
          "total": 6480,
          "expiredDays": 365,
          "expiredDate": "2025-01-15T23:59:59Z",
          "stores": ["總店", "分店"],
          "applicableEvents": [],
          "applicableBonusEvents": []
        }
      }
    ],
    "deposit": [
      {
        "deposit": 1000,
        "Atm": {
          "Bank": "台灣銀行",
          "BankCode": "004",
          "VACCNo": "1234567890123456",
          "FullName": "寵物美容店"
        }
      }
    ]
  }
}
```

### POST `/api/cart/add`
加入購物車

**中介層:** `isMember`
- 🔒 限制只有會員可以使用購物車
- 🛒 確保購物車項目與會員身份關聯

**請求參數:**
```json
{
  "priceId": "uuid|required",
  "quantity": "integer|required|min:1",
  "date": "date|required|format:Y-m-d H:i",
  "scheduleItemId": "uuid|nullable",
  "petId": "integer|nullable"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Cart front create success",
  "data": {
    "cartItemId": "cart-item-uuid"
  }
}
```

### POST `/api/cart/clear`
清空購物車

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 🗑️ 清空會員的購物車內容

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Cart front clear success",
  "data": null
}
```

### POST `/api/cart/checkout`
購物車結帳

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 💳 確保結帳安全性和會員資料完整性

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Cart front checkout success",
  "data": {
    "orderContainer": {
      "uuid": "order-container-uuid",
      "displayId": "20240115001",
      "paymentMethod": "Credit",
      "total": 800,
      "paymentExpiredDate": "2024-01-15T12:00:00Z",
      "paymentUrl": "https://payment.gateway.com/pay?token=xyz123"
    },
    "orders": [
      {
        "id": "order-uuid",
        "status": 2,
        "productName": "基礎美容",
        "date": "2024-01-15",
        "time": "09:00",
        "total": 800,
        "pet": {
          "name": "小白",
          "breed": "貴賓犬"
        }
      }
    ]
  }
}
```

---

## 訂單管理

### POST `/api/merchant/member/order/container/search`
搜尋訂單容器

**中介層:** `isMember`
- 🔒 限制會員只能查看自己的訂單
- 📋 提供訂單歷史記錄

**請求參數:**
```json
{
  "page": "integer|nullable",
  "limit": "integer|nullable",
  "startDate": "date|nullable",
  "endDate": "date|nullable",
  "status": "array|nullable",
  "type": "string|nullable|in:booking,deposit"
}
```

**回應範例:**
```json
{
  "data": [
    {
      "uuid": "order-container-uuid",
      "displayId": "20240115001",
      "type": "booking",
      "total": 800,
      "paymentMethod": "Credit",
      "paymentStatus": "PAID",
      "paidAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-15T09:00:00Z",
      "orders": [
        {
          "id": "order-uuid",
          "productName": "基礎美容",
          "status": 1,
          "date": "2024-01-15",
          "time": "09:00",
          "total": 800,
          "pet": {
            "name": "小白",
            "breed": "貴賓犬"
          }
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 48
  }
}
```

### GET `/api/merchant/member/hotels`
會員住宿訂單容器列表（分頁）

**中介層:** `isMember`

**Query 參數（節選）:**

| 參數 | 說明 |
|------|------|
| `page` | 頁碼 |
| `limit` | 每頁筆數（預設 9，上限 100） |
| `is_temp` | 是否僅暫存購物車時段內更新之容器 |
| `paymentStatus` | 付款狀態陣列，如 `PAID`、`UNPAID` |
| `storeAlias` | 可選，分店 alias（`products.alias`）。僅列出該分店底下之住宿子單所屬容器；無匹配分店時列表為空 |
| `orderBy` | 可選：`created`（預設，依容器 id 新到舊）或 `startDate`（依該容器內住宿最早入住日新到舊） |

**列表排除（預設會員列表，`is_temp` 未帶或為 false）：**

- 不包含 `orders_containers.is_temp = 1` 之暫存容器。
- 不包含 `cancel_at` 已填之已取消容器。
- 至少需有一筆住宿子單 `hotel_orders.status` 不為 `CANCEL`（若僅剩已取消子單則不列出）。

### GET `/api/merchant/member/order/container/{uuid}`
取得特定訂單容器

**中介層:** `isMember`
- 🔒 驗證會員身份
- 🔍 確保只能查看自己的訂單詳情

**回應範例:**
```json
{
  "uuid": "order-container-uuid",
  "displayId": "20240115001",
  "total": 800,
  "paymentMethod": "Credit",
  "paymentStatus": "PAID",
  "paymentExpiredDate": null,
  "paidAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-15T09:00:00Z",
  "orders": [
    {
      "id": "order-uuid",
      "productName": "基礎美容",
      "status": 1,
      "date": "2024-01-15",
      "time": "09:00",
      "endTime": "10:30",
      "total": 800,
      "pet": {
        "id": "pet-uuid",
        "name": "小白",
        "breed": "貴賓犬",
        "gender": "male"
      },
      "scheduleItem": {
        "id": "schedule-item-uuid",
        "name": "美容師小王"
      },
      "store": {
        "title": "總店",
        "address": "台北市大安區復興南路一段123號"
      }
    }
  ]
}
```

### POST `/api/merchant/member/order/container/checkout`
訂單容器結帳

**中介層:** `isMember`
- 🔒 驗證會員登入狀態
- 💳 處理訂單付款流程

**請求參數:**
```json
{
  "uuid": "uuid|required",
  "paymentMethod": "string|required|in:Credit,Cash,Vacc,StoreCredit,Atm,Deposit",
  "couponCode": "string|nullable",
  "useDeposit": "boolean|nullable",
  "depositAmount": "numeric|nullable"
}
```

**回應範例:**
```json
{
  "message": "付款處理中",
  "status": "processing",
  "orderContainer": {
    "uuid": "order-container-uuid",
    "displayId": "20240115001",
    "paymentMethod": "Credit",
    "total": 800,
    "paymentUrl": "https://payment.gateway.com/pay?token=xyz123"
  },
  "redirectUrl": "https://payment.gateway.com/pay?token=xyz123"
}
```

### POST `/api/merchant/member/order/remove`
取消訂單

**中介層:** `isMember`
- 🔒 驗證會員身份
- ❌ 限制只能取消自己的訂單


**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Order front cancel success",
  "data": {
    "orderId": "order-uuid",
    "refundAmount": 800,
    "refundMethod": "原付款方式退款"
  }
}
```

### POST `/api/merchant/member/order/{id}/cancel`
取消特定訂單

**中介層:** `isMember`
- 🔒 驗證會員身份
- ❌ 取消指定的訂單

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Order front cancel success",
  "data": {
    "orderId": "order-uuid",
    "refundAmount": 800,
    "refundMethod": "原付款方式退款",
    "cancelledAt": "2024-01-15T11:00:00Z"
  }
}
```

---

## 包套方案

### POST `/api/merchant/prepaid/search`
搜尋包套方案

**中介層:** `putMember`
- 🔓 可選會員登入
- 💰 會員可查看專屬方案

**請求參數:**
```json
{
  "page": "integer|nullable",
  "limit": "integer|nullable", 
  "category": "string|nullable",
  "search": "string|nullable"
}
```

**回應範例:**
```json
{
  "data": [
    {
      "title": "美容套餐10次",
      "alias": "grooming-10-pack",
      "groupAlias": "grooming-pack",
      "slogan": "超值美容套餐",
      "description": "包含10次基礎美容服務",
      "basePrice": 7200,
      "price": 6480,
      "memberPrice": 6480,
      "times": 10,
      "bonusTimes": 2,
      "expiredDays": 365,
      "image": "https://example.com/prepaid.jpg",
      "stores": ["總店", "分店"],
      "applicableEvents": [
        {
          "title": "基礎美容",
          "maxTimes": 10
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "total": 8,
    "per_page": 10
  }
}
```

### GET `/api/merchant/prepaid/{alias}`
取得特定包套方案

**中介層:** `putMember`
- 🔓 可選會員登入
- 💰 會員可查看專屬價格

### GET `/api/merchant/member/prepaid/order/{uuid}`
取得特定包套方案訂單

**中介層:** 無 (透過 UUID 驗證)

**說明:** 透過 UUID 存取，不需要中介層驗證

### POST `/api/merchant/member/prepaid/order/search`
搜尋包套方案訂單

**中介層:** `isMember`
- 🔒 限制會員只能查看自己的包套訂單
- 📦 提供包套使用記錄

### POST `/api/merchant/member/prepaid/order/{uuid}/checkout`
包套方案訂單結帳

**中介層:** 無 (透過 UUID 驗證)

### POST `/api/merchant/member/prepaid/order/available`
列出會員可用的包套方案

**中介層:** `isMember`
- 🔒 驗證會員身份
- 📦 顯示可用的包套額度

---

## 儲值金

### POST `/api/merchant/deposit/search`
搜尋儲值金方案

**中介層:** `isMember`
- 🔒 驗證會員身份
- 💰 查看可購買的儲值方案

### POST `/api/merchant/member/deposit/order/search`
搜尋儲值金訂單

**中介層:** `isMember`
- 🔒 限制會員只能查看自己的儲值訂單
- 💳 提供儲值購買記錄

### POST `/api/merchant/member/deposit/history/search`
搜尋儲值金使用記錄

**中介層:** `isMember`
- 🔒 驗證會員身份
- 📊 查看儲值金使用明細

### POST `/api/merchant/member/deposit/history/store`
新增儲值金使用記錄

**中介層:** `isMember`
- 🔒 驗證會員身份
- ➕ 記錄儲值金使用情況

---

## 優惠券

### POST `/api/merchant/member/coupon/search`
搜尋可用優惠券

**中介層:** 無 (但需會員資訊)

**請求參數:**
```json
{
  "page": "integer|nullable",
  "limit": "integer|nullable",
  "status": "string|nullable|in:available,used,expired"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Coupon front search success",
  "data": [
    {
      "title": "新客戶專屬優惠",
      "code": "NEWCUSTOMER50",
      "type": "percentage",
      "discount": 10.0,
      "rebatePrice": 0.0,
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": "2024-12-31T23:59:59Z"
    },
    {
      "title": "滿千折百",
      "code": "SAVE100",
      "type": "rebate",
      "discount": 0.0,
      "rebatePrice": 100.0,
      "startDate": "2024-01-01T00:00:00Z",
      "endDate": null
    }
  ]
}
```

### POST `/api/merchant/member/coupon/check`
檢查優惠券可用性

**中介層:** 無 (驗證功能)

**請求參數:**
```json
{
  "couponCode": "string|required",
  "orderTotal": "numeric|required",
  "orderItems": "array|required"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Coupon front search success",
  "data": {
    "title": "新客戶專屬優惠",
    "code": "NEWCUSTOMER50",
    "type": "percentage",
    "available": true,
    "discount": 10.0,
    "rebatePrice": 0.0
  }
}
```

---

## 寵物管理

### POST `/api/merchant/member/pet/store`
新增/更新寵物資訊

**中介層:** `isMember`
- 🔒 驗證會員身份
- 🐾 管理會員的寵物檔案

**請求參數:**
```json
{
  "id": "integer|nullable",
  "name": "string|required",
  "species": "string|required",
  "breed": "string|nullable", 
  "gender": "string|required|in:male,female",
  "birthday": "date|nullable",
  "weight": "numeric|nullable",
  "color": "string|nullable",
  "personality": "string|nullable",
  "medicalHistory": "array|nullable",
  "vaccinations": "array|nullable",
  "avatar": "string|nullable"
}
```

**回應範例:**
```json
{
  "status": "success",
  "code": 200,
  "message": "Pet front create success",
  "data": {
    "id": "pet-uuid",
    "name": "小白",
    "species": "狗",
    "breed": "貴賓犬",
    "gender": "male",
    "birthday": "2020-01-01",
    "age": "4歲",
    "weight": 3.5,
    "color": "白色",
    "personality": "活潑好動",
    "avatar": "https://example.com/pet-avatar.jpg",
    "medicalHistory": [
      {
        "date": "2023-12-01",
        "condition": "健康檢查",
        "notes": "一切正常"
      }
    ],
    "vaccinations": [
      {
        "vaccine": "狂犬病疫苗",
        "date": "2023-06-01",
        "nextDue": "2024-06-01"
      }
    ],
    "createdAt": "2023-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
}
```

### POST `/api/merchant/member/pet/remove`
刪除寵物

**中介層:** `isMember`
- 🔒 驗證會員身份
- 🗑️ 刪除指定寵物檔案

### POST `/api/merchant/member/pet/search`
搜尋寵物

**中介層:** `isMember`
- 🔒 限制會員只能查看自己的寵物
- 🐾 提供寵物列表

### GET `/api/merchant/member/pet/{id}`
取得特定寵物資訊

**中介層:** `isMember`
- 🔒 驗證會員身份
- 🐾 查看寵物詳細資訊

---

## 會員等級

### GET `/api/merchant/member/levels`
取得會員等級列表

**中介層:** 無 (公開資訊)

**回應範例:**
```json
{
  "data": [
    {
      "id": 1,
      "title": "一般會員",
      "alias": "normal",
      "discountRate": 100,
      "description": "基本會員等級"
    },
    {
      "id": 2,
      "title": "VIP會員", 
      "alias": "vip",
      "discountRate": 90,
      "description": "享有9折優惠"
    }
  ]
}
```

---

## 服務群組介紹

### POST `/api/merchant/service/price/group/search`
搜尋服務價格群組

**中介層:** 無 (公開端點)

**請求參數:**
```json
{
  "page": "integer|nullable",
  "limit": "integer|nullable",
  "category": "string|nullable"
}
```

---

## 服務備註

### GET `/api/comment/{uuid}`
取得服務備註

**中介層:** 無 (透過 UUID 存取)

---

## 金流回調

### POST `/api/order/container/{uuid}/checkout/callback`
訂單容器付款回調 (藍新金流)

**中介層:** 無 (金流系統回調)

### POST `/api/prepaid/order/{uuid}/checkout/callback`
包套方案訂單付款回調 (藍新金流)

**中介層:** 無 (金流系統回調)

---

## 排班人員

### GET `/api/{merchant_alias}/schedule/item/{item_id}/ical`
取得排班人員 iCal 檔案

**中介層:** 無 (公開行事曆)

**說明:** 
- 產生排班人員的 iCal 行事曆檔案
- 可匯入到各種行事曆應用程式 (Google Calendar、Outlook 等)
- 透過商家別名和排班項目 ID 存取
- 檔案格式符合 RFC 5545 標準

---

## 文章模組

### POST `/api/merchant/article/search`
搜尋文章

**中介層:** 無 (公開內容)

**請求參數:**
```json
{
  "page": "integer|nullable",
  "limit": "integer|nullable",
  "category": "string|nullable",
  "search": "string|nullable",
  "featured": "boolean|nullable"
}
```

### GET `/api/merchant/article/{id}`
取得特定文章

**中介層:** 無 (公開內容)

---

## Site 中介層說明

### `isMember`
**功能**: 驗證會員登入狀態
- 檢查會員是否已登入 (`mm` guard)
- 驗證 Token 是否有效且未過期
- 過期 Token 會自動刪除
- 將會員資訊注入到 `$request['member']`
- **失敗回應**: `MERCHANT_MEMBER_FRONT_UNAUTHORIZED`, `USER_TOKEN_EXPIRED`, `USER_UNAUTHORIZED`

### `putMember`
**功能**: 設定會員資訊 (不強制登入)
- 嘗試取得目前登入的會員資訊
- 將會員資訊注入到 `$request['member']` (可能為 null)
- 常用於可選登入的功能 (如瀏覽商品、查看價格等)

---

## 回應格式

所有 API 回應都遵循統一格式：

### 成功回應
```json
{
  "status": "success",
  "code": 200,
  "message": "操作成功",
  "data": {
    // 回應資料
  }
}
```

### 錯誤回應
```json
{
  "status": "error",
  "code": 400,
  "message": "錯誤訊息",
  "data": {
    "details": {}
  }
}
```

### 分頁回應
```json
{
  "status": "success",
  "code": 200,
  "message": "搜尋成功",
  "data": {
    "items": [],
    "pagination": {
      "current_page": 1,
      "total_pages": 10,
      "total_items": 100,
      "per_page": 10
    }
  }
}
```

---

## 常見錯誤代碼

- `VALIDATION_ERROR`: 驗證錯誤
- `UNAUTHORIZED`: 未授權
- `MERCHANT_MEMBER_FRONT_UNAUTHORIZED`: 會員未登入
- `USER_TOKEN_EXPIRED`: Token 已過期
- `MEMBER_NOT_FOUND`: 會員不存在
- `INSUFFICIENT_BALANCE`: 餘額不足
- `COUPON_INVALID`: 優惠券無效
- `ORDER_CANCELLED`: 訂單已取消
- `PAYMENT_FAILED`: 付款失敗

---

## Site 中介層快速參考

| 圖示 | 中介層 | 功能說明 | 使用場景 |
|------|--------|----------|----------|
| 🔒 | `isMember` | 強制會員登入驗證 | 會員專屬功能 |
| 🔓 | `putMember` | 可選會員資訊注入 | 瀏覽功能，會員有優惠 |

### 常用組合快速索引

- **🔒** = 會員專用功能
- **🔓** = 訪客友善，會員有優惠

---

## 版本資訊

- **API 版本**: v1
- **文件類型**: Site API (前台)
- **最後更新**: 2024年
- **相容性**: Laravel 8+, PHP 7.4+

---

*此文件基於 DDDream 套件的 Site API 自動生成，如有疑問請聯繫開發團隊。*