From 25bc00ac5188741efec6c0bd965d83e7a7fb6b2b Mon Sep 17 00:00:00 2001
From: zikai <1621362626@qq.com>
Date: Tue, 28 Jul 2026 11:12:37 +0800
Subject: [PATCH] =?UTF-8?q?refactor:=20=E6=B8=85=E7=90=86=E6=AD=BB?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=20+=20=E6=8F=90=E5=89=8D=E5=A4=B1=E8=B4=A5?=
 =?UTF-8?q?=20+=20=E9=94=99=E8=AF=AF=E8=AE=B0=E5=BD=95=E6=8E=A7=E5=88=B6?=
 =?UTF-8?q?=E5=8F=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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                    | 11 ++++++-----
 docs/error-handling.md       | 21 +++++++++++++++++++++
 docs/integration.md          | 19 +++++++++++++++++++
 src/App.vue                  | 12 ++++++++----
 src/components/JobList.vue   |  5 ++---
 src/composables/useLocale.js |  5 +----
 src/composables/usePdfApi.js | 17 ++++++++++-------
 src/i18n/locales/en.js       |  6 +-----
 src/i18n/locales/zh-CN.js    |  6 +-----
 test/usePdfApi.test.js       |  4 ++--
 10 files changed, 71 insertions(+), 35 deletions(-)
 create mode 100644 docs/error-handling.md
 create mode 100644 docs/integration.md

diff --git a/README.md b/README.md
index 6df0f00..77bd182 100644
--- a/README.md
+++ b/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
diff --git a/docs/error-handling.md b/docs/error-handling.md
new file mode 100644
index 0000000..f0c08e2
--- /dev/null
+++ b/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]` 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。
diff --git a/docs/integration.md b/docs/integration.md
new file mode 100644
index 0000000..b3ca24a
--- /dev/null
+++ b/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`。
diff --git a/src/App.vue b/src/App.vue
index 6a57ee4..e80a264 100644
--- a/src/App.vue
+++ b/src/App.vue
@@ -1,5 +1,5 @@
 <script setup>
-import { ref, onUnmounted } from 'vue'
+import { ref, watch, onUnmounted } from 'vue'
 import { usePdfApi, validateFile, uploadFile } from './composables/usePdfApi.js'
 import { useLocale } from './composables/useLocale.js'
 import { loadLocaleAsync } from './i18n/index.js'
@@ -14,7 +14,6 @@ const { t } = useLocale()
 const api = usePdfApi()
 
 // 跟随父项目语言开关切换本子项目 i18n 实例的 locale
