# DUPR API Proxy — 使用指南 (繁體中文 / English)

Base URL / 基底網址: https://duprapi.sportsbuddy.club
Local (XAMPP PHP 8) / 本機測試網址: http://localhost:8080/dupr_api/api

通用說明 / General Notes
- 支援 HTTP `GET` 與 `POST` 兩種方法，參數可放在 Query String 或 JSON Body。All endpoints accept both GET and POST; parameters may be in the query string or JSON body.
- 回應為 JSON 包裝格式，含 `success`、`action`、`reason`、`diagnostics`、`data`。Responses are returned in an envelope with success/failure reason and diagnostics.
- 不需額外授權，憑證由伺服器端自動處理 (.env + token.json)。No client auth required; server handles credentials internally.

### Response Envelope / 回應格式
```json
{
  "success": true,
  "action": "searchPlayers",
  "reason": "Request completed successfully. result.total=123.",
  "context": {"query":"Joe","offset":0,"limit":10},
  "diagnostics": {
    "time": "2026-02-27T00:00:00+00:00",
    "upstream": {
      "ok": true,
      "httpCode": 200,
      "url": "https://api.dupr.gg/player/v1.0/search",
      "method": "POST",
      "hasResult": true,
      "timestamp": "2026-02-27T00:00:00+00:00"
    }
  },
  "data": {"result": {}}
}
```

- `success=false` 時，`reason` 會盡量指出失敗原因，並附上上游 `httpCode/status`。
- HTTP 狀態碼會優先反映上游錯誤碼；若無法判斷則回 `502`。
- `diagnostics.routeDebug` 會顯示路由解析細節（`rawPath`, `segmentsBeforeNormalize`, `apiIndex`, `segments`），方便排查 404。

## Health Check / 健康檢查
GET/POST `/api/health`
- 成功: `{ "status": "ok", "service": "dupr-api" }`

## Search Clubs / 搜尋俱樂部
GET/POST `/api/clubs`
- 參數 / Params: `query` (必填/required), `offset` (預設 0), `limit` (預設 10)
- 範例 / Example (POST JSON):
```bash
curl -s -X POST "https://duprapi.sportsbuddy.club/api/clubs" \
  -H "Content-Type: application/json" \
  -d '{"query":"Hong Kong"}'
```

## Club Members / 俱樂部成員
GET/POST `/api/club/{clubId}/members`
- 參數 / Params: `offset` (預設 0), `limit` (預設 10)
- 範例 / Example:
```bash
curl -s "https://duprapi.sportsbuddy.club/api/club/123/members?offset=0&limit=10"
```

## Search Players / 搜尋球員
GET/POST `/api/players/search`
- 參數 / Params: `query` (必填/required), `filter` (object，可含 lat/lng/radiusInMeters/rating 等), `offset` (預設 0), `limit` (預設 10)
- 範例 / Example (POST JSON):
```bash
curl -s -X POST "https://duprapi.sportsbuddy.club/api/players/search" \
  -H "Content-Type: application/json" \
  -d '{"query":"Joe","filter":{"lat":22.39,"lng":114.10,"radiusInMeters":10000},"offset":0,"limit":10}'
```

## Search Player by DUPR ID / 以 DUPR ID 搜尋球員
GET/POST `/api/player/searchByDuprId`
- 參數 / Params: `duprId` (必填/required)
- 範例 / Example (POST JSON):
```bash
curl -s -X POST "https://duprapi.sportsbuddy.club/api/player/searchByDuprId" \
  -H "Content-Type: application/json" \
  -d '{"duprId":"9007199254740991"}'
```

## Player Detail / 球員資料
GET/POST `/api/player/{playerId}`
- 範例 / Example:
```bash
curl -s "https://duprapi.sportsbuddy.club/api/player/123"
```

## Player History / 球員歷史
GET/POST `/api/player/{playerId}/history`
- 參數 / Params: `offset` (預設 0), `limit` (預設 10)
- 範例 / Example:
```bash
curl -s "https://duprapi.sportsbuddy.club/api/player/123/history?offset=0&limit=10"
```

錯誤處理 / Error Handling
- 若 DUPR 回應 4xx/5xx，系統可能回 `{ "error": "HTTP error 4xx/5xx", ... }` 並附帶上游 payload；HTTP 狀態多為 502 或 500。Upstream failures surface as error JSON with HTTP 502/500.
- 若參數缺漏，回 400：`{ "error": "Query parameter q is required" }` 等。

聯絡 / Contact
- 若需協助或擴充更多端點，請聯絡維運人員。For additional endpoints or support, contact the service maintainer.