442 lines
9.6 KiB
Markdown
442 lines
9.6 KiB
Markdown
# 分销中心用户列表数据对接说明
|
||
|
||
## 📋 功能说明
|
||
|
||
小程序分销中心的"绑定用户"列表，包含三个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"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
**✅ 分销中心用户列表数据已完全对接！支持显示购买次数和过期时间。**
|