# TGOS 門牌定位 API 申請與設定

Delivery Radar 的地址搜尋（`GET /api/geocode/forward`）支援兩種來源：

1. **TGOS**（內政部全國門牌地址定位服務）— 有設定時**優先**使用，可精確到門牌
2. **Nominatim / OpenStreetMap** — 未設定 TGOS 時使用，台灣門牌常只能定位到路段

程式邏輯見 `backend/src/Controllers/GeocodeController.php` 的 `geocodeWithFallback()`：

```57:62:backend/src/Controllers/GeocodeController.php
    private function geocodeWithFallback(string $address): ?array
    {
        $tgos = $this->searchTgos($address);
        if ($tgos !== null) {
            return $tgos;
        }
```

---

## 一、申請 TGOS API

### 1. 前往申請網站

- 全國門牌地址定位服務：https://addr.tgos.tw/
- TGOS 開發者文件：https://api.tgos.tw/TGOS_MAP_API/docs/site/android/AddrLocate

### 2. 註冊帳號

使用真實資料註冊 TGOS 會員帳號（個人或單位皆可，依網站流程填寫）。

### 3. 申請「門牌地址定位服務」

在 TGOS 服務申請頁面，申請 **地址定位 / QueryAddr** 服務，填寫：

| 欄位 | 建議填寫 |
|------|----------|
| 應用程式名稱 | Delivery Radar |
| 用途說明 | 外送員查詢送餐地址附近雷區回報 |
| 網域 / 來源 | 你的網站網址（開發階段可填 `http://localhost:5173`） |

審核通過後會取得：

- **APPId**（`oAPPId`）
- **APIKey**（`oAPIKey`）

### 4. 使用額度（參考）

依內政部公開說明，門牌比對服務有每日查詢筆數限制（約每日 10,000 筆，實際以 TGOS 後台公告為準）。外送查詢場景通常足夠，但仍請避免短時間大量重複請求。

---

## 二、專案設定

### 1. 編輯 `backend/.env`

加入以下兩行（將值換成你申請到的金鑰）：

```env
TGOS_APP_ID=你的AppId
TGOS_API_KEY=你的ApiKey
```

`.env.example` 已預留相同欄位供參考。

### 2. 重啟後端

修改 `.env` 後需重啟 PHP / Docker 容器，環境變數才會生效。

### 3. 測試 API

瀏覽器或 curl 測試（請替換為你的後端網址）：

```
GET /api/geocode/forward?q=臺北市中山區德惠街19號
```

**成功（TGOS）** 回應範例：

```json
{
  "success": true,
  "data": {
    "latitude": 25.0668,
    "longitude": 121.5224,
    "display_name": "臺北市中山區德惠街19號",
    "match_level": "exact",
    "match_note": null
  }
}
```

**Fallback（Nominatim 路段）** 會出現：

```json
{
  "match_level": "street",
  "match_note": "門牌無法精確對應，已定位至路段附近"
}
```

---

## 三、前端顯示

`AddressSearchBar.vue` 會在 `match_note` 有值時顯示黃色提示，告知使用者目前為路段近似定位。

---

## 四、常見問題

### Q1：設定了 TGOS 還是顯示路段提示？

可能原因：

- `TGOS_APP_ID` / `TGOS_API_KEY` 填錯或未重啟後端
- 該門牌在 TGOS 資料庫中不存在
- 伺服器無法對外連線 `addr.tgos.tw`（防火牆 / Docker 網路）

此時會自動 fallback 到 Nominatim。

### Q2：臺 / 台 有差嗎？

程式會自動將「臺」轉為「台」再查詢，兩種寫法皆可。

### Q3：需要把金鑰提交到 Git 嗎？

**不要。** 只放在 `backend/.env`，並確認 `.env` 已在 `.gitignore` 中。

### Q4：開發環境沒申請 TGOS 能用嗎？

可以。未設定時使用 Nominatim + 路段 fallback，例如「臺北市中山區德惠街19號」會定位到德惠街附近。

---

## 五、官方 API 參考

TGOS QueryAddr 端點：

```
https://addr.tgos.tw/addrws/v30/QueryAddr.asmx/QueryAddr
```

本專案已依官方建議設定模糊比對參數（`oFuzzyType=0` 等），見 `searchTgos()`：

```188:207:backend/src/Controllers/GeocodeController.php
        $params = http_build_query([
            'oAPPId' => $appId,
            'oAPIKey' => $apiKey,
            'oAddress' => $address,
            'oSRS' => 'EPSG:4326',
            'oFuzzyType' => 0,
            ...
        ]);

        $url = 'https://addr.tgos.tw/addrws/v30/QueryAddr.asmx/QueryAddr?' . $params;
```

座標系統使用 **EPSG:4326（WGS84）**，與 Leaflet 地圖相容。