# qms_frontend

**Repository Path**: bukcn/qms_frontend

## Basic Information

- **Project Name**: qms_frontend
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-11-21
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: buk-cn

## README

# 差旅管理系统（TMS）

项目包含两个版本：
- **V2（稳定版）**: 根目录，Vue 2 + Webpack 4 SSR，端口 **8090**
- **V3（新版）**: [v3/](./v3) 目录，Vue 3 + Vite 6 SPA + TypeScript，端口 **8091**

---

## V2（稳定版）

基于 Vue 2 + Express 的 SSR（服务端渲染）差旅管理后台系统。

### 技术栈

- **前端框架**: Vue 2 + Vue Router + Vuex
- **服务端**: Express + Vue Server Renderer
- **样式**: Bootstrap 5 + jQuery 3
- **构建工具**: Webpack 4
- **HTTP 客户端**: Axios
- **图表**: ECharts + V-Charts

### 环境要求

- **Node.js** >= 18（推荐 22.x）
- **npm** >= 8

### 快速开始

#### 1. 安装依赖

```bash
# 设置 npm 镜像（国内加速）
npm config set registry https://registry.npmmirror.com

# 安装依赖
npm install
```

#### 2. 开发模式运行

```bash
npm run dev
```

服务启动后访问 **http://localhost:8090**。开发模式使用 webpack-dev-middleware + HMR，修改代码后浏览器自动热更新。

#### 3. 生产构建与运行

```bash
# 构建
npm run build

# 启动生产服务
npm run start-server
```

生产模式下，先执行 Webpack 构建生成 `dist/` 目录，然后启动 Express 服务，访问 **http://localhost:8090**。

### NPM 脚本说明

| 命令 | 说明 |
|------|------|
| `npm run dev` | 开发模式运行（热更新） |
| `npm run demo` | Demo 模式运行（连接演示环境 API） |
| `npm run build` | 生产构建（客户端 + 服务端） |
| `npm run build-client` | 仅构建客户端 |
| `npm run build-server` | 仅构建服务端 |
| `npm run start-server` | 启动生产服务 |
| `npm start` | 构建并启动生产服务 |
| `npm run lint` | ESLint 代码检查 |
| `npm test` | 运行单元测试（Jest） |
| `npm run e2e` | 运行端到端测试（Nightwatch） |

### Docker 运行

#### 构建镜像

```bash
docker build -t tms_saas_web:0.0.1 .
```

#### 启动容器

```bash
cd docker/tms_saas_web
docker compose up -d
```

容器暴露 **8090** 端口，映射到宿主机相同端口。

也可一键执行：

```bash
bash run.sh
```

---

## V3（新版）

基于 Vue 3 + Vite 6 + TypeScript 的差旅管理 SPA 系统（从 V2 迁移）。

### 技术栈

