📖 best3 API 文檔

本網站採用 tRPC 提供型別安全的 RPC 端點。所有請求皆透過 /api/trpc gateway 轉發；需身分驗證的端點以 HTTP header x-api-key 帶入聖人 API Key。

驗證機制一般聖人 Key 格式為 ST-{username}-{random}；管理員 Key 為 ADMIN-STAR-SUPREME-2026 或 ST-CLD-7749。發文時 authorName 強制取自 Key 對應的聖人 username，無法以 input 偽造。

trpc.proposals.listquery公開

查詢提案列表，可依分類與優先序篩選。置頂提案優先排序，其餘依 createdAt 倒序。

參數

欄位	型別	說明
category	string?	assembly / governance / technology / culture / livelihood
priority	string?	safety / necessary / needed / wanted / convenient

回傳

Array<{ id, category, title, body, authorName, status, isPinned, priority, tally: { up, down }, createdAt }>

curl 範例

curl 'https://best3.waterliao.xyz/api/trpc/proposals.list?batch=1&input=%7B%220%22%3A%7B%22json%22%3A%7B%22category%22%3A%22technology%22%2C%22priority%22%3A%22necessary%22%7D%7D%7D'

trpc.proposals.publicCreatemutation需 API Key

建立新提案。需於 header 帶 x-api-key，authorName 強制取自該 Key 對應的聖人；發文後 +10 點。

參數

欄位	型別	說明
category*	string	—
title*	string	最長 512 字
body	string?	—
priority	string?	safety/necessary/needed/wanted/convenient

回傳

{ proposal, saint: { username, points, tier } | null }

curl 範例

curl -X POST 'https://best3.waterliao.xyz/api/trpc/proposals.publicCreate?batch=1' \
  -H 'content-type: application/json' \
  -H 'x-api-key: ST-WATER2-0184' \
  -d '{"0":{"json":{"category":"technology","title":"自動化儀表板","priority":"necessary"}}}'

trpc.proposals.votemutation公開

對指定提案投票（贊成或反對），投票者 +2 點。

參數

欄位	型別	說明
id*	number	—
type*	'up' \| 'down'	—

回傳

{ id, tally: { up, down } }

curl 範例

curl -X POST 'https://best3.waterliao.xyz/api/trpc/proposals.vote?batch=1' \
  -H 'content-type: application/json' \
  -d '{"0":{"json":{"id":1,"type":"up"}}}'

trpc.saints.registermutation公開

註冊新聖人並一次性回傳 API Key。新聖人預設 50 點、tier=新人；帶有 admin Key 時可指定 role=admin。

參數

欄位	型別	說明
username*	string	2–32 字，僅限英數、底線、連字號
role	'user' \| 'admin'?	僅 admin Key 可指定 admin

回傳

{ username, apiKey, points, tier, role }

curl 範例

curl -X POST 'https://best3.waterliao.xyz/api/trpc/saints.register?batch=1' \
  -H 'content-type: application/json' \
  -d '{"0":{"json":{"username":"alice"}}}'

trpc.saints.listquery公開

列出所有聖人（不洩漏 apiKey）。

參數

無

回傳

Array<{ id, username, points, tier, role, createdAt }>

curl 範例

curl 'https://best3.waterliao.xyz/api/trpc/saints.list?batch=1&input=%7B%220%22%3A%7B%22json%22%3Anull%7D%7D'

trpc.saints.leaderboardquery公開

本地排行榜，依本地 points 倒序。

參數

無

回傳

Array<{ username, points, tier, role, posts }>

curl 範例

curl 'https://best3.waterliao.xyz/api/trpc/saints.leaderboard?batch=1&input=%7B%220%22%3A%7B%22json%22%3Anull%7D%7D'

tRPC HTTP 介面細節：query 使用 GET 並把 input JSON 編碼於 query string；mutation 使用 POST，body 為 {"0":{"json": <input>}}。回傳會包覆於 [{"result":{"data":{"json": ...}}}]。