Eloquent 作用域必须以 scope 开头、首参为 $query、返回 $query，否则链式中断；参数需显式声明，不可用 $this->where；应纯条件拼接，避免执行查询或修改状态。
局部作用域不是语法糖，是 Eloquent 查询复用的刚需机制；写错 signature 或漏 return $query 就会链式中断或直接报错。
scope 方法名必须以 scope 开头，且第一个参数固定是 $query
常见错误是定义成 active() 或 scopeActive($this) —— 前者调用时会抛 Call to undefined method，后者则因参数类型不匹配导致 PHP 类型错误或逻辑失效。Eloquent 只识别以 scope 开头、且首参为 Illuminate\Database\Eloquent\Builder 实例的方法。
- 正确写法：
public function scopeActive($query)，调用时写User::active()->get() - 方法必须声明为
public，否则无法被查询构造器反射调用 - 不要在作用域里用
$this->where()—— 模型实例没有where方法，只有$query有
带参数的作用域：参数必须紧接 $query，类型校验靠自己
比如按状态值筛选，不能写成 scopeOfType($type)，而必须是 scopeOfType($query, $type)。Eloquent 不做任何参数转换，传入字符串 '2024-01-01'，就得自己用 Carbon::parse() 处理，否则可能生成错误的 SQL 时间比较。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 多参数也一样：签名是
scopePublishedBetween($query, $start, $end)，调用是->publishedBetween('2024-01-01', '2024-12-31') - 避免在作用域里调用
DB::table()或其他模型查询 —— 它只负责拼条件，不该触发实际执行 - 如果参数可选，建议用默认值 +
isset()或filled()判断，而不是依赖 PHP 的可变参数
链式调用要确保每个作用域都 return $query
一旦某个作用域忘了 return，或者错误地写了 return $query->get()，后续的 ->orderBy() 或 ->paginate() 就会报错：「Call to a member function orderBy() on array」或「Trying to call method on null」。
- 所有作用域必须返回
$query，这是链式能继续的前提 - 可以混合使用：例如
Post::published()->with('author')->latest()->paginate(15)，其中published()是自定义作用域，with()和latest()是原生方法 - 调试时可用
toSql()查看最终 SQL：echo User::active()->ofType('admin')->toSql();
用 when() 动态启用作用域，避免空条件污染查询
比如搜索接口中，关键词存在才加模糊查询，否则不应生成 WHERE name LIKE '%' 这种无意义条件。硬编码 ->where('name', 'like', "%{$keyword}%") 容易出错，而 when() 能干净地控制逻辑分支。
- 写法：
User::when($request->filled('keyword'), fn ($q) => $q->where('name', 'like', "%{$request->keyword}%"))->get() - 也可调用已有作用域：
->when($request->boolean('only_active'), fn ($q) => $q->active()) - 注意
when()的闭包里必须显式接收$q并调用，不能写User::when(...)->active()—— 那样active()作用在外部查询上，不是when分支内
最常被忽略的是作用域的“纯条件性”：它只该做 where、whereHas 这类 SQL 拼接，不该查数据库、不该改模型属性、也不该触发事件。越往里塞逻辑，就越难测试、越容易在 paginate 或 with 预加载时引发意外行为。
