# 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 提供。生产部署经 [zMainPage](https://git.zikai.wang/zikai/zMainPage) 作为子模块集成，由其 apache2 静态托管 + `/api` 反代到 zTools2（无独立 apache2 配置）。

## 如何使用

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

npm run dev        # 开发服务器 http://localhost:5175（vite.config.js 已配 /api 代理到 zTools2:6867）
npm run build      # 构建到 dist/
npm test           # 单元测试（20 项）
```

> 开发时 `/api/pdf/*` 由 vite 代理到本地 zTools2（127.0.0.1:6867）；生产环境由 mainPage 同源反代到 zTools2，cookie 第一方生效。

## 嵌入 mainPage

作为 [mainPage](https://git.zikai.wang/zikai/zMainPage) 的 git submodule，经构建期组件 import 集成（非 iframe）。详见 [`docs/integration.md`](./docs/integration.md)。

## 技术栈

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

## 了解更多

- [嵌入 mainPage（构建期组件 import）](./docs/integration.md)
- [错误处理与日志约定](./docs/error-handling.md)
- 后端 API 与转换实现见 [zTools2](https://git.zikai.wang/zikai/zTools2) README