363 lines
13 KiB
Markdown
363 lines
13 KiB
Markdown
# Design Document: 订单管理模块前端迁移
|
||
|
||
## Overview
|
||
|
||
本设计文档描述订单管理模块从老项目（PHP ThinkPHP + Layui）迁移到新项目（ASP.NET Core + Vue 3 + Element Plus）的技术方案。订单管理模块是后台管理系统的核心业务模块，包含购买订单、发货订单、回收订单、卡单订单等多种订单类型的管理功能。
|
||
|
||
### 技术栈
|
||
- 前端框架：Vue 3 + TypeScript
|
||
- UI组件库：Element Plus
|
||
- 状态管理：Pinia
|
||
- HTTP客户端：Axios
|
||
- 后端框架：ASP.NET Core (.NET 10)
|
||
- 数据库：SQL Server
|
||
|
||
## Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 前端应用层 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 购买订单页面 │ │ 发货订单页面 │ │ 回收订单页面 │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ 卡单订单页面 │ │ 综合订单页面 │ │
|
||
│ └─────────────┘ └─────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 组件层 │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ SearchForm │ │ OrderTable │ │ DetailDialog│ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
│ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ShippingDialog│ │ PrizeList │ │
|
||
│ └─────────────┘ └─────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ API层 │
|
||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||
│ │ api/business/order.ts ││
|
||
│ └─────────────────────────────────────────────────────────────┘│
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 后端API层 │
|
||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||
│ │ OrderController ││
|
||
│ └─────────────────────────────────────────────────────────────┘│
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Components and Interfaces
|
||
|
||
### 1. 页面组件
|
||
|
||
#### 1.1 购买订单页面 (BuyOrderPage)
|
||
- 路径：`views/business/order/buy.vue`
|
||
- 功能：展示购买订单列表，支持搜索、分页、查看详情、导出
|
||
|
||
#### 1.2 发货订单页面 (ShippingOrderPage)
|
||
- 路径：`views/business/order/shipping.vue`
|
||
- 功能：展示发货订单列表，支持搜索、分页、查看详情、发货操作、取消发货、导出
|
||
|
||
#### 1.3 回收订单页面 (RecoveryOrderPage)
|
||
- 路径：`views/business/order/recovery.vue`
|
||
- 功能：展示回收订单列表，支持搜索、分页、查看详情、导出
|
||
|
||
#### 1.4 卡单订单页面 (StuckOrderPage)
|
||
- 路径：`views/business/order/stuck.vue`
|
||
- 功能：展示卡单订单列表，支持搜索、分页
|
||
|
||
#### 1.5 综合订单页面 (OrderListPage)
|
||
- 路径：`views/business/order/list.vue`
|
||
- 功能：展示综合订单列表，支持多条件搜索、分页、查看详情、导出
|
||
|
||
### 2. 公共组件
|
||
|
||
#### 2.1 订单搜索表单 (OrderSearchForm)
|
||
- 路径：`views/business/order/components/OrderSearchForm.vue`
|
||
- Props：
|
||
- `type`: 订单类型（buy/shipping/recovery/stuck/list）
|
||
- `modelValue`: 搜索条件对象
|
||
- Events：
|
||
- `search`: 触发搜索
|
||
- `reset`: 重置搜索条件
|
||
|
||
#### 2.2 订单表格 (OrderTable)
|
||
- 路径：`views/business/order/components/OrderTable.vue`
|
||
- Props：
|
||
- `type`: 订单类型
|
||
- `data`: 订单数据列表
|
||
- `loading`: 加载状态
|
||
- `total`: 总记录数
|
||
- `page`: 当前页码
|
||
- `pageSize`: 每页大小
|
||
- Events：
|
||
- `page-change`: 页码变化
|
||
- `view-detail`: 查看详情
|
||
- `ship`: 发货操作
|
||
- `cancel-ship`: 取消发货
|
||
|
||
#### 2.3 订单详情弹窗 (OrderDetailDialog)
|
||
- 路径：`views/business/order/components/OrderDetailDialog.vue`
|
||
- Props：
|
||
- `visible`: 是否显示
|
||
- `orderId`: 订单ID
|
||
- Events：
|
||
- `close`: 关闭弹窗
|
||
|
||
#### 2.4 发货订单详情弹窗 (ShippingDetailDialog)
|
||
- 路径：`views/business/order/components/ShippingDetailDialog.vue`
|
||
- Props：
|
||
- `visible`: 是否显示
|
||
- `sendId`: 发货记录ID
|
||
- Events：
|
||
- `close`: 关闭弹窗
|
||
- `shipped`: 发货成功
|
||
|
||
#### 2.5 发货操作弹窗 (ShipDialog)
|
||
- 路径：`views/business/order/components/ShipDialog.vue`
|
||
- Props：
|
||
- `visible`: 是否显示
|
||
- `sendId`: 发货记录ID
|
||
- Events：
|
||
- `close`: 关闭弹窗
|
||
- `success`: 发货成功
|
||
|
||
#### 2.6 回收订单详情弹窗 (RecoveryDetailDialog)
|
||
- 路径：`views/business/order/components/RecoveryDetailDialog.vue`
|
||
- Props：
|
||
- `visible`: 是否显示
|
||
- `recoveryId`: 回收记录ID
|
||
- Events：
|
||
- `close`: 关闭弹窗
|
||
|
||
### 3. API接口
|
||
|
||
#### 3.1 订单API模块
|
||
- 路径：`api/business/order.ts`
|
||
|
||
```typescript
|
||
// 接口类型定义
|
||
interface OrderListRequest {
|
||
page: number
|
||
pageSize: number
|
||
userId?: number
|
||
mobile?: string
|
||
orderNum?: string
|
||
startDate?: string
|
||
endDate?: string
|
||
status?: number
|
||
orderType?: number
|
||
}
|
||
|
||
interface OrderListResponse {
|
||
id: number
|
||
orderNum: string
|
||
userId: number
|
||
userNickname?: string
|
||
userMobile?: string
|
||
userUid?: string
|
||
goodsId: number
|
||
goodsTitle?: string
|
||
goodsImgUrl?: string
|
||
orderType: number
|
||
orderTotal: number
|
||
discount: number
|
||
discountTotal: number
|
||
weChatPayment: number
|
||
balancePayment: number
|
||
integralPayment: number
|
||
scorePayment: number
|
||
couponPayment?: number
|
||
num: number
|
||
prizeNum: number
|
||
status: number
|
||
statusName: string
|
||
payType: number
|
||
payTypeName: string
|
||
createdAt: string
|
||
payTime?: string
|
||
}
|
||
|
||
interface ShippingOrderListRequest {
|
||
page: number
|
||
pageSize: number
|
||
userId?: number
|
||
mobile?: string
|
||
sendNum?: string
|
||
startDate?: string
|
||
endDate?: string
|
||
status?: number
|
||
}
|
||
|
||
interface ShippingOrderResponse {
|
||
id: number
|
||
userId: number
|
||
userNickname?: string
|
||
userMobile?: string
|
||
userUid?: string
|
||
sendNum: string
|
||
freight: number
|
||
status: number
|
||
statusName: string
|
||
count: number
|
||
name?: string
|
||
receiverMobile?: string
|
||
address?: string
|
||
message?: string
|
||
courierNumber?: string
|
||
courierName?: string
|
||
courierCode?: string
|
||
deliveryStatus: number
|
||
deliveryStatusName: string
|
||
createdAt: string
|
||
payTime?: string
|
||
sendTime?: string
|
||
receiveTime?: string
|
||
prizes: ShippingPrizeDto[]
|
||
}
|
||
|
||
interface ShipOrderRequest {
|
||
courierName: string
|
||
courierNumber: string
|
||
courierCode?: string
|
||
}
|
||
|
||
// API函数
|
||
export function getOrderList(params: OrderListRequest): Promise<PagedResult<OrderListResponse>>
|
||
export function getOrderDetail(id: number): Promise<OrderDetailResponse>
|
||
export function getStuckOrders(params: OrderListRequest): Promise<PagedResult<OrderListResponse>>
|
||
export function getRecoveryOrders(params: OrderListRequest): Promise<PagedResult<RecoveryOrderResponse>>
|
||
export function getShippingOrders(params: ShippingOrderListRequest): Promise<PagedResult<ShippingOrderResponse>>
|
||
export function getShippingOrderDetail(id: number): Promise<ShippingOrderResponse>
|
||
export function shipOrder(id: number, data: ShipOrderRequest): Promise<void>
|
||
export function cancelShippingOrder(id: number): Promise<void>
|
||
export function exportOrders(params: OrderExportRequest): Promise<Blob>
|
||
```
|
||
|
||
## Data Models
|
||
|
||
### 1. 订单状态枚举
|
||
```typescript
|
||
enum OrderStatus {
|
||
Unpaid = 0, // 待支付
|
||
Paid = 1, // 已支付
|
||
Cancelled = 2 // 已取消
|
||
}
|
||
```
|
||
|
||
### 2. 发货状态枚举
|
||
```typescript
|
||
enum ShippingStatus {
|
||
Unpaid = 0, // 待支付
|
||
Pending = 1, // 待发货
|
||
Shipped = 2, // 已发货
|
||
Received = 3, // 已签收
|
||
Cancelled = 4 // 已取消
|
||
}
|
||
```
|
||
|
||
### 3. 订单项状态枚举
|
||
```typescript
|
||
enum OrderItemStatus {
|
||
Pending = 0, // 待处理
|
||
Recovered = 1, // 已回收
|
||
Shipped = 2 // 已发货
|
||
}
|
||
```
|
||
|
||
### 4. 支付方式枚举
|
||
```typescript
|
||
enum PayType {
|
||
Unpaid = 0, // 未支付
|
||
WeChat = 1, // 微信支付
|
||
Alipay = 2 // 支付宝
|
||
}
|
||
```
|
||
|
||
## Correctness Properties
|
||
|
||
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
||
|
||
### Property 1: 搜索参数正确传递
|
||
|
||
*For any* 搜索条件对象，当用户提交搜索时，API调用应该正确传递所有非空的搜索参数到后端。
|
||
|
||
**Validates: Requirements 1.2, 3.2, 4.2, 6.2, 7.2**
|
||
|
||
### Property 2: 分页参数正确传递
|
||
|
||
*For any* 页码和页大小组合，当用户切换分页时，API调用应该正确传递page和pageSize参数，且page >= 1，pageSize > 0。
|
||
|
||
**Validates: Requirements 1.3**
|
||
|
||
### Property 3: 发货信息验证
|
||
|
||
*For any* 发货表单输入，当物流公司名称或快递单号为空字符串或纯空白字符串时，表单验证应该失败并阻止提交。
|
||
|
||
**Validates: Requirements 5.4**
|
||
|
||
### Property 4: API响应格式一致性
|
||
|
||
*For any* API调用，响应数据应该符合定义的TypeScript接口类型，包含所有必需字段。
|
||
|
||
**Validates: Requirements 8.2, 8.3, 8.4, 8.5, 8.6**
|
||
|
||
### Property 5: 错误响应格式一致性
|
||
|
||
*For any* API调用失败，错误响应应该包含统一格式的错误信息（code和message字段）。
|
||
|
||
**Validates: Requirements 8.7**
|
||
|
||
## Error Handling
|
||
|
||
### 1. API错误处理
|
||
- 网络错误：显示"网络连接失败，请检查网络"
|
||
- 401未授权：跳转到登录页面
|
||
- 403无权限：显示"您没有权限执行此操作"
|
||
- 404未找到：显示"请求的资源不存在"
|
||
- 500服务器错误：显示"服务器错误，请稍后重试"
|
||
- 业务错误：显示后端返回的错误信息
|
||
|
||
### 2. 表单验证错误
|
||
- 必填字段为空：显示"xxx不能为空"
|
||
- 格式错误：显示具体的格式要求
|
||
|
||
### 3. 操作确认
|
||
- 取消发货：弹出确认对话框"确定要取消发货吗？取消后奖品将返回用户盒柜"
|
||
- 导出数据：大数据量时显示加载提示
|
||
|
||
## Testing Strategy
|
||
|
||
### 1. 单元测试
|
||
- 测试搜索表单组件的参数收集逻辑
|
||
- 测试表格组件的数据展示逻辑
|
||
- 测试发货表单的验证逻辑
|
||
- 测试API模块的请求构造逻辑
|
||
|
||
### 2. 属性测试
|
||
使用 fast-check 库进行属性测试，每个属性测试运行至少100次迭代。
|
||
|
||
- **Property 1**: 搜索参数正确传递
|
||
- 生成随机搜索条件对象
|
||
- 验证API调用参数包含所有非空字段
|
||
|
||
- **Property 2**: 分页参数正确传递
|
||
- 生成随机页码和页大小
|
||
- 验证API调用参数正确
|
||
|
||
- **Property 3**: 发货信息验证
|
||
- 生成随机字符串（包括空字符串、纯空白字符串、正常字符串）
|
||
- 验证验证函数的返回值正确
|
||
|
||
- **Property 4**: API响应格式一致性
|
||
- 模拟API响应数据
|
||
- 验证响应数据符合接口定义
|
||
|
||
- **Property 5**: 错误响应格式一致性
|
||
- 模拟各种错误响应
|
||
- 验证错误处理逻辑正确
|
||
|
||
### 3. 集成测试
|
||
- 测试完整的订单查询流程
|
||
- 测试完整的发货操作流程
|
||
- 测试导出功能
|