# 错误处理与日志约定

zPDF_package 的错误处理分两层：API 客户端 fail-fast（抛错），UI 层捕获后既写控制台又给用户反馈。

## API 客户端（src/composables/usePdfApi.js）

- `load` / `getJob` / `remove`：fetch 不可用抛 `fetch unavailable`；非 2xx 抛 `HTTP <status>`。
- `uploadFile`：XHR 不可用抛 `XMLHttpRequest unavailable`；网络错误 reject `network error`；响应非 200 时解析 `detail` 字段，无则 `HTTP <status>`。
- `pollPending`：单个任务查询失败不中断整体轮询，但 `console.warn` 记录（避免持久故障完全不可见）。
- `downloadUrl`：纯函数，无副作用。

## UI 层（src/App.vue, src/components/）

- `refresh()` 失败：捕获写入 `loadError`，JobList 显示「加载失败」。
- `onDelete()` 失败：`console.error` 记录 + 写入 `loadError` 提示用户。
- `Uploader.handle()` 失败：捕获写入 `errMsg` 显示。
- `validateFile` 返回 i18n key（非抛错），由 `onUpload` 翻译后抛 `Error(t(key))` 交给 Uploader 显示。

## 控制台前缀

所有 `[zPDF]` 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。