积分类型扩展指南

概述

积分系统已重构为配置化设计，新增积分类型只需修改一个文件，无需改动其他代码。

核心文件

配置文件: src/Config/TransactionType.php - 统一管理所有积分类型
模型类: src/Models/RewardActiveRule.php - 引用配置类的常量

新增积分类型步骤

1. 在 TransactionType.php 中添加新类型

class TransactionType
{
    // ... 现有类型 ...
    
    /**
     * 新类型：例如“完成任务”
     */
    const TASK_COMPLETE = 10;  // 使用下一个可用的ID
    
    public static function all(): array
    {
        return [
            // ... 现有类型配置 ...
            
            self::TASK_COMPLETE => [
                'code' => 'task_complete',      // 唯一代码标识
                'name' => '完成任务',            // 显示名称
                'description' => '完成指定任务获得积分',  // 描述
                'icon' => 'icon-task',          // 图标类名
                'color' => 'cyan',              // 颜色主题
            ],
        ];
    }
}

注意：

类型 ID 10 已预留给“积分过期”，用于系统自动处理过期积分
类型 ID 11 已预留给“兑换礼品卡”，用于积分兑换功能
类型 ID 99 已预留给“管理员操作”，不应在规则中使用
这些特殊类型不会出现在规则配置的下拉选项中
如果需要排除某些类型不出现在规则配置中，可以使用 getRuleTypes() 方法

2. 在 RewardActiveRule.php 中添加常量引用（保持向后兼容）

class RewardActiveRule extends Model
{
    // ... 现有常量 ...
    const TYPE_TASK_COMPLETE = TransactionType::TASK_COMPLETE;
}

3. 创建对应的事件监听器（如需要）

// src/Listeners/TaskEvents.php
namespace Longyi\RewardPoints\Listeners;

use Longyi\RewardPoints\Repositories\RewardPointRepository;
use Longyi\RewardPoints\Models\RewardActiveRule;

class TaskEvents
{
    protected $rewardPointRepository;

    public function __construct(RewardPointRepository $rewardPointRepository)
    {
        $this->rewardPointRepository = $rewardPointRepository;
    }

    public function handleTaskComplete($event): void
    {
        // 获取任务完成规则
        $rule = RewardActiveRule::active()
            ->ofType(RewardActiveRule::TYPE_TASK_COMPLETE)
            ->first();
        
        if (!$rule) {
            return;
        }
        
        // 检查规则是否适用
        if (!$rule->isApplicableToCustomer($event->customer)) {
            return;
        }
        
        // 获取积分值
        $points = $rule->getPointsForCustomer($event->customer);
        
        if ($points > 0) {
            $this->rewardPointRepository->addPoints(
                $event->customer->id,
                RewardActiveRule::TYPE_TASK_COMPLETE,
                $points,
                null,
                "完成任务: {$event->task_name}"
            );
        }
    }
}

4. 注册事件监听器

在 src/Providers/EventServiceProvider.php 中注册：

protected $listen = [
    // ... 其他事件 ...
    'App\Events\TaskCompleted' => [
        'Longyi\RewardPoints\Listeners\TaskEvents@handleTaskComplete',
    ],
];

5. 在后台创建规则

访问后台管理页面，创建新的积分规则：

交易类型选择："完成任务"
设置积分值、客户群组等参数

优势

✅ 单一配置源: 只需修改 TransactionType.php
✅ 向后兼容: 保留原有常量引用方式
✅ 易于维护: 类型信息集中管理
✅ 类型安全: 提供完整的类型检查和验证方法

常用工具方法

use Longyi\RewardPoints\Config\TransactionType;

// 获取所有类型
$allTypes = TransactionType::all();

// 获取类型名称
$name = TransactionType::getName(TransactionType::ORDER);  // "订单"

// 获取类型代码
$code = TransactionType::getCode(TransactionType::ORDER);  // "order"

// 根据代码获取ID
$id = TransactionType::getIdByCode('order');  // 3

// 检查类型是否存在
$exists = TransactionType::exists(3);  // true

// 获取下拉选项
$options = TransactionType::options();  // [1 => '签到', 2 => '注册', ...]

注意事项

ID 唯一性: 确保新类型的 ID 不与现有类型冲突
Code 唯一性: code 字段应该是唯一的英文标识符
数据库迁移: 如果需要在数据库中存储新类型，确保 type_of_transaction 字段能容纳新值
缓存清理: 修改后清除应用缓存以确保生效

扩展示例：添加"游戏成就"类型

// 1. 在 TransactionType.php 中添加
const GAME_ACHIEVEMENT = 10;

// 在 all() 方法中添加配置
self::GAME_ACHIEVEMENT => [
    'code' => 'game_achievement',
    'name' => '游戏成就',
    'description' => '完成游戏成就获得积分',
],

// 2. 在 RewardActiveRule.php 中添加
const TYPE_GAME_ACHIEVEMENT = TransactionType::GAME_ACHIEVEMENT;

// 3. 创建监听器处理游戏成就事件
// 4. 注册事件
// 5. 在后台创建规则

完成！无需修改任何其他代码。

EXTENSION_GUIDE.md 5.1 KB Bezpośredni odnośnik Historia Czysty