zikai
4d12b615c8
PDF 用户侧 UI 改由 zMainPage 构建期 import 本项目 App.vue 作为组件挂载（非 iframe， 与 timeTableFix 同范式）。相应更新文档与注释： - README：首页/嵌入 mainPage 小节从 iframe 描述改为组件 import；删除已废弃的 「部署到 zTools2」小节（zTools2 不再托管用户 UI，无内置实现可替换） - package.json description：iframe -> 构建期组件 import - vite.config.js 注释：去 iframe 字样，改为组件 import
80 lines
3.7 KiB
Markdown
80 lines
3.7 KiB
Markdown
# zPDF_package - PDF 转换前端
|
||
|
||
上传 epub 文件转为 PDF，显示转换进度，完成后下载。复用 [zTools2](https://git.zikai.wang/zikai/zTools2) 后端 API（`/api/pdf/*`）。便携式组件，可独立运行，亦可作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的子模块经构建期组件 import 集成展示（像 [timeTableFix](https://git.zikai.wang/zikai/timeTableFix)）。
|
||
|
||
## 功能
|
||
|
||
- 上传 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 便携式根组件（接受 :locale prop，独立/嵌入两用）
|
||
│ ├── 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 提供。
|
||
|
||
## 如何使用
|
||
|
||
```bash
|
||
# 克隆并安装
|
||
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 代理；生产环境由 mainPage 同源反代到 zTools2，cookie 第一方生效。
|
||
|
||
## 嵌入 mainPage
|
||
|
||
作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule（`third_party/zPDF_package`），mainPage 在构建期直接 `import` 本项目的 `src/App.vue` 作为组件挂载（非 iframe，与 [timeTableFix](https://git.zikai.wang/zikai/timeTableFix) 同范式）：mainPage 侧 `src/modules/pdf/Pdf.vue` 套 `PageShell` 并透传 `:locale`；组件内 `usePdfApi.js` 同源 fetch `/api/pdf/*`，httpOnly cookie（`zk_pdf`）经反代第一方自动携带，无需 CORS。组件自身保持「无 host 依赖」：不持 `defineOptions({ name })`、不引 mainPage 的 i18n，仅靠 `:locale` prop 驱动自有 i18n 实例。详见 mainPage 的 `docs/submodule-zPDF_package.md`。
|
||
|
||
## 技术栈
|
||
|
||
| 项 | 选择 |
|
||
|----|------|
|
||
| 框架 | Vue 3.5（SFC，`<script setup>`） |
|
||
| 构建 | Vite 6 |
|
||
| 国际化 | vue-i18n 9（中文同步，英文懒加载） |
|
||
| 状态管理 | composable 单例 |
|
||
| 测试 | Vitest |
|
||
| 包源 | npmmirror.com（中国镜像加速） |
|
||
|
||
## 了解更多
|
||
|
||
- [嵌入 mainPage（构建期组件 import）](../zMainPage/docs/submodule-zPDF_package.md)
|
||
- 后端 API 与转换实现见 [zTools2](https://git.zikai.wang/zikai/zTools2) README
|