# 分销中心用户列表数据对接说明
## 📋 功能说明
小程序分销中心的"绑定用户"列表，包含三个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
+¥{{item.commission}}
订单 ¥{{item.orderAmount}}
{{item.status === 'expired' ? '已过期' : item.daysRemaining + '天'}}
```
**新代码**:
```xml
+¥{{item.commission}}
已购{{item.purchaseCount || 1}}次
已过期
{{item.expiryDate}}
{{item.daysRemaining}}天
```
---
## 📊 数据流向
```
后端 /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"
}
]
}
}
```
---
**✅ 分销中心用户列表数据已完全对接！支持显示购买次数和过期时间。**