团队模块接口

1. 概述

团队模块对外提供一系列服务接口，用于管理用户推荐关系、达人等级和团队收益分成。这些接口主要供其他模块调用，实现模块间的交互和数据共享。本文档详细说明了团队模块提供的服务接口、参数和返回值。

2. 接口规范

2.1 接口命名规范

接口方法名采用驼峰命名法，如createReferralRelation
接口方法名应清晰表达功能，动词开头，如getUserReferrers
查询类接口使用get前缀，如getUserTalentInfo
创建类接口使用create前缀，如createReferralCode
更新类接口使用update前缀，如updateUserTalent
删除类接口使用delete前缀，如deleteReferralRelation
检查类接口使用check前缀，如checkReferralCode

2.2 参数规范

必选参数放在前面，可选参数放在后面
参数类型明确，使用强类型
复杂参数使用数组或对象传递
敏感参数不直接暴露，如密码等

2.3 返回值规范

返回值类型明确，使用强类型
成功操作返回布尔值或操作结果
查询操作返回数据对象或数组
异常情况抛出异常，不返回错误码

2.4 异常处理

业务异常使用自定义异常类，如ReferralException
异常信息清晰明确，便于定位问题
异常包含错误码和错误信息
调用方需捕获并处理异常

3. 推荐关系服务接口 (ReferralService)

3.1 建立推荐关系

/**
 * 建立推荐关系
 * 
 * @param int $userId 用户ID
 * @param int $referrerId 推荐人ID
 * @return bool 是否成功
 * @throws UserNotFoundException 用户不存在异常
 * @throws ReferralException 推荐关系异常
 */
public function createReferralRelation(int $userId, int $referrerId): bool;

功能说明：

建立用户与推荐人之间的推荐关系
同时建立直推和间推关系
更新推荐人的直推人数和团队总人数
触发检查达人等级

调用示例：

try {
    $result = $referralService->createReferralRelation(1001, 1000);
    if ($result) {
        // 推荐关系建立成功
    }
} catch (UserNotFoundException $e) {
    // 用户不存在
} catch (ReferralException $e) {
    // 推荐关系异常
}

3.2 获取用户的推荐人

/**
 * 获取用户的推荐人
 * 
 * @param int $userId 用户ID
 * @param int $level 推荐层级(1=直推,2=间推,0=全部)
 * @return array 推荐人列表
 */
public function getUserReferrers(int $userId, int $level = 0): array;

功能说明：

获取用户的所有推荐人（上级）
可以指定只获取直推或间推关系
返回推荐人的基本信息和推荐关系

调用示例：

// 获取所有推荐人
$allReferrers = $referralService->getUserReferrers(1001);

// 只获取直推推荐人
$directReferrers = $referralService->getUserReferrers(1001, 1);

3.3 获取用户的团队成员

/**
 * 获取用户的团队成员
 * 
 * @param int $userId 用户ID
 * @param int $level 推荐层级(1=直推,2=间推,0=全部)
 * @param int $page 页码
 * @param int $pageSize 每页数量
 * @return array 团队成员列表和分页信息
 */
public function getPromotionMembers(int $userId, int $level = 0, int $page = 1, int $pageSize = 20): array;

功能说明：

获取用户的所有团队成员（下级）
可以指定只获取直推或间推成员
支持分页查询
返回团队成员的基本信息和推荐关系

调用示例：

// 获取所有团队成员，第1页，每页20条
$allMembers = $referralService->getPromotionMembers(1000);

// 只获取直推成员，第1页，每页50条
$directMembers = $referralService->getPromotionMembers(1000, 1, 1, 50);

3.4 检查推荐关系

/**
 * 检查用户是否是另一用户的推荐人
 * 
 * @param int $userId 用户ID
 * @param int $memberId 成员ID
 * @param int $level 推荐层级(1=直推,2=间推,0=任意层级)
 * @return bool 是否存在推荐关系
 */
public function checkReferralRelation(int $userId, int $memberId, int $level = 0): bool;

功能说明：

检查用户是否是另一用户的推荐人
可以指定检查直推或间推关系
返回布尔值表示是否存在推荐关系

调用示例：

