> ## Documentation Index
> Fetch the complete documentation index at: https://solarium-1f74f072.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API 參考

> FastAPI 後端 REST API 總覽與互動式測試

後端正式環境：`https://solarmoney.up.railway.app`。本地開發為 `http://localhost:8000`。

本節左側導覽列出可互動測試的端點頁面。Playground 預設使用 **Production** server；在本機預覽且後端跑在本機時，請改選 **Local development**。

## 快速開始

1. 在任一端點頁面確認 Server 為 **Production**（`https://solarmoney.up.railway.app`）。
2. 按 **Send** 測試（例如 [GET /healthz](/api-reference/health/health) 應回傳 `{"status":"ok"}`）。
3. 需登入的端點（`/api/me/*`）請先呼叫 **POST /api/auth/login** 取得 JWT，再在 playground 的 **Authorization** 欄位貼上 token。

<Note>
  本機開發時請啟動後端（見[安裝指南](/developer-guide/installation)），並將 Server 改為 **Local development**。FastAPI Swagger UI：`http://localhost:8000/docs`。
</Note>

## 端點分類

| 分類                    | 說明                            |
| --------------------- | ----------------------------- |
| **Health**            | 服務健康檢查                        |
| **Buildings**         | 建物查詢（GBA DB → fallback → OSM） |
| **Shadows**           | 陰影幾何、可裝設面積、預計算快取              |
| **Terrain & Climate** | DEM tile、鄉鎮氣候、最佳傾角            |
| **Assessments**       | 匿名評估紀錄                        |
| **Authentication**    | 註冊與登入                         |
| **User Account**      | 登入後的評估、詢價（需 JWT）              |
| **Vendors**           | 廠商列表、入駐、詢價                    |

## 認證方式

| 方式                                               | 適用端點                |
| ------------------------------------------------ | ------------------- |
| 無                                                | 多數公開查詢（建物、氣候、廠商列表等） |
| `Authorization: Bearer <JWT>`                    | `/api/me/*`         |
| `Authorization: Bearer <JWT>` 或 `X-Admin-Secret` | `/api/admin/*`      |

## Playground 如何運作

Playground 請求預設經 Mintlify proxy 轉發（`proxy: true`），以避免瀏覽器 CORS 限制。若要在後端直接接受瀏覽器請求，請在 Railway 的 `CORS_ORIGINS` 加入文件站網址（例如 `http://localhost:3333`、你的 Mintlify 網域）。

| 情境                 | 要選的 Server                              | 必要條件                  |
| ------------------ | --------------------------------------- | --------------------- |
| 本機預覽文件（`mint dev`） | `https://solarmoney.up.railway.app`（預設） | 可直接測試正式後端；若要連本機後端，見下方 |

<Warning>
  Playground 預設連線至 `https://solarmoney.up.railway.app`。若仍看到 `localhost`，代表文件站尚未部署最新的 `docs/openapi.json`。
</Warning>

### 本機後端測試（選用）

若要改測本機後端，重新匯出 OpenAPI 並加入 localhost server：

```bash theme={null}
DOCS_INCLUDE_LOCAL=1 python scripts/export_openapi.py
```

然後啟動本機後端與 `mint dev`。

## 更新 OpenAPI 規格

端點變更後，在專案根目錄執行：

```bash theme={null}
python scripts/export_openapi.py
```

會重新產生 `docs/openapi.json`（預設含 Production：`https://solarmoney.up.railway.app`）。