# DocuConvertWeb

**Repository Path**: Liyingpu/docu-convert-web

## Basic Information

- **Project Name**: DocuConvertWeb
- **Description**: 文件转换前端
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DocuConvert Web — 文档转换前端

基于 Vue 3 的文件格式转换前端，配合后端服务实现 Word/PDF/Excel/PPT 多种格式互转。

## 功能特性

| 功能 | 说明 |
|------|------|
| Word → PDF | 支持 .doc 和 .docx 格式 |
| PDF → Word | 输出 .docx 格式 |
| Excel → PDF | 支持 .xlsx 和 .xls 格式 |
| PPT → PDF | 支持 .pptx 格式 |
| 批量转换 | 多文件上传，结果打包为 ZIP 下载 |
| 拖拽上传 | 支持文件拖拽到页面上传 |
| 转换设置 | 可配置转换格式和参数 |
| 批量进度 | 批量转换实时进度面板 |
| 文件预览 | 转换前预览源文件信息 |
| 异步任务 | 大文件异步转换，WebSocket 实时进度推送 |
| 发票解析 | PDF 发票信息提取 |
| 历史记录 | 转换历史查看和管理 |
| 任务列表 | 异步任务状态查看、下载、重试 |
| 用户认证 | 登录、注册、密码修改 |
| 路由守卫 | 未登录自动跳转登录页 |

## 技术栈

- Vue 3 + Composition API（`<script setup>`）
- Vue Router 4（路由管理 + 导航守卫）
- Pinia（状态管理）
- Vite 8（构建工具）
- WebSocket（实时进度推送）
- 原生 Fetch API（HTTP 请求）

## 项目结构

```
word-web/
├── src/
│   ├── views/
│   │   ├── HomeView.vue            # 首页 - 文件转换主页面
│   │   ├── LoginView.vue           # 登录页面
│   │   ├── RegisterView.vue        # 注册页面
│   │   ├── HistoryView.vue         # 转换历史记录
│   │   ├── TaskHistoryView.vue     # 异步任务列表
│   │   ├── InvoiceView.vue         # 发票解析页面
│   │   └── UserProfileView.vue     # 个人中心
│   ├── components/
│   │   ├── NavBar.vue              # 顶部导航栏（响应式汉堡菜单）
│   │   ├── WordPdfConverter.vue    # 核心转换组件
│   │   ├── DragDropUpload.vue      # 拖拽上传组件
│   │   ├── ConversionSettings.vue  # 转换格式设置组件
│   │   ├── BatchProgressDashboard.vue # 批量转换进度面板
│   │   └── FilePreview.vue         # 文件预览组件
│   ├── stores/
│   │   └── index.js                # Pinia 状态管理
│   ├── utils/
│   │   ├── request.js              # HTTP 请求封装（拦截器、token 注入）
│   │   └── websocket.js            # WebSocket 连接管理
│   ├── router/
│   │   └── index.js                # 路由配置 + 导航守卫
│   ├── App.vue                     # 根组件
│   ├── main.js                     # 入口文件
│   └── style.css                   # 全局样式
├── public/
├── index.html                      # HTML 入口
├── vite.config.js                  # Vite 配置（含 API 代理）
├── .env.example                    # 环境变量示例
└── package.json
```

## 快速开始

### 环境要求

- Node.js 18+
- npm 9+

### 安装运行

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端默认运行在 `http://localhost:5173`，API 请求通过 Vite 代理转发到后端 `http://localhost:8090`。

> 需要先启动后端服务，详见 [后端 README](../word2pdf/word2pdf/README.md)

### 构建部署

```bash
npm run build
```

构建产物输出到 `dist/` 目录。

## 路由配置

| 路径 | 页面 | 说明 |
|------|------|------|
| `/` | HomeView | 文件转换主页（需登录） |
| `/login` | LoginView | 登录页 |
| `/register` | RegisterView | 注册页 |
| `/history` | HistoryView | 转换历史（需登录） |
| `/tasks` | TaskHistoryView | 异步任务列表（需登录） |
| `/invoice` | InvoiceView | 发票解析（需登录） |
| `/profile` | UserProfileView | 个人中心（需登录） |

路由守卫：未登录用户访问需认证页面时自动跳转到 `/login`，已登录用户访问 `/login` 或 `/register` 时自动跳转到首页。

## 环境变量

| 变量名 | 默认值 | 说明 |
|---|---|---|
| `VITE_API_BASE_URL` | `/word2pdf` | 后端 API 基础地址 |

创建 `.env` 文件进行配置：

```bash
# .env
VITE_API_BASE_URL=/word2pdf
```

## 开发配置

### Vite 代理（vite.config.js）

开发环境通过代理解决跨域问题：

```js
server: {
  proxy: {
    '/word2pdf': {
      target: 'http://localhost:8090',
      changeOrigin: true,
    },
    '/auth': {
      target: 'http://localhost:8090',
      changeOrigin: true,
    },
    '/task': {
      target: 'http://localhost:8090',
      changeOrigin: true,
    },
    '/history': {
      target: 'http://localhost:8090',
      changeOrigin: true,
    }
  }
}
```

### 文件大小限制

在 `WordPdfConverter.vue` 中配置：

```js
const MAX_FILE_SIZE = 100 * 1024 * 1024    // 单文件 100MB
const MAX_BATCH_SIZE = 500 * 1024 * 1024   // 批量 500MB
```

## API 对接

前端通过 `fetch` 发送 `multipart/form-data` 请求，响应为文件流：

| 场景 | 请求 | 响应 |
|---|---|---|
| 单文件 Word→PDF | `POST /word2pdf/word2PdfFileMultipart` | PDF 文件流 |
| 批量 Word→PDF | `POST /word2pdf/word2PdfFilesMultipartBatch` | ZIP 文件流 |
| 单文件 PDF→Word | `POST /word2pdf/pdf2WordFileMultipart` | DOCX 文件流 |
| 批量 PDF→Word | `POST /word2pdf/pdf2WordFilesMultipartBatch` | ZIP 文件流 |
| Excel/PPT 转 PDF | `POST /office/convert` | PDF 文件流 |
| 异步任务提交 | `POST /task/submit` | 任务 ID |
| 任务状态查询 | `GET /task/status/{taskId}` | 任务状态 JSON |
| 任务结果下载 | `GET /task/download/{taskId}` | 转换结果文件流 |
| 任务列表 | `GET /task/list` | 任务列表 JSON |
| 任务重试 | `POST /task/retry/{taskId}` | 操作结果 JSON |

### 认证接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | 用户登录（返回 JWT token） |
| POST | /auth/register | 用户注册 |
| POST | /auth/change-password | 修改密码 |

成功响应的文件名从 `Content-Disposition` 头解析，失败响应为 JSON 格式：

```json
{ "code": "500", "message": "错误信息" }
```

## 生产部署

生产环境需要配置反向代理将 API 请求转发到后端。以 Nginx 为例：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    location / {
        root /path/to/word-web/dist;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location ~ ^/(word2pdf|auth|task|history|statistics|office)/ {
        proxy_pass http://localhost:8090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 500M;
    }

    # WebSocket 代理
    location /ws/ {
        proxy_pass http://localhost:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}
```

## 相关仓库

- **后端**: https://gitee.com/Liyingpu/docu-convert.git
- **小程序端**: https://gitee.com/Liyingpu/docu-convert-weichat.git

## 许可证

MIT License