soul-yongping/开发文档/8、部署/分销中心用户列表数据对接说明.md

# 分销中心用户列表数据对接说明

## 📋 功能说明

小程序分销中心的"绑定用户"列表，包含三个Tab：
1. **绑定中** - 当前活跃的绑定关系
2. **已付款** - 购买过商品的用户
3. **已过期** - 过期或取消的绑定

---

## 🔧 本次修改

### 1. 后端API优化（/api/referral/data）

**文件**: `app/api/referral/data/route.ts`

**修改内容**: 
- 在 `convertedUsers` 中添加 `purchaseCount`（购买次数）字段

```typescript
convertedUsers: convertedBindings.map((b: any) => ({
  id: b.referee_id,
  nickname: b.nickname,
  avatar: b.avatar,
  commission: parseFloat(b.commission_amount) || 0,
  orderAmount: parseFloat(b.order_amount) || 0,
  purchaseCount: parseInt(b.purchase_count) || 0,  // 新增
  conversionDate: b.conversion_date,
  status: 'converted'
}))
```

---

### 2. 小程序前端优化

#### 2.1 数据格式化（referral.js）

**文件**: `miniprogram/pages/referral/referral.js`

**修改内容**: 
```javascript
// formatUser 函数增强
const formatUser = (user, type) => {
  return {
    id: user.id,
    nickname: user.nickname,
    avatar: user.avatar,
    status: type,
    daysRemaining: user.daysRemaining || 0,
    bindingDate: this.formatDate(user.bindingDate),
    expiryDate: this.formatDate(user.expiryDate),  // 新增：过期时间
    commission: (user.commission || 0).toFixed(2),
    orderAmount: (user.orderAmount || 0).toFixed(2),
    purchaseCount: user.purchaseCount || 0,  // 新增：购买次数
    conversionDate: this.formatDate(user.conversionDate)  // 新增：转化时间
  }
}
```

---

#### 2.2 UI显示优化（referral.wxml）

**文件**: `miniprogram/pages/referral/referral.wxml`

**旧代码**:
```xml
<view class="user-status">
  <block wx:if="{{item.status === 'converted'}}">
    <text class="status-amount">+¥{{item.commission}}</text>
    <text class="status-order">订单 ¥{{item.orderAmount}}</text>
  </block>
  <block wx:else>
    <text class="status-tag">
      {{item.status === 'expired' ? '已过期' : item.daysRemaining + '天'}}
    </text>
  </block>
</view>
```

**新代码**:
```xml
<view class="user-status">
  <!-- 已付款：显示佣金 + 购买次数 -->
  <block wx:if="{{item.status === 'converted'}}">
    <text class="status-amount">+¥{{item.commission}}</text>
    <text class="status-order">已购{{item.purchaseCount || 1}}次</text>
  </block>
  
  <!-- 已过期：显示过期标签 + 过期时间 -->
  <block wx:elif="{{item.status === 'expired'}}">
    <text class="status-tag tag-gray">已过期</text>
    <text class="status-time">{{item.expiryDate}}</text>
  </block>
  
  <!-- 绑定中：显示剩余天数 -->
  <block wx:else>
    <text class="status-tag {{item.daysRemaining <= 3 ? 'tag-red' : item.daysRemaining <= 7 ? 'tag-orange' : 'tag-green'}}">
      {{item.daysRemaining}}天
    </text>
  </block>
</view>
```

---

## 📊 数据流向

```
后端 /api/referral/data
  ↓
返回三类用户数据
  ├─ activeUsers（绑定中）
  │   - daysRemaining（剩余天数）
  │   - bindingDate（绑定时间）
  │
  ├─ convertedUsers（已付款）
  │   - commission（佣金）
  │   - purchaseCount（购买次数）✨ 新增
  │   - conversionDate（转化时间）
  │
  └─ expiredUsers（已过期）
      - expiryDate（过期时间）
      - bindingDate（绑定时间）
  ↓
小程序接收并格式化
  ↓
分Tab显示
```

---

## 🎨 显示效果

### Tab 1: 绑定中
```
┌─────────────────────────────┐
│ [头像] 张三                  │
│        绑定于 02-01          │
│                       [15天]│
└─────────────────────────────┘
```

**显示内容**:
- 用户昵称
- 绑定时间
- 剩余天数（颜色标识：绿色>7天，橙色3-7天，红色≤3天）

---

### Tab 2: 已付款
```
┌─────────────────────────────┐
│ [✓] 李四                     │
│     绑定于 01-20             │
│              +¥0.90  已购1次│
└─────────────────────────────┘

┌─────────────────────────────┐
│ [✓] 王五                     │
│     绑定于 01-15             │
│              +¥2.70  已购3次│
└─────────────────────────────┘
```

**显示内容**:
- 用户昵称（头像显示✓）
- 绑定时间
- 累计佣金
- **购买次数**（✨ 新增）

**数据来源**:
```javascript
{
  commission: 0.90,        // 累计佣金
  purchaseCount: 1,        // 购买次数 ✨
  conversionDate: "2026-01-20"
}
```

---

### Tab 3: 已过期
```
┌─────────────────────────────┐
│ [⏰] 赵六                    │
│      绑定于 01-05            │
│              [已过期] 02-04│
└─────────────────────────────┘
```

