soul-yongping/开发文档/8、部署/提现卡片数据优化说明.md

# 提现卡片数据优化说明

## 一、修改需求

**用户需求**：
1. **累计佣金**：显示用户获得的所有佣金总额（包括可提现、待审核、已提现的所有佣金）
2. **待审核金额**：显示当前已发起提现申请但还未审核的金额累计总和（`withdrawals` 表中 `status = 'pending'` 的金额）
3. **可提现金额**：显示可以发起提现的金额（即 `users.pending_earnings`）

## 二、数据定义

### 1. 原数据结构

| 字段 | 原定义 | 问题 |
|------|--------|------|
| `users.earnings` | 已结算收益 | 不够直观 |
| `users.pending_earnings` | 待结算收益 | 命名容易误解，实际是可提现金额 |
| `users.withdrawn_earnings` | 已提现金额 | ✅ 正确 |

### 2. 新数据结构

| 字段 | 新定义 | 说明 |
|------|--------|------|
| **累计佣金** (`totalCommission`) | `earnings` + `pending_earnings` + `withdrawn_earnings` | 所有获得的佣金总额 |
| **可提现金额** (`availableEarnings`) | `pending_earnings` | 未申请提现的佣金，可以发起提现 |
| **待审核金额** (`pendingWithdrawAmount`) | `SUM(withdrawals.amount) WHERE status='pending'` | 已发起提现但未审核的金额 |
| **已提现金额** (`withdrawnEarnings`) | `withdrawn_earnings` | 已成功提现的金额 |

### 3. 业务流程

```
用户获得佣金 
  ↓
累计佣金 +X
可提现金额 +X (pending_earnings)
  ↓
用户发起提现申请
  ↓
可提现金额 -X (pending_earnings)
待审核金额 +X (withdrawals.status='pending')
  ↓
管理员审核通过
  ↓
待审核金额 -X (withdrawals.status='success')
已提现金额 +X (withdrawn_earnings)
累计佣金不变
```

## 三、代码修改

### 1. 后端 API 修改 (`app/api/referral/data/route.ts`)

#### 添加待审核金额查询

```typescript
// 7. 获取待审核提现金额
let pendingWithdrawAmount = 0
try {
  const pendingResult = await query(`
    SELECT COALESCE(SUM(amount), 0) as pending_amount
    FROM withdrawals
    WHERE user_id = ? AND status = 'pending'
  `, [userId]) as any[]
  pendingWithdrawAmount = parseFloat(pendingResult[0]?.pending_amount || 0)
} catch (e) {
  console.log('[ReferralData] 获取待审核提现金额失败:', e)
}
```

#### 修改返回数据

```typescript
// === 收益数据 ===
// 累计佣金总额（所有获得的佣金）
totalCommission: Math.round((
  (parseFloat(user.earnings) || 0) + 
  (parseFloat(user.pending_earnings) || 0) + 
  (parseFloat(user.withdrawn_earnings) || 0)
) * 100) / 100,
// 可提现金额（pending_earnings）
availableEarnings: parseFloat(user.pending_earnings) || 0,
// 待审核金额（提现申请中的金额）
pendingWithdrawAmount: Math.round(pendingWithdrawAmount * 100) / 100,
// 已提现金额
withdrawnEarnings: parseFloat(user.withdrawn_earnings) || 0,
// 已结算收益（保留兼容）
earnings: parseFloat(user.earnings) || 0,
// 待结算收益（保留兼容）
pendingEarnings: parseFloat(user.pending_earnings) || 0,
```

### 2. 小程序前端修改

#### 数据字段 (`miniprogram/pages/referral/referral.js`)

```javascript
data: {
  // === 收益数据 ===
  totalCommission: 0,   // 累计佣金总额（所有获得的佣金）
  availableEarnings: 0, // 可提现金额（未申请提现的佣金）
  pendingWithdrawAmount: 0, // 待审核金额（已申请提现但未审核）
  withdrawnEarnings: 0, // 已提现金额
  earnings: 0,          // 已结算收益（保留兼容）
  pendingEarnings: 0,   // 待结算收益（保留兼容）
  shareRate: 90,        // 分成比例（90%）
  minWithdrawAmount: 10, // 最低提现金额（从后端获取）
}
```

