zPDF_package/README.md

zPDF_package - PDF 转换前端

上传 epub 文件转为 PDF，显示转换进度，完成后下载。复用 zTools2 后端 API（/api/pdf/*）。便携式组件，可独立运行，亦可作为 mainPage 的子模块经 iframe 集成展示。

功能

• 上传 epub（拖拽/选择，≤250MB，客户端预校验 + 服务端校验）
• 上传进度显示
• 转换进度轮询（pending/converting -> done/failed）
• 完成后下载 PDF
• 用户软删（不再对自己展示；管理员仍可见，需管理员硬删才真正删除）
• 凭浏览器 cookie（zk_pdf，httpOnly）标识用户、记住任务

项目结构

zPDF_package/
├── index.html                  Vite 入口
├── package.json
├── vite.config.js              base:'./' 便携式构建
├── vitest.config.js
├── .npmrc                      npmmirror 镜像加速
├── src/
│   ├── main.js                 应用挂载（i18n + 全局样式）
│   ├── App.vue                 便携式根组件（嵌入与独立两用）
│   ├── i18n/                   独立 vue-i18n 实例 + 中英 locale
│   ├── composables/
│   │   ├── usePdfApi.js        API 客户端 + 进度轮询状态机（可单测）
│   │   └── useLocale.js        语言辅助（直读自身 i18n 实例）
│   ├── components/
│   │   ├── Uploader.vue        拖拽/选择 + 上传进度
│   │   └── JobList.vue         任务列表（进度/状态/下载/删除）
│   └── styles/global.css       全局重置 + 设计令牌
└── test/                       Vitest 单元测试（20 项）

外部依赖

项	说明
Node.js	≥ 18
zTools2	后端 /api/pdf/*（同源调用，cookie 自动管理）

前端纯静态，无运行期后端依赖；API 由 zTools2 提供。

如何使用

# 克隆并安装
git clone https://git.zikai.wang/zikai/zPDF_package.git
cd zPDF_package
npm install        # 已配 npmmirror 镜像加速

npm run dev        # 开发服务器 http://localhost:5173（需 zTools2 在同源或配置代理）
npm run build      # 构建到 dist/
npm test           # 单元测试（20 项）

开发时 /api/pdf/* 需指向 zTools2。可配 Vite 代理，或直接由 zTools2 托管 dist/。

部署到 zTools2

zTools2 的 /pdf 页面（static/pdf.html + pdf.js）为内置同款实现。如需用本项目的 Vue 构建产物替换：

cd zPDF_package && npm run build
# 把 dist/ 部署到 zTools2 静态目录（如 static/pdf_app/），改 pdf.html 引用之

嵌入 mainPage

作为 mainPage 的 git submodule（third_party/zPDF_package），mainPage 用 iframe 嵌入 zTools2 托管的 /pdf 页面（同源，cookie 第一方生效，无需 CORS）。详见 mainPage 的 docs/submodule-zPDF_package.md。

技术栈

项	选择
框架	Vue 3.5（SFC，<script setup>）
构建	Vite 6
国际化	vue-i18n 9（中文同步，英文懒加载）
状态管理	composable 单例
测试	Vitest
包源	npmmirror.com（中国镜像加速）

了解更多

• 嵌入 mainPage（iframe 同源集成）
• 后端 API 与转换实现见 zTools2 README