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 部署说明
2026-07-28 11:12:37 +08:00
parent cfbf4ad2b4
commit 25bc00ac51
10 changed files with 71 additions and 35 deletions
--- 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
--- a/docs/error-handling.md
+++ 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]` 前缀的日志来自本子项目，便于嵌入宿主时与宿主日志区分。
--- a/docs/integration.md
+++ 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`。
--- 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) {
+  try {
    await api.remove(job.id)
    await refresh()
+  } catch (e) {
+    console.error('[zPDF] 删除任务失败', e)
+    loadError.value = String(e.message || e)
+  }
 }

 onUnmounted(() => {
--- 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)">
--- 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 }
 }
--- 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 {
--- 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)',
--- 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} 个任务',
--- 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', () => {