# Pet Hotel 系統架構文件

## 概述

本文檔詳細說明 Pet Hotel 功能的技術架構，包含後端架構、資料庫設計、程式規範等技術細節。

## 🏗️ 技術架構

### 後端架構
```
Controllers/Hotel/Admin/
├── HotelRoomTypeAdminController.php    # 房型管理控制器
├── HotelRoomAdminController.php        # 房間管理控制器
├── HotelPriceRuleAdminController.php   # 價格規則控制器
└── HotelRoomScheduleAdminController.php # 排班管理控制器

Models/Hotel/
├── HotelRoomType.php                   # 房型模型
├── HotelRoom.php                       # 房間模型
├── HotelPriceRule.php                  # 價格規則模型
└── HotelRoomSchedule.php               # 排班模型

Services/Hotel/Admin/
├── HotelRoomTypeAdminService.php       # 房型業務邏輯
├── HotelRoomAdminService.php           # 房間業務邏輯
├── HotelPriceRuleAdminService.php      # 價格規則業務邏輯
└── HotelRoomScheduleAdminService.php   # 排班業務邏輯

Repositories/Hotel/Admin/
├── HotelRoomTypeAdminRepository.php    # 房型資料存取
├── HotelRoomAdminRepository.php        # 房間資料存取
└── HotelRoomScheduleAdminRepository.php # 排班資料存取
```

### 資料庫設計

