list-query-sync

name	list-query-sync
description	MallBase ThinkPHP 列表查询与分页返回规则；实现或调整 Service 的 buildListQuery、分页 list/total、动态筛选、关联查询、统计、导出或 compact('total', 'list') 返回时使用。

ThinkPHP 列表查询同源规则

查询构建

当列表、总数、统计或导出共享筛选条件时，在 Service 中集中定义 buildListQuery(array $where)：

protected function buildListQuery(array $where)
{
    return $this->model()
        ->when(!empty($where['keyword']), function ($query) use ($where) {
            $query->whereLike('name|subtitle', "%{$where['keyword']}%");
        })
        ->when(
            ($where['status'] ?? null) !== null && $where['status'] !== '',
            function ($query) use ($where) {
                $query->where('status', $where['status']);
            }
        );
}

1. 只在构建方法中维护共享筛选条件，分页、展示排序和结果补充留在调用方。
2. 用新的查询实例分别执行列表与总数，或在修改查询前显式克隆；不要让 page/order/select 污染计数查询。
3. 对 0、false 等有效筛选值使用显式空值判断，不使用 empty()。
4. 新增列表筛选不要再引入模型 withSearch() 或 search*Attr() 双轨入口。
5. 统计、导出需要与页面列表同口径时复用同一构建方法，不复制条件。

关联选择

• 关联数据只用于展示时，优先模型关系和 with()。
• 关联字段参与筛选、排序、聚合或扁平字段输出时，使用 join、exists 或明确的关联 ID 查询。
• 先查关联 ID 再 whereIn 时，空结果必须显式返回空集，不能让空数组退化为全量查询。

分页返回

返回契约正好是 {total, list} 时，变量统一命名为 $total、$list，并返回：

$list = $this->buildListQuery($where)
    ->order('id', 'desc')
    ->page($page, $limit)
    ->select()
    ->toArray();
$total = $this->buildListQuery($where)->count();

return compact('total', 'list');

接口还包含 tabs、stats 或其它字段时，按真实契约返回，不为了使用 compact() 隐藏额外字段。

自检

• 列表、总数、统计和导出的共享筛选只有一份。
• status=0 等值能正确命中。
• 计数查询未携带分页或展示排序副作用。
• 关联策略与筛选、展示用途一致。