<?php

namespace Kylin\Rbac\Models;

use Illuminate\Database\Eloquent\Relations\BelongsToMany;
use Kylin\Core\Models\BaseModel;

/**
 * 权限模型
 *
 * 继承自 BaseModel（默认启用软删除），存储权限信息。
 * 通过多对多关联与角色（Role）建立关系。
 *
 * 属性：
 *  - name：权限标识（唯一，如 user.create、post.edit）
 *  - display_name：显示名称（如 创建用户、编辑文章）
 *  - guard_name：守卫名称（如 web、api）
 *  - module：所属模块（如 user、post）
 *  - description：权限描述
 *
 * @property int     $id
 * @property string  $name          权限标识
 * @property string  $display_name  显示名称
 * @property string  $guard_name    守卫名称
 * @property string  $module        所属模块
 * @property string  $description   描述
 *
 * @method static self|null findByName(string $name, ?string $guardName = null)  按名称查找权限
 */
class Permission extends BaseModel
{
    /** 权限数据表名 */
    protected $table = 'kylin_permissions';

    /** 可批量赋值的属性 */
    protected $fillable = [
        'name', 'display_name', 'guard_name', 'module', 'description',
    ];

    /**
     * 权限关联的角色列表（多对多）
     *
     * 关联表名从 kylin-rbac.table_names.role_has_permissions 配置读取。
     */
    public function roles(): BelongsToMany
    {
        return $this->belongsToMany(
            Role::class,
            config('kylin-rbac.table_names.role_has_permissions', 'kylin_role_has_permissions'),
            'permission_id',
            'role_id',
        );
    }

    /**
     * 按名称查找权限
     *
     * @param  string       $name       权限标识
     * @param  string|null  $guardName  守卫名称（null 则使用默认配置）
     * @return self|null
     */
    public static function findByName(string $name, ?string $guardName = null): ?self
    {
        return static::where('name', $name)
            ->where('guard_name', $guardName ?? config('kylin-rbac.guard', 'web'))
            ->first();
    }
}
