zikai
04f11b5432
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：更新结构、子模块列表、文档链接
63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
# 子项目 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 集成，非构建期组件集成）。
|
||
|
||
## 克隆（含子模块）
|
||
|
||
```bash
|
||
git clone --recursive https://git.zikai.wang/zikai/zMainPage.git mainPage
|
||
```
|
||
|
||
若已 clone 但未带子模块：
|
||
|
||
```bash
|
||
cd mainPage
|
||
git submodule update --init --recursive
|
||
```
|
||
|
||
## 升级子模块到最新版本
|
||
|
||
```bash
|
||
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 本身）
|
||
|
||
```bash
|
||
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`。
|