zikai
25dbceee2d
死代码清理： - 删除未使用的 UI 组件 Card.vue / Tag.vue - 移除 app.config.js 死字段 healthTimeoutMs（×2）与 isDev() - 移除 PageShell.vue 死 prop padded（恒为默认值） - 移除 useLocale.js 死导出 isZh/pick/locale - 移除 router/index.js 不可达 try/catch，简化为直接 .map() - 移除 package.json 重复依赖 ical.js（子模块自带） - 移除 i18n 死键 common.notAvailable / common.serviceUnavailable - 移除 vite.config.js 陈旧的 /448 /449 dev proxy（z449 为构建期组件，不走该 URL） 提前失败/日志： - useI18nLazy.js switchLocale 加载语言包失败时 console.error 记录（原静默吞错） - modules/index.js 字段不全的模块跳过时 console.warn 告警（原与文档承诺不符、静默跳过） - deploy.sh 补齐 zWhiteBoard / zPDF_package 的 npm install 与子模块初始化 （均为构建期组件 import，全新检出时缺少依赖会构建失败） 文档对齐现状（无 iframe、无外部域名）： - README 改写为简洁版，修正 iframe/ical.js/子模块数量过时描述 - architecture.md 修正 requiresAlive 示例（同源 /api/health，非外部域名） 与「仅白板使用」断言（PDF 也用）；移除已删 padded prop - add-module.md 同步移除 padded、修正 requiresAlive 示例 - submodule-timeTableFix.md 修正 ical.js 归属（子模块自带，非父项目共享） - submodule-zPDF_package.md 子项目数量 3 -> 4 - 新增 submodule-zWhiteBoard.md - readme-fixes.md 记录本次勘误
3.3 KiB
3.3 KiB
子项目 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。
克隆（含子模块）
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，否则别人 clone mainPage 时拉不到子模块对应 commit。
移除子模块集成（仅移除 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） | 构建期组件 import（共享构建/KeepAlive） |
| 后端依赖 | 无（纯前端） | 有（zTools2 /api/pdf/*） |
| 同源/CORS | 不涉及 | 同源经反代，无需 CORS |
| cookie | 不涉及 | httpOnly zk_pdf，同源自动携带（首次上传种下） |
| mainPage 是否编译子模块 | 是（import .vue） | 是（import .vue） |
四个子项目（timeTableFix / z449 / zPDF_package / zWhiteBoard）均采用构建期组件 import 集成，无 iframe。zPDF_package 与 zWhiteBoard 额外依赖 zTools2 后端 API，页签带存活探针。