zikai
ae540a1a70
前后端分离：UI/交互在 zPDF_package，能力由 zTools2 的 /api/pdf/* REST API 提供。
组件经同源 fetch 调用，httpOnly cookie（zk_pdf）经反代第一方自动携带，无需 CORS。
与 timeTableFix 集成范式完全一致。
- src/modules/pdf/Pdf.vue：iframe 包装器重写为组件挂载包装器，套 PageShell +
透传 :locale；删除 pageSrc/getLiveness/scheduleFailCheck/openExternal 等 iframe 逻辑
- src/modules/pdf/index.js：注释从 iframe 改为构建期组件 import（requiresAlive 探针保留）
- src/config/app.config.js：移除 pdf.pagePath（iframe src），保留探针配置
- src/i18n/{zh-CN,en}.js：移除 pdf.openExternal（iframe 降级按钮文案，已无用）
- docs/submodule-zPDF_package.md：集成方式改为构建期组件 import，补 cookie 认证说明
- docs/deployment.md：拓扑去 /api/pdf 页面行，措辞改为组件 fetch
- third_party/zPDF_package：子模块指针升级到 4d12b61（去 iframe 表述）
65 lines
3.2 KiB
Markdown
65 lines
3.2 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` 包装器 import 子模块的 `src/App.vue` 作为组件，套 `PageShell` 统一容器与标题，并持有 KeepAlive 匹配名 `defineOptions({ name: 'pdf' })`。
|
||
|
||
- 子模块 `App.vue` 保持纯净（不持 name、不依赖宿主），可独立 `npm run build` / `npm test` / 部署。
|
||
- **构建期集成（非 iframe）**，共享 mainPage 的构建与 KeepAlive 缓存。前后端分离：UI/交互在 zPDF_package，能力由 zTools2 的 `/api/pdf/*` REST API 提供。
|
||
- 子模块样式已隔离（scoped + `zpdf-` 前缀类名），全局重置仅在独立 app 的 `main.js` 加载，不污染宿主。
|
||
- 页签带 `requiresAlive: healthUrl('pdf')`，zTools2 不可达时隐藏页签并卸载组件。
|
||
- **认证**：用户身份凭 httpOnly cookie（`zk_pdf`，samesite=lax）标识。该 cookie 在首次 `POST /api/pdf/jobs`（上传）的响应里种下，与页面路由无关。组件经同源 fetch 调用 `/api/pdf/*`，反代使 `/api/` 与主页同源，cookie 自动携带，无需 CORS。
|
||
|
||
## 克隆（含子模块）
|
||
|
||
```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，否则别人 clone mainPage 时拉不到子模块对应 commit。
|
||
|
||
## 移除子模块集成（仅移除 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） | 构建期组件 import（共享构建/KeepAlive） |
|
||
| 后端依赖 | 无（纯前端） | 有（zTools2 `/api/pdf/*`） |
|
||
| 同源/CORS | 不涉及 | 同源经反代，无需 CORS |
|
||
| cookie | 不涉及 | httpOnly `zk_pdf`，同源自动携带（首次上传种下） |
|
||
| mainPage 是否编译子模块 | 是（import .vue） | 是（import .vue） |
|
||
|
||
> 三个子项目（timeTableFix / z449 / zPDF_package）均采用构建期组件 import 集成，无 iframe。zPDF_package 额外依赖 zTools2 后端 API，页签带存活探针。
|