chatroom/app/Models/Position.php

<?php

/**
 * 文件功能：职务模型
 * 对应 positions 表，职务属于某个部门，包含等级、图标、人数上限和奖励上限
 * 任命权限通过 position_appoint_limits 中间表多对多关联定义，
 * 聊天室顶部管理权限通过 permissions JSON 字段配置
 *
 * @author   ChatRoom Laravel
 *
 * @version  1.0.0
 */

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Illuminate\Database\Eloquent\Relations\HasMany;

class Position extends Model
{
    /**
     * 允许批量赋值的字段
     *
     * @var list<string>
     */
    protected $fillable = [
        'department_id',
        'name',
        'icon',
        'rank',
        'level',
        'max_persons',
        'max_reward',
        'daily_reward_limit',
        'recipient_daily_limit',
        'sort_order',
        'permissions',
        'red_packet_amount',
        'red_packet_count',
    ];

    /**
     * 字段类型转换
     */
    public function casts(): array
    {
        return [
            'rank' => 'integer',
            'level' => 'integer',
            'max_persons' => 'integer',
            'max_reward' => 'integer',
            'daily_reward_limit' => 'integer',
            'recipient_daily_limit' => 'integer',
            'sort_order' => 'integer',
            'permissions' => 'array',
            'red_packet_amount' => 'integer',
            'red_packet_count' => 'integer',
        ];
    }

    /**
     * 所属部门
     */
    public function department(): BelongsTo
    {
        return $this->belongsTo(Department::class);
    }

    /**
     * 该职务当前在职的用户记录（user_positions）
     */
    public function activeUserPositions(): HasMany
    {
        return $this->hasMany(UserPosition::class)->where('is_active', true);
    }

    /**
     * 该职务的所有历史任职记录
     */
    public function userPositions(): HasMany
    {
        return $this->hasMany(UserPosition::class);
    }

    /**
     * 该职务可以任命的目标职务列表（position_appoint_limits 中间表）
     */
    public function appointablePositions(): BelongsToMany
    {
        return $this->belongsToMany(
            Position::class,
            'position_appoint_limits',
            'appointer_position_id',
            'appointable_position_id'
        );
    }

    /**
     * 哪些职务的持有者可以将用户任命到本职务
     */
    public function appointedByPositions(): BelongsToMany
    {
        return $this->belongsToMany(
            Position::class,
            'position_appoint_limits',
            'appointable_position_id',
            'appointer_position_id'
        );
    }

    /**
     * 获取当前在职人数
     */
    public function currentCount(): int
    {
        return $this->activeUserPositions()->count();
    }

    /**
     * 是否已满员
     */
    public function isFull(): bool
    {
        if ($this->max_persons === null) {
            return false;
        }

        return $this->currentCount() >= $this->max_persons;
    }

    /**
     * 判断当前职务是否拥有指定权限码。
     */
    public function hasPermission(string $permission): bool
    {
        return in_array($permission, $this->permissions ?? [], true);
    }

    /**
     * 返回当前职务的权限码列表。
     *
     * @return list<string>
     */
    public function permissionCodes(): array
    {
        return array_values($this->permissions ?? []);
    }

    /**
     * 查询范围：按位阶降序
     */
    public function scopeOrdered($query): void
    {
        $query->orderBy('sort_order')->orderByDesc('rank');
    }
}