// 检查用户1000是否是用户1001的推荐人（任意层级）
$isReferrer = $referralService->checkReferralRelation(1000, 1001);

// 检查用户1000是否是用户1001的直推推荐人
$isDirectReferrer = $referralService->checkReferralRelation(1000, 1001, 1);

3.5 生成推荐码

/**
 * 生成用户推荐码
 * 
 * @param int $userId 用户ID
 * @return string 推荐码
 * @throws UserNotFoundException 用户不存在异常
 */
public function generateReferralCode(int $userId): string;

功能说明：

为用户生成唯一的推荐码
如果用户已有推荐码，则返回现有推荐码
推荐码可用于邀请新用户注册

调用示例：

try {
    $code = $referralService->generateReferralCode(1000);
    // 生成的推荐码
} catch (UserNotFoundException $e) {
    // 用户不存在
}

3.6 验证推荐码

/**
 * 验证推荐码并获取推荐人ID
 * 
 * @param string $code 推荐码
 * @return int|null 推荐人ID，无效返回null
 */
public function verifyReferralCode(string $code): ?int;

功能说明：

验证推荐码的有效性
返回推荐码对应的用户ID
无效推荐码返回null

调用示例：

$referrerId = $referralService->verifyReferralCode('ABC123');
if ($referrerId !== null) {
    // 有效的推荐码，获取到推荐人ID
} else {
    // 无效的推荐码
}

4. 达人等级服务接口 (TalentService)

4.1 获取用户达人信息

/**
 * 获取用户达人信息
 * 
 * @param int $userId 用户ID
 * @return array 达人信息
 */
public function getUserTalentInfo(int $userId): array;

功能说明：

获取用户的达人等级信息
包括达人等级、直推人数、团队总人数等
同时返回达人等级对应的权益信息

调用示例：

$talentInfo = $talentService->getUserTalentInfo(1000);
// 达人信息数组

4.2 检查并更新达人等级

/**
 * 检查并更新用户达人等级
 * 
 * @param int $userId 用户ID
 * @return bool 是否有等级变化
 */
public function checkAndUpdateTalentLevel(int $userId): bool;

功能说明：

检查用户的团队规模，计算新的达人等级
如果等级有变化，更新用户的达人等级
等级提升时触发达人升级事件

调用示例：

$levelChanged = $talentService->checkAndUpdateTalentLevel(1000);
if ($levelChanged) {
    // 达人等级有变化
}

4.3 获取达人等级配置

/**
 * 获取达人等级配置
 * 
 * @param int $level 达人等级，0表示获取所有等级
 * @return array 达人等级配置
 */
public function getTalentLevelConfig(int $level = 0): array;

功能说明：

获取指定达人等级的配置信息
包括等级名称、升级条件、权益等
可以获取所有等级的配置信息

调用示例：

// 获取所有达人等级配置
$allConfigs = $talentService->getTalentLevelConfig();

// 获取3级达人的配置
$level3Config = $talentService->getTalentLevelConfig(3);

4.4 获取达人等级分成比例

/**
 * 获取达人等级的间推分成比例
 * 
 * @param int $level 达人等级
 * @return float 分成比例
 */
public function getTalentProfitRate(int $level): float;

功能说明：

获取指定达人等级的间推分成比例
用于计算团队收益分成
非达人（0级）返回0

调用示例：

// 获取3级达人的分成比例
$rate = $talentService->getTalentProfitRate(3);
// 返回0.02 (2%)

5. 团队收益服务接口 (PromotionProfitService)

5.1 计算团队收益分成

/**
 * 计算团队收益分成
 * 
 * @param int $userId 产生收益的用户ID
 * @param string $sourceType 收益来源类型
 * @param int $sourceId 收益来源ID
 * @param int $itemId 物品ID
 * @param int $amount 收益数量
 * @return bool 是否成功
 */
public function calculatePromotionProfit(int $userId, string $sourceType, int $sourceId, int $itemId, int $amount): bool;

功能说明：

计算用户产生收益时的团队分成
根据推荐关系和达人等级计算分成比例
记录分成收益并添加到推荐人账户
支持多种收益来源类型

调用示例：

