chatroom/app/Models/Position.php

<?php

/**
 * 文件功能：职务模型
 * 对应 positions 表，职务属于某个部门，包含等级、图标、人数上限和奖励上限
 * 任命权限通过 position_appoint_limits 中间表多对多关联定义
 *
 * @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',
        'sort_order',
    ];

    /**
     * 字段类型转换
     */
    public function casts(): array
    {
        return [
            'rank' => 'integer',
            'level' => 'integer',
            'max_persons' => 'integer',
            'max_reward' => 'integer',
            'sort_order' => '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 scopeOrdered($query): void
    {
        $query->orderBy('sort_order')->orderByDesc('rank');
    }
}