docs: 更新优惠券相关文档- 新增优惠券API集成文档

- 新增优惠券卡片对齐修复文档 - 新增优惠券状态显示调试文档 - 新增优惠券组件警告修复文档- 更新用ShopInfo Hook字段迁移文档 - 更新Arguments关键字修复文档
2025-08-15 01:52:36 +08:00
parent dc87f644c9
commit 1b24a611a8
50 changed files with 6530 additions and 595 deletions
--- a/docs/COUPON_STATUS_DEBUG.md
+++ b/docs/COUPON_STATUS_DEBUG.md
@@ -0,0 +1,224 @@
+# 🐛 优惠券状态显示问题调试
+
+## 🔍 问题描述
+
+用户反馈优惠券显示"1过期"状态不对，应该显示正确的状态文本。
+
+## 📊 问题分析
+
+### 可能的原因
+
+1. **数据转换问题**：后端数据转换为前端格式时出错
+2. **状态文本缺失**：后端没有返回`statusText`字段
+3. **显示逻辑错误**：CouponCard组件的显示逻辑有问题
+4. **类型不匹配**：优惠券类型值不匹配导致显示异常
+
+## 🔧 已实施的修复
+
+### 1. **更新CouponCard组件状态显示逻辑**
+
+```typescript
+// 格式化有效期显示
+const formatValidityPeriod = () => {
+  // 第一优先级：使用后端返回的状态文本
+  if (statusText) {
+    return statusText
+  }
+  
+  // 第二优先级：根据状态码显示
+  if (status === 2) {
+    return '已过期'
+  }
+  
+  if (status === 1) {
+    return '已使用'
+  }
+  
+  // 第三优先级：使用后端计算的剩余时间
+  if (isExpiringSoon && daysRemaining !== undefined) {
+    if (daysRemaining <= 0 && hoursRemaining !== undefined) {
+      return `${hoursRemaining}小时后过期`
+    }
+    return `${daysRemaining}天后过期`
+  }
+  
+  // 兜底逻辑：使用前端计算
+  // ...
+}
+```
+
+### 2. **统一数据转换函数**
+
+```typescript
+// 使用统一的转换函数
+const transformCouponDataWithAction = (coupon: ShopUserCoupon): CouponCardProps => {
+  console.log('原始优惠券数据:', coupon)
+  
+  // 使用统一的转换函数
+  const transformedCoupon = transformCouponData(coupon)
+  
+  console.log('转换后的优惠券数据:', transformedCoupon)
+  
+  // 添加使用按钮和点击事件
+  const result = {
+    ...transformedCoupon,
+    showUseBtn: transformedCoupon.status === 0,
+    onUse: () => handleUseCoupon(coupon)
+  }
+  
+  console.log('最终优惠券数据:', result)
+  return result
+}
+```
+
+### 3. **修复类型值匹配**
+
+```typescript
+// CouponCardProps接口更新
+export interface CouponCardProps {
+  type?: 10 | 20 | 30;  // 更新为后端使用的类型值
+  statusText?: string;   // 添加状态文本字段
+  // ...其他字段
+}
+
+// CouponCard组件类型处理更新
+const formatAmount = () => {
+  switch (type) {
+    case 10: // 满减券
+      return `¥${amount}`
+    case 20: // 折扣券
+      return `${amount}折`
+    case 30: // 免费券
+      return '免费'
+    default:
+      return `¥${amount}`
+  }
+}
+```
+
+## 🧪 调试步骤
+
+### 1. **检查后端数据**
+
+在浏览器开发者工具中查看网络请求：
+
+```javascript
+// 检查API返回的数据结构
+{
+  "code": 0,
+  "data": [
+    {
+      "id": "123",
+      "name": "测试优惠券",
+      "type": 10,           // 优惠券类型
+      "status": 0,          // 使用状态
+      "statusText": "可用",  // 状态文本 ← 检查这个字段
+      "isExpire": 0,        // 是否过期
+      "reducePrice": "5",   // 减免金额
+      "minPrice": "20",     // 最低消费
+      "startTime": "2024-01-01",
+      "endTime": "2024-12-31",
+      "isExpiringSoon": false,
+      "daysRemaining": 30,
+      "hoursRemaining": null
+    }
+  ]
+}
+```
+
+### 2. **检查控制台日志**
+
+查看浏览器控制台中的调试信息：
+
+```javascript
+// 应该看到这些日志
+原始优惠券数据: { id: "123", name: "测试优惠券", ... }
+转换后的优惠券数据: { id: "123", amount: 5, type: 10, statusText: "可用", ... }
+最终优惠券数据: { id: "123", amount: 5, type: 10, statusText: "可用", showUseBtn: true, ... }
+```
+
+### 3. **检查组件渲染**
+
+在CouponCard组件中添加调试信息：
+
+```typescript
+console.log('CouponCard props:', {
+  id,
+  amount,
+  type,
+  status,
+  statusText,
+  title,
+  isExpiringSoon,
+  daysRemaining
+})
+
+console.log('formatValidityPeriod result:', formatValidityPeriod())
+```
+
+## 🔍 常见问题排查
+
+### 问题1：显示"1过期"而不是"已过期"
+
+**可能原因**：
+- 后端没有返回`statusText`字段
+- `statusText`字段值不正确
+- 前端显示逻辑有误
+
+**排查方法**：
+1. 检查网络请求中的`statusText`字段
+2. 检查控制台中的转换日志
+3. 确认CouponCard组件接收到的props
+
+### 问题2：优惠券类型显示错误
+
+**可能原因**：
+- 类型值不匹配（1,2,3 vs 10,20,30）
+- 转换函数逻辑错误
+
+**排查方法**：
+1. 检查后端返回的`type`字段值
+2. 确认转换函数中的类型映射
+3. 检查CouponCard组件的类型处理
+
+### 问题3：状态判断错误
+
+**可能原因**：
+- `status`和`isExpire`字段逻辑冲突
+- 状态优先级处理错误
+
+**排查方法**：
+1. 检查后端状态字段的含义
+2. 确认前端状态判断逻辑
+3. 验证不同状态的显示效果
+
+## 🎯 预期修复效果
+
+### 修复前
+```
+显示：¥5 无门槛 测试 1过期 [立即使用]
+```
+
+### 修复后
+```
+显示：¥5 无门槛 测试优惠券 1天后过期 [立即使用]
+或者：¥5 无门槛 测试优惠券 已过期 [不显示按钮]
+```
+
+## 📝 测试清单
+
+- [ ] 可用优惠券显示正确的剩余时间
+- [ ] 已使用优惠券显示"已使用"
+- [ ] 已过期优惠券显示"已过期"
+- [ ] 即将过期优惠券显示"X天后过期"
+- [ ] 优惠券类型和金额显示正确
+- [ ] 使用按钮只在可用状态显示
+
+## 🚀 下一步行动
+
+1. **测试修复效果**：重新加载页面，检查优惠券状态显示
+2. **验证数据流**：确认从API到组件的数据传递正确
+3. **完善错误处理**：添加数据异常时的兜底显示
+4. **优化用户体验**：确保状态变化时的实时更新
+
+**如果问题仍然存在，请检查浏览器控制台中的调试日志，并提供具体的错误信息。** 🔍