CodeBuddy开发记丨医药商城小程序系统重构实战：佣金明细、退款流程与菜单治理

     * 推广订单明细列表查询
     * @param array $where
     * @param string $nickname
     * @param int $page
     * @param int $limit
     * @return array
     */
    public function getCommissionOrderList(array $where, string $nickname, int $page, int $limit): array
    {
        $query = $this->getModel()->alias('o')
            ->where(function ($q) {
                $q->where('o.spread_uid', '>', 0)
                  ->whereOr('o.brokerage_status', '<>', '');
            });
        if (!empty($where['brokerage_status'])) {
            $query->where('o.brokerage_status', $where['brokerage_status']);
        }
        if (!empty($where['brokerage_status_not_normal'])) {
            $query->where('o.brokerage_status', '<>', 'normal')->where('o.brokerage_status', '<>', '');
        }
        if (!empty($where['order_id'])) {
            $query->where('o.order_id', 'like', '%' . $where['order_id'] . '%');
        }
        // 分销员昵称搜索：通过 user 表关联
        if (!empty($nickname)) {
            $query->join('eb_user u', 'o.spread_uid = u.uid', 'LEFT')
                  ->where('u.nickname', 'like', '%' . $nickname . '%');
        }
        return $query->field('o.id,o.order_id,o.spread_uid,o.one_brokerage,o.pay_price,o.brokerage_status')
            ->page($page, $limit)
            ->order('o.id', 'desc')
            ->select()
            ->toArray();
    }

    /**
     * 推广订单明细总数
     * @param array $where
     * @param string $nickname
     * @return int
     */
    public function getCommissionOrderCount(array $where, string $nickname): int
    {
        $query = $this->getModel()->alias('o')
            ->where(function ($q) {
                $q->where('o.spread_uid', '>', 0)
                  ->whereOr('o.brokerage_status', '<>', '');
            });
        if (!empty($where['brokerage_status'])) {
            $query->where('o.brokerage_status', $where['brokerage_status']);
        }
        if (!empty($where['brokerage_status_not_normal'])) {
            $query->where('o.brokerage_status', '<>', 'normal')->where('o.brokerage_status', '<>', '');
        }
        if (!empty($where['order_id'])) {
            $query->where('o.order_id', 'like', '%' . $where['order_id'] . '%');
        }
        if (!empty($nickname)) {
            $query->join('eb_user u', 'o.spread_uid = u.uid', 'LEFT')
                  ->where('u.nickname', 'like', '%' . $nickname . '%');
        }
        return $query->count();
    }

    /**
     * 推广订单明细导出（不分页）
     * @param array $where
     * @param string $nickname
     * @return array
     */
    public function getCommissionOrderListAll(array $where, string $nickname): array
    {
        $query = $this->getModel()->alias('o')
            ->where(function ($q) {
                $q->where('o.spread_uid', '>', 0)
                  ->whereOr('o.brokerage_status', '<>', '');
            });
        if (!empty($where['brokerage_status'])) {
            $query->where('o.brokerage_status', $where['brokerage_status']);
        }
        if (!empty($where['brokerage_status_not_normal'])) {
            $query->where('o.brokerage_status', '<>', 'normal')->where('o.brokerage_status', '<>', '');
        }
        if (!empty($where['order_id'])) {
            $query->where('o.order_id', 'like', '%' . $where['order_id'] . '%');
        }
        if (!empty($nickname)) {
            $query->join('eb_user u', 'o.spread_uid = u.uid', 'LEFT')
                  ->where('u.nickname', 'like', '%' . $nickname . '%');
        }
        return $query->field('o.id,o.order_id,o.spread_uid,o.one_brokerage,o.pay_price,o.brokerage_status')
            ->order('o.id', 'desc')
            ->select()
            ->toArray();
    }

     * 整单退款强校验：仅允许整单退款，禁止单品/部分退款
     * 有效商品集合：订单 order_id 匹配、剩余可退（surplus_num>0）的全部 cart 行（含赠品，不过滤 pid）
     * 校验通过后强制清空 cart_ids，走 applyRefund 整单分支，确保佣金正确置 0
     * @param mixed $order 订单信息（Model 对象或数组均可）
     * @param array $cart_ids 提交的退款商品集合（引用，校验通过将被置空以走整单分支）
     * @throws ApiException
     */
    protected function checkWholeOrderRefund($order, array &$cart_ids)
    {
        // 订单可能为 Model 对象或数组，统一转数组便于访问
        if (is_object($order) && method_exists($order, 'toArray')) {
            $order = $order->toArray();
        }
        // 空集合：后台/客服整单退款入口，直接放行
        if (empty($cart_ids)) {
            return;
        }
        /** @var StoreOrderCartInfoServices $cartInfoServices */
        $cartInfoServices = app()->make(StoreOrderCartInfoServices::class);
        // 有效集合：该订单下剩余可退（surplus_num>0）的全部 cart 行，含赠品，不过滤 pid；以主键 id 为键
        $validCarts = $cartInfoServices->getCartColunm(['oid' => $order['id']], 'id,cart_num,surplus_num,refund_num', 'id');
        $validIds = [];
        $surplusMap = [];
        foreach ($validCarts as $cid => $cart) {
            if (($cart['surplus_num'] ?? 0) > 0) {
                $validIds[] = $cid;
                $surplusMap[$cid] = (int)$cart['surplus_num'];
            }
        }
        $submitIds = array_column($cart_ids, 'cart_id');
        // 提交集合必须与有效集合完全匹配（顺序无关），防止漏退/部分退（含赠品）
        if (count($submitIds) !== count($validIds)
            || array_diff($submitIds, $validIds)
            || array_diff($validIds, $submitIds)) {
            throw new ApiException('本订单仅支持整单退款，请选择全部商品申请退款。');
        }
        // 每项申请退款数量必须等于该行剩余可退数量（强制整件全退，不允许同一商品仅退部分数量）
        $cartMap = array_column($cart_ids, 'cart_num', 'cart_id');
        foreach ($validIds as $cid) {
            if ((int)($cartMap[$cid] ?? 0) !== $surplusMap[$cid]) {
                throw new ApiException('本订单仅支持整单退款，请选择全部商品申请退款。');
            }
        }
        // 校验通过：强制按整单方式退款（清空，走 applyRefund 整单分支，佣金正确置 0）
        $cart_ids = [];
    }

    {
      path: 'finance/commission_order',
      name: `${pre}commissionOrder`,
      meta: {
        auth: ['finance-finance-commission-order'],
        title: '推广订单明细',
      },
      component: () => import('@/pages/finance/commissionOrder/index'),
    },
    {