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 部署说明

README.md

@@ -41,7 +41,7 @@ zPDF_package/
 | Node.js | ≥ 18 |
 | zTools2 | 后端 `/api/pdf/*`（同源调用，cookie 自动管理） |
 
-> 前端纯静态，无运行期后端依赖；API 由 zTools2 提供。
+> 前端纯静态，无运行期后端依赖；API 由 zTools2 提供。生产部署经 [zMainPage](https://git.zikai.wang/zikai/zMainPage) 作为子模块集成，由其 apache2 静态托管 + `/api` 反代到 zTools2（无独立 apache2 配置）。
 
 ## 如何使用
 
@@ -51,16 +51,16 @@ git clone https://git.zikai.wang/zikai/zPDF_package.git
 cd zPDF_package
 npm install        # 已配 npmmirror 镜像加速
 
-npm run dev        # 开发服务器 http://localhost:5173（需 zTools2 在同源或配置代理）
+npm run dev        # 开发服务器 http://localhost:5175（vite.config.js 已配 /api 代理到 zTools2:6867）
 npm run build      # 构建到 dist/
 npm test           # 单元测试（20 项）
 ```
 
-> 开发时 `/api/pdf/*` 需指向 zTools2。可配 Vite 代理；生产环境由 mainPage 同源反代到 zTools2，cookie 第一方生效。
+> 开发时 `/api/pdf/*` 由 vite 代理到本地 zTools2（127.0.0.1:6867）；生产环境由 mainPage 同源反代到 zTools2，cookie 第一方生效。
 
 ## 嵌入 mainPage
 
-作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule（`third_party/zPDF_package`），mainPage 在构建期直接 `import` 本项目的 `src/App.vue` 作为组件挂载（非 iframe，与 [timeTableFix](https://git.zikai.wang/zikai/timeTableFix) 同范式）：mainPage 侧 `src/modules/pdf/Pdf.vue` 套 `PageShell` 并透传 `:locale`；组件内 `usePdfApi.js` 同源 fetch `/api/pdf/*`，httpOnly cookie（`zk_pdf`）经反代第一方自动携带，无需 CORS。组件自身保持「无 host 依赖」：不持 `defineOptions({ name })`、不引 mainPage 的 i18n，仅靠 `:locale` prop 驱动自有 i18n 实例。详见 mainPage 的 `docs/submodule-zPDF_package.md`。
+作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule，经构建期组件 import 集成（非 iframe）。详见 [`docs/integration.md`](./docs/integration.md)。
 
 ## 技术栈
 
@@ -75,5 +75,6 @@ npm test           # 单元测试（20 项）
 
 ## 了解更多
 
-- [嵌入 mainPage（构建期组件 import）](../zMainPage/docs/submodule-zPDF_package.md)
+- [嵌入 mainPage（构建期组件 import）](./docs/integration.md)
+- [错误处理与日志约定](./docs/error-handling.md)
 - 后端 API 与转换实现见 [zTools2](https://git.zikai.wang/zikai/zTools2) README