// 用户1001收获农场作物，产生100个物品ID为2001的收益
$result = $promotionProfitService->calculatePromotionProfit(1001, 'farm_harvest', 5001, 2001, 100);
if ($result) {
    // 分成计算成功
}

5.2 获取用户团队收益统计

/**
 * 获取用户团队收益统计
 * 
 * @param int $userId 用户ID
 * @param string $sourceType 收益来源类型，空字符串表示所有类型
 * @param string $timeRange 时间范围(today,yesterday,week,month,all)
 * @return array 收益统计
 */
public function getUserPromotionProfitStats(int $userId, string $sourceType = '', string $timeRange = 'all'): array;

功能说明：

获取用户的团队收益统计数据
可以按收益来源类型和时间范围筛选
返回总收益、直推收益、间推收益等统计数据

调用示例：

// 获取用户1000的所有团队收益统计
$allStats = $promotionProfitService->getUserPromotionProfitStats(1000);

// 获取用户1000的本月农场收益统计
$farmMonthStats = $promotionProfitService->getUserPromotionProfitStats(1000, 'farm_harvest', 'month');

5.3 获取用户团队收益记录

/**
 * 获取用户团队收益记录
 * 
 * @param int $userId 用户ID
 * @param string $sourceType 收益来源类型，空字符串表示所有类型
 * @param int $page 页码
 * @param int $pageSize 每页数量
 * @return array 收益记录和分页信息
 */
public function getUserPromotionProfitRecords(int $userId, string $sourceType = '', int $page = 1, int $pageSize = 20): array;

功能说明：

获取用户的团队收益详细记录
可以按收益来源类型筛选
支持分页查询
返回收益记录的详细信息

调用示例：

// 获取用户1000的所有团队收益记录，第1页，每页20条
$allRecords = $promotionProfitService->getUserPromotionProfitRecords(1000);

// 获取用户1000的农场收益记录，第1页，每页50条
$farmRecords = $promotionProfitService->getUserPromotionProfitRecords(1000, 'farm_harvest', 1, 50);

5.4 获取收益分成规则

/**
 * 获取收益分成规则
 * 
 * @param string $sourceType 收益来源类型
 * @return array 分成规则
 */
public function getProfitRule(string $sourceType): array;

功能说明：

获取指定收益来源类型的分成规则
包括直推分成比例、最大间推层级等
用于计算团队收益分成

调用示例：

// 获取农场收益的分成规则
$farmRule = $promotionProfitService->getProfitRule('farm_harvest');

6. 事件接口

团队模块会触发以下事件，其他模块可以监听这些事件：

6.1 达人等级提升事件 (TalentLevelUpEvent)

/**
 * 达人等级提升事件
 */
class TalentLevelUpEvent
{
    /**
     * @var int 用户ID
     */
    public $userId;
    
    /**
     * @var int 旧等级
     */
    public $oldLevel;
    
    /**
     * @var int 新等级
     */
    public $newLevel;
    
    /**
     * 构造函数
     */
    public function __construct(int $userId, int $oldLevel, int $newLevel)
    {
        $this->userId = $userId;
        $this->oldLevel = $oldLevel;
        $this->newLevel = $newLevel;
    }
}

事件说明：

当用户达人等级提升时触发
包含用户ID、旧等级和新等级
可用于任务完成、发放奖励等

监听示例：

// 在EventServiceProvider中注册监听器
protected $listen = [
    'App\Module\Promotion\Events\TalentLevelUpEvent' => [
        'App\Module\Task\Listeners\TalentLevelUpListener',
    ],
];

// 监听器实现
public function handle(TalentLevelUpEvent $event)
{
    // 处理达人等级提升事件
    $userId = $event->userId;
    $newLevel = $event->newLevel;
    
    // 完成相关任务
    $this->taskService->completeTask($userId, 'talent_level_up', ['level' => $newLevel]);
}

6.2 推荐关系创建事件 (ReferralCreatedEvent)

/**
 * 推荐关系创建事件
 */
class ReferralCreatedEvent
{
    /**
     * @var int 用户ID
     */
    public $userId;
    
    /**
     * @var int 推荐人ID
     */
    public $referrerId;
    
    /**
     * @var int 推荐层级
     */
    public $level;
    
