daniel.w
/
pet_data
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
pet_data/docs/API_STRUCTURE.md

5.2 KiB
Raw Permalink Blame History

API 端點結構設計

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

基礎配置

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

API 端點列表

1. 寵物狀態相關

GET /pet/state

獲取當前寵物狀態

Response:

{
  "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:

{
  "hunger": 85,
  "happiness": 70
}

Response:

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

POST /pet/save

儲存完整寵物狀態

Request Body:

{ /* 完整 PetState 物件 */ }

Response:

{
  "success": true,
  "message": "狀態已儲存"
}

2. 事件系統相關

GET /events/list

獲取所有事件配置

Response:

[
  {
    "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:

{
  "eventId": "lucky_find",
  "petState": { /* 當前狀態 */ }
}

Response:

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

3. Buff 系統相關

POST /buffs/apply

應用 Buff

Request Body:

{
  "id": "fortune",
  "name": "福運加持",
  "durationTicks": 5,
  "percent": { "luck": 0.2 }
}

Response:

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

4. 神明系統相關

GET /deities/list

獲取所有神明資料

Response:

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

POST /deities/pray

祈福

Request Body:

{
  "deityId": "mazu",
  "petState": { /* 當前狀態 */ }
}

Response:

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

5. 籤詩系統相關

POST /fortune/draw

抽籤

Request Body:

{
  "deityId": "guanyin" // 可選
}

Response:

{
  "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:

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

POST /items/use

使用道具

Request Body:

{
  "itemId": "cookie",
  "count": 1
}

Response:

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

錯誤處理

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

{
  "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，方便測試和開發。