pet_data/docs/API_STRUCTURE.md

# API 端點結構設計

本文檔定義了虛擬寵物系統的 API 端點結構，用於前端與後端整合。

## 基礎配置

- **Base URL**: `http://localhost:3000/api` (開發環境)
- **認證**: 未來可加入 JWT Token
- **資料格式**: JSON

## API 端點列表

### 1. 寵物狀態相關

#### GET `/pet/state`
獲取當前寵物狀態

**Response:**
```json
{
  "speciesId": "tinyTigerCat",
  "stage": "baby",
  "hunger": 80.5,
  "happiness": 60.2,
  "health": 100,
  "weight": 500,
  "ageSeconds": 120,
  "poopCount": 2,
  "str": 5,
  "int": 3,
  "dex": 8,
  "luck": 15,
  "isSleeping": false,
  "isSick": false,
  "isDead": false,
  "currentDeityId": "mazu",
  "deityFavors": {
    "mazu": 20,
    "earthgod": 10,
    "yuelao": 0,
    "wenchang": 0,
    "guanyin": 5
  },
  "dailyPrayerCount": 1,
  "destiny": null,
  "buffs": [],
  "inventory": [],
  "generation": 1,
  "lastTickTime": 1234567890
}
```

#### POST `/pet/update`
更新寵物狀態（部分更新）

**Request Body:**
```json
{
  "hunger": 85,
  "happiness": 70
}
```

**Response:**
```json
{
  "success": true,
  "data": { /* 完整狀態物件 */ }
}
```

#### POST `/pet/save`
儲存完整寵物狀態

**Request Body:**
```json
{ /* 完整 PetState 物件 */ }
```

**Response:**
```json
{
  "success": true,
  "message": "狀態已儲存"
}
```

---

### 2. 事件系統相關

#### GET `/events/list`
獲取所有事件配置

**Response:**
```json
[
  {
    "id": "lucky_find",
    "type": "good",
    "weight": 0.3,
    "condition": "function_string_or_null",
    "effects": [
      {
        "type": "modifyStats",
        "payload": { "happiness": 10, "luck": 5 }
      }
    ]
  }
]
```

#### POST `/events/trigger`
觸發事件

**Request Body:**
```json
{
  "eventId": "lucky_find",
  "petState": { /* 當前狀態 */ }
}
```

**Response:**
```json
{
  "success": true,
  "eventId": "lucky_find",
  "effects": [
    {
      "type": "modifyStats",
      "updates": { "happiness": 10, "luck": 5 }
    }
  ]
}
```

---

### 3. Buff 系統相關

#### POST `/buffs/apply`
應用 Buff

**Request Body:**
```json
{
  "id": "fortune",
  "name": "福運加持",
  "durationTicks": 5,
  "percent": { "luck": 0.2 }
}
```

**Response:**
```json
{
  "success": true,
  "buff": { /* Buff 物件 */ }
}
```

---

### 4. 神明系統相關

#### GET `/deities/list`
獲取所有神明資料

**Response:**
```json
[
  {
    "id": "mazu",
    "name": "媽祖",
    "personality": "溫柔守護",
    "buffs": {
      "gameSuccessRate": 0.1,
      "sicknessReduction": 0.15
    },
    "buffDescriptions": ["小遊戲 +10%", "生病機率 -15%"],
    "dialogues": ["好孩子，媽祖保佑你平安喔"],
    "icon": "deity-mazu"
  }
]
```

#### POST `/deities/pray`
祈福

**Request Body:**
```json
{
  "deityId": "mazu",
  "petState": { /* 當前狀態 */ }
}
```

**Response:**
```json
{
  "success": true,
  "favorIncrease": 5,
  "newFavor": 25,
  "message": "祈福成功"
}
```

---

### 5. 籤詩系統相關

#### POST `/fortune/draw`
抽籤

**Request Body:**
```json
{
  "deityId": "guanyin" // 可選
}
```

**Response:**
```json
{
  "success": true,
  "lot": {
    "id": "1",
    "grade": "上上",
    "palace": "子宮",
    "poem1": "天開地闢萬物全 人力回天事事全",
    "poem2": "若問前途與運泰 唯有善德鬼神欽",
    "meaning": "大吉大利，萬事亨通",
    "explanation": "此籤象徵開天闢地之意，預示大吉",
    "oracle": "家宅：平安、事業：順利",
    "story": "宋太祖黃袍加身"
  },
  "buff": {
    "id": "fortune_blessing",
    "name": "上上籤祝福",
    "durationTicks": 20,
    "percent": { "luck": 0.3, "dropRate": 0.25 }
  }
}
```

---

### 6. 道具系統相關

#### GET `/items/list`
獲取所有道具

**Response:**
```json
[
  {
    "id": "cookie",
    "name": "幸運餅乾",
    "type": "consumable",
    "effects": {
      "modifyStats": { "hunger": 20, "happiness": 10 }
    },
    "description": "增加飢餓和快樂"
  }
]
```

#### POST `/items/use`
使用道具

**Request Body:**
```json
{
  "itemId": "cookie",
  "count": 1
}
```

**Response:**
```json
{
  "success": true,
  "itemId": "cookie",
  "count": 1,
  "effects": {
    "modifyStats": { "hunger": 20, "happiness": 10 }
  }
}
```

---

## 錯誤處理

所有 API 錯誤應返回以下格式：

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "錯誤訊息"
  }
}
```

常見錯誤碼：
- `PET_NOT_FOUND`: 寵物不存在
- `INVALID_STATE`: 狀態無效
- `EVENT_CONDITION_FAILED`: 事件條件不滿足
- `DAILY_LIMIT_EXCEEDED`: 每日限制已達上限
- `ITEM_NOT_FOUND`: 道具不存在
- `INSUFFICIENT_ITEM`: 道具數量不足

---

## 實作建議

### 後端實作
1. 使用 RESTful API 設計
2. 實作資料驗證（Joi/Yup）
3. 加入認證中介層（未來）
4. 實作速率限制（rate limiting）
5. 使用資料庫儲存狀態（PostgreSQL/MongoDB）

### 前端整合
1. 使用 `ApiService` 類別統一管理 API 呼叫
2. 實作錯誤處理和重試機制
3. 使用狀態管理（Pinia/Vuex）同步狀態
4. 實作樂觀更新（Optimistic Updates）

### Mock 模式
開發階段可使用 `ApiService` 的 mock 模式，所有資料儲存在 `localStorage`，方便測試和開發。