    /**
     * 构造函数
     */
    public function __construct(int $userId, int $referrerId, int $level)
    {
        $this->userId = $userId;
        $this->referrerId = $referrerId;
        $this->level = $level;
    }
}

事件说明：

当建立新的推荐关系时触发
包含用户ID、推荐人ID和推荐层级
可用于任务完成、发放奖励等

监听示例：

// 在EventServiceProvider中注册监听器
protected $listen = [
    'App\Module\Promotion\Events\ReferralCreatedEvent' => [
        'App\Module\Task\Listeners\ReferralCreatedListener',
    ],
];

// 监听器实现
public function handle(ReferralCreatedEvent $event)
{
    // 处理推荐关系创建事件
    $userId = $event->userId;
    $referrerId = $event->referrerId;
    
    // 完成相关任务
    if ($event->level == 1) {
        $this->taskService->completeTask($referrerId, 'direct_referral');
    }
}

7. 监听的事件

团队模块会监听以下来自其他模块的事件：

7.1 用户注册事件 (UserRegisteredEvent)

// 用户模块中定义的事件
namespace App\Module\User\Events;

class UserRegisteredEvent
{
    /**
     * @var int 用户ID
     */
    public $userId;
    
    /**
     * @var string 推荐码
     */
    public $referralCode;
    
    /**
     * 构造函数
     */
    public function __construct(int $userId, string $referralCode = '')
    {
        $this->userId = $userId;
        $this->referralCode = $referralCode;
    }
}

监听处理：

namespace App\Module\Promotion\Listeners;

use App\Module\User\Events\UserRegisteredEvent;
use App\Module\Promotion\Services\ReferralService;

class UserRegisteredListener
{
    /**
     * @var ReferralService
     */
    protected $referralService;
    
    /**
     * 构造函数
     */
    public function __construct(ReferralService $referralService)
    {
        $this->referralService = $referralService;
    }
    
    /**
     * 处理事件
     */
    public function handle(UserRegisteredEvent $event)
    {
        // 处理用户注册事件
        $userId = $event->userId;
        $referralCode = $event->referralCode;
        
        // 验证推荐码
        if (!empty($referralCode)) {
            $referrerId = $this->referralService->verifyReferralCode($referralCode);
            if ($referrerId !== null) {
                // 建立推荐关系
                $this->referralService->createReferralRelation($userId, $referrerId);
            }
        }
        
        // 生成用户推荐码
        $this->referralService->generateReferralCode($userId);
    }
}

7.2 作物收获事件 (CropHarvestedEvent)

// 农场模块中定义的事件
namespace App\Module\Farm\Events;

class CropHarvestedEvent
{
    /**
     * @var int 用户ID
     */
    public $userId;
    
    /**
     * @var int 作物ID
     */
    public $cropId;
    
    /**
     * @var int 产出物品ID
     */
    public $itemId;
    
    /**
     * @var int 产出数量
     */
    public $amount;
    
    /**
     * 构造函数
     */
    public function __construct(int $userId, int $cropId, int $itemId, int $amount)
    {
        $this->userId = $userId;
        $this->cropId = $cropId;
        $this->itemId = $itemId;
        $this->amount = $amount;
    }
}

监听处理：

namespace App\Module\Promotion\Listeners;

use App\Module\Farm\Events\CropHarvestedEvent;
use App\Module\Promotion\Services\PromotionProfitService;

class CropHarvestedListener
{
    /**
     * @var PromotionProfitService
     */
    protected $promotionProfitService;
    
    /**
     * 构造函数
     */
    public function __construct(PromotionProfitService $promotionProfitService)
    {
        $this->promotionProfitService = $promotionProfitService;
    }
    
    /**
     * 处理事件
     */
    public function handle(CropHarvestedEvent $event)
    {
        // 处理作物收获事件
        $userId = $event->userId;
        $cropId = $event->cropId;
        $itemId = $event->itemId;
        $amount = $event->amount;
        
        // 计算团队收益分成
        $this->promotionProfitService->calculatePromotionProfit(
            $userId,
            'farm_harvest',
            $cropId,
            $itemId,
            $amount
        );
    }
}

8. 接口使用示例

8.1 用户注册时建立推荐关系