#### 1. 房型表 (hotels_rooms_types)
```sql
CREATE TABLE hotels_rooms_types (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    merchant_id UUID NOT NULL,
    product_id UUID NOT NULL,
    title VARCHAR(255) NOT NULL,           -- 房型名稱
    enTitle VARCHAR(255) NOT NULL,         -- 英文房型名稱
    subTitle VARCHAR(255) NOT NULL,        -- 副標題
    maxPets TINYINT NOT NULL,              -- 最大寵物數量
    code VARCHAR(255) NOT NULL,            -- 房型代碼
    startNumber SMALLINT UNSIGNED NOT NULL, -- 起始編號
    state TINYINT DEFAULT 1,               -- 狀態
    description TEXT,                      -- 描述
    features TEXT NOT NULL,                -- 特色功能 (JSON)
    created_by INT UNSIGNED NOT NULL,
    updated_by INT UNSIGNED,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

#### 2. 房間表 (hotels_rooms)
```sql
CREATE TABLE hotels_rooms (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    product_id UUID NOT NULL,
    roomTypeId BIGINT UNSIGNED NOT NULL,   -- 房型ID
    code VARCHAR(255) NOT NULL,            -- 房間代碼
    number SMALLINT UNSIGNED NOT NULL,     -- 房間號碼
    state TINYINT DEFAULT 1,               -- 狀態
    created_by INT UNSIGNED NOT NULL,
    updated_by INT UNSIGNED,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    deleted_at TIMESTAMP                   -- 軟刪除
);
```

#### 3. 價格規則表 (hotels_prices_rules)
```sql
CREATE TABLE hotels_prices_rules (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    merchant_id UUID NOT NULL,
    product_id UUID NOT NULL,
    title VARCHAR(255) NOT NULL,           -- 規則名稱
    type VARCHAR(255) NOT NULL,            -- 規則類型
    state TINYINT DEFAULT 1,               -- 狀態
    valueType VARCHAR(255) NOT NULL,       -- 數值類型
    operator VARCHAR(255) NOT NULL,        -- 操作符
    value DECIMAL NOT NULL,                -- 數值
    minNight INT UNSIGNED,                 -- 最少住宿天數
    startDate DATETIME,                    -- 開始日期
    endDate DATETIME,                      -- 結束日期
    created_by INT UNSIGNED NOT NULL,
    updated_by INT UNSIGNED,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

#### 4. 價格規則與房型關聯表 (hotels_prices_rules_rooms_types_maps)
```sql
CREATE TABLE hotels_prices_rules_rooms_types_maps (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    price_rule_id BIGINT UNSIGNED NOT NULL,
    room_type_id BIGINT UNSIGNED NOT NULL,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

#### 5. 排班表 (hotels_rooms_schedules)
```sql
CREATE TABLE hotels_rooms_schedules (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    product_id UUID NOT NULL,
    roomId BIGINT UNSIGNED NOT NULL,       -- 房間ID
    startDate DATETIME NOT NULL,           -- 開始時間
    endDate DATETIME NOT NULL,             -- 結束時間
    state TINYINT DEFAULT 1,               -- 狀態
    created_by INT UNSIGNED NOT NULL,
    updated_by INT UNSIGNED,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

#### 6. 房間價格表 (hotels_rooms_prices)
```sql
CREATE TABLE hotels_rooms_prices (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    room_type_id BIGINT UNSIGNED NOT NULL,
    price DECIMAL NOT NULL,
    currency VARCHAR(3) NOT NULL,
    created_by INT UNSIGNED NOT NULL,
    updated_by INT UNSIGNED,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

## 📊 功能特色

### 1. 彈性房型配置
- 支援多種房型設定
- 可設定每個房型的寵物數量限制
- 支援房型特色功能的 JSON 格式儲存
- 多語言支援（中英文）

### 2. 智慧價格管理
- 動態價格規則系統
- 支援時間區間定價
- 最少住宿天數限制
- 多種計算方式（固定金額、百分比）

### 3. 完整排程管理
- 房間可用性即時查詢
- 住宿時段衝突檢測
- 彈性排班設定

### 4. 標準化 API 設計
- RESTful API 架構
- 統一的錯誤處理
- 完整的 CRUD 操作
- 資料驗證和安全控制

## 🔧 技術規格

### 開發環境
- **PHP**: Laravel Framework
- **資料庫**: MySQL
- **架構**: MVC + Repository Pattern
- **API**: RESTful API

### 程式規範
- PSR-4 自動載入
- 標準化命名規則
- 完整的資料驗證
- 軟刪除支援
- 記錄變更追蹤

### 中介層 (Middleware)
- `hasMerchant`: 檢查商戶權限
- `expired`: 檢查商戶是否過期
- `admin`: 檢查管理員權限

### 資料驗證
- 使用 Laravel Request 類別進行資料驗證
- 支援複雜的驗證規則
- 統一的錯誤回應格式

## 🎯 商業價值

### 對商家的價值
1. **服務多樣化**: 從單純預約服務擴展到住宿服務
2. **收入增長**: 新增住宿收入來源
3. **客戶黏著度**: 提供更完整的寵物照護服務
4. **營運效率**: 系統化管理住宿資源

### 對平台的價值
1. **競爭優勢**: 提供更完整的寵物服務生態
2. **市場擴展**: 進入寵物住宿市場
3. **用戶留存**: 一站式寵物服務平台

## 🚀 開發進度

### 已完成功能 ✅
- [x] 房型管理系統（後台）
- [x] 房間管理系統（後台）
- [x] 價格規則系統（後台）
- [x] 住宿排班系統（後台）
- [x] 資料庫遷移檔案
- [x] 後台管理 API 端點
- [x] 房間可用性查詢功能

### 目前開發狀態 📊
根據實際程式碼分析：

**✅ 已實現**：
- 完整的後台管理功能
- 4 個核心 API 端點
- 資料庫結構設計
- 基礎業務邏輯

**🔍 分析發現**：
- 目前僅有後台管理功能
- 尚未發現前台住宿預約相關程式碼
- 主要專注於管理端功能建置

**📝 備註**：
此分支主要完成了住宿管理的**後台基礎架構**，為後續前台功能開發奠定了穩固的基礎。前台功能的開發時程和規劃需要進一步確認。

## 📁 檔案結構

### 控制器 (Controllers)
```
src/Controllers/Hotel/
├── Admin/
│   ├── HotelRoomTypeAdminController.php
│   ├── HotelRoomAdminController.php
│   ├── HotelPriceRuleAdminController.php
│   └── HotelRoomScheduleAdminController.php
├── HotelRoomTypeController.php
├── HotelRoomController.php
├── HotelPriceRuleController.php
└── HotelRoomScheduleController.php
```

### 模型 (Models)
```
src/Models/Hotel/
├── Admin/
│   ├── HotelRoomTypeAdmin.php
│   ├── HotelRoomAdmin.php
│   ├── HotelPriceRuleAdmin.php
│   └── HotelRoomScheduleAdmin.php
├── HotelRoomType.php
├── HotelRoom.php
├── HotelPriceRule.php
└── HotelRoomSchedule.php
```

### 服務 (Services)
```
src/Services/Hotel/
├── Admin/
│   ├── HotelRoomTypeAdminService.php
│   ├── HotelRoomAdminService.php
│   ├── HotelPriceRuleAdminService.php
│   └── HotelRoomScheduleAdminService.php
├── HotelRoomTypeService.php
├── HotelRoomService.php
├── HotelPriceRuleService.php
└── HotelRoomScheduleService.php
```

### 資料存取層 (Repositories)
```
src/Repositories/Hotel/
├── Admin/
│   ├── HotelRoomTypeAdminRepository.php
│   ├── HotelRoomAdminRepository.php
│   ├── HotelPriceRuleAdminRepository.php
│   └── HotelRoomScheduleAdminRepository.php
├── HotelRoomTypeRepository.php
├── HotelRoomRepository.php
├── HotelPriceRuleRepository.php
└── HotelRoomScheduleRepository.php
```

### 請求驗證 (Requests)
```
src/Requests/Hotel/
├── Admin/
│   ├── HotelRoomTypeAdminStorePost.php
│   ├── HotelRoomAdminAvailabilityPost.php
│   ├── HotelPriceRuleAdminStorePost.php
│   └── HotelRoomScheduleAdminStorePost.php
└── [其他請求驗證類別]
```

### 資源 (Resources)
```
src/Resources/Hotel/
└── Admin/
    ├── Models/
    │   └── HotelRoomAdminAvailabilityResource.php
    └── Collections/
        └── HotelRoomAdminAvailabilityResourceCollection.php
```

---

**最後更新**: 2025年9月26日  
**分支**: `ipetbooking/feat/pet-hotel`