**显示内容**:
- 用户昵称（头像显示⏰）
- 绑定时间
- 已过期标签
- **过期时间**（✨ 优化显示）

**数据来源**:
```javascript
{
  bindingDate: "2026-01-05",
  expiryDate: "2026-02-04"  // 显示具体过期日期
}
```

---

## 🔍 数据验证

### 测试场景1: 已付款用户（单次购买）
```json
{
  "nickname": "张三",
  "commission": 0.90,
  "purchaseCount": 1,
  "conversionDate": "2026-02-01"
}
```

**显示**: `+¥0.90  已购1次`

---

### 测试场景2: 已付款用户（多次购买）
```json
{
  "nickname": "李四",
  "commission": 2.70,
  "purchaseCount": 3,
  "conversionDate": "2026-01-20"
}
```

**显示**: `+¥2.70  已购3次`

---

### 测试场景3: 已过期用户
```json
{
  "nickname": "王五",
  "bindingDate": "2026-01-05",
  "expiryDate": "2026-02-04"
}
```

**显示**: 
- 标签：`已过期`
- 时间：`02-04`

---

## 🎯 优化亮点

### 1. 已付款用户
**旧显示**: 
```
+¥0.90
订单 ¥1.00
```
- ❌ 显示订单金额（用户可能多次购买，只显示一个金额不准确）

**新显示**: 
```
+¥0.90
已购1次
```
- ✅ 显示购买次数（更直观）
- ✅ 支持多次购买（已购3次）

---

### 2. 已过期用户
**旧显示**: 
```
[已过期]
```
- ❌ 只有标签，不知道什么时候过期

**新显示**: 
```
[已过期] 02-04
```
- ✅ 显示具体过期时间
- ✅ 用户可以看到过期日期

---

## 📊 后端数据说明

### convertedBindings 查询
```sql
SELECT 
  rb.referee_id,
  rb.purchase_count,           -- 购买次数
  rb.total_commission,          -- 累计佣金
  rb.last_purchase_date,        -- 最后购买时间
  u.nickname, u.avatar
FROM referral_bindings rb
JOIN users u ON rb.referee_id = u.id
WHERE rb.referrer_id = ? 
  AND rb.status = 'active' 
  AND rb.purchase_count > 0
ORDER BY rb.last_purchase_date DESC
```

**关键字段**:
- `purchase_count` - 购买次数（每次购买 +1）
- `total_commission` - 累计佣金（每次购买累加）
- `last_purchase_date` - 最后购买时间（用于排序）

---

### expiredBindings 查询
```sql
SELECT 
  rb.referee_id,
  rb.binding_date,              -- 绑定时间
  rb.expiry_date,               -- 过期时间
  u.nickname, u.avatar
FROM referral_bindings rb
JOIN users u ON rb.referee_id = u.id
WHERE rb.referrer_id = ? 
  AND (rb.status = 'expired' OR rb.status = 'cancelled')
ORDER BY rb.expiry_date DESC
```

**关键字段**:
- `binding_date` - 绑定时间
- `expiry_date` - 过期时间（显示在前端）
- `status` - expired（自然过期）或 cancelled（被切换）

---

## 🚀 部署步骤

### 1. 后端部署
```bash
pnpm build
python devlop.py
pm2 restart soul
```

### 2. 小程序上传
- 在微信开发者工具上传代码
- 提交审核
- 发布新版本

---

## ✅ 测试清单

### 已付款用户
- [ ] 显示累计佣金
- [ ] 显示购买次数
- [ ] 单次购买显示"已购1次"
- [ ] 多次购买显示"已购N次"
- [ ] 头像显示✓标记

### 已过期用户
- [ ] 显示"已过期"标签
- [ ] 显示过期时间
- [ ] 头像显示⏰标记
- [ ] 时间格式正确（MM-DD）

### 绑定中用户
- [ ] 显示剩余天数
- [ ] 颜色标识正确（绿/橙/红）
- [ ] 头像显示首字母

---

## 🎨 样式优化（可选）

如果需要调整样式，在 `referral.wxss` 中添加：

```css
/* 已过期时间显示 */
.status-time {
  font-size: 22rpx;
  color: #999;
  margin-top: 4rpx;
}

/* 灰色标签（已过期） */
.tag-gray {
  background: #f5f5f5;
  color: #999;
}
```

---

## 📝 API 返回数据示例

### 完整响应
```json
{
  "success": true,
  "data": {
    "activeUsers": [
      {
        "id": "user_123",
        "nickname": "张三",
        "avatar": "https://...",
        "daysRemaining": 15,
        "bindingDate": "2026-01-20T10:00:00.000Z",
        "status": "active"
      }
    ],
    "convertedUsers": [
      {
        "id": "user_456",
        "nickname": "李四",
        "avatar": "https://...",
        "commission": 0.90,
        "orderAmount": 1.00,
        "purchaseCount": 1,
        "conversionDate": "2026-02-01T14:30:00.000Z",
        "status": "converted"
      }
    ],
    "expiredUsers": [
      {
        "id": "user_789",
        "nickname": "王五",
        "avatar": "https://...",
        "bindingDate": "2026-01-05T08:00:00.000Z",
        "expiryDate": "2026-02-04T08:00:00.000Z",
        "status": "expired"
      }
    ]
  }
}
```

---

**✅ 分销中心用户列表数据已完全对接！支持显示购买次数和过期时间。**