haha/qdb-sdk/src/main/java/com/qdb/sdk/api/GoodsApi.java

package com.qdb.sdk.api;

import com.alibaba.fastjson2.TypeReference;
import com.qdb.sdk.QdbClient;
import com.qdb.sdk.QdbException;
import com.qdb.sdk.model.request.*;
import com.qdb.sdk.model.response.*;

import java.util.List;

/**
 * 商品管理 API
 * <p>
 * 提供商品上传、查询、单位管理等接口的调用封装。
 * 对应文档：02-商品管理.md
 * </p>
 *
 * @author qdb-sdk
 * @version 1.0.0
 */
public class GoodsApi extends BaseQdbApi {

    /** 商品上传（系统商品 + 店铺商品） */
    private static final String METHOD_GOODS_SAVE = "foonsu.erp.goods.save";

    /** 系统商品上传（批量，最大100） */
    private static final String METHOD_SYS_GOODS_SAVE = "foonsu.erp.sysGoods.save";

    /** 商品单位查询 */
    private static final String METHOD_SYS_GOODS_LIST_UNIT = "foonsu.erp.sysGoods.listUnit";

    /** 系统商品查询 */
    private static final String METHOD_SYS_GOODS_LIST = "foonsu.erp.sysGoods.list";

    /** 批量新增店铺商品 */
    private static final String METHOD_PLATFORM_GOODS_BATCH_SAVE = "foonsu.erp.platForm.goods.batchSave";

    /** 批量修改店铺商品 */
    private static final String METHOD_PLATFORM_GOODS_BATCH_UPDATE = "foonsu.erp.platForm.goods.batchUpdate";

    public GoodsApi(QdbClient client) {
        super(client);
    }

    /**
     * 商品上传
     * <p>
     * 上传至系统商品以及店铺商品（即【商品信息】、【店铺商品设置】页面）。
     * </p>
     *
     * @param request 商品上传请求参数
     * @return 响应对象（data 为 null）
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<Void> saveGoods(GoodsSaveRequest request) throws QdbException {
        return execute(METHOD_GOODS_SAVE, request);
    }

    /**
     * 系统商品上传
     * <p>
     * 批量上传至系统商品（即【商品信息】页面），单次最大100条。
     * </p>
     *
     * @param request 系统商品上传请求参数
     * @return 响应对象，data 包含上传结果统计
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<SysGoodsSaveResponse> saveSysGoods(SysGoodsSaveRequest request) throws QdbException {
        return execute(METHOD_SYS_GOODS_SAVE, request, SysGoodsSaveResponse.class);
    }

    /**
     * 商品单位查询
     * <p>
     * 查询商品单位列表。
     * </p>
     *
     * @param request 查询请求参数（可分页）
     * @return 响应对象，data 包含单位列表
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<GoodsUnitListResponse> listGoodsUnits(GoodsUnitQueryRequest request) throws QdbException {
        return execute(METHOD_SYS_GOODS_LIST_UNIT, request, GoodsUnitListResponse.class);
    }

    /**
     * 系统商品查询
     * <p>
     * 查询系统商品信息（即【商品信息】、【组合商品】页面数据）。
     * 注意：此方法解析 data 为扁平列表，不适用于分页场景。
     * 分页场景请使用 {@link #listSysGoodsPaged(SysGoodsQueryRequest)}。
     * </p>
     *
     * @param request 查询请求参数（支持多种筛选条件）
     * @return 响应对象，data 为系统商品列表
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<List<SysGoodsVO>> listSysGoods(SysGoodsQueryRequest request) throws QdbException {
        return execute(METHOD_SYS_GOODS_LIST, request,
                new TypeReference<List<SysGoodsVO>>() {});
    }

    /**
     * 系统商品查询（带分页信息）
     * <p>
     * 查询系统商品信息，返回包含 total 和 data 的分页结果。
     * 适用于需要分页遍历所有系统商品的场景（如同步到本地缓存）。
     * </p>
     *
     * @param request 查询请求参数
     * @return 响应对象，data 为包含 total 和商品列表的分页结果
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<SysGoodsPageResult> listSysGoodsPaged(SysGoodsQueryRequest request) throws QdbException {
        return execute(METHOD_SYS_GOODS_LIST, request,
                new TypeReference<SysGoodsPageResult>() {});
    }

    /**
     * 批量新增店铺商品
     * <p>
     * 批量新增店铺商品（即【店铺商品设置】页面）。
     * </p>
     *
     * @param request 批量新增请求参数
     * @return 响应对象，data 包含操作结果统计
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<PlatformGoodsBatchResponse> batchSavePlatformGoods(
            PlatformGoodsBatchSaveRequest request) throws QdbException {
        return execute(METHOD_PLATFORM_GOODS_BATCH_SAVE, request, PlatformGoodsBatchResponse.class);
    }

    /**
     * 批量修改店铺商品
     * <p>
     * 批量更新店铺商品信息。
     * </p>
     *
     * @param request 批量修改请求参数
     * @return 响应对象，data 包含操作结果统计
     * @throws QdbException 调用失败时抛出
     */
    public QdbResponse<PlatformGoodsBatchResponse> batchUpdatePlatformGoods(
            PlatformGoodsBatchUpdateRequest request) throws QdbException {
        return execute(METHOD_PLATFORM_GOODS_BATCH_UPDATE, request, PlatformGoodsBatchResponse.class);
    }
}