// 用户注册处理
public function register(Request $request)
{
    // 创建用户
    $userId = $this->userService->createUser($request->all());
    
    // 处理推荐码
    $referralCode = $request->input('referral_code');
    if (!empty($referralCode)) {
        try {
            // 验证推荐码
            $referrerId = $this->referralService->verifyReferralCode($referralCode);
            if ($referrerId !== null) {
                // 建立推荐关系
                $this->referralService->createReferralRelation($userId, $referrerId);
            }
        } catch (\Exception $e) {
            // 处理异常
            Log::error('建立推荐关系失败', [
                'user_id' => $userId,
                'referral_code' => $referralCode,
                'error' => $e->getMessage()
            ]);
        }
    }
    
    // 生成用户推荐码
    $this->referralService->generateReferralCode($userId);
    
    // 返回结果
    return response()->json([
        'success' => true,
        'user_id' => $userId
    ]);
}

8.2 作物收获时计算团队收益

// 作物收获处理
public function harvestCrop(int $cropId)
{
    return DB::transaction(function () use ($cropId) {
        // 收获作物
        $result = $this->cropService->harvestCrop($cropId);
        
        // 获取收获信息
        $userId = $result['user_id'];
        $itemId = $result['item_id'];
        $amount = $result['amount'];
        
        // 计算团队收益分成
        $this->promotionProfitService->calculatePromotionProfit(
            $userId,
            'farm_harvest',
            $cropId,
            $itemId,
            $amount
        );
        
        // 触发作物收获事件
        event(new CropHarvestedEvent($userId, $cropId, $itemId, $amount));
        
        return $result;
    });
}

8.3 获取用户团队信息

// 获取用户团队信息
public function getUserPromotionInfo(int $userId)
{
    // 获取用户达人信息
    $talentInfo = $this->talentService->getUserTalentInfo($userId);
    
    // 获取直推成员
    $directMembers = $this->referralService->getPromotionMembers($userId, 1, 1, 10);
    
    // 获取团队收益统计
    $profitStats = $this->promotionProfitService->getUserPromotionProfitStats($userId);
    
    // 获取最近收益记录
    $recentProfits = $this->promotionProfitService->getUserPromotionProfitRecords($userId, '', 1, 5);
    
    // 返回结果
    return [
        'talent_info' => $talentInfo,
        'direct_members' => $directMembers,
        'profit_stats' => $profitStats,
        'recent_profits' => $recentProfits
    ];
}

9. 总结

团队模块提供了丰富的服务接口，用于管理用户推荐关系、达人等级和团队收益分成。这些接口设计清晰、功能完善，能够满足团队系统的各种需求。通过事件机制，团队模块与其他模块保持松耦合的交互方式，提高了系统的可维护性和可扩展性。在使用这些接口时，需要注意异常处理和事务管理，确保数据的一致性和完整性。

模块接口.md 20 KB Istoric Crud

团队模块接口

1. 概述

2. 接口规范

2.1 接口命名规范

2.2 参数规范

2.3 返回值规范

2.4 异常处理

3. 推荐关系服务接口 (ReferralService)

3.1 建立推荐关系

3.2 获取用户的推荐人

3.3 获取用户的团队成员

3.4 检查推荐关系

3.5 生成推荐码

3.6 验证推荐码

4. 达人等级服务接口 (TalentService)

4.1 获取用户达人信息

4.2 检查并更新达人等级

4.3 获取达人等级配置

4.4 获取达人等级分成比例

5. 团队收益服务接口 (PromotionProfitService)

5.1 计算团队收益分成

5.2 获取用户团队收益统计

5.3 获取用户团队收益记录

5.4 获取收益分成规则

6. 事件接口

6.1 达人等级提升事件 (TalentLevelUpEvent)

6.2 推荐关系创建事件 (ReferralCreatedEvent)

7. 监听的事件

7.1 用户注册事件 (UserRegisteredEvent)

7.2 作物收获事件 (CropHarvestedEvent)

8. 接口使用示例

8.1 用户注册时建立推荐关系

8.2 作物收获时计算团队收益

8.3 获取用户团队信息

9. 总结

模块接口.md 20 KB

Istoric Crud