WIDESEA WMS 前端项目 - 快速开始指南

项目概述

本项目是基于 Vue 3 + TypeScript + Ant Design Vue 开发的 WIDESEA WMS 仓库管理系统前端，已完成与后端 API 的适配。

技术栈

• 框架: Vue 3.4 (Composition API)
• 语言: TypeScript 5.3
• 构建工具: Vite 5.0
• UI 组件库: Ant Design Vue 4.1
• 路由: Vue Router 4.2
• 状态管理: Pinia 2.1
• HTTP 客户端: Axios 1.6
• 日期处理: Day.js 1.11
• 工具库: Lodash-es 4.17

项目结构

WIDESEA_WMS_Frontend/
├── src/
│   ├── api/                    # API 接口定义
│   │   ├── auth.ts             # 认证相关 API
│   │   ├── system/             # 系统管理 API
│   │   └── basic/              # 基础信息 API
│   ├── assets/                 # 静态资源
│   │   └── styles/             # 样式文件
│   ├── layouts/                # 布局组件
│   │   └── BasicLayout.vue     # 基础布局
│   ├── router/                 # 路由配置
│   │   ├── index.ts            # 路由主文件
│   │   ├── routes.ts           # 路由定义
│   │   └── guard.ts            # 路由守卫
│   ├── stores/                 # Pinia 状态管理
│   │   ├── auth.ts             # 认证状态
│   │   └── app.ts              # 应用状态
│   ├── types/                  # TypeScript 类型定义
│   │   ├── api.ts              # API 类型
│   │   ├── user.ts             # 用户类型
│   │   └── common.ts           # 通用类型
│   ├── utils/                  # 工具函数
│   │   ├── request.ts          # Axios 封装
│   │   ├── auth.ts             # 认证工具
│   │   └── common.ts           # 通用工具
│   ├── views/                  # 页面组件
│   │   ├── login/              # 登录页
│   │   ├── dashboard/          # 首页
│   │   ├── system/             # 系统管理
│   │   │   ├── user/           # 用户管理
│   │   │   ├── role/           # 角色管理
│   │   │   └── menu/           # 菜单管理
│   │   ├── basic/              # 基础信息
│   │   │   ├── warehouse/      # 仓库管理
│   │   │   ├── location/       # 货位管理
│   │   │   └── materiel/       # 物料管理
│   │   ├── inbound/            # 入库管理
│   │   │   └── order/          # 入库单管理
│   │   ├── outbound/           # 出库管理
│   │   │   └── order/          # 出库单管理
│   │   ├── stock/              # 库存管理
│   │   │   └── info/           # 库存信息
│   │   ├── check/              # 盘点管理
│   │   │   └── order/          # 盘点单管理
│   │   ├── task/               # 任务管理
│   │   │   └── info/           # 任务信息
│   │   └── error/              # 错误页面
│   │       └── 404.vue         # 404 页面
│   ├── App.vue                 # 根组件
│   └── main.ts                 # 入口文件
├── index.html                  # HTML 模板
├── package.json                # 项目配置
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 配置
└── README.md                   # 项目说明

## 安装依赖

