272 lines
8.7 KiB
Markdown
272 lines
8.7 KiB
Markdown
# WMMS Vue 重构设计方案
|
||
|
||
**日期**：2026-09-07
|
||
**项目**：仓库物料管理系统（WMMS）
|
||
**目标**：jQuery 前端 → Vue 3 前端
|
||
|
||
---
|
||
|
||
## 一、技术选型
|
||
|
||
| 层 | 选型 | 说明 |
|
||
|---|---|---|
|
||
| 框架 | Vue 3 (Composition API) | 最新稳定版 |
|
||
| 构建工具 | Vite | 快速开发热更新 |
|
||
| 状态管理 | Pinia | Vue 3 官方推荐 |
|
||
| 路由 | Vue Router 4 | History 模式 |
|
||
| UI 组件库 | Element Plus | 后台管理系统标配 |
|
||
| HTTP 客户端 | Axios | 封装请求拦截器 |
|
||
| 开发端口 | 8081 | 与旧版 8080 分离 |
|
||
|
||
---
|
||
|
||
## 二、项目结构
|
||
|
||
```
|
||
warehouse-mms/
|
||
├── web/ # 旧版 jQuery 前端（已禁用）
|
||
│ ├── index.html # 已重命名为 index.html.bak
|
||
│ ├── js/
|
||
│ └── css/
|
||
├── frontend/ # 新版 Vue 项目
|
||
│ ├── src/
|
||
│ │ ├── assets/ # 静态资源
|
||
│ │ ├── components/ # 基础组件
|
||
│ │ │ ├── business/ # 业务组件
|
||
│ │ │ │ ├── BaseTable.vue
|
||
│ │ │ │ ├── BasePagination.vue
|
||
│ │ │ │ ├── BaseModal.vue
|
||
│ │ │ │ ├── BaseForm.vue
|
||
│ │ │ │ ├── StatusBadge.vue
|
||
│ │ │ │ ├── RoleBadge.vue
|
||
│ │ │ │ ├── DeleteConfirm.vue
|
||
│ │ │ │ ├── AlertTip.vue
|
||
│ │ │ │ ├── LoadingOverlay.vue
|
||
│ │ │ │ ├── ImagePreview.vue
|
||
│ │ │ │ ├── DatePicker.vue
|
||
│ │ │ │ └── MaterialSelect.vue
|
||
│ │ │ └── layout/ # 布局组件
|
||
│ │ │ ├── AppHeader.vue
|
||
│ │ │ └── AppSidebar.vue
|
||
│ │ ├── views/ # 页面组件
|
||
│ │ │ ├── Login.vue
|
||
│ │ │ ├── Materials.vue
|
||
│ │ │ ├── Inbound.vue
|
||
│ │ │ ├── Outbound.vue
|
||
│ │ │ ├── Stock.vue
|
||
│ │ │ ├── Application.vue
|
||
│ │ │ ├── Approval.vue
|
||
│ │ │ ├── Logs.vue
|
||
│ │ │ └── Users.vue
|
||
│ │ ├── stores/ # Pinia Store
|
||
│ │ │ ├── auth.js
|
||
│ │ │ ├── materials.js
|
||
│ │ │ ├── stock.js
|
||
│ │ │ ├── inbound.js
|
||
│ │ │ ├── outbound.js
|
||
│ │ │ ├── application.js
|
||
│ │ │ ├── approval.js
|
||
│ │ │ ├── logs.js
|
||
│ │ │ ├── users.js
|
||
│ │ │ └── ui.js
|
||
│ │ ├── api/ # API 封装层
|
||
│ │ │ ├── index.js # Axios 实例
|
||
│ │ │ ├── auth.js
|
||
│ │ │ ├── materials.js
|
||
│ │ │ ├── inbound.js
|
||
│ │ │ ├── outbound.js
|
||
│ │ │ ├── stock.js
|
||
│ │ │ ├── application.js
|
||
│ │ │ ├── logs.js
|
||
│ │ │ └── users.js
|
||
│ │ ├── router/ # 路由配置
|
||
│ │ │ └── index.js
|
||
│ │ ├── App.vue
|
||
│ │ └── main.js
|
||
│ ├── public/
|
||
│ ├── index.html
|
||
│ ├── vite.config.js
|
||
│ └── package.json
|
||
└── internal/ # Go 后端（不变）
|
||
```
|
||
|
||
---
|
||
|
||
## 三、路由设计
|
||
|
||
| 路径 | 页面 | 权限 |
|
||
|---|---|---|
|
||
| /login | 登录页 | 游客 |
|
||
| /materials | 物料管理 | admin |
|
||
| /inbound | 入库管理 | admin |
|
||
| /outbound | 出库管理 | admin |
|
||
| /stock | 库存查询 | 登录用户 |
|
||
| /application | 物料申请 | 登录用户 |
|
||
| /approval | 申请审批 | admin |
|
||
| /logs | 日志记录 | admin |
|
||
| /users | 用户管理 | admin |
|
||
|
||
**路由守卫**：
|
||
- `authRequired`：需登录
|
||
- `adminOnly`：需管理员权限
|
||
- `guestOnly`：仅限未登录用户
|
||
|
||
---
|
||
|
||
## 四、组件设计
|
||
|
||
### 4.1 布局组件
|
||
|
||
**AppHeader**
|
||
- 顶部导航栏
|
||
- 显示系统标题、当前用户、角色徽章、退出按钮
|
||
- Props: `user`, `isLoggedIn`
|
||
- Emits: `logout`
|
||
|
||
**AppSidebar**
|
||
- 左侧菜单
|
||
- 根据用户权限动态显示菜单项
|
||
- 高亮当前激活菜单
|
||
- Props: `menuItems`, `activeMenu`
|
||
- Emits: `menu-select`
|
||
|
||
### 4.2 基础组件
|
||
|
||
| 组件 | 职责 |
|
||
|---|---|
|
||
| BaseTable | 通用表格，封装分页、加载状态 |
|
||
| BasePagination | 分页组件 |
|
||
| BaseModal | 弹窗基础组件 |
|
||
| BaseForm | 表单基础组件 |
|
||
| StatusBadge | 状态徽章（pending/completed/processing） |
|
||
| RoleBadge | 角色徽章（admin/user） |
|
||
| DeleteConfirm | 删除确认弹窗 |
|
||
| AlertTip | 提示消息 |
|
||
| LoadingOverlay | 加载遮罩 |
|
||
| ImagePreview | 图片预览 |
|
||
| DatePicker | 日期选择 |
|
||
| MaterialSelect | 物料选择器 |
|
||
|
||
### 4.3 业务组件
|
||
|
||
| 组件 | 对应模块 | 职责 |
|
||
|---|---|---|
|
||
| MaterialTable | materials.js | 物料列表、新增编辑删除 |
|
||
| MaterialForm | materials.js | 物料表单 |
|
||
| InboundTable | inbound.js | 入库单列表 |
|
||
| InboundForm | inbound.js | 入库单表单 |
|
||
| OutboundTable | outbound.js | 出库单列表 |
|
||
| OutboundForm | outbound.js | 出库单表单 |
|
||
| StockTable | stock.js | 库存列表 |
|
||
| StockWarning | stock.js | 库存预警 |
|
||
| StockLogs | stock.js | 库存变动日志 |
|
||
| ApplicationForm | application.js | 物料申请表单 |
|
||
| MyApplications | application.js | 我的申请列表 |
|
||
| ApprovalTable | application.js | 审批列表 |
|
||
| LogsTable | logs.js | 日志记录 |
|
||
| UserTable | users.js | 用户管理 |
|
||
|
||
---
|
||
|
||
## 五、Pinia Store 设计
|
||
|
||
### auth
|
||
- State: `token`, `user`, `isLoggedIn`, `isAdmin`
|
||
- Actions: `login`, `logout`, `fetchCurrentUser`, `saveAuth`, `clearAuth`
|
||
|
||
### materials
|
||
- State: `materials`, `materialsCache`, `categoryMap`, `loading`, `pagination`
|
||
- Actions: `fetchMaterials`, `createMaterial`, `updateMaterial`, `deleteMaterial`
|
||
|
||
### stock
|
||
- State: `stockList`, `warningList`, `logs`, `loading`, `stockPage`, `warningPage`, `logsPage`
|
||
- Actions: `fetchStock`, `fetchStockWarning`, `fetchStockLogs`
|
||
|
||
### inbound
|
||
- State: `inboundList`, `currentInbound`, `loading`, `page`
|
||
- Actions: `fetchInboundList`, `createInbound`, `updateInbound`, `deleteInbound`
|
||
|
||
### outbound
|
||
- State: `outboundList`, `currentOutbound`, `loading`, `page`
|
||
- Actions: `fetchOutboundList`, `createOutbound`, `updateOutbound`, `deleteOutbound`
|
||
|
||
### application
|
||
- State: `myApplications`, `materialsCache`, `loading`, `myPage`
|
||
- Actions: `createApplication`, `fetchMyApplications`, `cancelApplication`
|
||
|
||
### approval
|
||
- State: `applications`, `loading`, `approvalPage`
|
||
- Actions: `fetchPendingApplications`, `approveApplication`, `rejectApplication`
|
||
|
||
### logs
|
||
- State: `logs`, `loading`, `page`, `filters`
|
||
- Actions: `fetchLogs`, `setFilters`, `resetFilters`
|
||
|
||
### users
|
||
- State: `users`, `loading`, `page`
|
||
- Actions: `fetchUsers`, `createUser`, `updateUser`, `deleteUser`
|
||
|
||
### ui
|
||
- State: `loading`, `loadingText`, `activeTab`, `sidebarCollapsed`
|
||
- Actions: `setLoading`, `setActiveTab`, `toggleSidebar`
|
||
|
||
---
|
||
|
||
## 六、API 层设计
|
||
|
||
基于现有 `web/js/api.js` 重构为 `frontend/src/api/` 模块化结构。
|
||
|
||
**Axios 实例配置**：
|
||
- baseURL: `/api`
|
||
- timeout: 30000ms
|
||
- 请求拦截器：添加 `Authorization: Bearer token`
|
||
- 响应拦截器：2xx 直接返回 data，401 跳转登录
|
||
|
||
**API 模块**：
|
||
- `auth.js` - 登录、获取当前用户
|
||
- `materials.js` - 物料 CRUD
|
||
- `inbound.js` - 入库单 CRUD
|
||
- `outbound.js` - 出库单 CRUD
|
||
- `stock.js` - 库存查询、预警、日志
|
||
- `application.js` - 申请单
|
||
- `logs.js` - 操作日志
|
||
- `users.js` - 用户 CRUD
|
||
|
||
**WebSocket**：
|
||
- 端口：8080/ws（与后端相同）
|
||
- 重连机制：指数退避
|
||
- 用途：实时库存更新推送
|
||
|
||
---
|
||
|
||
## 七、实施计划
|
||
|
||
| Day | 任务 | 交付物 |
|
||
|---|---|---|
|
||
| Day 1 | 初始化 Vue 项目 + API 层 + Pinia 基础 | 项目架子、API 接口封装、Store 基础模块 |
|
||
| Day 2 | 基础组件 + 登录/物料/库存页面 | 10 个基础组件、3 个主要页面 |
|
||
| Day 3 | 出入库/申请/审批/日志/用户 + 权限 | 剩余页面、路由守卫、权限控制 |
|
||
|
||
---
|
||
|
||
## 八、风险与应对
|
||
|
||
| 风险 | 影响 | 应对 |
|
||
|---|---|---|
|
||
| 业务逻辑遗漏 | 重构后功能不完整 | 逐模块对照旧版代码、详细测试 |
|
||
| 性能退化 | 大数据量时变慢 | 虚拟滚动、合理使用 computed |
|
||
| WebSocket 重连 | 实时功能失效 | 指数退避重连 + 心跳检测 |
|
||
| 权限控制绕过 | 安全风险 | 后端 API 也有 AdminOnly 验证 |
|
||
|
||
---
|
||
|
||
## 九、测试验收标准
|
||
|
||
1. 所有 8 个页面功能正常
|
||
2. 登录/登出正常
|
||
3. 权限控制生效（admin vs 普通用户）
|
||
4. 分页、搜索功能正常
|
||
5. 新增/编辑/删除操作正常
|
||
6. WebSocket 实时推送正常
|
||
7. 旧版 `web/` 可随时恢复
|