Laravel范围查询需严守作用域边界：whereHas闭包仅限关联表字段，主表条件须在外层；or条件必须包裹在where闭包中；join需distinct及表前缀；addSelect子查询需处理NULL与类型转换。
范围查询在 Laravel 关联场景中，本质是「主表条件 + 关联表条件」的组合控制，不是简单套 where 就能生效。用错方式会导致空结果、SQL 报错或逻辑漏判——尤其当涉及日期范围、多字段 or 搜索、或嵌套关系时。
whereHas() 闭包里只能写关联表字段
这是最常踩的坑：把主表字段（比如 users.name）塞进 whereHas 的闭包里，MySQL 直接报错或返回空集合。
-
whereHas('userAttr', function ($q) { $q->where('job', 'teacher'); })✅ 正确：job属于user_attrs表 -
whereHas('userAttr', function ($q) { $q->where('users.name', 'John'); })❌ 错误：users.name不在user_attrs表中，SQL 解析失败 - 主表条件必须写在
whereHas外层，例如User::where('status', 'active')->whereHas(...)
日期范围 + 关键词搜索必须用 where() 闭包包裹 or 条件
混合 whereDate() 和多个 orWhere() 时，不加闭包会导致 AND/OR 优先级混乱，结果完全偏离预期——比如日期外的数据也被查出来。
- 错误写法：
->whereDate('posts.created_at', '>=', $from)->orWhere('title', 'like', $q)->orWhere('content', 'like', $q)→ 实际 SQL 等价于(date AND title) OR content - 正确写法：
->whereDate('posts.created_at', '>=', $from)->where(function ($q) use ($search) { $q->where('title', 'like', "%{$search}%")->orWhere('content', 'like', "%{$search}%"); }) - 所有 or 条件必须收进一个
where()闭包，确保它们整体与日期条件以 AND 连接
join() 做范围筛选要防重复 + 字段前缀
用 join() 查父子数据并做范围过滤时，一对多关系下容易因匹配多条子记录而重复返回同一主记录；同时字段名若不带表前缀，Laravel 可能混淆归属。
- 必须加
->distinct()，否则一个post有 3 个tag就会返回 3 次 - 所有字段都得显式写表前缀：
'posts.id'、'posts_tags.tag_id'，不能只写'id'或'tag_id' - 如果想保留无子记录的父行，改用
leftJoin()，但注意后续where若作用于子表字段（如where('posts_tags.status', 'active')），实际效果等同innerJoin
addSelect 子查询字段要处理 NULL 和类型转换
用 addSelect() 给主查询加子查询字段（比如每个用户的最新订单时间），看似简洁，但默认行为极不安全：NULL 值不处理、时间字段不转 Carbon、字段别名易冲突。
- 子查询没匹配记录时，该字段值为
NULL，前端访问$user->last_order_at->format(...)会报错 - 应显式加
COALESCE或后端判空：->addSelect(['last_order_at' => Order::selectRaw('COALESCE(MAX(created_at), "1970-01-01")')...]) -
last_order_at是字符串，不是Carbon实例，需手动调用asDateTime()或用访问器封装 -
whereColumn('user_id', 'users.id')中的'users.id'必须是字符串，不能传变量$user->id，否则变成固定值查询
真正难的不是写出能跑的代码，而是理解每个方法背后的作用域边界：whereHas 的闭包只认关联表字段，join 后所有字段必须带前缀，addSelect 返回的是原始数据库值而非模型属性——这些边界一旦模糊，调试成本远高于重写。
