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:更新结构、子模块列表、文档链接
This commit is contained in:
2026-07-27 11:35:28 +08:00
parent 3e5c1d5494
commit 04f11b5432
9 changed files with 246 additions and 3 deletions

View File

@@ -0,0 +1,62 @@
# 子项目 zPDF_packagegit submodule
zPDF_packagePDF 转换前端)作为 **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 同源嵌入**(非组件 importPDF 转换有后端依赖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 # 推送 mainPagegitlink
```
> 推送顺序:先确保子模块的 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 管理源码,便于独立开发/测试/升级;其构建产物部署到 zTools2mainPage 经 iframe 引用 zTools2 的 `/pdf`。