template-10584/docs/COUPON_API_INTEGRATION.md

# 🎯 优惠券API集成更新

## 📊 后端接口分析

根据后端提供的接口，有三个专门的端点来获取不同状态的优惠券：

### 🔗 API端点

| 接口 | 路径 | 说明 | 返回数据 |
|------|------|------|----------|
| 获取可用优惠券 | `/my/available` | 获取我的可用优惠券 | `List<ShopUserCoupon>` |
| 获取已使用优惠券 | `/my/used` | 获取我的已使用优惠券 | `List<ShopUserCoupon>` |
| 获取已过期优惠券 | `/my/expired` | 获取我的已过期优惠券 | `List<ShopUserCoupon>` |

## 🔧 前端API函数实现

### 新增API函数

```typescript
/**
 * 获取我的可用优惠券
 */
export async function getMyAvailableCoupons() {
  const res = await request.get<ApiResult<ShopUserCoupon[]>>('/my/available');
  if (res.code === 0 && res.data) {
    return res.data;
  }
  return Promise.reject(new Error(res.message));
}

/**
 * 获取我的已使用优惠券
 */
export async function getMyUsedCoupons() {
  const res = await request.get<ApiResult<ShopUserCoupon[]>>('/my/used');
  if (res.code === 0 && res.data) {
    return res.data;
  }
  return Promise.reject(new Error(res.message));
}

/**
 * 获取我的已过期优惠券
 */
export async function getMyExpiredCoupons() {
  const res = await request.get<ApiResult<ShopUserCoupon[]>>('/my/expired');
  if (res.code === 0 && res.data) {
    return res.data;
  }
  return Promise.reject(new Error(res.message));
}
```

## 🚀 业务逻辑更新

### 1. **订单确认页面** (`src/shop/orderConfirm/index.tsx`)

#### 更新前
```typescript
// 使用通用接口 + 状态过滤
const res = await listShopUserCoupon({
  status: 0,
  validOnly: true
})
```

#### 更新后
```typescript
// 直接使用专门的可用优惠券接口
const res = await getMyAvailableCoupons()
```

#### 优势
- ✅ **性能提升**：后端直接返回可用优惠券，无需前端过滤
- ✅ **数据准确**：后端计算状态，避免前后端逻辑不一致
- ✅ **代码简化**：减少前端状态判断逻辑

### 2. **用户优惠券页面** (`src/user/coupon/index.tsx`)

#### 更新前
```typescript
// 使用分页接口 + 复杂的状态过滤
const res = await pageShopUserCoupon({
  page: currentPage,
  limit: 10,
  status: 0,
  isExpire: 0,
  // 其他过滤条件...
})
```

#### 更新后
```typescript
// 根据tab直接调用对应接口
switch (tab) {
  case '0': // 可用优惠券
    res = await getMyAvailableCoupons()
    break
  case '1': // 已使用优惠券
    res = await getMyUsedCoupons()
    break
  case '2': // 已过期优惠券
    res = await getMyExpiredCoupons()
    break
}
```

#### 数据处理优化
```typescript
// 前端处理搜索和筛选
if (searchValue) {
  filteredList = res.filter((item: any) => 
    item.name?.includes(searchValue) || 
    item.description?.includes(searchValue)
  )
}

// 前端排序
filteredList.sort((a: any, b: any) => {
  const aValue = getValueForSort(a, filters.sortBy)
  const bValue = getValueForSort(b, filters.sortBy)
  return filters.sortOrder === 'asc' ? aValue - bValue : bValue - aValue
})
```

### 3. **统计数据更新**

#### 更新前
```typescript
// 使用分页接口获取count
const [availableRes, usedRes, expiredRes] = await Promise.all([
  pageShopUserCoupon({page: 1, limit: 1, status: 0, isExpire: 0}),
  pageShopUserCoupon({page: 1, limit: 1, status: 1}),
  pageShopUserCoupon({page: 1, limit: 1, isExpire: 1})
])

setStats({
  available: availableRes?.count || 0,
  used: usedRes?.count || 0,
  expired: expiredRes?.count || 0
})
```

#### 更新后
```typescript
// 直接获取数据并计算长度
const [availableRes, usedRes, expiredRes] = await Promise.all([
  getMyAvailableCoupons(),
  getMyUsedCoupons(),
  getMyExpiredCoupons()
])

setStats({
  available: availableRes?.length || 0,
  used: usedRes?.length || 0,
  expired: expiredRes?.length || 0
})
```

## 📈 性能优化效果

### 网络请求优化
- ✅ **减少请求参数**：不需要复杂的状态过滤参数
- ✅ **减少数据传输**：后端直接返回目标数据
- ✅ **提高缓存效率**：专门的端点更容易缓存

### 前端处理优化
- ✅ **简化状态管理**：不需要复杂的状态过滤逻辑
- ✅ **提高响应速度**：减少前端数据处理时间
- ✅ **降低内存占用**：只加载需要的数据

## 🔍 数据流对比

### 更新前的数据流
```
前端请求 → 后端分页接口 → 返回所有数据 → 前端状态过滤 → 显示结果
```

### 更新后的数据流
```
前端请求 → 后端专门接口 → 返回目标数据 → 直接显示结果
```

## 🧪 测试要点

### 功能测试
1. **订单确认页面**
   - [ ] 优惠券列表正确加载
   - [ ] 只显示可用的优惠券
   - [ ] 优惠券选择功能正常

2. **用户优惠券页面**
   - [ ] 三个tab分别显示对应状态的优惠券
   - [ ] 统计数据正确显示
   - [ ] 搜索和筛选功能正常

3. **错误处理**
   - [ ] 网络异常时的错误提示
   - [ ] 空数据时的显示
   - [ ] 接口返回异常数据的处理

### 性能测试
1. **加载速度**
   - [ ] 页面初始化速度
   - [ ] tab切换响应速度
   - [ ] 数据刷新速度

2. **内存使用**
   - [ ] 数据加载后的内存占用
   - [ ] 页面切换时的内存释放

## 🚨 注意事项

### 1. **接口兼容性**
- 确保后端接口已经部署并可用
- 检查接口返回的数据结构是否符合预期
- 验证错误码和错误信息的处理

### 2. **数据一致性**
- 确保三个接口返回的数据状态正确
- 验证统计数据与列表数据的一致性
- 检查实时状态更新的准确性

### 3. **用户体验**
- 保持加载状态的显示
- 提供合适的错误提示
- 确保操作反馈及时

## 🎯 预期收益

### 开发效率
- ✅ **代码简化**：减少复杂的状态判断逻辑
- ✅ **维护便利**：业务逻辑更清晰
- ✅ **扩展性强**：易于添加新的状态类型

### 用户体验
- ✅ **响应更快**：减少数据处理时间
- ✅ **数据准确**：后端计算状态更可靠
- ✅ **功能稳定**：减少前端状态判断错误

### 系统性能
- ✅ **网络优化**：减少不必要的数据传输
- ✅ **服务器优化**：专门的查询更高效
- ✅ **缓存友好**：专门接口更容易缓存

**现在优惠券功能已经完全适配后端的专门接口，提供了更好的性能和用户体验！** 🎉