修复：统一前后端的订单状态

2025-08-10 21:18:08 +08:00
parent 7074da30f4
commit f36d794a2a
10 changed files with 1603 additions and 31 deletions
--- a/docs/ORDER_FILTER_COMPARISON.md
+++ b/docs/ORDER_FILTER_COMPARISON.md
@@ -0,0 +1,245 @@
+# 订单筛选逻辑对比
+
+## 修改前后对比
+
+### 移动端筛选逻辑
+
+#### 修改前（复杂的前端筛选）
+
+```typescript
+// 原有的复杂筛选逻辑
+const getOrderStatusParams = (index: string | number) => {
+  let params: ShopOrderParam = {};
+  params.userId = Taro.getStorageSync('UserId');
+
+  const indexStr = String(index);
+  switch (indexStr) {
+    case '1': // 待付款
+      params.payStatus = 0; // 0表示未付款
+      break;
+    case '2': // 待发货
+      params.payStatus = 1; // 1表示已付款
+      params.deliveryStatus = 10; // 10表示未发货
+      break;
+    case '3': // 待收货
+      params.deliveryStatus = 20; // 20表示已发货
+      break;
+    case '4': // 已完成
+      params.orderStatus = 1; // 1表示已完成
+      break;
+    case '5': // 已取消
+      // 对于已取消的订单，获取所有数据然后在前端筛选
+      break;
+    case '0': // 全部
+    default:
+      // 全部订单，不添加额外的筛选条件
+      break;
+  }
+  return params;
+};
+
+// 前端二次筛选
+const filterOrdersByTab = (orders: OrderWithGoods[], tabIndex: number) => {
+  const indexStr = String(tabIndex);
+  return orders.filter(order => {
+    switch (indexStr) {
+      case '1': // 待付款
+        return !order.payStatus && !isCancelledOrder(order);
+      case '2': // 待发货
+        return order.payStatus && order.deliveryStatus === 10 && !isCancelledOrder(order);
+      case '3': // 待收货
+        return order.deliveryStatus === 20 && !isCancelledOrder(order);
+      case '4': // 已完成
+        return order.orderStatus === 1;
+      case '5': // 已取消
+        return isCancelledOrder(order);
+      case '0': // 全部
+      default:
+        return true;
+    }
+  });
+};
+
+// 复杂的取消状态判断
+const isCancelledOrder = (order: ShopOrder) => {
+  const cancelledStatuses = [2, 3, 4, 6, 7];
+  return cancelledStatuses.includes(order.orderStatus || 0);
+};
+```
+
+#### 修改后（统一的后端筛选）
+
+```typescript
+// 简化的统一筛选逻辑
+const tabs = [
+  {
+    index: 0,
+    statusFilter: undefined // 全部
+  },
+  {
+    index: 1,
+    statusFilter: 0 // 待付款
+  },
+  {
+    index: 2,
+    statusFilter: 1 // 待发货
+  },
+  {
+    index: 3,
+    statusFilter: 3 // 待收货
+  },
+  {
+    index: 4,
+    statusFilter: 5 // 已完成
+  },
+  {
+    index: 5,
+    statusFilter: 6 // 已取消/已退款
+  }
+];
+
+const getOrderStatusParams = (index: string | number) => {
+  let params: ShopOrderParam = {};
+  params.userId = Taro.getStorageSync('UserId');
+
+  const currentTab = tabs.find(tab => tab.index === Number(index));
+  if (currentTab && currentTab.statusFilter !== undefined) {
+    params.statusFilter = currentTab.statusFilter;
+  }
+
+  return params;
+};
+
+// 不再需要前端二次筛选，直接使用后端返回的数据
+```
+
+### 后台管理系统筛选逻辑
+
+#### 修改前
+
+```typescript
+// 注释不够清晰
+// 根据文档，statusFilter的值对应：
+// -1全部，0待付款，1待发货，2待核销，3待收货，4待评价，5已完成，6已退款，7已删除
+switch (activeKey.value) {
+  case 'all':
+    filterParams.statusFilter = -1; // 使用-1表示全部
+    break;
+  // ... 其他case
+}
+```
+
+#### 修改后
+
+```typescript
+// 更清晰的注释和实现
+// 根据后端 statusFilter 的值对应：
+// undefined全部，0待付款，1待发货，2待核销，3待收货，4待评价，5已完成，6已退款，7已删除
+switch (activeKey.value) {
+  case 'all':
+    // 全部订单：不传statusFilter参数
+    // filterParams.statusFilter = undefined; // 不设置该字段
+    break;
+  // ... 其他case保持一致
+}
+```
+
+## 主要改进点
+
+### 1. 性能优化
+
+| 方面 | 修改前 | 修改后 |
+|------|--------|--------|
+| 数据筛选位置 | 前端 + 后端 | 纯后端 |
+| 网络传输 | 传输所有数据再筛选 | 只传输筛选后的数据 |
+| 前端处理 | 复杂的二次筛选逻辑 | 直接使用后端数据 |
+| 查询效率 | 低（多次查询+前端筛选） | 高（单次精确查询） |
+
+### 2. 代码复杂度
+
+| 方面 | 修改前 | 修改后 |
+|------|--------|--------|
+| 筛选逻辑行数 | ~80行 | ~20行 |
+| 筛选条件数量 | 多个字段组合 | 单个statusFilter |
+| 维护难度 | 高（前后端都要维护） | 低（只需维护后端） |
+| 出错概率 | 高（逻辑复杂） | 低（逻辑简单） |
+
+### 3. 一致性保证
+
+| 方面 | 修改前 | 修改后 |
+|------|--------|--------|
+| 前端移动端 | 自定义筛选逻辑 | 使用statusFilter |
+| 后台管理系统 | 使用statusFilter | 使用statusFilter |
+| 数据一致性 | 可能不一致 | 完全一致 |
+| 维护成本 | 高（两套逻辑） | 低（统一逻辑） |
+
+## 具体的筛选条件对比
+
+### 待付款订单
+
+**修改前（移动端）：**
+```typescript
+// 后端查询
+params.payStatus = 0;
+
+// 前端再筛选
+return !order.payStatus && !isCancelledOrder(order);
+```
+
+**修改后：**
+```typescript
+// 只需后端查询
+params.statusFilter = 0; // 对应 pay_status = false
+```
+
+### 待发货订单
+
+**修改前（移动端）：**
+```typescript
+// 后端查询
+params.payStatus = 1;
+params.deliveryStatus = 10;
+
+// 前端再筛选
+return order.payStatus && order.deliveryStatus === 10 && !isCancelledOrder(order);
+```
+
+**修改后：**
+```typescript
+// 只需后端查询
+params.statusFilter = 1; // 对应 pay_status = true AND delivery_status = 10
+```
+
+### 已取消订单
+
+**修改前（移动端）：**
+```typescript
+// 后端查询所有数据
+// 无特定筛选条件
+
+// 前端复杂筛选
+const isCancelledOrder = (order: ShopOrder) => {
+  const cancelledStatuses = [2, 3, 4, 6, 7];
+  return cancelledStatuses.includes(order.orderStatus || 0);
+};
+return isCancelledOrder(order);
+```
+
+**修改后：**
+```typescript
+// 只需后端查询
+params.statusFilter = 6; // 对应 order_status = 6 (已退款)
+```
+
+## 迁移建议
+
+1. **立即可用**：新的移动端组件已经创建，可以直接使用
+2. **逐步替换**：可以先在新功能中使用，再逐步替换现有页面
+3. **测试验证**：建议先在测试环境验证各个筛选条件的正确性
+4. **性能监控**：关注查询性能的改善情况
+
+## 注意事项
+
+1. **移动端显示逻辑**：虽然筛选使用statusFilter，但显示的状态文本仍可以根据业务需求自定义
+2. **特殊状态处理**：某些复杂的状态组合可能需要在显示层面进行适配
+3. **向后兼容**：确保现有功能不受影响
--- a/docs/ORDER_STATUS_UNIFIED_FILTER.md
+++ b/docs/ORDER_STATUS_UNIFIED_FILTER.md
@@ -0,0 +1,192 @@
+# 订单状态筛选统一方案
+
+## 问题描述
+
+原先前端移动端和后台管理系统的订单状态筛选逻辑不一致：
+
+### 移动端原有问题：
+1. 使用多个字段组合进行筛选（payStatus, orderStatus, deliveryStatus）
+2. 在前端进行二次过滤，效率低下
+3. 筛选逻辑复杂，容易出错
+4. 与后端设计的 statusFilter 字段不一致
+
+### 后台管理系统：
+1. 已经使用 statusFilter 字段
+2. 但注释和实现有些不一致的地方
+
+## 解决方案
+
+统一使用后端的 `statusFilter` 字段进行订单状态筛选，所有前端页面都采用相同的筛选逻辑。
+
+## 后端 statusFilter 字段定义
+
+根据后端 `ShopOrderParam.java` 和 `ShopOrderMapper.xml` 的定义：
+
+```java
+@Schema(description = "订单状态筛选：-1全部，0待支付，1待发货，2待核销，3待收货，4待评价，5已完成，6已退款，7已删除")
+private Integer statusFilter;
+```
+
+## 统一的状态筛选映射表
+
+| statusFilter | 标签名称 | 后端筛选条件 | 说明 |
+|-------------|---------|-------------|------|
+| undefined   | 全部    | 无筛选条件   | 显示所有订单（包括已删除的） |
+| 0          | 待付款   | pay_status = false | 未付款的订单 |
+| 1          | 待发货   | pay_status = true AND delivery_status = 10 | 已付款但未发货 |
+| 2          | 待核销   | pay_status = true AND delivery_status = 10 | 与待发货相同（特定业务场景） |
+| 3          | 待收货   | pay_status = true AND delivery_status = 20 | 已发货待收货 |
+| 4          | 待评价   | order_status = 1 | 与已完成相同（特定业务场景） |
+| 5          | 已完成   | order_status = 1 | 订单已完成 |
+| 6          | 已退款   | order_status = 6 | 退款成功的订单 |
+| 7          | 已删除   | deleted = 1 | 已删除的订单 |
+
+## 前端实现
+
+### 移动端（React/Taro）
+
+```typescript
+// 统一的订单状态标签配置
+const tabs = [
+  {
+    index: 0,
+    key: '全部',
+    title: '全部',
+    description: '所有订单',
+    statusFilter: undefined // 不传statusFilter，显示所有订单
+  },
+  {
+    index: 1,
+    key: '待付款',
+    title: '待付款',
+    description: '等待付款的订单',
+    statusFilter: 0 // 对应后端：pay_status = false
+  },
+  {
+    index: 2,
+    key: '待发货',
+    title: '待发货',
+    description: '已付款待发货的订单',
+    statusFilter: 1 // 对应后端：pay_status = true AND delivery_status = 10
+  },
+  {
+    index: 3,
+    key: '待收货',
+    title: '待收货',
+    description: '已发货待收货的订单',
+    statusFilter: 3 // 对应后端：pay_status = true AND delivery_status = 20
+  },
+  {
+    index: 4,
+    key: '已完成',
+    title: '已完成',
+    description: '已完成的订单',
+    statusFilter: 5 // 对应后端：order_status = 1
+  },
+  {
+    index: 5,
+    key: '已取消',
+    title: '已取消',
+    description: '已取消/退款的订单',
+    statusFilter: 6 // 对应后端：order_status = 6 (已退款)
+  }
+]
+
+// 筛选参数生成
+const getOrderStatusParams = (index: string | number) => {
+  let params: ShopOrderParam = {};
+  params.userId = Taro.getStorageSync('UserId');
+
+  const currentTab = tabs.find(tab => tab.index === Number(index));
+  if (currentTab && currentTab.statusFilter !== undefined) {
+    params.statusFilter = currentTab.statusFilter;
+  }
+
+  return params;
+};
+```
+
+### 后台管理系统（Vue）
+
+```typescript
+const onTabs = () => {
+  const filterParams: Record<string, any> = {};
+
+  switch (activeKey.value) {
+    case 'all':
+      // 全部订单：不传statusFilter参数
+      break;
+    case 'unpaid':
+      filterParams.statusFilter = 0;
+      break;
+    case 'undelivered':
+      filterParams.statusFilter = 1;
+      break;
+    case 'unreceived':
+      filterParams.statusFilter = 3;
+      break;
+    case 'completed':
+      filterParams.statusFilter = 5;
+      break;
+    case 'refunded':
+      filterParams.statusFilter = 6;
+      break;
+    case 'deleted':
+      filterParams.statusFilter = 7;
+      break;
+  }
+
+  reload(filterParams);
+}
+```
+
+## 优化效果
+
+### 1. 性能提升
+- 筛选逻辑在后端执行，减少前端数据处理
+- 减少网络传输的数据量
+- 提高查询效率
+
+### 2. 代码简化
+- 移除前端复杂的筛选逻辑
+- 统一前后端筛选标准
+- 减少维护成本
+
+### 3. 一致性保证
+- 前端移动端和后台管理系统使用相同的筛选逻辑
+- 与后端设计保持一致
+- 避免数据不一致的问题
+
+## 注意事项
+
+### 1. 移动端特殊处理
+移动端可能需要将某些后端状态合并显示：
+- "已取消" 标签可以包含多种取消状态（orderStatus: 2,3,4,6,7）
+- 可以在前端显示时进行状态文本的转换，但筛选仍使用 statusFilter
+
+### 2. 向后兼容
+- 保持现有API接口不变
+- 逐步迁移现有代码
+- 确保不影响现有功能
+
+### 3. 测试验证
+- 验证各个状态筛选的正确性
+- 确认前后端数据一致性
+- 测试边界情况和异常处理
+
+## 迁移步骤
+
+1. **创建新的移动端组件**：使用统一的 statusFilter 逻辑
+2. **更新后台管理系统**：完善注释和实现细节
+3. **测试验证**：确保所有筛选功能正常工作
+4. **逐步替换**：将旧的移动端组件替换为新组件
+5. **清理代码**：移除不再使用的筛选逻辑
+
+## 相关文件
+
+- 移动端新组件：`src/views/shop/shopOrder/mobile/index.tsx`
+- 后台管理系统：`src/views/shop/shopOrder/index.vue`
+- API接口：`src/api/shop/shopOrder/index.ts`
+- 数据模型：`src/api/shop/shopOrder/model/index.ts`
+- 后端参数：`ShopOrderParam.java`
+- 后端SQL：`ShopOrderMapper.xml`