laravel 中自定义局部作用域（scope）时，若方法名与 eloquent 内置查询方法（如 `latest`、`oldest`、`with` 等）重名，将导致作用域失效——实际调用的是框架原生方法，而非你的逻辑。

在 Laravel 中，局部作用域是通过在模型中定义以 scope 开头的公共方法（如 scopeLatest）来实现的，它会被 Eloquent 的魔术方法 __call() 自动识别并代理为链式查询的一部分。但这一机制仅在调用的方法名未被模型或其父类（如 Builder）定义时才生效。

问题根源在于：latest() 是 Eloquent Builder 类中已存在的公开方法（用于按时间字段倒序排序，默认使用 created_at），签名如下：

public function latest($column = 'created_at')

当你在控制器中写 Test::latest(3)->get() 时，PHP 直接调用了 Builder::latest()，完全跳过了你的 scopeLatest() —— 因为 latest 已存在且可访问，__call() 根本不会触发，自然也就不会查找或执行任何 scope* 方法。

✅ 正确做法：为自定义作用域选择唯一、非保留的名称。推荐采用语义清晰 + 前缀组合，例如：

// ✅ 推荐：使用业务语义前缀，避免冲突
public function scopeAvailableLatest($query, $limit = 3)
{
    return $query
        ->select(['id', 'title', 'main_photo', 'area', 'price', 'city', 'short_desc'])
        ->whereIn('status', ['Dostepne', 'Zarezerwowane'])
        ->orderBy('id', 'desc')
        ->limit($limit);
}

控制器中调用：

$flats = Test::availableLatest(3)->get(); // ✅ 正确触发自定义作用域

⚠️ 注意事项：

• 不要覆盖 where*, orderBy*, with*, first, get, count 等任意 Eloquent/Builder 已有方法名；
• 可通过查看 Laravel 官方文档 — Query Scopes 和 Illuminate\Database\Eloquent\Builder 源码确认保留方法列表；
• 若需调试作用域是否生效，可在作用域内添加 Log::debug('scope hit') 或抛出异常临时验证；
• 局部作用域方法必须声明第一个参数为 Builder $query（Laravel 9+ 支持类型提示，旧版本可省略但建议保留）；
• 作用域应只构建查询，不执行（即不调用 get()/first()），保持链式调用的灵活性。

? 进阶建议：对于高频复用的复杂查询逻辑，可考虑结合 全局作用域（Global Scopes） 或封装为 查询构造器宏（Macro），进一步提升可维护性与一致性。