feat: 新增 PDF 转换页签（iframe 嵌入 zTools2 /pdf，zPDF_package 子模块）

mainPage 用 iframe 嵌入 zTools2 同源托管的 /pdf 页面（PDF 转换：上传 epub、
进度显示、下载、用户软删/管理员硬删）。同源使 cookie 第一方生效，无需 CORS。

- src/modules/pdf/：页签模块（requiresAlive 存活校验 + iframe + 降级提示）
- src/config/app.config.js：新增 pdf 服务配置（baseUrl/healthPath/pagePath）
- i18n：tabs.pdf 中英文案 + pdf.openExternal
- third_party/zPDF_package：git submodule（源码管理，iframe 集成非构建期编译）
- docs/submodule-zPDF_package.md：集成/升级/移除文档
- README：更新结构、子模块列表、文档链接

src/config/app.config.js

@@ -15,6 +15,17 @@ export const appConfig = {
     defaultBoardId: 'share',
     // 探测超时（毫秒）
     healthTimeoutMs: 4000
+  },
+  // PDF 转换服务（zTools2 托管的 /pdf 页面，iframe 同源嵌入）
+  pdf: {
+    // 服务根地址（含协议与域名）
+    baseUrl: 'https://f.zikai.wang',
+    // 存活探针路径；周期探测，挂掉则隐藏页签并卸载组件
+    healthPath: '/health',
+    // PDF 转换页面路径
+    pagePath: '/pdf',
+    // 探测超时（毫秒）
+    healthTimeoutMs: 4000
   }
 }
 

src/i18n/locales/en.js

@@ -13,12 +13,16 @@ export default {
     mobileGame: 'Mobile Game Project',
     calendar: 'CQY Timetable',
     whiteboard: 'Shared Notepad',
-    timetable: 'Schedule Organizer'
+    timetable: 'Schedule Organizer',
+    pdf: 'PDF Converter'
   },
   whiteboard: {
     openExternal: 'Open in new tab',
     boardId: 'Board ID',
     switch: 'Switch'
+  },
+  pdf: {
+    openExternal: 'Open in new tab'
   }
   // Mobile-game copy is provided by the z449 submodule's own i18n;
   // mainPage keeps only tabs.mobileGame. Locale syncs to z449 via :locale prop.

src/i18n/locales/zh-CN.js

@@ -12,12 +12,16 @@ export default {
     mobileGame: '移动游戏项目',
     calendar: 'cqy课程表',
     whiteboard: '共享记事本',
-    timetable: '日程整理'
+    timetable: '日程整理',
+    pdf: 'PDF 转换'
   },
   whiteboard: {
     openExternal: '在新标签页打开',
     boardId: '白板 ID',
     switch: '切换'
+  },
+  pdf: {
+    openExternal: '在新标签页打开'
   }
   // 注：移动游戏项目（mobile-game）的文案由子模块 z449 自有 i18n 提供，
   // mainPage 仅保留 tabs.mobileGame 页签标题。切换语言时经 :locale prop 同步给 z449。

src/modules/pdf/Pdf.vue

