chatroom/app/Models/Riddle.php

<?php

/**
 * 文件功能：猜谜活动题库模型
 *
 * 对应 idioms 表，统一承载成语题与脑筋急转弯题目。
 */

namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

/**
 * 类功能：统一管理猜谜活动的题目、答案、提示与题型。
 */
class Riddle extends Model
{
    /**
     * 属性功能：显式绑定历史题库表名，避免类名重命名后推导到错误表。
     *
     * @var string
     */
    protected $table = 'idioms';

    /**
     * 常量功能：声明成语题题型标识。
     */
    public const TYPE_IDIOM = 'idiom';

    /**
     * 常量功能：声明脑筋急转弯题型标识。
     */
    public const TYPE_BRAIN_TEASER = 'brain_teaser';

    /**
     * 方法功能：声明允许批量赋值的题库字段。
     *
     * @var array<int, string>
     */
    protected $fillable = [
        'type',
        'answer',
        'hint',
        'is_active',
        'sort',
    ];

    /**
     * 方法功能：定义题库字段的类型转换规则。
     *
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'is_active' => 'boolean',
            'sort' => 'integer',
        ];
    }

    /**
     * 方法功能：返回系统支持的全部题型。
     *
     * @return array<int, string>
     */
    public static function supportedTypes(): array
    {
        return [
            self::TYPE_IDIOM,
            self::TYPE_BRAIN_TEASER,
        ];
    }

    /**
     * 方法功能：判断给定题型是否属于系统支持范围。
     */
    public static function isSupportedType(string $type): bool
    {
        return in_array($type, self::supportedTypes(), true);
    }

    /**
     * 方法功能：根据题型返回面向用户的中文名称。
     */
    public static function labelForType(string $type): string
    {
        return match ($type) {
            self::TYPE_BRAIN_TEASER => '脑筋急转弯',
            default => '猜成语',
        };
    }

    /**
     * 方法功能：返回后台表单可直接使用的题型键值对。
     *
     * @return array<string, string>
     */
    public static function typeOptions(): array
    {
        return collect(self::supportedTypes())
            ->mapWithKeys(fn (string $type): array => [$type => self::labelForType($type)])
            ->all();
    }

    /**
     * 方法功能：返回题型对应的活动标题。
     */
    public static function activityLabelForType(string $type): string
    {
        return '猜谜活动·'.self::labelForType($type);
    }

    /**
     * 方法功能：按题型筛选题库记录。
     */
    public function scopeOfType(Builder $query, string $type): Builder
    {
        return $query->where('type', self::isSupportedType($type) ? $type : self::TYPE_IDIOM);
    }
}