# Services Guide

`services` 是 HTTP 與外部 API 邊界。service 回傳資料，不持有 UI 狀態。

## 資料流

```txt
component/view -> store/composable -> service module -> httpClient -> hooks
```

## 規則

- 新 API 放在 `services/modules/<domain>.ts`。
- 使用 `httpClient`，不要直接建立新的 ky instance。
- 不 import component、view 或 store。
- 不管理 loading、dialog、snackbar、AbortController lifecycle。
- request option 可接收 `signal`。
- 錯誤正規化交給既有 error/http hooks 流程。

## 錯誤處理體系

- `error.ts`：定義 `ApiRequestError`（正規化後的錯誤類別）、`CanceledRequestError`（取消請求）、`normalizeError()`（將 ky HTTPError / TimeoutError / DOMException 統一轉為 `ApiRequestError`）。
- `http-error.ts`：ky `beforeError` hook，將 response body 的錯誤訊息注入 error 物件。
- `http-toast.ts`：全域 HTTP error toast，依 status code 顯示對應 snackbar。

service module 不需要自行 catch 並處理錯誤，交由 interceptors/hooks 與上層 composable（如 `useApiCall`）處理。

## ky 注意事項

- 本專案使用 ky，不使用 axios。
- JSON response 用 `.json<T>()`。
- JSON payload 用 `json`，FormData 用 `body`。
- 取消請求使用原生 `AbortController` 與 `signal`。
- token 注入與 401 force logout 集中在 hooks，不在單一 API module 重寫。