系统分销开发文档

1. 分销机制概述

CRMEB系统实现了完整的分销功能，支持二级分销、分销等级、佣金计算、分销申请审核等核心功能。分销系统通过推广关系链实现用户之间的推广和佣金分配，帮助商家扩大销售渠道，提高用户粘性。

1.1 核心功能

二级分销：支持一级和二级分销关系，可配置分销层级
分销等级：支持多级分销等级，不同等级享受不同的佣金比例
佣金计算：支持按商品售价比例计算佣金，可配置一二级佣金比例
自购返佣：支持用户自购返佣功能，可配置是否开启
分销申请：支持用户申请成为分销员，需管理员审核
分销关系管理：支持查看和管理用户的分销关系链
佣金提现：支持分销员申请提现佣金，管理员审核后发放

2. 核心组件

2.1 数据模型

AgentLevel：分销等级模型，定义分销等级信息和佣金比例
AgentLevelTask：分销等级任务模型，定义升级所需完成的任务
AgentLevelTaskRecord：分销等级任务记录模型，记录用户任务完成情况
User：用户模型，扩展了分销相关字段（spread_uid、agent_level等）
StoreOrder：订单模型，记录订单的佣金信息
UserExtract：用户提现模型，记录用户的提现申请
UserBrokerage：用户佣金模型，记录用户的佣金流水

2.2 服务层

AgentLevelServices：分销等级服务，处理分销等级的增删改查和升级逻辑
AgentManageServices：分销管理服务，处理分销员的管理和统计
UserServices：用户服务，扩展了分销相关功能
StoreOrderCreateServices：订单创建服务，处理订单佣金计算

2.3 控制器

AgentManage：分销员管理控制器，提供分销员列表和统计功能
AgentLevel：分销等级控制器，提供分销等级的管理功能
SpreadApply：分销申请控制器，处理用户的分销申请

3. 分销配置

3.1 系统配置项

分销功能的核心配置项在系统配置中管理，主要包括：

配置项	描述	默认值
brokerage_func_status	分销功能开关	0
store_brokerage_ratio	一级分销佣金比例	0
store_brokerage_two	二级分销佣金比例	0
brokerage_level	分销层级（1或2）	2
store_brokerage_statu	分销员申请开关	0
store_brokerage_binding_status	分销绑定模式	0
is_self_brokerage	是否开启自购返佣	0

3.2 配置示例

// 获取分销功能开关状态
sys_config('brokerage_func_status');

// 获取一级分销佣金比例
sys_config('store_brokerage_ratio');

// 获取二级分销佣金比例
sys_config('store_brokerage_two');

4. 分销等级

4.1 等级模型

分销等级模型定义了分销员的等级信息，包括佣金比例、升级条件等：

class AgentLevel extends BaseModel
{
    protected $pk = 'id';
    protected $name = 'agent_level';
    
    // 关联等级任务
    public function task()
    {
        return $this->hasMany(AgentLevelTask::class, 'level_id', 'id')->where('is_del', 0);
    }
}

4.2 等级升级机制

用户可以通过完成指定任务升级分销等级，享受更高的佣金比例：

// 检查用户等级任务完成情况
public function checkUserLevelFinish($uid)
{
    // 获取用户当前等级
    $userInfo = app()->make(UserServices::class)->getUserInfo($uid);
    if (!$userInfo) return false;
    
    // 获取下一级等级信息
    $levelList = $this->dao->getList(['is_del' => 0, 'status' => 1], '*', [], 0, 0, $userInfo['agent_level']);
    
    // 检查任务完成情况
    foreach ($levelList as $levelInfo) {
        // 获取等级任务
        $task_list = $levelInfo['task'] ?? [];
        
        // 检查每个任务是否完成
        foreach ($task_list as $task) {
            $levelTaskServices->checkLevelTaskFinish($uid, (int)$task['id'], $task);
        }
        
        // 统计完成的任务数量
        $finish_task = $levelTaskRecordServices->count([
            'level_id' => $levelInfo['id'], 
            'uid' => $uid, 
            'task_id' => array_column($task_list, 'id')
        ]);
        
        // 任务完成升级
        if ($finish_task >= $levelInfo['task_num']) {
            $userServices->update($uid, ['agent_level' => $levelInfo['id']]);
        }
    }
}

