> For the complete documentation index, see [llms.txt](https://terryhuanghd.gitbook.io/build-game-services/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://terryhuanghd.gitbook.io/build-game-services/you-xi-fu-wu/leaderboard-pai-hang-bang-xi-tong/she-ji-jian-yi-de-gong-kai-pai-hang-bang-xi-tong-tou-guo-parse.md).

# 設計簡易的公開排行榜系統 - 透過 Parse

以下的案例是以 **公開排行榜** 來設計初始概念，並不夠優化在正式環境中使用。在務實上，由於排行榜的資料使用存在很大的不對稱性，所以都會設計有預先計算以及快取的機制，來避免浪費大量的運算資源來 **重複讀取** 變動性不大的資訊

## Leaderboard 排行榜資料表設計

| 欄位           | 類型     | 解釋                                                        | 範例                                                                       |
| ------------ | ------ | --------------------------------------------------------- | ------------------------------------------------------------------------ |
| ID           | String | 排行榜 ID，供辨識使用                                              | leaderboard\_hunt\_master                                                |
| NAME         | String | 顯示的名稱                                                     | <p>leaderboard\_highest\_score\_name <br> 多國語系鍵值，可於字串映射檔轉譯 <br> 最高分榜</p> |
| ICON         | File   | 圖示                                                        | < File Object >                                                          |
| IS\_PUBLIC   | Bool   | 是否為公開排行榜                                                  | True                                                                     |
| DESCENDING   | Bool   | 排名方式以數值由大到小排列                                             | True                                                                     |
| LASTING      | String | 統計時段                                                      | DAILY, WEEKLY, ALL                                                       |
| MAX\_VALUE   | Number | 合理數值上限                                                    | 100000                                                                   |
| MIN\_VALUE   | Number | 合理數值下限                                                    | 0.1                                                                      |
| VALUE\_TYPE  | String | 數值類別                                                      | NORMAL, CONCURRENCY, TIME                                                |
| ORDER        | Number | 排行榜顯示的順序                                                  | 1                                                                        |
| APP\_VERSION | Number | <p>排行榜要求的程式版本 <br> 用來過濾舊版本程式不支援的成就 <br> 也方便開發、測試新的排行榜</p> | 1                                                                        |
| IS\_DELETE   | Bool   | 是否已經刪除                                                    | False                                                                    |

> 多國語系的支援，可以透過本機端或是快取雲端字串映射來轉譯

* 新增排行榜：新增一筆排行榜的資料表，並將 APP\_VERSION 設定為下一個 APP 版本編號。然後於新增多國語系的字串映射檔描述，以及結算時候的對應邏輯
* 修改排行榜：以此設計而言，可簡單的透過雲端資料的變更，可動態修改的欄位有：圖樣、合理數值、顯示順序...等等
* 移除排行榜：將排行榜 IS\_DELETE 設定為 True 即可。不直接刪除，可避免部分資料相依性造成的錯誤
* 取得排行榜清單：將 **目前程式端支援** 以及 **未被刪除** 的排行榜取出，**依照順序排列**

```
curl -X GET \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -G \
  --data-urlencode 'order=ORDER' \
  --data-urlencode 'where={"APP_VERSION":{"$lte":${CURRENT_APP_VERSION}},"IS_DELETE":false}' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/Leaderboard
```

## LeaderboardRecord 排行榜紀錄表設計

| 欄位          | 類型                                        | 解釋       | 範例                        |
| ----------- | ----------------------------------------- | -------- | ------------------------- |
| objectId    | String                                    | 此紀錄物件 ID | ${OBJECT ID}              |
| USER        | <p>String <br> Pointer -> User</p>        | 玩家 ID    | user\_id\_terry           |
| LEADERBOARD | <p>String <br> Pointer -> Leaderboard</p> | 排行榜 ID   | leaderboard\_hunt\_master |
| VALUE       | Number                                    | 排行數值     | 100                       |
| TIME        | <p>Number <br> Date</p>                   | 最新記錄創造時間 | ${UNIX\_TIMESTAMP}        |

* 取得玩家在特定排行榜自己的紀錄

```
curl -X GET \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -G \
  --data-urlencode 'where={"USER":${USER_ID},"LEADERBOARD":${LEADERBOARD_ID}}' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/LeaderboardRecord
```

* 取得玩家在特定公開排行榜自己的名次

  > DESCENDING 以 $gt 取得比自己大的數量, ASCENDING 以 $lt 取得比自己小的數量。如果是有重複性數值的排行榜，通常會另外設計一個欄位來實作雙重排序因子的計數

```
curl -X GET \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -G \
  --data-urlencode 'where={"LEADERBOARD":${LEADERBOARD_ID},"VALUE":{"$gt":${VALUE}}}' \
  --data-urlencode 'count=1' \
  --data-urlencode 'limit=0' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/LeaderboardRecord
```

* 取得特定公開排行榜榜單

  > 以 -VALUE 或是 VALUE 來取得 DESCENDING 與 ASCENDING 的排序。limit 與 skip 可用來作 paging

```
curl -X GET \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -G \
  --data-urlencode 'where={"LEADERBOARD":${LEADERBOARD_ID}}' \
  --data-urlencode 'order=-VALUE' \
  --data-urlencode 'limit=30' \
  --data-urlencode 'skip=0' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/LeaderboardRecord
```

* 新增排行榜紀錄

```
  curl -X POST \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"USER":${USER_ID},"LEADERBOARD":"leaderboard_highest_score_name","VALUE":${VALUE},"TIME":${NOW}}' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/LeaderboardRecord
```

* 更新排行榜紀錄

```
curl -X PUT \
  -H "X-Parse-Application-Id: ${APPLICATION_ID}" \
  -H "X-Parse-REST-API-Key: ${REST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"VALUE":${VALUE},"TIME":${NOW}}' \
  https://YOUR.PARSE-SERVER.HERE/parse/classes/LeaderboardRecord/${OBJECT ID}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://terryhuanghd.gitbook.io/build-game-services/you-xi-fu-wu/leaderboard-pai-hang-bang-xi-tong/she-ji-jian-yi-de-gong-kai-pai-hang-bang-xi-tong-tou-guo-parse.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.