# 积分类型扩展指南

## 概述

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

## 核心文件

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

## 新增积分类型步骤

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

```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 中添加常量引用（保持向后兼容）

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

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

```php
// 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` 中注册：

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

### 5. 在后台创建规则

访问后台管理页面，创建新的积分规则：
- 交易类型选择："完成任务"
- 设置积分值、客户群组等参数

## 优势

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

## 常用工具方法

```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 => '注册', ...]
```

## 注意事项

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

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

```php
// 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. 在后台创建规则
```

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