refactor: 清理死代码 + 提前失败 + 错误记录控制台

- downloadUrl 提升为顶层纯函数导出, JobList 不再为此实例化整个 api 对象
- createPdfApi 返回对象移除内部用的 getJob / downloadUrl (高内聚)
- useLocale 移除未用的 isZh/pick 返回值
- 移除 4 个死 i18n key (upload.uploading/submitted/failed/networkError)
- App.vue: import {watch} 提升至顶部; onDelete 补 try/catch + console.error
- usePdfApi: pollPending 单任务失败补 console.warn; uploadFile 响应解析失败补 console.error
- docs: 新增 error-handling.md / integration.md (嵌入细节从 README 移入)
- README: 修正 dev 端口 5173->5175; 补 apache2 部署说明

docs/error-handling.md

@@ -0,0 +1,21 @@
+# 错误处理与日志约定
+
+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]` 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。

docs/integration.md

@@ -0,0 +1,19 @@
+# 嵌入 mainPage
+
+zPDF_package 作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule（`third_party/zPDF_package`），经构建期组件 import 集成（非 iframe，与 timeTableFix 同范式）。
+
+## 集成方式
+
+- mainPage 侧 `src/modules/pdf/Pdf.vue` 套 `PageShell` 并透传 `:locale`。
+- 构建期直接 `import` 本项目 `src/App.vue`，共享 mainPage 的构建与 KeepAlive 缓存。
+- 组件内 `usePdfApi.js` 同源 fetch `/api/pdf/*`，httpOnly cookie（`zk_pdf`）经反代第一方自动携带，无需 CORS。
+
+## 便携式设计（无 host 依赖）
+
+组件自身保持「无 host 依赖」：
+
+- 不持 `defineOptions({ name })`（避免与宿主组件名冲突）。
+- 不引 mainPage 的 i18n，仅靠 `:locale` prop 驱动自有 i18n 实例。
+- `useLocale` 直接读本子项目模块级 `i18n.global`，而非 `useI18n()`（后者嵌入时会解析到宿主实例，文案回退成 key）。
+
+详见 mainPage 的 `docs/submodule-zPDF_package.md`。