zMainPage/docs/submodule-zPDF_package.md

子项目 zPDF_package（git submodule）

zPDF_package（PDF 转换前端）作为 git submodule 被 mainPage 引入，位于 third_party/zPDF_package，独立仓库为 https://git.zikai.wang/zikai/zPDF_package.git 。

集成方式

mainPage 侧的 src/modules/pdf/Pdf.vue 用 iframe 嵌入 zTools2 托管的 /pdf 页面（https://f.zikai.wang/pdf），套 PageShell 统一容器与标题，并持有 KeepAlive 匹配名 defineOptions({ name: 'pdf' })。

• iframe 同源嵌入（非组件 import）：PDF 转换有后端依赖（zTools2 的 /api/pdf/*），iframe 嵌入使页面与 API 同源（均在 f.zikai.wang），用户 cookie（zk_pdf）第一方自然生效，无需给 zTools2 加 CORS，不受第三方 cookie 限制。与白板页签的嵌入方式一致。
• 页签带 requiresAlive: healthUrl('pdf')，zTools2 不可达时隐藏页签并卸载组件；直链进入则显示降级提示与「在新标签页打开」。
• zPDF_package 源码作为 submodule 管理，其 npm run build 产物部署到 zTools2 托管。mainPage 构建不编译子模块（iframe 集成，非构建期组件集成）。

克隆（含子模块）

git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage

若已 clone 但未带子模块：

cd mainPage
git submodule update --init --recursive

升级子模块到最新版本

cd mainPage
git submodule update --remote third_party/zPDF_package      # 拉取最新
cd third_party/zPDF_package && git checkout master           # 固定到目标分支/commit
cd ../..
git add third_party/zPDF_package                             # 更新 gitlink 指针
git commit -m "chore: 升级 zPDF_package 子模块"
npm run build                                                # 重新构建 mainPage
git push                                                     # 推送 mainPage（gitlink）

推送顺序：先确保子模块的 commit 已推到 zPDF_package.git，再推 mainPage 的 gitlink。

移除子模块集成（仅移除 mainPage 页签，不影响 zPDF_package 本身）

cd mainPage
git submodule deinit -f third_party/zPDF_package
git rm third_party/zPDF_package
git commit -m "chore: 移除 zPDF_package 子模块集成"

同时删 src/modules/pdf/ 文件夹即移除页签。zPDF_package 独立仓库不受影响。

与其他子模块的差异

维度	timeTableFix / z449	zPDF_package
集成方式	构建期组件 import（共享构建/KeepAlive）	iframe 嵌入 zTools2 托管页
后端依赖	无（纯前端）	有（zTools2 /api/pdf/*）
同源/CORS	不涉及	同源（f.zikai.wang），无需 CORS
cookie	不涉及	第一方 httpOnly cookie 自然生效
mainPage 是否编译子模块	是（import .vue）	否（iframe）

zPDF_package 仍作为 submodule 管理源码，便于独立开发/测试/升级；其构建产物部署到 zTools2，mainPage 经 iframe 引用 zTools2 的 /pdf。