#### 数据更新逻辑

```javascript
this.setData({
  // 收益数据 - 格式化为两位小数
  totalCommission: formatMoney(realData?.totalCommission || 0),
  availableEarnings: formatMoney(realData?.availableEarnings || 0),
  pendingWithdrawAmount: formatMoney(realData?.pendingWithdrawAmount || 0),
  withdrawnEarnings: formatMoney(realData?.withdrawnEarnings || 0),
  earnings: formatMoney(realData?.earnings || 0),
  pendingEarnings: formatMoney(realData?.pendingEarnings || 0),
  shareRate: realData?.shareRate || 90,
  minWithdrawAmount: realData?.minWithdrawAmount || 10,
})
```

#### 提现逻辑修改

```javascript
async handleWithdraw() {
  const availableEarnings = parseFloat(this.data.availableEarnings) || 0
  const minWithdrawAmount = this.data.minWithdrawAmount || 10
  
  if (availableEarnings <= 0) {
    wx.showToast({ title: '暂无可提现收益', icon: 'none' })
    return
  }
  
  // 检查是否达到最低提现金额
  if (availableEarnings < minWithdrawAmount) {
    wx.showToast({ 
      title: `满${minWithdrawAmount}元可提现`, 
      icon: 'none' 
    })
    return
  }
  
  // 确认提现
  wx.showModal({
    title: '确认提现',
    content: `将提现 ¥${availableEarnings.toFixed(2)} 到您的微信零钱`,
    confirmText: '立即提现',
    success: async (res) => {
      if (res.confirm) {
        await this.doWithdraw(availableEarnings)
      }
    }
  })
}
```

### 3. UI 界面修改 (`miniprogram/pages/referral/referral.wxml`)

```xml
<!-- 收益卡片 - 对齐 Next.js -->
<view class="earnings-card">
  <view class="earnings-bg"></view>
  <view class="earnings-main">
    <view class="earnings-header">
      <view class="earnings-left">
        <view class="wallet-icon">
          <image class="icon-wallet" src="/assets/icons/wallet.svg" mode="aspectFit"></image>
        </view>
        <view class="earnings-info">
          <text class="earnings-label">累计佣金</text>
          <text class="commission-rate">{{shareRate}}% 返利</text>
        </view>
      </view>
      <view class="earnings-right">
        <text class="earnings-value">¥{{totalCommission}}</text>
        <text class="pending-text">待审核: ¥{{pendingWithdrawAmount}}</text>
      </view>
    </view>
    <view class="withdraw-btn {{availableEarnings < minWithdrawAmount ? 'btn-disabled' : ''}}" bindtap="handleWithdraw">
      {{availableEarnings < minWithdrawAmount ? '满' + minWithdrawAmount + '元可提现' : '申请提现 ¥' + availableEarnings}}
    </view>
  </view>
</view>
```

### 4. 界面变化对比

| 位置 | 原显示 | 新显示 | 说明 |
|------|--------|--------|------|
| 卡片标题 | 累计收益 | 累计佣金 | 更准确的描述 |
| 主金额 | `earnings` | `totalCommission` | 显示所有佣金总和 |
| 副金额标签 | "待结算" | "待审核" | 更明确的状态描述 |
| 副金额 | `pendingEarnings` | `pendingWithdrawAmount` | 显示提现申请中的金额 |
| 按钮文案 | "申请提现" | "申请提现 ¥XX" | 显示可提现金额 |
| 按钮禁用 | `pendingEarnings < minWithdrawAmount` | `availableEarnings < minWithdrawAmount` | 使用可提现金额判断 |

## 四、验证方法

### 1. 数据库检查

```sql
-- 查看用户收益数据
SELECT 
  id,
  nickname,
  earnings,
  pending_earnings,
  withdrawn_earnings,
  (earnings + pending_earnings + withdrawn_earnings) as total_commission
FROM users
WHERE id = 'user_xxx';

-- 查看待审核提现金额
SELECT 
  user_id,
  SUM(amount) as pending_amount
FROM withdrawals
WHERE status = 'pending'
GROUP BY user_id;
```

### 2. API 测试

```bash
# 测试接口
curl -X GET "http://localhost:3000/api/referral/data" \
  -H "Cookie: auth_token=xxx"
```