-import { watch } from 'vue'
 watch(
   () => props.locale,
   (val) => {
@@ -67,8 +66,13 @@ async function onUpload(file, onProgress) {
 }
 
 async function onDelete(job) {
-  await api.remove(job.id)
-  await refresh()
+  try {
+    await api.remove(job.id)
+    await refresh()
+  } catch (e) {
+    console.error('[zPDF] 删除任务失败', e)
+    loadError.value = String(e.message || e)
+  }
 }
 
 onUnmounted(() => {
diff --git a/src/components/JobList.vue b/src/components/JobList.vue
index ad01e71..b5ab5be 100644
--- a/src/components/JobList.vue
+++ b/src/components/JobList.vue
@@ -1,6 +1,6 @@
 <script setup>
 import { useLocale } from '../composables/useLocale.js'
-import { usePdfApi, fmtBytes } from '../composables/usePdfApi.js'
+import { downloadUrl, fmtBytes } from '../composables/usePdfApi.js'
 
 const props = defineProps({
   items: { type: Array, default: () => [] },
@@ -11,7 +11,6 @@ const props = defineProps({
 
 const emit = defineEmits(['refresh', 'delete'])
 const { t } = useLocale()
-const api = usePdfApi()
 
 function statusText(job) {
   if (job.status === 'done') return t('job.statusDone')
@@ -83,7 +82,7 @@ function onDelete(job) {
             <a
               v-if="j.status === 'done'"
               class="zpdf-btn zpdf-btn--primary zpdf-btn--sm"
-              :href="api.downloadUrl(j.id)"
+              :href="downloadUrl(j.id)"
               download
             >{{ t('job.download') }}</a>
             <button class="zpdf-btn zpdf-btn--danger zpdf-btn--sm" @click="onDelete(j)">
diff --git a/src/composables/useLocale.js b/src/composables/useLocale.js
index 58b43c3..390caa9 100644
--- a/src/composables/useLocale.js
+++ b/src/composables/useLocale.js
@@ -1,4 +1,3 @@
-import { computed } from 'vue'
 import i18n from '../i18n/index.js'
 
 // ★ 子项目自有的语言辅助 composable。
@@ -8,7 +7,5 @@ import i18n from '../i18n/index.js'
 // 改为直接引用本子项目实例的 .global，无论是否 app.use() 都拿到本子项目的 t。
 export function useLocale() {
   const { t, locale } = i18n.global
-  const isZh = computed(() => locale.value === 'zh-CN')
-  const pick = (obj) => (isZh.value ? obj.zh : obj.en)
-  return { t, locale, isZh, pick }
+  return { t, locale }
 }
diff --git a/src/composables/usePdfApi.js b/src/composables/usePdfApi.js
index d93b7ad..d968fb5 100644
--- a/src/composables/usePdfApi.js
+++ b/src/composables/usePdfApi.js
@@ -17,6 +17,11 @@ export function isTerminal(job) {
   return !!job && (job.status === 'done' || job.status === 'failed')
 }
 
+/** 产物下载 URL（纯函数，供组件直接 import）。 */
+export function downloadUrl(id) {
+  return `/api/pdf/jobs/${id}/download`
+}
+
 /** 格式化字节为人类可读（供组件与测试复用）。 */
 export function fmtBytes(n) {
   const x = Number(n)
@@ -70,10 +75,6 @@ export function createPdfApi(opts = {}) {
     return res.json()
   }
 
-  function downloadUrl(id) {
-    return `/api/pdf/jobs/${id}/download`
-  }
-
   /**
    * 轮询未完成任务直至全部终态。每次拉取后调 onUpdate(freshItems)，全部终态后调 onDone()。
    * 返回 stop 函数，可提前停止（如组件卸载）。
@@ -95,8 +96,9 @@ export function createPdfApi(opts = {}) {
       for (const id of pendingIds) {
         try {
           fresh.push(await getJob(id))
-        } catch {
-          // 单个查询失败不中断整体轮询
+        } catch (e) {
+          // 单个查询失败不中断整体轮询, 但记录便于排查持久故障
+          console.warn('[zPDF] 轮询单任务失败', id, e)
           fresh.push(items.find((j) => j.id === id))
         }
       }
@@ -120,7 +122,7 @@ export function createPdfApi(opts = {}) {
     return stop
   }
 
-  return { load, getJob, remove, downloadUrl, pollPending }
+  return { load, remove, pollPending }
 }
 
 /**
@@ -156,6 +158,7 @@ export function uploadFile(file, onProgress, opts = {}) {
         try {
           resolve(JSON.parse(xhr.responseText))
         } catch (e) {
+          console.error('[zPDF] 解析上传响应失败', e)
           reject(new Error('bad response'))
         }
       } else {
diff --git a/src/i18n/locales/en.js b/src/i18n/locales/en.js
index 400db78..0953845 100644
--- a/src/i18n/locales/en.js
+++ b/src/i18n/locales/en.js
@@ -9,11 +9,7 @@ export default {
     pick: 'click to choose',
     limit: 'Only epub, up to 250MB',
     requireEpub: 'Only epub files are supported',
-    oversize: 'File exceeds the 250MB limit',
-    uploading: 'Uploading…',
-    submitted: 'Submitted, converting…',
-    failed: 'Upload failed',
-    networkError: 'Network error'
+    oversize: 'File exceeds the 250MB limit'
   },
   list: {
     count: '{total} task(s)',
diff --git a/src/i18n/locales/zh-CN.js b/src/i18n/locales/zh-CN.js
index 312f4e9..00bb011 100644
--- a/src/i18n/locales/zh-CN.js
+++ b/src/i18n/locales/zh-CN.js
@@ -8,11 +8,7 @@ export default {
     pick: '点击选择文件',
     limit: '仅支持 epub，最大 250MB',
     requireEpub: '仅支持 epub 文件',
-    oversize: '文件超过 250MB 上限',
-    uploading: '上传中…',
-    submitted: '已提交，转换中…',
-    failed: '上传失败',
-    networkError: '网络错误'
+    oversize: '文件超过 250MB 上限'
   },
   list: {
     count: '共 {total} 个任务',
diff --git a/test/usePdfApi.test.js b/test/usePdfApi.test.js
index d334a1f..1992aee 100644
--- a/test/usePdfApi.test.js
+++ b/test/usePdfApi.test.js
@@ -6,6 +6,7 @@ import {
   fmtBytes,
   validateFile,
   uploadFile,
+  downloadUrl,
 } from '../src/composables/usePdfApi.js'
 
 describe('isTerminal', () => {
@@ -94,8 +95,7 @@ describe('createPdfApi', () => {
   })
 
   it('downloadUrl 生成路径', () => {
-    const api = createPdfApi({ fetch: vi.fn() })
-    expect(api.downloadUrl(3)).toBe('/api/pdf/jobs/3/download')
+    expect(downloadUrl(3)).toBe('/api/pdf/jobs/3/download')
   })
 
   it('pollPending 无未完成任务立即 onDone', () => {