skytek_xinliang
e90d412956
Document new GUIDE.md expectations for src-layer edits and add index entries for models and shared types. Clarify layout usage, composable placement, error page conventions, and model/type ownership so future changes follow the intended layer boundaries.docs: update LLM guides for models and layout rules Document new GUIDE.md expectations for src-layer edits and add index entries for models and shared types. Clarify layout usage, composable placement, error page conventions, and model/type ownership so future changes follow the intended layer boundaries.
1.4 KiB
1.4 KiB
Services Guide
services 是 HTTP 與外部 API 邊界。service 回傳資料，不持有 UI 狀態。
資料流
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：kybeforeErrorhook，將 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 重寫。