13 KiB
13 KiB
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
// 接口类型定义
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. 订单状态枚举
enum OrderStatus {
Unpaid = 0, // 待支付
Paid = 1, // 已支付
Cancelled = 2 // 已取消
}
2. 发货状态枚举
enum ShippingStatus {
Unpaid = 0, // 待支付
Pending = 1, // 待发货
Shipped = 2, // 已发货
Received = 3, // 已签收
Cancelled = 4 // 已取消
}
3. 订单项状态枚举
enum OrderItemStatus {
Pending = 0, // 待处理
Recovered = 1, // 已回收
Shipped = 2 // 已发货
}
4. 支付方式枚举
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. 集成测试
- 测试完整的订单查询流程
- 测试完整的发货操作流程
- 测试导出功能