5. 佣金计算

5.1 佣金计算逻辑

佣金计算在订单创建时完成，根据商品售价和佣金比例计算：

public function computeOrderProductTruePrice($cartInfo, $priceData, $addressId, $uid, $orderInfo)
{
    // 获取分销佣金比例和返佣人员
    [$storeBrokerageRatio, $storeBrokerageTwo, $spread_one_uid, $spread_two_uid] = $this->getSpreadDate($uid);
    
    // 计算佣金
    if ($storeBrokerageRatio > 0 || $storeBrokerageTwo > 0 || $staffPercent > 0 || $agentPercent > 0 || $divisionPercent > 0) {
        // 计算商品售价
        $price = bcsub((string)$cart['truePrice'], (string)$cart['truePostage'], 2);
        
        // 计算一级佣金
        if ($storeBrokerageRatio > 0) {
            $brokerageRatio = bcdiv($storeBrokerageRatio, 100, 4);
            $oneBrokerage = bcmul((string)$price, (string)$brokerageRatio, 2);
        }
        
        // 计算二级佣金
        if ($storeBrokerageTwo > 0) {
            $brokerageTwo = bcdiv($storeBrokerageTwo, 100, 4);
            $twoBrokerage = bcmul((string)$price, (string)$brokerageTwo, 2);
        }
        
        // 记录佣金信息
        $cart['one_brokerage'] = $oneBrokerage;
        $cart['two_brokerage'] = $twoBrokerage;
    }
    
    return [$cartInfo, [$spread_one_uid, $spread_two_uid]];
}

5.2 分销层级控制

系统支持配置分销层级（1或2级），可根据配置调整佣金计算：

// 判断返佣层级为一级时，将二级用户uid和二级分佣比例改为0
if (sys_config('brokerage_level') == 1) {
    $storeBrokerageTwo = $spread_two_uid = 0;
}

5.3 自购返佣

系统支持配置用户自购返佣功能：

// 获取上级和上上级的uid，开启自购获取自己和上级的uid
$spread_one_uid = $userServices->getSpreadUid($uid, $userInfo);

6. 分销申请与审核

6.1 分销申请

用户可以申请成为分销员，申请信息存储在数据库中等待管理员审核：

// 分销申请接口
public function apply()
{
    // 检查分销功能是否开启
    if (!sys_config('brokerage_func_status')) {
        throw new ApiException(100209);
    }
    
    // 检查是否已经是分销员
    if ($this->services->checkUserPromoter($this->uid)) {
        throw new ApiException(100210);
    }
    
    // 提交申请
    $this->services->applySpread($this->uid, $this->request->post());
    
    return app('json')->success(100211);
}

6.2 申请审核

管理员可以审核用户的分销申请，审核通过后用户成为分销员：

// 分销申请审核接口
public function applyExamine($id, $uid, $status)
{
    // 检查参数
    if (!$id || !$uid || !in_array($status, [0, 1])) {
        throw new AdminException(100026);
    }
    
    // 审核申请
    $this->services->examineSpreadApply($id, $uid, $status);
    
    return app('json')->success(100014);
}

7. 分销关系管理

7.1 推广关系绑定

用户通过分享链接或二维码注册时，会自动绑定推广关系：

// 保存用户信息并绑定推广关系
public function setUserInfo($user, int $spreadUid = 0, string $userType = 'wechat')
{
    $data = [
        // 用户基本信息
        'nickname' => $user['nickname'] ?? '',
        'avatar' => $user['headimgurl'] ?? '',
        // ... 其他字段
    ];
    
    // 绑定推广关系
    if ($spreadUid) {
        $data['spread_uid'] = $spreadUid;
        $data['spread_time'] = time();
    }
    
    // 保存用户信息
    $res = $this->dao->save($data);
    
    // 触发用户注册事件
    event('UserRegisterListener', [$spreadUid, $userType, $user['nickname'], $res->uid, 1]);
    
    return $res;
}

7.2 推广关系查询

系统提供接口查询用户的推广关系链：