cd WIDESEA_WMS_Frontend
npm install
```

启动开发服务器

npm run dev

访问: http://localhost:3000

构建生产版本

npm run build

构建产物将生成在 dist 目录。

预览生产构建

npm run preview

后端 API 配置

后端 API 地址配置在 vite.config.ts 中：

server: {
  proxy: {
    '/api': {
      target: 'http://localhost:9291',  // 后端 API 地址
      changeOrigin: true,
    },
  },
}

重要: 启动前端之前，请确保后端服务已经启动在 http://localhost:9291。

登录功能

登录流程

1. 访问 http://localhost:3000，自动跳转到登录页
2. 输入用户名和密码
3. 点击登录按钮
4. 登录成功后，Token 存储在 localStorage
5. 自动跳转到首页

认证机制

• Token 存储: localStorage (key: token)
• Token 有效期: 120 分钟
• Token 刷新: 当响应头包含 widesea_exp: 1 时自动刷新
• 请求头: Authorization: Bearer {token}
• 未认证处理: 401 错误自动跳转登录页

测试账号

请使用后端数据库中的用户账号进行登录测试。

功能模块

1. 系统管理

用户管理 (/system/user)

• 用户列表查询（分页、搜索）
• 新增用户
• 编辑用户
• 删除用户
• API: /api/User/GetPageData, /api/User/Add, /api/User/Update, /api/User/Del

角色管理 (/system/role)

• 角色列表查询
• 新增角色
• 编辑角色
• 删除角色
• API: /api/Role/GetPageData, /api/Role/Add, /api/Role/Update, /api/Role/Del

菜单管理 (/system/menu)

• 菜单列表查询（树形结构）
• 新增菜单
• 编辑菜单
• 删除菜单
• API: /api/Menu/GetPageData, /api/Menu/Add, /api/Menu/Update, /api/Menu/Del

2. 基础信息

仓库管理 (/basic/warehouse)

• 仓库列表查询（分页、搜索）
• 新增仓库
• 编辑仓库
• 删除仓库
• API: /api/Warehouse/GetPageData, /api/Warehouse/Add, /api/Warehouse/Update, /api/Warehouse/Del

货位管理 (/basic/location)

• 货位列表查询（分页、搜索）
• 新增货位
• 编辑货位
• 删除货位
• 货位状态显示（空闲/占用）
• API: /api/LocationInfo/GetPageData, /api/LocationInfo/Add, /api/LocationInfo/Update, /api/LocationInfo/Del

物料管理 (/basic/materiel)

• 物料列表查询（分页、搜索）
• 新增物料
• 编辑物料
• 删除物料
• API: /api/MaterielInfo/GetPageData, /api/MaterielInfo/Add, /api/MaterielInfo/Update, /api/MaterielInfo/Del

3. 入库管理

入库单管理 (/inbound/order)

• 入库单列表查询（分页、搜索）
• 新增入库单
• 查看入库单详情
• 编辑入库单
• 删除入库单
• 订单状态显示（待处理/处理中/已完成/已取消）
• API: /api/InboundOrder/GetPageData, /api/InboundOrder/Add, /api/InboundOrder/Update, /api/InboundOrder/Del

4. 出库管理

出库单管理 (/outbound/order)

• 出库单列表查询（分页、搜索）
• 新增出库单
• 查看出库单详情
• 编辑出库单
• 删除出库单
• 订单状态显示（待处理/处理中/已完成/已取消）
• API: /api/OutboundOrder/GetPageData, /api/OutboundOrder/Add, /api/OutboundOrder/Update, /api/OutboundOrder/Del

5. 库存管理

库存信息 (/stock/info)

• 库存列表查询（分页、搜索）
• 查看库存明细
• 导出库存数据
• 显示总数量、可用数量、锁定数量
• API: /api/StockInfo/GetPageData, /api/StockInfoDetail/GetDetailPage

6. 盘点管理

盘点单管理 (/check/order)

• 盘点单列表查询（分页、搜索）
• 新增盘点单
• 查看盘点单详情
• 编辑盘点单
• 删除盘点单
• 盘点状态显示（待盘点/盘点中/已完成）
• API: /api/CheckOrder/GetPageData, /api/CheckOrder/Add, /api/CheckOrder/Update, /api/CheckOrder/Del

7. 任务管理

任务信息 (/task/info)

• 任务列表查询（分页、搜索）
• 任务状态筛选
• 查看任务详情
• 任务状态显示（待处理/处理中/已完成/已取消）
• API: /api/Task/GetPageData

API 请求格式

分页请求

{
  page: 1,              // 当前页码
  rows: 20,             // 每页条数
  sort: 'CreateDate',   // 排序字段
  order: 'desc',        // 排序方式 (asc/desc)
  wheres: [             // 查询条件（可选）
    {
      name: 'UserName',           // 字段名
      value: 'admin',             // 字段值
      displayType: 'like'         // 查询类型 (like/equal/notEqual/greaterThan/lessThan/in/notIn)
    }
  ]
}

响应格式

{
  status: true,         // 成功/失败
  message: '',          // 消息
  data: {               // 数据
    rows: [],           // 数据列表
    total: 0,           // 总条数
    page: 1,            // 当前页
    records: 20         // 每页条数
  }
}

开发指南

添加新页面

1. 在 src/views 下创建页面组件
2. 在 src/router/routes.ts 中添加路由配置
3. 在 src/api 中添加 API 接口定义
4. 在 src/types 中添加类型定义（如需要）

添加新 API

在 src/api 目录下创建或编辑 API 文件：

import request from '../utils/request';
import type { ApiResponse, PageRequest, PageResponse } from '../types/api';

export function getList(data: PageRequest) {
  return request<ApiResponse<PageResponse<YourType>>>({
    url: '/YourController/GetPageData',
    method: 'post',
    data,
  });
}

export function add(data: Partial<YourType>) {
  return request<ApiResponse<boolean>>({
    url: '/YourController/Add',
    method: 'post',
    data,
  });
}

状态管理

使用 Pinia 进行状态管理，已创建的 Store：

• useAuthStore: 认证状态（登录、登出、用户信息）
• useAppStore: 应用状态（侧边栏折叠、加载状态）

创建新 Store：

import { defineStore } from 'pinia';
import { ref } from 'vue';

export const useYourStore = defineStore('your-store', () => {
  const data = ref<any>(null);

  function setData(value: any) {
    data.value = value;
  }

  return {
    data,
    setData,
  };
});

常见问题

1. 登录后 Token 未生效

检查：
- 后端是否正确返回 Token
- Token 是否存储在 localStorage
- 请求头是否包含 Authorization: Bearer {token}

2. API 请求 404

检查：
- 后端服务是否启动
- API 路径是否正确
- Vite 代理配置是否正确

3. 跨域问题

已在 vite.config.ts 中配置代理，开发环境不会有跨域问题。生产环境需要后端配置 CORS。

4. Token 过期处理

系统会自动处理 Token 过期：
- 401 错误自动跳转登录页
- Token 即将过期时自动刷新（响应头 widesea_exp: 1）

部署

开发环境

npm run dev

生产环境

1. 构建项目：
   bash npm run build

2. 将 dist 目录部署到 Web 服务器（Nginx、Apache 等）

3. 配置 Nginx 反向代理（示例）：

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

    location / {
        root /path/to/dist;
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://localhost:9291;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

后续扩展

待完善功能

1. 入库/出库单明细: 添加明细表格和编辑功能
2. 权限控制: 基于角色的菜单和按钮权限控制
3. 数据导出: Excel 导出功能
4. 数据导入: Excel 批量导入功能
5. 报表统计: 各类业务报表和图表
6. 消息通知: WebSocket 实时消息推送
7. 操作日志: 用户操作日志记录和查询
8. 数据字典: 字典管理和字典项管理
9. 文件上传: 图片和文件上传功能
10. 打印功能: 单据打印功能

性能优化

1. 路由懒加载（已实现）
2. 组件懒加载
3. 图片懒加载
4. 虚拟滚动（大数据量表格）
5. 请求防抖和节流
6. 缓存优化

技术支持

如有问题，请联系开发团队或查看后端 API 文档。

许可证

MIT