**期望返回数据**：
```json
{
  "success": true,
  "data": {
    "totalCommission": 100.00,        // 累计佣金 = 30 + 50 + 20
    "availableEarnings": 50.00,       // 可提现 = pending_earnings
    "pendingWithdrawAmount": 20.00,   // 待审核 = SUM(withdrawals WHERE status='pending')
    "withdrawnEarnings": 30.00,       // 已提现
    "earnings": 30.00,                // 已结算（保留兼容）
    "pendingEarnings": 50.00,         // 待结算（保留兼容）
    "shareRate": 90,
    "minWithdrawAmount": 10
  }
}
```

### 3. 小程序测试

1. **查看提现卡片**
   - ✅ 累计佣金显示正确（所有佣金总和）
   - ✅ 待审核金额显示正确（提现申请中的金额）
   - ✅ 提现按钮显示可提现金额

2. **发起提现**
   - ✅ 提现按钮使用 `availableEarnings` 判断是否可用
   - ✅ 提现金额为 `availableEarnings`
   - ✅ 提现后，`availableEarnings` 减少，`pendingWithdrawAmount` 增加

3. **管理员审核后**
   - ✅ `pendingWithdrawAmount` 减少
   - ✅ `withdrawnEarnings` 增加
   - ✅ `totalCommission` 保持不变

## 五、注意事项

### 1. 向后兼容

为了保证系统稳定，保留了原有的 `earnings` 和 `pendingEarnings` 字段，仅在小程序中使用新字段。

### 2. 提现流程

用户发起提现时，系统会：
1. 扣减 `users.pending_earnings`
2. 创建 `withdrawals` 记录（`status = 'pending'`）
3. 管理员审核通过后，`withdrawals.status` 改为 `'success'`
4. 同时增加 `users.withdrawn_earnings`

### 3. 数据一致性

确保以下等式始终成立：
```
totalCommission = availableEarnings + pendingWithdrawAmount + withdrawnEarnings
```

### 4. 前端显示

所有金额都使用 `formatMoney()` 函数格式化为两位小数。

## 六、影响范围

### 修改文件

1. **后端**
   - `app/api/referral/data/route.ts` - 添加 `pendingWithdrawAmount` 查询和返回字段

2. **小程序**
   - `miniprogram/pages/referral/referral.js` - 数据字段和提现逻辑
   - `miniprogram/pages/referral/referral.wxml` - UI 显示

### 不影响

- ❌ 提现流程逻辑（`/api/withdraw`）
- ❌ 管理后台（仍使用原字段）
- ❌ 佣金计算逻辑（`/api/payment/*/notify`）
- ❌ 数据库表结构（无需修改）

## 七、测试场景

### 场景 1：新用户获得佣金

```
初始状态：
- totalCommission = 0
- availableEarnings = 0
- pendingWithdrawAmount = 0
- withdrawnEarnings = 0

用户 A 购买了 100 元的书籍，推荐人 B 获得 90 元佣金：
- totalCommission = 90
- availableEarnings = 90
- pendingWithdrawAmount = 0
- withdrawnEarnings = 0
```

### 场景 2：用户发起提现

```
用户 B 发起提现 90 元：
- totalCommission = 90（不变）
- availableEarnings = 0（减少 90）
- pendingWithdrawAmount = 90（增加 90）
- withdrawnEarnings = 0
```

### 场景 3：管理员审核通过

```
管理员审核通过，打款成功：
- totalCommission = 90（不变）
- availableEarnings = 0
- pendingWithdrawAmount = 0（减少 90）
- withdrawnEarnings = 90（增加 90）
```

### 场景 4：管理员拒绝提现

```
管理员拒绝提现：
- totalCommission = 90（不变）
- availableEarnings = 90（恢复 90）
- pendingWithdrawAmount = 0（减少 90）
- withdrawnEarnings = 0
```

## 八、总结

此次优化主要解决了提现卡片数据定义不清晰的问题：

1. **累计佣金**：直观展示用户获得的所有佣金
2. **可提现金额**：明确告知用户可以发起提现的金额
3. **待审核金额**：让用户清楚知道有多少提现申请正在处理中

优化后的界面更加清晰、易懂，用户体验更佳！