@@ -0,0 +1,140 @@
+<script setup>
+import { ref, computed, watch } from 'vue'
+// 组件名与模块 id 一致，供 <KeepAlive :include> 按 id 精确匹配；
+// PDF 服务后端失活时把它从 include 移除即可卸载组件
+defineOptions({ name: 'pdf' })
+import { appConfig, healthUrl } from '../../config/app.config.js'
+import { useLocale } from '../../composables/useLocale.js'
+import { getLiveness } from '../../composables/useLiveness.js'
+import PageShell from '../../components/ui/PageShell.vue'
+
+const { t } = useLocale()
+
+const pdfConfig = appConfig.pdf
+
+// 完整 PDF 转换页 URL（zTools2 同源托管，可被 iframe 嵌入）
+const pageSrc = computed(() => `${pdfConfig.baseUrl}${pdfConfig.pagePath}`)
+
+// 存活态：服务挂掉时显示降级提示（页签本身也已隐藏，但用户若直链进入仍可见）
+const aliveState = getLiveness(healthUrl('pdf'))
+const isDown = computed(() => aliveState.value === 'down')
+
+const loaded = ref(false)
+const failed = ref(false)
+
+function onLoad() {
+  loaded.value = true
+}
+function scheduleFailCheck() {
+  setTimeout(() => {
+    if (!loaded.value) failed.value = true
+  }, 6000)
+}
+scheduleFailCheck()
+
+function openExternal() {
+  window.open(pageSrc.value, '_blank', 'noopener')
+}
+</script>
+
+<template>
+  <PageShell title-key="tabs.pdf">
+    <!-- 服务不可达 / iframe 加载超时降级 -->
+    <div v-if="isDown || failed" class="pdf-fallback">
+      <p class="pdf-fallback__text">{{ t('common.serviceUnavailable') }}</p>
+      <button type="button" class="pdf-fallback__open" @click="openExternal">
+        {{ t('pdf.openExternal') }}
+      </button>
+    </div>
+
+    <div v-else class="pdf-frame">
+      <!-- 加载骨架（iframe 加载完成后淡出） -->
+      <Transition name="fade">
+        <div v-if="!loaded" class="pdf-frame__skeleton">
+          <div class="pdf-frame__skeleton-text">{{ t('common.loading') }}</div>
+        </div>
+      </Transition>
+      <iframe
+        :src="pageSrc"
+        class="pdf-frame__iframe"
+        frameborder="0"
+        :title="t('tabs.pdf')"
+        @load="onLoad"
+      />
+    </div>
+  </PageShell>
+</template>
+
+<style scoped>
+.pdf-frame {
+  position: relative;
+  border-radius: var(--radius);
+  overflow: hidden;
+  box-shadow: var(--shadow);
+  border: 1px solid var(--border);
+  width: 100%;
+  /* 转换页以上传与列表为主，给足高度 */
+  height: 78vh;
+  min-height: 520px;
+  background: var(--surface);
+}
+.pdf-frame__iframe {
+  width: 100%;
+  height: 100%;
+  display: block;
+  border: 0;
+}
+.pdf-frame__skeleton {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--surface);
+}
+.pdf-frame__skeleton-text {
+  color: var(--text-tertiary);
+  font-size: 0.95rem;
+}
+.pdf-fallback {
+  text-align: center;
+  padding: var(--space-2xl) var(--space-lg);
+  border: 1px dashed var(--border-strong);
+  border-radius: var(--radius);
+  background: var(--surface);
+}
+.pdf-fallback__text {
+  color: var(--text-secondary);
+  margin-bottom: var(--space-md);
+}
+.pdf-fallback__open {
+  display: inline-flex;
+  align-items: center;
+  padding: 8px 18px;
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: #fff;
+  background: var(--accent);
+  border-radius: var(--radius-sm);
+  transition: background var(--transition);
+}
+.pdf-fallback__open:hover {
+  background: var(--accent-hover);
+}
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.4s ease;
+}
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+
+@media (max-width: 768px) {
+  .pdf-frame {
+    height: 72vh;
+    min-height: 400px;
+  }
+}
+</style>

src/modules/pdf/index.js

@@ -0,0 +1,15 @@
+// 模块元数据 -- PDF 转换页签
+// requiresAlive 指向存活探针 URL：启动时探测，zTools2 不可达则隐藏该页签。
+// 页面用 iframe 嵌入 zTools2 托管的 /pdf（同源，cookie 第一方生效，无需 CORS）。
+// 删除本目录即可移除此页签，其余模块不受影响。
+import { healthUrl } from '../../config/app.config.js'
+
+export default {
+  id: 'pdf',
+  tabKey: 'tabs.pdf',
+  order: 4,
+  // 存活探针 URL；useProjects 启动时探测一次，挂掉则不显示页签
+  requiresAlive: healthUrl('pdf'),
+  // 懒加载组件 -> 独立 chunk
+  component: () => import('./Pdf.vue')
+}