docs: 补充商品管理接口说明

Author: binarywang

weixin-java-channel/src/main/java/me/chanjar/weixin/channel/api/WxChannelProductService.java

@@ -233,45 +233,121 @@ WxChannelBaseResponse updateStock(String productId, String skuId, Integer diffTy
    */
   ProductTagLinkResponse getProductTagLink(String productId) throws WxErrorException;
 
-  /** 获取商品的移动应用跳转 scheme 码. */
+  /**
+   * 获取商品的移动应用跳转 scheme 码.
+   *
+   * @param param 商品 ID、来源 appid、过期时间和附加信息
+   * @return 商品跳转 scheme 码
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductSchemeResponse getProductScheme(ProductSchemeParam param) throws WxErrorException;
 
-  /** 商品类目推荐. */
+  /**
+   * 商品类目推荐.
+   *
+   * @param param 请求类型、商品标题、主图和可选类目 ID；当请求类型为 2 时必须提供类目 ID
+   * @return 推荐类目及店铺经营权限
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductCategoryClassifyResponse classifyProductCategory(ProductCategoryClassifyParam param) throws WxErrorException;
 
-  /** 商品立即开售. */
+  /**
+   * 将定时开售商品改为立即开售.
+   *
+   * @param param 商品 ID 和定时开售任务 ID
+   * @return 操作结果
+   * @throws WxErrorException 调用微信接口失败
+   */
   WxChannelBaseResponse beginTimingSale(ProductTimingSaleParam param) throws WxErrorException;
 
-  /** 取消商品开售. */
+  /**
+   * 取消商品开售.
+   *
+   * @param productId 商品 ID
+   * @return 操作结果
+   * @throws WxErrorException 调用微信接口失败
+   */
   WxChannelBaseResponse cancelTimingSale(String productId) throws WxErrorException;
 
-  /** 站内外商品属性映射. */
+  /**
+   * 查询站内外商品属性映射.
+   *
+   * @param param 叶子类目 ID、外部类目和外部属性
+   * @return 对应的站内属性及可选属性值
+   * @throws WxErrorException 调用微信接口失败
+   */
   ExternalProductMappingResponse externalProductMapping(ExternalProductMappingParam param) throws WxErrorException;
 
-  /** 发品前校验. */
+  /**
+   * 发品前校验店铺类目资质.
+   *
+   * @param param 待发布商品的叶子类目 ID
+   * @return 校验结果和未通过原因
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductCategoryPreCheckResponse categoryPreCheck(ProductCategoryPreCheckParam param) throws WxErrorException;
 
-  /** 获取商品上架策略. */
+  /**
+   * 获取店铺维度的商品上架策略.
+   *
+   * @return 当前上架策略
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductAuditStrategyResponse getProductAuditStrategy() throws WxErrorException;
 
-  /** 设置商品上架策略. */
+  /**
+   * 设置店铺维度的商品上架策略.
+   *
+   * @param param 要设置的上架策略
+   * @return 操作结果
+   * @throws WxErrorException 调用微信接口失败
+   */
   WxChannelBaseResponse setProductAuditStrategy(ProductAuditStrategySetParam param) throws WxErrorException;
 
-  /** 获取商品提审限额. */
+  /**
+   * 获取当前店铺的商品提审限额.
+   *
+   * @return 提审总额度和新品剩余额度
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductAuditQuotaResponse getProductAuditQuota() throws WxErrorException;
 
-  /** 商品属性映射及推荐. */
+  /**
+   * 商品属性映射及推荐.
+   *
+   * @param param 叶子类目、商品标题、主图及可选的外部属性
+   * @return 推荐的站内属性
+   * @throws WxErrorException 调用微信接口失败
+   */
   ExternalProductMappingNewResponse externalProductMappingNew(ExternalProductMappingNewParam param)
     throws WxErrorException;
 
-  /** 商品品牌推荐. */
+  /**
+   * 根据商品信息推荐店铺已有资质的品牌.
+   *
+   * @param param 商品叶子类目、标题和图片
+   * @return 推荐品牌
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductBrandRecommendResponse productBrandRecommend(ProductBrandRecommendParam param) throws WxErrorException;
 
-  /** 新增第三方货源信息. */
+  /**
+   * 新增第三方货源信息.
+   *
+   * @param param 场景、发布方式、货主及货源商品信息
+   * @return 包含第三方货源 ID 的操作结果
+   * @throws WxErrorException 调用微信接口失败
+   */
   AddProductThirdPartySourceResponse addProductThirdPartySource(AddProductThirdPartySourceParam param)
     throws WxErrorException;
 
-  /** 获取库存流水. */
+  /**
+   * 获取商品库存流水.
+   *
+   * @param param 商品、SKU、库存类型、时间范围和分页参数；pageSize 必填，库存类型非 0 和 1 时 stockTypeId 必填
+   * @return 库存流水及下一页标识
+   * @throws WxErrorException 调用微信接口失败
+   */
   ProductStockFlowResponse getStockFlow(ProductStockFlowParam param) throws WxErrorException;
 
   /**

weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/product/ProductAuditQuotaResponse.java

@@ -1,6 +1,7 @@
 package me.chanjar.weixin.channel.bean.product;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.io.Serializable;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 import me.chanjar.weixin.channel.bean.base.WxChannelBaseResponse;
@@ -15,7 +16,9 @@ public class ProductAuditQuotaResponse extends WxChannelBaseResponse {
   private AuditQuota auditQuota;
 
   @Data
-  public static class AuditQuota {
+  public static class AuditQuota implements Serializable {
+    private static final long serialVersionUID = 6066821247844334714L;
+
     @JsonProperty("block_status")
     private Integer blockStatus;
     @JsonProperty("avail_quota")

weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/product/ProductCategoryClassifyResponse.java

@@ -1,6 +1,7 @@
 package me.chanjar.weixin.channel.bean.product;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import java.io.Serializable;
 import java.util.List;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
@@ -17,20 +18,26 @@ public class ProductCategoryClassifyResponse extends WxChannelBaseResponse {
   private Boolean wrongCat;
 
   @Data
-  public static class CategoryInfo {
+  public static class CategoryInfo implements Serializable {
+    private static final long serialVersionUID = -4800760946330901306L;
+
     private List<CategoryLevel> cats;
   }
 
   @Data
-  public static class CategoryLevel {
+  public static class CategoryLevel implements Serializable {
+    private static final long serialVersionUID = 8010801623725584755L;
+
     @JsonProperty("cat_info")
     private Category catInfo;
     @JsonProperty("has_permission")
     private Boolean hasPermission;
   }
 
   @Data
-  public static class Category {
+  public static class Category implements Serializable {
+    private static final long serialVersionUID = -9013991576741902059L;
+
     @JsonProperty("cat_id")
     private String catId;
     @JsonProperty("cat_name")

weixin-java-channel/src/main/java/me/chanjar/weixin/channel/bean/product/ProductStockFlowResponse.java

@@ -2,6 +2,7 @@
 
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.databind.JsonNode;
+import java.io.Serializable;
 import java.util.List;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
@@ -16,7 +17,9 @@ public class ProductStockFlowResponse extends WxChannelBaseResponse {
   private StockFlowData data;
 
   @Data
-  public static class StockFlowData {
+  public static class StockFlowData implements Serializable {
+    private static final long serialVersionUID = -4963813730951045381L;
+
     @JsonProperty("stock_flow_info_list")
     private List<JsonNode> stockFlowInfoList;
     @JsonProperty("next_key")

weixin-java-channel/src/test/java/me/chanjar/weixin/channel/api/impl/WxChannelProductManagementServiceImplTest.java

@@ -3,6 +3,9 @@
 import static org.testng.Assert.assertEquals;
 import static org.testng.Assert.assertTrue;
 
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.ObjectOutputStream;
 import java.util.Arrays;
 import me.chanjar.weixin.channel.bean.base.WxChannelBaseResponse;
 import me.chanjar.weixin.channel.bean.product.AddProductThirdPartySourceParam;
@@ -213,6 +216,21 @@ public void shouldGetStockFlowWithRequiredPaginationAndStockTypeId() throws WxEr
     assertEquals(result.getData().getNextKey(), "next");
   }
 
+  @Test
+  public void shouldSerializeNestedProductManagementResponses() throws IOException {
+    ProductAuditQuotaResponse.AuditQuota auditQuota = new ProductAuditQuotaResponse.AuditQuota();
+    ProductCategoryClassifyResponse.Category category = new ProductCategoryClassifyResponse.Category();
+    ProductCategoryClassifyResponse.CategoryLevel categoryLevel = new ProductCategoryClassifyResponse.CategoryLevel();
+    ProductCategoryClassifyResponse.CategoryInfo categoryInfo = new ProductCategoryClassifyResponse.CategoryInfo();
+    ProductStockFlowResponse.StockFlowData stockFlowData = new ProductStockFlowResponse.StockFlowData();
+
+    assertSerializable(auditQuota);
+    assertSerializable(category);
+    assertSerializable(categoryLevel);
+    assertSerializable(categoryInfo);
+    assertSerializable(stockFlowData);
+  }
+
   private static WxChannelProductServiceImpl productService(RecordingChannelService channelService) {
     return new WxChannelProductServiceImpl(channelService);
   }
@@ -230,6 +248,13 @@ private static void assertRequest(RecordingChannelService channelService, String
     assertEquals(JsonUtils.decode(channelService.getRequestJson(), Object.class), JsonUtils.decode(expectedJson, Object.class));
   }
 
+  private static void assertSerializable(Object value) throws IOException {
+    ByteArrayOutputStream output = new ByteArrayOutputStream();
+    try (ObjectOutputStream objectOutput = new ObjectOutputStream(output)) {
+      objectOutput.writeObject(value);
+    }
+  }
+
   private static class RecordingChannelService extends WxChannelServiceHttpClientImpl {
     private final String response;
     private String url;