// 获取用户的一级和二级推广用户
public function getSpreadList(int $uid, array $where, bool $is_page = true)
{
    // 获取一级推广用户
    $one_list = $this->dao->getSpreadUserList($where, $uid, 1, $is_page);
    
    // 获取二级推广用户
    $two_list = $this->dao->getSpreadUserList($where, $uid, 2, $is_page);
    
    return ['one_list' => $one_list, 'two_list' => $two_list];
}

8. 分销等级任务

8.1 任务类型

系统支持多种分销等级任务类型：

推广人数：推广指定数量的用户
订单金额：完成指定金额的订单
订单数量：完成指定数量的订单
自购金额：自购指定金额的商品
自购数量：自购指定数量的商品

8.2 任务完成检查

系统会定期检查用户的任务完成情况，满足条件时自动升级：

// 检查任务完成情况
public function checkLevelTaskFinish($uid, $taskId, $task)
{
    // 根据任务类型检查完成情况
    switch ($task['type']) {
        case 1: // 推广人数
            $count = $this->dao->getSpreadUserCount($uid);
            break;
        case 2: // 订单金额
            $count = $this->dao->getUserOrderAmount($uid);
            break;
        case 3: // 订单数量
            $count = $this->dao->getUserOrderCount($uid);
            break;
        // ... 其他任务类型
    }
    
    // 更新任务完成记录
    if ($count >= $task['value']) {
        $this->taskRecordServices->updateTaskRecord($uid, $taskId);
    }
}

9. API接口

9.1 分销员管理接口

GET /api/admin/agent/manage/index：分销员列表
GET /api/admin/agent/manage/get_badge：分销员统计
GET /api/admin/agent/manage/get_stair_list：推广人列表

9.2 分销等级接口

GET /api/admin/agent/level/index：分销等级列表
POST /api/admin/agent/level/save：添加分销等级
PUT /api/admin/agent/level/update/:id：编辑分销等级

9.3 分销申请接口

GET /api/admin/agent/spread/apply/list：分销申请列表
POST /api/admin/agent/spread/apply/examine/:id/:uid/:status：分销申请审核

9.4 用户端接口

POST /api/user/spread/apply：用户申请成为分销员
GET /api/user/spread/list：获取推广用户列表
GET /api/user/agent/level_task_list：获取分销等级任务列表

10. 最佳实践

10.1 分销等级设计

合理设置等级数量：建议设置3-5个分销等级，过多等级会增加管理复杂度
梯度设置佣金比例：不同等级的佣金比例应该有明显差异，激励用户升级
设置合理的升级条件：升级条件应该具有可实现性，避免设置过高的门槛

10.2 佣金设置

合理设置佣金比例：根据商品利润率设置合理的佣金比例，避免影响商家利润
控制分销层级：建议使用二级分销，符合国家相关法规要求
开启自购返佣：可以提高用户的购买积极性，增加销售额

10.3 推广关系管理

明确推广规则：制定清晰的推广规则，避免用户之间的纠纷
定期清理无效关系：定期清理长期不活跃的推广关系，保持数据整洁
保护用户隐私：在展示推广关系时，注意保护用户的隐私信息

11. 常见问题

11.1 分销功能不生效

检查分销功能开关是否开启
检查佣金比例是否设置正确
检查用户是否具有推广资格

11.2 佣金计算错误

检查佣金比例设置是否正确
检查订单金额是否正确
检查分销层级设置是否正确

11.3 推广关系绑定失败

检查推广链接是否正确
检查推广参数是否传递正确
检查用户注册流程是否正确

11.4 分销等级不升级

检查升级条件是否设置正确
检查任务完成情况是否正确
检查升级逻辑是否存在bug

12. 总结

CRMEB系统的分销功能提供了完整的二级分销解决方案，支持分销等级、佣金计算、分销申请审核等核心功能。通过合理配置和使用分销功能，商家可以扩大销售渠道，提高用户粘性，实现销售增长。开发人员可以根据业务需求，基于现有框架扩展更多的分销功能，如三级分销、团队奖励等。

提示：该文档由AI生成，仅供参考。

系统分销开发文档.md 13 KB History Raw