- **前端框架**: Vue 3 + Vue Router 4 + Pinia
- **组件库**: [shadcn-vue](https://www.shadcn-vue.com/) + [radix-vue](https://www.radix-vue.com/) + [reka-ui](https://reka-ui.com/)
- **样式方案**: [Tailwind CSS v4](https://tailwindcss.com/) + CSS 变量主题系统（亮色/暗色）
- **图标**: [Lucide Vue Next](https://lucide.dev/guide/packages/lucide-vue-next)
- **表单验证**: [VeeValidate](https://vee-validate.logaretm.com/) + [Zod](https://zod.dev/)
- **日期处理**: [dayjs](https://dayjs.io/) + [date-fns](https://date-fns.org/)
- **工具函数**: [VueUse](https://vueuse.org/)
- **通知**: [Vue Sonner](https://vue-sonner.vercel.app/)
- **构建工具**: [Vite 6](https://vitejs.dev/)
- **HTTP 客户端**: Axios
- **语言**: TypeScript
- **测试**: Playwright（e2e）+ Vitest（单元测试）

> **注**：Bootstrap 已从 npm 依赖中移除，仅保留 `public/css/app.min.css` 作为全局样式兜底，通过 CSS 别名映射实现类名兼容。

### SPA 架构说明

V3 使用 **SPA（Single Page Application）** 架构，由 [Express](v3/server.js) 提供静态文件服务和 API 反向代理，不再使用服务端渲染：

- **开发模式**: `npx vite` 启动开发服务器（端口 5173），支持 HMR 热更新
- **生产模式**: 构建后的 `dist/` 目录由 Express 静态托管（端口 8091）
- **API 代理**: `server.js` 和 `vite.config.ts` 均配置了 `/api/v1` 代理到后端 Java 服务
- **后端**: 基于 Vue 3 Composition API + `<script setup>` 语法

### 功能模块

| 模块 | 路由前缀 | 说明 |
|------|----------|------|
| 通用 | `/`、`/login`、`/my/`、`/ai/` | 登录/登出、工作台、修改密码、操作历史、AI 工作台 |
| 机票订单 | `/flt/` | 国内/国际机票预订、退票、改签、订单详情与历史 |
| 配送单 | `/flt/orders/delivery/` | 机票配送单管理 |
| 保险订单 | `/insurance/` | 保险订单管理 |
| 增值服务（VAS） | `/vas/` | 服务订单 |
| 机场服务（VAAS） | `/vaas/` | 机场增值服务订单 |
| 酒店订单 | `/hotel/` | 酒店搜索、预订、订单管理 |
| 火车票 | `/train/` | 火车票订单、退票 |
| 租车 | `/car/` | 租车订单管理 |
| 账单 | `/bills`、`/bill/` | 账单列表、待审核、待结算、机票/火车票/酒店明细 |
| 结算 | `/ent/` | 企业结算单、收(退)款单、核销 |
| 报表 | `/report/` | 销售月报、退票月报、支付方式/供应商/航司/操作员统计 |
| 客户 | `/customer/` | 企业信息、部门、员工、旅客、成本中心 |
| 基础数据 | `/data/` | 机场、航司、城市、舱位、行李额管理 |
| 工具 | `/tool/` | 短信发送 |
| 管理设置 | `/admin/` | 用户/部门/权限管理、系统配置、会员管理、企业余额 |
| 业务设置 | `/setting/`、`/suppliers`、`/products` | 供应商、产品、账单模板、燃油附加费、客服组等 |

### 快速开始

```bash
cd v3

# 安装依赖
npm install

# 开发模式运行（HMR 热更新）
npm run dev
```

Vite 开发服务器默认运行在 **http://localhost:5173**，API 请求自动代理到 `http://localhost:8080`。

### 生产构建

```bash
cd v3

# 构建
npm run build

# 启动生产服务
npm run preview
```

生产服务运行在 **http://localhost:8091**。

### 部署方式

#### 方式一：Express 直接部署（推荐）

构建后直接运行 Node.js 服务端，由 [server.js](v3/server.js) 提供静态文件服务和 API 代理：

```bash
cd v3
npm run build
npm run preview
```

#### 方式二：Docker 部署

可参考以下模板自行创建 `v3/Dockerfile`：

```dockerfile
FROM node:22.14.0
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
EXPOSE 8091
CMD ["node", "server.js"]
```

构建镜像并启动容器：

```bash
cd v3
docker build -t tms-v3:latest .
docker run -d -p 8091:8091 tms-v3:latest
```

#### 方式三：Nginx 部署

将 `dist/` 构建产物部署到 Nginx，并通过反向代理转发 API 请求到后端 Java 服务：

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

    # 静态文件
    location / {
        root /path/to/v3/dist;
        try_files $uri $uri/ /index.html;  # SPA fallback
    }

    # API 代理到后端 Java 服务
    location /api/v1/ {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}
```

构建：

```bash
cd v3 && npm install && npm run build
```

然后将 `v3/dist/` 目录内容上传到 Nginx 配置的静态文件目录即可。

> **注意**：Docker 和 Nginx 部署时，需确保后端 Java 服务先启动，且 API 代理地址与实际后端地址一致。

### NPM 脚本说明（V3）

| 命令 | 说明 |
|------|------|
| `npm run dev` | Vite 开发模式（HMR 热更新，端口 5173） |
| `npm run build` | 生产构建 |
| `npm run preview` | 启动生产模式 Express 服务（端口 8091） |
| `npm run test:e2e` | 运行 Playwright 端到端测试 |
| `npm run test:e2e:ui` | 运行 Playwright UI 模式 |
| `npm run test:e2e:debug` | Playwright 调试模式 |
| `npm run test:unit` | 运行 Vitest 单元测试 |
| `npm run test:unit:watch` | Vitest 监听模式 |
| `npm run lint` | ESLint 代码检查 |
| `npm run format` | Prettier 代码格式化 |

### 测试

V3 使用 **Playwright** 进行端到端测试，**Vitest** 进行单元测试。

#### E2E 测试

测试用例位于 `v3/tests/e2e/` 目录。

```bash
cd v3

# 运行所有 e2e 测试
npx playwright test

# 运行指定测试文件
npx playwright test tests/e2e/core-workflow.spec.ts
```

测试流程：
1. **全局前置**（`tests/e2e/helpers/global-setup.ts`）：使用 `sy-admin / 12345678.sy` 账号登录，预取所有后端 API 数据保存到 `api-data.json`
2. **Mock 运行**：测试运行时通过 Mock 拦截 API 请求，返回预设数据，无需连接真实后端

#### 单元测试

```bash
cd v3

# 运行所有单元测试
npm run test:unit

# 监听模式
npm run test:unit:watch
```

单元测试使用 Vitest + jsdom 环境，测试文件位于 `src/**/*.{test,spec}.ts`。

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `NODE_ENV` | 运行环境（production/development） | development |

## 目录结构

```
├── docs/                # 项目文档（迁移计划、UI 审核等）
├── build/               # V2 开发服务器配置
├── dist/                # V2 构建产物
├── docker/              # Docker 部署配置
├── public/              # V2 静态资源
├── src/                 # V2 源代码
│   ├── api/             # API 接口
│   ├── components/      # 公共组件
│   ├── pages/           # 页面组件
│   ├── pages_h5/        # H5 页面（已逐步合并至自适应方案）
│   ├── router/          # 路由配置
│   ├── store/           # Vuex 状态管理
│   └── main.js          # 应用入口
├── tests/               # V2 测试
├── v3/                  # Vue 3 新版（Vite SPA）
│   ├── src/             # V3 源代码
│   │   ├── api/         # API 接口层（按模块拆分）
│   │   ├── components/  # 公共组件（含 shadcn-vue 组件）
│   │   ├── composables/ # 组合式函数（折叠状态、加载提示等）
│   │   ├── lib/         # 工具库
│   │   ├── pages/       # 页面组件（按业务模块分目录）
│   │   ├── router/      # 路由配置（按模块分文件）
│   │   ├── stores/      # Pinia 状态管理
│   │   ├── types/       # TypeScript 类型定义
│   │   ├── utils/       # 工具函数
│   │   ├── main.ts      # 应用入口
│   │   └── main.css     # 全局样式（Tailwind CSS + shadcn-vue 主题变量）
│   ├── tests/e2e/       # Playwright 端到端测试
│   │   └── helpers/     # 测试辅助（全局 setup、Mock 数据预取）
│   ├── public/          # 静态资源
│   ├── server.js        # 生产 Express 服务（端口 8091，SPA 模式）
│   ├── vite.config.ts   # Vite 构建配置
│   ├── vitest.config.ts # Vitest 单元测试配置
│   ├── playwright.config.ts  # Playwright 测试配置
│   ├── api-data.json    # E2E 测试预取 API 数据（运行生成）
│   └── auth.json        # E2E 测试登录状态（运行生成）
├── AGENTS.md            # AI 辅助开发指南
├── server.js            # V2 Express 服务入口（端口 8090）
└── package.json
```