# 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                   # 项目说明

## 安装依赖

```bash
cd WIDESEA_WMS_Frontend
npm install
```

## 启动开发服务器

```bash
npm run dev
```

访问: http://localhost:3000

## 构建生产版本

```bash
npm run build
```

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

## 预览生产构建

```bash
npm run preview
```

## 后端 API 配置

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

```typescript
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 请求格式

### 分页请求

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

### 响应格式

```typescript
{
  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 文件：

```typescript
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：

```typescript
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`）

## 部署

### 开发环境

```bash
npm run dev
```

### 生产环境

1. 构建项目：
```bash
npm run build
```

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

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

```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