Merge remote-tracking branch 'yudao/feature/mall_product' into feature/mall_product

# Conflicts: # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/AppCommentController.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentBaseVO.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentRespVO.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/spu/AppProductSpuController.java # yudao-module-mall/yudao-module-product-biz/src/test/java/cn/iocoder/yudao/module/product/service/comment/ProductCommentServiceImplTest.java

Merge remote-tracking branch 'yudao/feature/mall_product' into feature/mall_product
# Conflicts: # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/AppCommentController.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentBaseVO.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentRespVO.java # yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/spu/AppProductSpuController.java # yudao-module-mall/yudao-module-product-biz/src/test/java/cn/iocoder/yudao/module/product/service/comment/ProductCommentServiceImplTest.java
puhui999
2 parents 9ff873fe dcb16608
Showing 57 changed files with 1539 additions and 98 deletions
yudao-framework/yudao-common/src/main/java/cn/iocoder/yudao/framework/common/util/json/JsonUtils.java
yudao-framework/yudao-spring-boot-starter-mybatis/src/main/java/cn/iocoder/yudao/framework/mybatis/core/query/LambdaQueryWrapperX.java
yudao-framework/yudao-spring-boot-starter-web/src/main/java/cn/iocoder/yudao/framework/web/config/YudaoWebAutoConfiguration.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentBaseVO.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/comment/vo/AppProductCommentRespVO.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/spu/AppProductSpuController.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/spu/vo/AppProductSpuDetailRespVO.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/controller/app/spu/vo/AppProductSpuPageReqVO.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/convert/spu/ProductSpuConvert.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/dal/dataobject/comment/ProductCommentDO.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/dal/mysql/spu/ProductSpuMapper.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/service/spu/ProductSpuService.java
yudao-module-mall/yudao-module-product-biz/src/main/java/cn/iocoder/yudao/module/product/service/spu/ProductSpuServiceImpl.java
yudao-module-mall/yudao-module-product-biz/src/test/java/cn/iocoder/yudao/module/product/service/comment/ProductCommentServiceImplTest.java
yudao-module-mall/yudao-module-promotion-api/src/main/java/cn/iocoder/yudao/module/promotion/enums/common/PromotionTypeEnum.java
yudao-module-mall/yudao-module-promotion-biz/src/main/java/cn/iocoder/yudao/module/promotion/controller/admin/seckill/vo/activity/SeckillActivityBaseVO.java
yudao-module-mall/yudao-module-promotion-biz/src/main/java/cn/iocoder/yudao/module/promotion/controller/app/AppMarketTestController.java
yudao-module-mall/yudao-module-promotion-biz/src/main/java/cn/iocoder/yudao/module/promotion/controller/app/activity/AppActivityController.java
yudao-module-mall/yudao-module-promotion-biz/src/main/java/cn/iocoder/yudao/module/promotion/controller/app/activity/vo/AppActivityRespVO.java
yudao-module-mall/yudao-module-promotion-biz/src/main/java/cn/iocoder/yudao/module/promotion/controller/app/coupon/AppCouponController.java
@@ -4,6 +4,7 @@ import cn.hutool.core.util.ArrayUtil;
 import cn.hutool.core.util.StrUtil;
 import cn.hutool.json.JSONUtil;
 import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.DeserializationFeature;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
@@ -29,6 +30,7 @@ public class JsonUtils {
  
     static {
         objectMapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
+        objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
         objectMapper.registerModules(new JavaTimeModule()); // 解决 LocalDateTime 的序列化
     }
  
@@ -2,7 +2,6 @@ package cn.iocoder.yudao.framework.mybatis.core.query;
  
 import cn.hutool.core.util.ArrayUtil;
 import cn.hutool.core.util.ObjectUtil;
-import cn.hutool.core.util.StrUtil;
 import cn.iocoder.yudao.framework.common.util.collection.ArrayUtils;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.toolkit.CollectionUtils;
@@ -10,11 +10,14 @@ import cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.autoconfigure.web.client.RestTemplateAutoConfiguration;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.web.client.RestTemplateBuilder;
 import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.util.AntPathMatcher;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.client.RestTemplate;
 import org.springframework.web.cors.CorsConfiguration;
 import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
 import org.springframework.web.filter.CorsFilter;
@@ -113,4 +116,13 @@ public class YudaoWebAutoConfiguration implements WebMvcConfigurer {
         return bean;
     }
  
+    /**
+     * 创建 RestTemplate 实例
+     *
+     * @param restTemplateBuilder {@link RestTemplateAutoConfiguration#restTemplateBuilder}
+     */
+    @Bean
+    public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder) {
+        return restTemplateBuilder.build();
+    }
 }
 package cn.iocoder.yudao.module.product.controller.app.comment.vo;
  
+import cn.iocoder.yudao.module.product.controller.app.property.vo.value.AppProductPropertyValueDetailRespVO;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
  
@@ -27,6 +28,9 @@ public class AppProductCommentBaseVO {
     @NotNull(message = "商品SKU编号不能为空")
     private Long skuId;
  
+    @Schema(description = "商品 SKU 属性", required = true)
+    private List<AppProductPropertyValueDetailRespVO> skuProperties; // TODO puhui999：这个需要从数据库查询哈
+
     @Schema(description = "评分星级 1-5分", required = true, example = "5")
     @NotNull(message = "评分星级 1-5分不能为空")
     private Integer scores;
@@ -9,8 +9,6 @@ import org.springframework.format.annotation.DateTimeFormat;
 import java.time.LocalDateTime;
 import java.util.List;
  
-import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND;
-
 @Schema(description = "用户APP - 商品评价 Response VO")
 @Data
 @EqualsAndHashCode(callSuper = true)
@@ -3,7 +3,7 @@ package cn.iocoder.yudao.module.product.controller.app.spu;
 import cn.iocoder.yudao.framework.common.pojo.CommonResult;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuDetailRespVO;
-import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageItemRespVO;
+import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageRespVO;
 import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageReqVO;
 import cn.iocoder.yudao.module.product.convert.spu.ProductSpuConvert;
 import cn.iocoder.yudao.module.product.dal.dataobject.sku.ProductSkuDO;
@@ -13,6 +13,7 @@ import cn.iocoder.yudao.module.product.service.sku.ProductSkuService;
 import cn.iocoder.yudao.module.product.service.spu.ProductSpuService;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -40,9 +41,22 @@ public class AppProductSpuController {
     @Resource
     private ProductSkuService productSkuService;
  
+    @GetMapping("/list")
+    @Operation(summary = "获得商品 SPU 列表")
+    @Parameters({
+            @Parameter(name = "recommendType", description = "推荐类型", required = true), // 参见 AppProductSpuPageReqVO.RECOMMEND_TYPE_XXX 常量
+            @Parameter(name = "count", description = "数量", required = true)
+    })
+    public CommonResult<List<AppProductSpuPageRespVO>> getSpuList(
+            @RequestParam("recommendType") String recommendType,
+            @RequestParam(value = "count", defaultValue = "10") Integer count) {
+        List<ProductSpuDO> list = productSpuService.getSpuList(recommendType, count);
+        return success(ProductSpuConvert.INSTANCE.convertListForGetSpuList(list));
+    }
+
     @GetMapping("/page")
     @Operation(summary = "获得商品 SPU 分页")
-    public CommonResult<PageResult<AppProductSpuPageItemRespVO>> getSpuPage(@Valid AppProductSpuPageReqVO pageVO) {
+    public CommonResult<PageResult<AppProductSpuPageRespVO>> getSpuPage(@Valid AppProductSpuPageReqVO pageVO) {
         PageResult<ProductSpuDO> pageResult = productSpuService.getSpuPage(pageVO);
         return success(ProductSpuConvert.INSTANCE.convertPageForGetSpuPage(pageResult));
     }
@@ -39,6 +39,11 @@ public class AppProductSpuDetailRespVO {
     @Schema(description = "单位名", required = true, example = "个")
     private String unitName;
  
+    // ========== 营销相关字段 =========
+
+    @Schema(description = "活动排序数组", required = true, example = "1024")
+    private List<Integer> activityOrders;
+
     // ========== SKU 相关字段 =========
  
     @Schema(description = "规格类型", required = true, example = "true")
@@ -20,6 +20,7 @@ public class AppProductSpuPageReqVO extends PageParam {
     public static final String SORT_FIELD_SALES_COUNT = "salesCount";
  
     public static final String RECOMMEND_TYPE_HOT = "hot";
+    public static final String RECOMMEND_TYPE_GOOD = "good";
  
     @Schema(description = "分类编号", example = "1")
     private Long categoryId;
@@ -33,7 +34,7 @@ public class AppProductSpuPageReqVO extends PageParam {
     @Schema(description = "排序方式", example = "true")
     private Boolean sortAsc;
  
-    @Schema(description = "推荐类型", example = "hot") // 参见 AppProductSpuPageReqVO.RECOMMEND_TYPE_XXX 常亮
+    @Schema(description = "推荐类型", example = "hot") // 参见 AppProductSpuPageReqVO.RECOMMEND_TYPE_XXX 常量
     private String recommendType;
  
     @AssertTrue(message = "排序字段不合法")
@@ -5,9 +5,9 @@ import lombok.Data;
  
 import java.util.List;
  
-@Schema(description = "用户 App - 商品 SPU 分页项 Response VO")
+@Schema(description = "用户 App - 商品 SPU Response VO")
 @Data
-public class AppProductSpuPageItemRespVO {
+public class AppProductSpuPageRespVO {
  
     @Schema(description = "商品 SPU 编号", required = true, example = "1")
     private Long id;
@@ -35,6 +35,11 @@ public class AppProductSpuPageItemRespVO {
     @Schema(description = "库存", required = true, example = "666")
     private Integer stock;
  
+    // ========== 营销相关字段 =========
+
+    @Schema(description = "活动排序数组", required = true, example = "1024")
+    private List<Integer> activityOrders;
+
     // ========== 统计相关字段 =========
  
     @Schema(description = "商品销量", required = true, example = "1024")
 package cn.iocoder.yudao.module.product.convert.spu;
  
-import cn.hutool.core.collection.CollUtil;
 import cn.hutool.core.util.StrUtil;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.dict.core.util.DictFrameworkUtils;
 import cn.iocoder.yudao.module.product.api.spu.dto.ProductSpuRespDTO;
-import cn.iocoder.yudao.module.product.controller.admin.sku.vo.ProductSkuRespVO;
 import cn.iocoder.yudao.module.product.controller.admin.spu.vo.*;
 import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuDetailRespVO;
-import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageItemRespVO;
+import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageRespVO;
 import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageReqVO;
 import cn.iocoder.yudao.module.product.convert.sku.ProductSkuConvert;
 import cn.iocoder.yudao.module.product.dal.dataobject.sku.ProductSkuDO;
@@ -80,14 +78,15 @@ public interface ProductSpuConvert {
  
     // ========== 用户 App 相关 ==========
  
-    default PageResult<AppProductSpuPageItemRespVO> convertPageForGetSpuPage(PageResult<ProductSpuDO> page) {
-        // 累加虚拟销量
-        page.getList().forEach(spu -> spu.setSalesCount(spu.getSalesCount() + spu.getVirtualSalesCount()));
-        // 然后进行转换
-        return convertPageForGetSpuPage0(page);
-    }
+    PageResult<AppProductSpuPageRespVO> convertPageForGetSpuPage(PageResult<ProductSpuDO> page);
  
-    PageResult<AppProductSpuPageItemRespVO> convertPageForGetSpuPage0(PageResult<ProductSpuDO> page);
+    default List<AppProductSpuPageRespVO> convertListForGetSpuList(List<ProductSpuDO> list) {
+        // 处理虚拟销量
+        list.forEach(spu -> spu.setSalesCount(spu.getSalesCount() + spu.getVirtualSalesCount()));
+        return convertListForGetSpuList0(list);
+    }
+    @Named("convertListForGetSpuList0")
+    List<AppProductSpuPageRespVO> convertListForGetSpuList0(List<ProductSpuDO> list);
  
     default AppProductSpuDetailRespVO convertForGetSpuDetail(ProductSpuDO spu, List<ProductSkuDO> skus) {
         // 处理 SPU
@@ -109,15 +108,9 @@ public interface ProductSpuConvert {
     List<AppProductSpuDetailRespVO.Sku> convertListForGetSpuDetail(List<ProductSkuDO> skus);
  
     default ProductSpuDetailRespVO convertForSpuDetailRespVO(ProductSpuDO spu, List<ProductSkuDO> skus) {
-        ProductSpuDetailRespVO productSpuDetailRespVO = convert03(spu);
-        // skus 为空直接返回
-        if (CollUtil.isEmpty(skus)) {
-            return productSpuDetailRespVO;
-        }
-        List<ProductSkuRespVO> skuVOs = ProductSkuConvert.INSTANCE.convertList(skus);
-        // fix: 因为现在已改为 sku 属性列表 属性 已包含 属性名字 属性值名字 所以不需要再额外处理，属性更新时更新 sku 中的属性相关冗余即可
-        productSpuDetailRespVO.setSkus(skuVOs);
-        return productSpuDetailRespVO;
+        ProductSpuDetailRespVO detailRespVO = convert03(spu);
+        detailRespVO.setSkus(ProductSkuConvert.INSTANCE.convertList(skus));
+        return detailRespVO;
     }
  
 }
@@ -40,7 +40,7 @@ public class ProductCommentDO extends BaseDO {
     private Long id;
  
     /**
-     * 评价人 用户编号
+     * 评价人的用户编号
      *
      * 关联 MemberUserDO 的 id 编号
      */
@@ -5,6 +5,7 @@ import cn.hutool.core.util.ObjectUtil;
 import cn.iocoder.yudao.framework.common.pojo.PageResult;
 import cn.iocoder.yudao.framework.mybatis.core.mapper.BaseMapperX;
 import cn.iocoder.yudao.framework.mybatis.core.query.LambdaQueryWrapperX;
+import cn.iocoder.yudao.framework.mybatis.core.query.QueryWrapperX;
 import cn.iocoder.yudao.module.product.controller.admin.spu.vo.ProductSpuExportReqVO;
 import cn.iocoder.yudao.module.product.controller.admin.spu.vo.ProductSpuPageReqVO;
 import cn.iocoder.yudao.module.product.controller.app.spu.vo.AppProductSpuPageReqVO;
@@ -66,7 +67,10 @@ public interface ProductSpuMapper extends BaseMapperX&lt;ProductSpuDO&gt; {
         // 推荐类型的过滤条件
         if (ObjUtil.equal(pageReqVO.getRecommendType(), AppProductSpuPageReqVO.RECOMMEND_TYPE_HOT)) {
             query.eq(ProductSpuDO::getRecommendHot, true);
+        } else if (ObjUtil.equal(pageReqVO.getRecommendType(), AppProductSpuPageReqVO.RECOMMEND_TYPE_GOOD)) {
+            query.eq(ProductSpuDO::getRecommendGood, true);
         }
+
         // 排序逻辑
         if (Objects.equals(pageReqVO.getSortField(), AppProductSpuPageReqVO.SORT_FIELD_SALES_COUNT)) {
             query.last(String.format(" ORDER BY (sales_count + virtual_sales_count) %s, sort DESC, id DESC",
@@ -80,6 +84,21 @@ public interface ProductSpuMapper extends BaseMapperX&lt;ProductSpuDO&gt; {
         return selectPage(pageReqVO, query);
     }
  
+    default List<ProductSpuDO> selectListByRecommendType(String recommendType, Integer count) {
+        QueryWrapperX<ProductSpuDO> query = new QueryWrapperX<>();
+        // 上架状态 且有库存
+        query.eq("status", ProductSpuStatusEnum.ENABLE.getStatus()).gt("stock", 0);
+        // 推荐类型的过滤条件
+        if (ObjUtil.equal(recommendType, AppProductSpuPageReqVO.RECOMMEND_TYPE_HOT)) {
+            query.eq("recommend_hot", true);
+        } else if (ObjUtil.equal(recommendType, AppProductSpuPageReqVO.RECOMMEND_TYPE_GOOD)) {
+            query.eq("recommend_good", true);
+        }
+        // 设置最大长度
+        query.limitN(count);
+        return selectList(query);
+    }
+
     /**
      * 更新商品 SPU 库存
      *
@@ -111,33 +130,34 @@ public interface ProductSpuMapper extends BaseMapperX&lt;ProductSpuDO&gt; {
     }
  
     /**
-     * 验证选项卡类型构建条件
+     * 添加后台 Tab 选项的查询条件
      *
      * @param tabType      标签类型
-     * @param queryWrapper 查询条件
+     * @param query 查询条件
      */
-    static void appendTabQuery(Integer tabType, LambdaQueryWrapperX<ProductSpuDO> queryWrapper) {
+    static void appendTabQuery(Integer tabType, LambdaQueryWrapperX<ProductSpuDO> query) {
         // 出售中商品
         if (ObjectUtil.equals(ProductSpuPageReqVO.FOR_SALE, tabType)) {
-            queryWrapper.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.ENABLE.getStatus());
+            query.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.ENABLE.getStatus());
         }
         // 仓储中商品
         if (ObjectUtil.equals(ProductSpuPageReqVO.IN_WAREHOUSE, tabType)) {
-            queryWrapper.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.DISABLE.getStatus());
+            query.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.DISABLE.getStatus());
         }
         // 已售空商品
         if (ObjectUtil.equals(ProductSpuPageReqVO.SOLD_OUT, tabType)) {
-            queryWrapper.eqIfPresent(ProductSpuDO::getStock, 0);
+            query.eqIfPresent(ProductSpuDO::getStock, 0);
         }
         // 警戒库存
         if (ObjectUtil.equals(ProductSpuPageReqVO.ALERT_STOCK, tabType)) {
-            queryWrapper.le(ProductSpuDO::getStock, ProductConstants.ALERT_STOCK)
+            query.le(ProductSpuDO::getStock, ProductConstants.ALERT_STOCK)
                     // 如果库存触发警戒库存且状态为回收站的话则不在警戒库存列表展示
                     .notIn(ProductSpuDO::getStatus, ProductSpuStatusEnum.RECYCLE.getStatus());
         }
         // 回收站
         if (ObjectUtil.equals(ProductSpuPageReqVO.RECYCLE_BIN, tabType)) {
-            queryWrapper.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.RECYCLE.getStatus());
+            query.eqIfPresent(ProductSpuDO::getStatus, ProductSpuStatusEnum.RECYCLE.getStatus());
         }
     }
+
 }
@@ -99,6 +99,15 @@ public interface ProductSpuService {
     PageResult<ProductSpuDO> getSpuPage(AppProductSpuPageReqVO pageReqVO);
  
     /**
+     * 获得商品 SPU 列表，提供给用户 App 使用
+     *
+     * @param recommendType 推荐类型
+     * @param count 数量
+     * @return 商品 SPU 列表
+     */
+    List<ProductSpuDO> getSpuList(String recommendType, Integer count);
+
+    /**
      * 更新商品 SPU 库存（增量）
      *
      * @param stockIncrCounts SPU 编号与库存变化（增量）的映射
@@ -202,6 +202,11 @@ public class ProductSpuServiceImpl implements ProductSpuService {
     }
  
     @Override
+    public List<ProductSpuDO> getSpuList(String recommendType, Integer count) {
+        return productSpuMapper.selectListByRecommendType(recommendType, count);
+    }
+
+    @Override
     @Transactional(rollbackFor = Exception.class)
     public void updateSpuStock(Map<Long, Integer> stockIncrCounts) {
         stockIncrCounts.forEach((id, incCount) -> productSpuMapper.updateStock(id, incCount));
@@ -192,9 +192,4 @@ public class ProductCommentServiceImplTest extends BaseDbUnitTest {
         assertEquals("测试", productCommentDO.getReplyContent());
     }
  
-    @Test
-    public void testCreateComment_success() {
-        // mock 测试
-    }
-
 }
@@ -15,11 +15,15 @@ import java.util.Arrays;
 @AllArgsConstructor
 public enum PromotionTypeEnum implements IntArrayValuable {
  
-    DISCOUNT_ACTIVITY(1, "限时折扣"),
-    REWARD_ACTIVITY(2, "满减送"),
+    SECKILL_ACTIVITY(1, "秒杀活动"),
+    BARGAIN_ACTIVITY(2, "拼团活动"),
+    COMBINATION_ACTIVITY(3, "砍价活动"),
  
-    MEMBER(3, "会员折扣"), // TODO 芋艿：待实现 StrUtil.format("会员折扣：省 {} 元", formatPrice(orderItem.getPayPrice() - memberPrice)
-    COUPON(4, "优惠劵")
+    DISCOUNT_ACTIVITY(4, "限时折扣"),
+    REWARD_ACTIVITY(5, "满减送"),
+
+    MEMBER(6, "会员折扣"),
+    COUPON(7, "优惠劵")
     ;
  
     public static final int[] ARRAYS = Arrays.stream(values()).mapToInt(PromotionTypeEnum::getType).toArray();
@@ -58,7 +58,7 @@ public class SeckillActivityBaseVO {
  
         @Schema(description = "每人限购", example = "10") // 如果为 0 则不限购
         @Min(value = 0, message = "每人限购需要大于等于 0")
-        private Integer limitBuyCount;
+        private Integer limitCount;
  
     }
  
-package cn.iocoder.yudao.module.promotion.controller.app;
-
-import cn.iocoder.yudao.framework.common.pojo.CommonResult;
-import io.swagger.v3.oas.annotations.Operation;
-import io.swagger.v3.oas.annotations.tags.Tag;
-import org.springframework.validation.annotation.Validated;
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.RequestMapping;
-import org.springframework.web.bind.annotation.RestController;
-
-import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
-
-@Tag(name = "用户 App - 营销")
-@RestController
-@RequestMapping("/market/test")
-@Validated
-public class AppMarketTestController {
-
-    @GetMapping("/get")
-    @Operation(summary = "获取 market 信息")
-    public CommonResult<String> get() {
-        return success("true");
-    }
-}
+package cn.iocoder.yudao.module.promotion.controller.app.activity;
+
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.module.promotion.controller.app.activity.vo.AppActivityRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.LocalDateTime;
+import java.util.*;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+
+@Tag(name = "用户 APP - 营销活动") // 用于提供跨多个活动的 HTTP 接口
+@RestController
+@RequestMapping("/promotion/activity")
+@Validated
+public class AppActivityController {
+
+    @GetMapping("/list-by-spu-id")
+    @Operation(summary = "获得单个商品，近期参与的每个活动") // 每种活动，只返回一个
+    @Parameter(name = "spuId", description = "商品编号", required = true)
+    public CommonResult<List<AppActivityRespVO>> getActivityListBySpuId(@RequestParam("spuId") Long spuId) {
+        // TODO 芋艿，实现
+        List<AppActivityRespVO> randomList = new ArrayList<>();
+        Random random = new Random();
+        for (int i = 0; i < 3; i++) { // 生成5个随机对象
+            AppActivityRespVO vo = new AppActivityRespVO();
+            vo.setId(random.nextLong()); // 随机生成一个长整型 ID
+            vo.setType(i + 1); // 随机生成一个介于0到2之间的整数，对应枚举类型的三种类型之一
+            vo.setName(String.format("活动%d", random.nextInt(100))); // 随机生成一个类似于“活动XX”的活动名称，XX为0到99之间的随机整数
+            vo.setStartTime(LocalDateTime.now()); // 随机生成一个在过去的一年内的开始时间（以毫秒为单位）
+            vo.setEndTime(LocalDateTime.now()); // 随机生成一个在未来的一年内的结束时间（以毫秒为单位）
+            randomList.add(vo);
+        }
+        return success(randomList);
+    }
+
+    @GetMapping("/list-by-spu-ids")
+    @Operation(summary = "获得多个商品，近期参与的每个活动") // 每种活动，只返回一个；key 为 SPU 编号
+    @Parameter(name = "spuIds", description = "商品编号数组", required = true)
+    public CommonResult<Map<Long, List<AppActivityRespVO>>> getActivityListBySpuIds(@RequestParam("spuIds") List<Long> spuIds) {
+        // TODO 芋艿，实现
+        List<AppActivityRespVO> randomList = new ArrayList<>();
+        Random random = new Random();
+        for (int i = 0; i < 5; i++) { // 生成5个随机对象
+            AppActivityRespVO vo = new AppActivityRespVO();
+            vo.setId(random.nextLong()); // 随机生成一个长整型 ID
+            vo.setType(random.nextInt(3)); // 随机生成一个介于0到2之间的整数，对应枚举类型的三种类型之一
+            vo.setName(String.format("活动%d", random.nextInt(100))); // 随机生成一个类似于“活动XX”的活动名称，XX为0到99之间的随机整数
+            vo.setStartTime(LocalDateTime.now()); // 随机生成一个在过去的一年内的开始时间（以毫秒为单位）
+            vo.setEndTime(LocalDateTime.now()); // 随机生成一个在未来的一年内的结束时间（以毫秒为单位）
+            randomList.add(vo);
+        }
+        Map<Long, List<AppActivityRespVO>> map = new HashMap<>();
+        map.put(109L, randomList);
+        return success(map);
+    }
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.activity.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Schema(description = "用户 App - 营销活动 Response VO")
+@Data
+public class AppActivityRespVO {
+
+    @Schema(description = "活动编号", required = true, example = "1024")
+    private Long id;
+
+    @Schema(description = "活动类型", required = true, example = "1") // 对应 PromotionTypeEnum 枚举
+    private Integer type;
+
+    @Schema(description = "活动名称", required = true, example = "618 大促")
+    private String name;
+
+    @Schema(description = "活动开始时间", required = true)
+    private LocalDateTime startTime;
+
+    @Schema(description = "活动结束时间", required = true)
+    private LocalDateTime endTime;
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.coupon;
+
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.template.AppCouponTemplatePageReqVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+
+@Tag(name = "用户 App - 优惠劵")
+@RestController
+@RequestMapping("/promotion/coupon")
+@Validated
+public class AppCouponController {
+
+    // TODO 芋艿：待实现
+    @PostMapping("/take")
+    @Operation(summary = "领取优惠劵")
+    public CommonResult<Long> takeCoupon(@RequestBody AppCouponTemplatePageReqVO pageReqVO) {
+        return success(1L);
+    }
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.coupon;
+
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.framework.common.pojo.PageResult;
+import cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.template.AppCouponTemplatePageReqVO;
+import cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.template.AppCouponTemplateRespVO;
+import cn.iocoder.yudao.module.promotion.service.coupon.CouponTemplateService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import javax.annotation.Resource;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Random;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+
+@Tag(name = "用户 App - 优惠劵模板")
+@RestController
+@RequestMapping("/promotion/coupon-template")
+@Validated
+public class AppCouponTemplateController {
+
+    @Resource
+    private CouponTemplateService couponTemplateService;
+
+    // TODO 芋艿：待实现
+    @GetMapping("/list")
+    @Operation(summary = "获得优惠劵模版列表") // 目前主要给商品详情使用
+    @Parameters({
+            @Parameter(name = "spuId", description = "商品 SPU 编号", required = true),
+            @Parameter(name = "useType", description = "使用类型"),
+            @Parameter(name = "count", description = "数量", required = true)
+    })
+    public CommonResult<List<AppCouponTemplateRespVO>> getCouponTemplateList(@RequestParam("spuId") Long spuId,
+                                                                             @RequestParam(value = "useType", required = false) Integer useType) {
+        List<AppCouponTemplateRespVO> list = new ArrayList<>();
+        Random random = new Random();
+        for (int i = 0; i < 10; i++) {
+            AppCouponTemplateRespVO vo = new AppCouponTemplateRespVO();
+            vo.setId(i + 1L);
+            vo.setName("优惠劵" + (i + 1));
+            vo.setTakeLimitCount(random.nextInt(10) + 1);
+            vo.setUsePrice(random.nextInt(100) * 100);
+            vo.setValidityType(random.nextInt(2) + 1);
+            if (vo.getValidityType() == 1) {
+                vo.setValidStartTime(LocalDateTime.now().plusDays(random.nextInt(10)));
+                vo.setValidEndTime(LocalDateTime.now().plusDays(random.nextInt(20) + 10));
+            } else {
+                vo.setFixedStartTerm(random.nextInt(10));
+                vo.setFixedEndTerm(random.nextInt(10) + vo.getFixedStartTerm() + 1);
+            }
+            vo.setDiscountType(random.nextInt(2) + 1);
+            if (vo.getDiscountType() == 1) {
+                vo.setDiscountPercent(null);
+                vo.setDiscountPrice(random.nextInt(50) * 100);
+                vo.setDiscountLimitPrice(null);
+            } else {
+                vo.setDiscountPercent(random.nextInt(90) + 10);
+                vo.setDiscountPrice(null);
+                vo.setDiscountLimitPrice(random.nextInt(200) * 100);
+            }
+            vo.setTakeStatus(random.nextBoolean());
+            list.add(vo);
+        }
+        return success(list);
+    }
+
+    // TODO 芋艿：待实现
+    @GetMapping("/page")
+    @Operation(summary = "获得优惠劵模版分页")
+    public CommonResult<PageResult<AppCouponTemplateRespVO>> getCouponTemplatePage(AppCouponTemplatePageReqVO pageReqVO) {
+        return null;
+    }
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.coupon;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import javax.validation.constraints.NotNull;
+
+@Schema(description = "用户 App - 优惠劵领取 Request VO")
+@Data
+public class AppCouponTakeReqVO {
+
+    @Schema(description = "优惠劵模板编号", example = "1")
+    @NotNull(message = "优惠劵模板编号不能为空")
+    private Long templateId;
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.template;
+
+import cn.iocoder.yudao.framework.common.pojo.PageParam;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import lombok.ToString;
+
+@Schema(description = "用户 App - 优惠劵模板分页 Request VO")
+@Data
+@EqualsAndHashCode(callSuper = true)
+@ToString(callSuper = true)
+public class AppCouponTemplatePageReqVO extends PageParam {
+
+    @Schema(description = "使用类型", example = "1")
+    // TODO 芋艿：这里要限制下枚举的使用
+    private Integer useType;
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.coupon.vo.template;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import javax.validation.constraints.Min;
+import java.time.LocalDateTime;
+
+@Schema(description = "用户 App - 优惠劵模板 Response VO")
+@Data
+public class AppCouponTemplateRespVO {
+
+    @Schema(description = "优惠劵模板编号", required = true, example = "1")
+    private Long id;
+
+    @Schema(description = "优惠劵名", required = true, example = "春节送送送")
+    private String name;
+
+    @Schema(description = "每人限领个数", required = true, example = "66") // -1 - 则表示不限制
+    private Integer takeLimitCount;
+
+    @Schema(description = "是否设置满多少金额可用", required = true, example = "100") // 单位：分；0 - 不限制
+    private Integer usePrice;
+
+    // TODO 芋艿：这两要改的
+//    @Schema(description = "商品范围", required = true, example = "1")
+//    @InEnum(PromotionProductScopeEnum.class)
+//    private Integer productScope;
+//
+//    @Schema(description = "商品 SPU 编号的数组", example = "1,3")
+//    private List<Long> productSpuIds;
+
+    @Schema(description = "生效日期类型", required = true, example = "1")
+    private Integer validityType;
+
+    @Schema(description = "固定日期 - 生效开始时间")
+    private LocalDateTime validStartTime;
+
+    @Schema(description = "固定日期 - 生效结束时间")
+    private LocalDateTime validEndTime;
+
+    @Schema(description = "领取日期 - 开始天数")
+    @Min(value = 0L, message = "开始天数必须大于 0")
+    private Integer fixedStartTerm;
+
+    @Schema(description = "领取日期 - 结束天数")
+    @Min(value = 1L, message = "开始天数必须大于 1")
+    private Integer fixedEndTerm;
+
+    @Schema(description = "优惠类型", required = true, example = "1")
+    private Integer discountType;
+
+    @Schema(description = "折扣百分比", example = "80") //  例如说，80% 为 80
+    private Integer discountPercent;
+
+    @Schema(description = "优惠金额", example = "10")
+    @Min(value = 0, message = "优惠金额需要大于等于 0")
+    private Integer discountPrice;
+
+    @Schema(description = "折扣上限", example = "100") // 单位：分，仅在 discountType 为 PERCENT 使用
+    private Integer discountLimitPrice;
+
+    // ========== 用户相关字段 ==========
+
+    @Schema(description = "是否已领取", required = true, example = "true")
+    private Boolean takeStatus;
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.seckill;
+
+import cn.iocoder.yudao.framework.common.pojo.CommonResult;
+import cn.iocoder.yudao.module.promotion.controller.app.seckill.vo.AppSeckillActivitiDetailRespVO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.List;
+
+import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
+
+@Tag(name = "用户 App - 秒杀活动")
+@RestController
+@RequestMapping("/promotion/seckill-activity")
+@Validated
+public class AppSeckillActivityController {
+
+    @GetMapping("/get-detail")
+    @Operation(summary = "获得秒杀活动明细")
+    @Parameter(name = "id", description = "活动编号", required = true, example = "1024")
+    public CommonResult<AppSeckillActivitiDetailRespVO> getSeckillActivity(@RequestParam("id") Long id) {
+        // TODO 芋艿：如果禁用的时候，需要抛出异常；
+        AppSeckillActivitiDetailRespVO obj = new AppSeckillActivitiDetailRespVO();
+        // 设置其属性的值
+        obj.setId(id);
+        obj.setName("晚九点限时秒杀");
+        obj.setStatus(1);
+        obj.setStartTime(LocalDateTime.of(2023, 6, 11, 0, 0, 0));
+        obj.setEndTime(LocalDateTime.of(2023, 6, 11, 23, 59, 0));
+        obj.setSpuId(633L);
+        // 创建一个Product对象的列表
+        List<AppSeckillActivitiDetailRespVO.Product> productList = new ArrayList<>();
+        // 创建三个新的Product对象并设置其属性的值
+        AppSeckillActivitiDetailRespVO.Product product1 = new AppSeckillActivitiDetailRespVO.Product();
+        product1.setSkuId(1L);
+        product1.setSeckillPrice(100);
+        product1.setQuota(50);
+        product1.setLimitCount(3);
+        // 将第一个Product对象添加到列表中
+        productList.add(product1);
+        // 创建第二个Product对象并设置其属性的值
+        AppSeckillActivitiDetailRespVO.Product product2 = new AppSeckillActivitiDetailRespVO.Product();
+        product2.setSkuId(2L);
+        product2.setSeckillPrice(200);
+        product2.setQuota(100);
+        product2.setLimitCount(4);
+        // 将第二个Product对象添加到列表中
+        productList.add(product2);
+        // 创建第三个Product对象并设置其属性的值
+        AppSeckillActivitiDetailRespVO.Product product3 = new AppSeckillActivitiDetailRespVO.Product();
+        product3.setSkuId(3L);
+        product3.setSeckillPrice(300);
+        product3.setQuota(150);
+        product3.setLimitCount(5);
+        // 将第三个Product对象添加到列表中
+        productList.add(product3);
+        // 将Product列表设置为对象的属性值
+        obj.setProducts(productList);
+        return success(obj);
+    }
+
+}
+package cn.iocoder.yudao.module.promotion.controller.app.seckill.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+@Schema(description = "用户 App - 秒杀活动 Response VO")
+@Data
+public class AppSeckillActivitiDetailRespVO {
+
+    @Schema(description = "秒杀活动编号", required = true, example = "1024")
+    private Long id;
+
+    @Schema(description = "秒杀活动名称", required = true, example = "晚九点限时秒杀")
+    private String name;
+
+    @Schema(description = "活动状态", required = true, example = "1")
+    private Integer status;
+
+    // TODO @芋艿：开始时间、结束时间，要和场次结合起来；就是要算到当前场次，是几点哈；
+
+    @Schema(description = "活动开始时间", required = true)
+    private LocalDateTime startTime;
+
+    @Schema(description = "活动结束时间", required = true)
+    private LocalDateTime endTime;
+
+    @Schema(description = "商品 SPU 编号", required = true, example = "2048")
+    private Long spuId;
+
+    @Schema(description = "商品 SPU 名字", required = true)
+    private List<Product> products;
+
+    @Schema(description = "商品信息")
+    @Data
+    public static class Product {
+
+        @Schema(description = "商品 SKU 编号", required = true, example = "4096")
+        private Long skuId;
+
+        @Schema(description = "秒杀金额，单位：分", required = true, example = "100")
+        private Integer seckillPrice;
+
+        @Schema(description = "秒杀限量库存", required = true, example = "50")
+        private Integer quota;
+
+        @Schema(description = "limitCount", required = true, example = "10")
+        private Integer limitCount;
+
+    }
+
+}
@@ -56,7 +56,7 @@ public interface SeckillActivityConvert {
                 && ObjectUtil.equals(productDO.getSkuId(), productVO.getSkuId())
                 && ObjectUtil.equals(productDO.getSeckillPrice(), productVO.getSeckillPrice())
                 && ObjectUtil.equals(productDO.getStock(), productVO.getStock())
-                && ObjectUtil.equals(productDO.getLimitBuyCount(), productVO.getLimitBuyCount());
+                && ObjectUtil.equals(productDO.getLimitCount(), productVO.getLimitCount());
     }
  
     /**
@@ -71,7 +71,7 @@ public interface SeckillActivityConvert {
                 && ObjectUtil.equals(productDO.getSkuId(), productVO.getSkuId())
                 && ObjectUtil.equals(productDO.getSeckillPrice(), productVO.getSeckillPrice())
                 && ObjectUtil.equals(productDO.getStock(), productVO.getStock())
-                && ObjectUtil.equals(productDO.getLimitBuyCount(), productVO.getLimitBuyCount());
+                && ObjectUtil.equals(productDO.getLimitCount(), productVO.getLimitCount());
  
     }
  
@@ -37,7 +37,7 @@ public class SeckillActivityDO extends BaseDO {
     private String name;
     /**
      * 活动状态
-     * <p>
+     *
      * 枚举 {@link PromotionActivityStatusEnum 对应的类}
      */
     private Integer status;
@@ -53,6 +53,7 @@ public class SeckillProductDO extends BaseDO {
      */
     private Integer seckillPrice;
  
+    // TODO @芋艿：改成 quota 限量库存；每次购买时，需要减小；
     /**
      * 秒杀库存
      */
@@ -61,5 +62,6 @@ public class SeckillProductDO extends BaseDO {
     /**
      * 每人限购
      */
-    private Integer limitBuyCount;
-}
 \ No newline at end of file
+    private Integer limitCount;
+
+}
@@ -51,9 +51,11 @@ public interface ErrorCodeConstants {
     ErrorCode EXPRESS_CODE_DUPLICATE = new ErrorCode(1011003001, "已经存在该编码的快递公司");
     ErrorCode EXPRESS_TEMPLATE_NOT_EXISTS = new ErrorCode(1011003002, "运费模板不存在");
     ErrorCode EXPRESS_TEMPLATE_NAME_DUPLICATE = new ErrorCode(1011003003, "已经存在该运费模板名");
-    ErrorCode DELIVERY_EXPRESS_USER_ADDRESS_IS_EMPTY = new ErrorCode(1011003004, "计算快递运费时，收件人地址编号为空");
-    ErrorCode PRODUCT_EXPRESS_TEMPLATE_NOT_FOUND = new ErrorCode(1011003005, "找不到到商品对应的运费模板");
-    ErrorCode PICK_UP_STORE_NOT_EXISTS = new ErrorCode(1011003006, "自提门店不存在");
+    ErrorCode DELIVERY_EXPRESS_USER_ADDRESS_IS_EMPTY = new ErrorCode(1011003004, "计算快递运费时，收件人地址编号为空"); // TODO @jaosn：这个错误码，放到 Price 这块
+    ErrorCode PRODUCT_EXPRESS_TEMPLATE_NOT_FOUND = new ErrorCode(1011003005, "找不到到商品对应的运费模板");  // TODO @jaosn：这个错误码，放到 Price 这块
+    ErrorCode EXPRESS_API_QUERY_ERROR = new ErrorCode(1011003006, "快递查询接口异常");
+    ErrorCode EXPRESS_API_QUERY_FAILED = new ErrorCode(1011003007, "快递查询返回失败, 原因：{}");
+    ErrorCode PICK_UP_STORE_NOT_EXISTS = new ErrorCode(1011003008, "自提门店不存在");
  
     // ========== Price 相关 1011004000 ============
     ErrorCode PRICE_CALCULATE_PAY_PRICE_ILLEGAL = new ErrorCode(1011004000, "支付价格计算异常，原因：价格小于等于 0");
@@ -17,10 +17,8 @@ public enum TradeOrderTypeEnum implements IntArrayValuable {
  
     NORMAL(0, "普通订单"),
     SECKILL(1, "秒杀订单"),
-    // TODO 芋艿：如下三个字段，名字需要改下，等后面表设计完成后。
-    KANJIA(2, "砍价订单"),
-    PINTUAN(3, "拼团订单"),
-    YUSHOU(4, "预售订单"),
+    BARGAIN(2, "砍价订单"),
+    COMBINATION(3, "拼团订单"),
     ;
  
     public static final int[] ARRAYS = Arrays.stream(values()).mapToInt(TradeOrderTypeEnum::getType).toArray();
@@ -71,7 +71,7 @@ public class AppTradeOrderController {
     }
  
     @PostMapping("/update-paid")
-    @Operation(description = "更新订单为已支付") // 由 pay-module 支付服务，进行回调，可见 PayNotifyJob
+    @Operation(summary = "更新订单为已支付") // 由 pay-module 支付服务，进行回调，可见 PayNotifyJob
     public CommonResult<Boolean> updateOrderPaid(@RequestBody PayOrderNotifyReqDTO notifyReqDTO) {
         tradeOrderService.updateOrderPaid(Long.valueOf(notifyReqDTO.getMerchantOrderId()),
                 notifyReqDTO.getPayOrderId());
+package cn.iocoder.yudao.module.trade.framework.delivery.config;
+
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderEnum;
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+import org.springframework.validation.annotation.Validated;
+
+import javax.validation.Valid;
+import javax.validation.constraints.NotEmpty;
+
+// TODO @jason：TradeExpressProperties；更通用哈
+// TODO @芋艿：未来要不要放数据库中？考虑 saas 多租户时，不同租户使用不同的配置？
+/**
+ * 交易快递查询的配置项
+ *
+ * @author jason
+ */
+@Component
+@ConfigurationProperties(prefix = "yudao.trade.express.query")
+@Data
+@Validated
+public class TradeExpressQueryProperties {
+
+    /**
+     * 快递查询服务商
+     *
+     * 如果未配置，默认使用快递鸟
+     */
+    // TODO @jason：可以把 expressQueryProvider 改成 client 变量，更简洁一点；
+    private ExpressQueryProviderEnum expressQueryProvider; // TODO @jaosn：默认值可以通过属性直接赋值哈；
+    // TODO @jason：需要考虑下，用户只配置了其中一个；
+    /**
+     * 快递鸟配置
+     */
+    @Valid
+    private KdNiaoConfig kdNiao;
+    /**
+     * 快递 100 配置
+     */
+    @Valid
+    private Kd100Config kd100;
+
+    /**
+     * 快递鸟配置项目
+     */
+    @Data
+    public static class KdNiaoConfig {
+
+        /**
+         * 快递鸟用户 ID
+         */
+        @NotEmpty(message = "快递鸟用户 ID 配置项不能为空")
+        private String businessId;
+        /**
+         * 快递鸟 API Key
+         */
+        @NotEmpty(message = "快递鸟 Api Key 配置项不能为空")
+        private String apiKey;
+
+    }
+
+    /**
+     * 快递100 配置项
+     */
+    @Data
+    public static class Kd100Config {
+
+        /**
+         * 快递 100 授权码
+         */
+        @NotEmpty(message = "快递 100 授权码配置项不能为空")
+        private String customer;
+        /**
+         * 快递 100 授权 key
+         */
+        @NotEmpty(message = "快递 100 授权 Key 配置项不能为空")
+        private String key;
+
+    }
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core;
+
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+
+import java.util.List;
+
+// TODO @jason：可以改成 ExpressClient，未来可能还对接别的接口噢
+/**
+ * 快递查询客户端
+ *
+ * @author jason
+ */
+public interface ExpressQueryClient {
+
+    /**
+     * 快递实时查询
+     *
+     * @param reqDTO 查询请求参数
+     */
+    // TODO @jason：可以改成 getExpressTrackList。返回字段可以参考 https://doc.youzanyun.com/detail/API/0/5 响应的 data
+    List<ExpressQueryRespDTO> realTimeQuery(ExpressQueryReqDTO reqDTO);
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core;
+
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+
+import java.util.List;
+
+/**
+ * 快递查询服务商
+ *
+ * @author jason
+ */
+public interface ExpressQueryProvider {
+
+    /**
+     * 快递实时查询
+     *
+     * @param reqDTO 查询请求参数
+     */
+    List<ExpressQueryRespDTO> realTimeQueryExpress(ExpressQueryReqDTO reqDTO);
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core;
+
+import lombok.Getter;
+
+/**
+ * 快递查询服务商枚举
+ *
+ * @author jason
+ */
+@Getter
+
+public enum ExpressQueryProviderEnum {
+
+    KD_NIAO("kd-niao", "快递鸟"),
+    KD_100("kd-100", "快递100");
+
+    /**
+     * 快递服务商唯一编码
+     */
+    private final String code;
+
+    /**
+     * 快递服务商名称
+     */
+    private final String name;
+
+    // TODO @jaosn：@AllArgsConstructor 可以替代哈
+    ExpressQueryProviderEnum(String code, String name) {
+        this.code = code;
+        this.name = name;
+    }
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core;
+
+/**
+ * 快递服务商工厂，用于创建和缓存快递服务商服务
+ *
+ * @author jason
+ */
+public interface ExpressQueryProviderFactory {
+
+    /**
+     * 通过枚举获取快递查询服务商
+     *
+     * 如果不存在，就创建一个对应的快递查询服务商
+     *
+     * @param queryProviderEnum 快递服务商枚举
+     */
+    ExpressQueryProvider getOrCreateExpressQueryProvider(ExpressQueryProviderEnum queryProviderEnum);
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.convert;
+
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100.Kd100ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100.Kd100ExpressQueryRespDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao.KdNiaoExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao.KdNiaoExpressQueryRespDTO;
+import org.mapstruct.Mapper;
+import org.mapstruct.factory.Mappers;
+
+import java.util.List;
+
+@Mapper
+public interface ExpressQueryConvert {
+
+    ExpressQueryConvert INSTANCE = Mappers.getMapper(ExpressQueryConvert.class);
+
+    List<ExpressQueryRespDTO> convertList(List<KdNiaoExpressQueryRespDTO.ExpressTrack> expressTrackList);
+
+    List<ExpressQueryRespDTO> convertList2(List<Kd100ExpressQueryRespDTO.ExpressTrack> expressTrackList);
+
+    KdNiaoExpressQueryReqDTO convert(ExpressQueryReqDTO dto);
+
+    Kd100ExpressQueryReqDTO convert2(ExpressQueryReqDTO dto);
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto;
+
+import cn.iocoder.yudao.module.trade.dal.dataobject.delivery.DeliveryExpressDO;
+import lombok.Data;
+
+/**
+ * 快递查询 Req DTO
+ *
+ * @author jason
+ */
+@Data
+public class ExpressQueryReqDTO {
+
+    /**
+     * 快递公司编码
+     *
+     * 对应 {@link DeliveryExpressDO#getCode()}
+     */
+    // TODO @jaosn：要不改成 expressCode；项目里使用这个哈
+    private String expressCompanyCode;
+
+    /**
+     * 发货快递单号
+     */
+    private String logisticsNo;
+
+    /**
+     * 收、寄件人的电话号码
+     */
+    private String phone;
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto;
+
+import lombok.Data;
+
+/**
+ * 快递查询 Resp DTO
+ *
+ * @author jason
+ */
+@Data
+public class ExpressQueryRespDTO {
+
+    // TODO @jason：LocalDateTime
+    /**
+     * 发生时间
+     */
+    private String time;
+    // TODO @jason：其它字段可能要补充下
+    /**
+     * 快递状态
+     */
+    private String state;
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+/**
+ * 快递 100 快递查询 Req DTO
+ *
+ * @author jason
+ */
+@Data
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class Kd100ExpressQueryReqDTO {
+
+    // TODO @jaosn：要不改成 expressCode；项目里使用这个哈
+    /**
+     * 快递公司编码
+     */
+    @JsonProperty("com")
+    private String expressCompanyCode;
+
+    /**
+     * 快递单号
+     */
+    @JsonProperty("num")
+    private String logisticsNo;
+
+    /**
+     * 收、寄件人的电话号码
+     */
+    private String phone;
+    /**
+     * 出发地城市
+     */
+    private String from;
+    /**
+     * 目的地城市，到达目的地后会加大监控频率
+     */
+    private String to;
+
+    /**
+     * 返回结果排序
+     *
+     * desc 降序（默认）, asc 升序
+     */
+    private String order;
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 快递 100 实时快递查询 Resp DTO 参见  <a href="https://api.kuaidi100.com/document/5f0ffb5ebc8da837cbd8aefc">快递 100 文档</a>
+ *
+ * @author jason
+ */
+@Data
+public class Kd100ExpressQueryRespDTO {
+
+    /**
+     * 快递公司编码
+     */
+    @JsonProperty("com")
+    private String expressCompanyCode;
+    /**
+     * 快递单号
+     */
+    @JsonProperty("nu")
+    private String logisticsNo;
+    /**
+     * 快递单当前状态
+     */
+    private String state;
+
+    /**
+     * 查询结果
+     *
+     * 失败返回 "false"
+     */
+    private String result;
+    /**
+     * 查询结果失败时的错误信息
+     */
+    private String message;
+
+    @JsonProperty("data")
+    private List<ExpressTrack> tracks;
+
+    @Data
+    public static class ExpressTrack {
+        /**
+         * 轨迹发生时间
+         */
+        @JsonProperty("time")
+        private String time;
+        /**
+         * 轨迹描述
+         */
+        @JsonProperty("context")
+        private String state;
+    }
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+/**
+ * 快递鸟快递查询 Req DTO
+ *
+ * @author jason
+ */
+@Data
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class KdNiaoExpressQueryReqDTO {
+
+    // TODO @jaosn：要不改成 expressCode；项目里使用这个哈
+    /**
+     * 快递公司编码
+     */
+    @JsonProperty("ShipperCode")
+    private String expressCompanyCode;
+    /**
+     * 快递单号
+     */
+    @JsonProperty("LogisticCode")
+    private String logisticsNo;
+    /**
+     * 订单编号
+     */
+    @JsonProperty("OrderCode")
+    private String orderNo;
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 快递鸟快递查询 Resp DTO 参见  <a href="https://www.yuque.com/kdnjishuzhichi/dfcrg1/wugo6k">快递鸟接口文档</a>
+ *
+ * @author jason
+ */
+@Data
+public class KdNiaoExpressQueryRespDTO {
+
+    /**
+     * 快递公司编码
+     */
+    @JsonProperty("ShipperCode")
+    private String expressCompanyCode;
+
+    /**
+     * 快递单号
+     */
+    @JsonProperty("LogisticCode")
+    private String logisticsNo;
+
+    /**
+     * 订单编号
+     */
+    @JsonProperty("OrderCode")
+    private String orderNo;
+
+    @JsonProperty("EBusinessID")
+    private String businessId;
+    @JsonProperty("State")
+    private String state;
+    /**
+     * 成功与否
+     */
+    @JsonProperty("Success")
+    private Boolean success;
+    /**
+     * 失败原因
+     */
+    @JsonProperty("Reason")
+    private String reason;
+
+    @JsonProperty("Traces")
+    private List<ExpressTrack> tracks;
+
+    @Data
+    public static class ExpressTrack {
+        /**
+         * 轨迹发生时间
+         */
+        @JsonProperty("AcceptTime")
+        private String time;
+        /**
+         * 轨迹描述
+         */
+        @JsonProperty("AcceptStation")
+        private String state;
+    }
+
+//    {
+//        "EBusinessID": "1237100",
+//            "Traces": [],
+//        "State": "0",
+//            "ShipperCode": "STO",
+//            "LogisticCode": "638650888018",
+//            "Success": true,
+//            "Reason": "暂无轨迹信息"
+//    }
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.hutool.core.lang.Assert;
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryClient;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProvider;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderEnum;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderFactory;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import javax.annotation.PostConstruct;
+import javax.annotation.Resource;
+import java.util.List;
+
+import static cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderEnum.KD_NIAO;
+
+// TODO @jason：可以把整体包结构调整下；参考 sms client 的方式；
+// + config
+// + core
+//      client
+//         + dto
+//         + impl：里面可以放 kdniaoclient、kd100client
+//         ExpressClient
+//         ExpressClientFactory: 通过它直接获取默认和创建默认的 Client
+//      enums
+/**
+ * 快递查询客户端实现
+ *
+ * @author jason
+ */
+@Component
+@Slf4j
+public class ExpressQueryClientImpl implements ExpressQueryClient  {
+
+    @Resource
+    private ExpressQueryProviderFactory expressQueryProviderFactory;
+    @Resource
+    private TradeExpressQueryProperties tradeExpressQueryProperties;
+
+    private ExpressQueryProvider expressQueryProvider;
+
+    @PostConstruct
+    private void init() {
+        // 如果未设置，默认使用快递鸟
+        ExpressQueryProviderEnum queryProvider = tradeExpressQueryProperties.getExpressQueryProvider();
+        if (queryProvider == null) {
+            queryProvider = KD_NIAO;
+        }
+        // 创建客户端
+        expressQueryProvider = expressQueryProviderFactory.getOrCreateExpressQueryProvider(queryProvider);
+        if (expressQueryProvider == null) {
+            log.error("获取创建快递查询服务商{}失败，请检查相关配置", queryProvider);
+        }
+        Assert.notNull(expressQueryProvider, "快递查询服务商不能为空");
+    }
+
+    @Override
+    public List<ExpressQueryRespDTO> realTimeQuery(ExpressQueryReqDTO reqDTO) {
+        return expressQueryProvider.realTimeQueryExpress(reqDTO);
+    }
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProvider;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderEnum;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProviderFactory;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestTemplate;
+
+import javax.annotation.Resource;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * // TODO @jason：注释不全
+ * @author jason
+ */
+@Component
+public class ExpressQueryProviderFactoryImpl implements ExpressQueryProviderFactory {
+
+    private final Map<ExpressQueryProviderEnum, ExpressQueryProvider> providerMap = new ConcurrentHashMap<>(8);
+
+    @Resource
+    private TradeExpressQueryProperties tradeExpressQueryProperties;
+    @Resource
+    private RestTemplate restTemplate;
+
+    @Override
+    public ExpressQueryProvider getOrCreateExpressQueryProvider(ExpressQueryProviderEnum queryProviderEnum) {
+        return providerMap.computeIfAbsent(queryProviderEnum,
+                provider -> createExpressQueryProvider(provider, tradeExpressQueryProperties));
+    }
+
+    private ExpressQueryProvider createExpressQueryProvider(ExpressQueryProviderEnum queryProviderEnum,
+                                                            TradeExpressQueryProperties tradeExpressQueryProperties) {
+        // TODO @jason：是不是直接 return 就好啦，更简洁一点
+        ExpressQueryProvider result = null;
+        switch (queryProviderEnum) {
+            case KD_NIAO:
+                result = new KdNiaoExpressQueryProvider(restTemplate, tradeExpressQueryProperties.getKdNiao());
+                break;
+            case KD_100:
+                result = new Kd100ExpressQueryProvider(restTemplate, tradeExpressQueryProperties.getKd100());
+                break;
+        }
+        return result;
+    }
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.hutool.core.collection.CollUtil;
+import cn.hutool.core.util.HexUtil;
+import cn.hutool.crypto.digest.DigestUtil;
+import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProvider;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100.Kd100ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kd100.Kd100ExpressQueryRespDTO;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.*;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static cn.iocoder.yudao.module.trade.enums.ErrorCodeConstants.EXPRESS_API_QUERY_ERROR;
+import static cn.iocoder.yudao.module.trade.enums.ErrorCodeConstants.EXPRESS_API_QUERY_FAILED;
+import static cn.iocoder.yudao.module.trade.framework.delivery.core.convert.ExpressQueryConvert.INSTANCE;
+
+// TODO @jason：可以参考 KdNiaoExpressQueryProvider 建议改改哈
+/**
+ * 快递 100 服务商
+ *
+ * @author jason
+ */
+@Slf4j
+public class Kd100ExpressQueryProvider implements ExpressQueryProvider {
+
+    private static final String REAL_TIME_QUERY_URL = "https://poll.kuaidi100.com/poll/query.do";
+
+    private final RestTemplate restTemplate;
+    private final TradeExpressQueryProperties.Kd100Config config;
+
+    public Kd100ExpressQueryProvider(RestTemplate restTemplate, TradeExpressQueryProperties.Kd100Config config) {
+        this.restTemplate = restTemplate;
+        this.config = config;
+    }
+
+    @Override
+    public List<ExpressQueryRespDTO> realTimeQueryExpress(ExpressQueryReqDTO reqDTO) {
+        // 发起查询
+        Kd100ExpressQueryReqDTO kd100ReqParam = INSTANCE.convert2(reqDTO);
+        kd100ReqParam.setExpressCompanyCode(kd100ReqParam.getExpressCompanyCode().toLowerCase()); // 快递公司编码需要转成小写
+        Kd100ExpressQueryRespDTO respDTO = sendExpressQueryReq(REAL_TIME_QUERY_URL, kd100ReqParam,
+                Kd100ExpressQueryRespDTO.class);
+        log.debug("[realTimeQueryExpress][快递 100 接口 查询接口返回 {}]", respDTO);
+        // 处理结果
+        if (Objects.equals("false", respDTO.getResult())) {
+            log.error("[realTimeQueryExpress][快递 100 接口 返回失败 {}]", respDTO.getMessage());
+            throw exception(EXPRESS_API_QUERY_FAILED, respDTO.getMessage());
+        // TODO @json：else 可以不用写哈；
+        } else {
+            // TODO @jason：convertList2 如果空，应该返回 list 了；
+            if (CollUtil.isNotEmpty(respDTO.getTracks())) {
+                return INSTANCE.convertList2(respDTO.getTracks());
+            } else {
+                return Collections.emptyList();
+            }
+        }
+    }
+
+    /**
+     * 发送快递 100 实时快递查询请求，可以作为通用快递 100 通用请求接口。 目前没有其它场景需要使用。暂时放这里
+     *
+     * @param url 请求 url
+     * @param req 对应请求的请求参数
+     * @param respClass 对应请求的响应 class
+     * @param <Req> 每个请求的请求结构 Req DTO
+     * @param <Resp> 每个请求的响应结构 Resp DTO
+     */
+    // TODO @jason：可以改成 request，发起请求哈；
+    private <Req, Resp> Resp sendExpressQueryReq(String url, Req req, Class<Resp> respClass) {
+        // 请求头
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
+        // 生成签名
+        String param = JsonUtils.toJsonString(req);
+        String sign = generateReqSign(param, config.getKey(), config.getCustomer());
+        // 请求体
+        MultiValueMap<String, String> requestBody = new LinkedMultiValueMap<>();
+        requestBody.add("customer", config.getCustomer());
+        requestBody.add("sign", sign);
+        requestBody.add("param", param);
+        log.debug("[sendExpressQueryReq][快递 100 接口的请求参数: {}]", requestBody);
+        // 发送请求
+        HttpEntity<MultiValueMap<String, String>> requestEntity = new HttpEntity<>(requestBody, headers);
+        // TODO @jason：可以使用 restTemplate 的 post 方法哇？
+        ResponseEntity<String> responseEntity = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
+        log.debug("[sendExpressQueryReq][快递 100 接口响应结果 {}]", responseEntity);
+
+        // 处理响应
+        // TODO @jason：if return 原则；if (!responseEntity.getStatusCode().is2xxSuccessful()) 抛出异常；接着处理成功的
+        if (responseEntity.getStatusCode().is2xxSuccessful()) {
+            String response = responseEntity.getBody();
+            return JsonUtils.parseObject(response, respClass);
+        } else {
+            throw exception(EXPRESS_API_QUERY_ERROR);
+        }
+    }
+
+    private String generateReqSign(String param, String key, String customer) {
+        String plainText = String.format("%s%s%s", param, key, customer);
+        // TODO @jason：DigestUtil.md5Hex(plainText);
+        return HexUtil.encodeHexStr(DigestUtil.md5(plainText), false);
+    }
+
+}
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.hutool.core.codec.Base64;
+import cn.hutool.core.collection.CollUtil;
+import cn.hutool.core.net.URLEncodeUtil;
+import cn.hutool.crypto.digest.DigestUtil;
+import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.ExpressQueryProvider;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryRespDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao.KdNiaoExpressQueryReqDTO;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.provider.kdniao.KdNiaoExpressQueryRespDTO;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.*;
+import org.springframework.util.LinkedMultiValueMap;
+import org.springframework.util.MultiValueMap;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.Collections;
+import java.util.List;
+
+import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
+import static cn.iocoder.yudao.module.trade.enums.ErrorCodeConstants.EXPRESS_API_QUERY_FAILED;
+import static cn.iocoder.yudao.module.trade.enums.ErrorCodeConstants.EXPRESS_API_QUERY_ERROR;
+import static cn.iocoder.yudao.module.trade.framework.delivery.core.convert.ExpressQueryConvert.INSTANCE;
+
+/**
+ * 快递鸟服务商
+ *
+ * @author jason
+ */
+@Slf4j
+public class KdNiaoExpressQueryProvider implements ExpressQueryProvider {
+
+    private static final String REAL_TIME_QUERY_URL = "https://api.kdniao.com/Ebusiness/EbusinessOrderHandle.aspx";
+
+    /**
+     * 快递鸟即时查询免费版 RequestType
+     */
+    private static final String REAL_TIME_FREE_REQ_TYPE = "1002";
+
+    private final RestTemplate restTemplate;
+    private final TradeExpressQueryProperties.KdNiaoConfig config;
+
+    // TODO @jason：可以改成 lombok 哈
+    public KdNiaoExpressQueryProvider(RestTemplate restTemplate, TradeExpressQueryProperties.KdNiaoConfig config) {
+        this.restTemplate = restTemplate;
+        this.config = config;
+    }
+
+    /**
+     * 快递鸟即时查询免费版本
+     *
+     * @see <a href="https://www.yuque.com/kdnjishuzhichi/dfcrg1/wugo6k">快递鸟接口文档</a>
+     * @param reqDTO 查询请求参数
+     */
+    @Override
+    public List<ExpressQueryRespDTO> realTimeQueryExpress(ExpressQueryReqDTO reqDTO) {
+        KdNiaoExpressQueryReqDTO kdNiaoReqData = INSTANCE.convert(reqDTO);
+        // 快递公司编码需要转成大写
+        kdNiaoReqData.setExpressCompanyCode(reqDTO.getExpressCompanyCode().toUpperCase());
+        KdNiaoExpressQueryRespDTO respDTO = sendKdNiaoApiRequest(REAL_TIME_QUERY_URL, REAL_TIME_FREE_REQ_TYPE,
+                kdNiaoReqData, KdNiaoExpressQueryRespDTO.class);
+        log.debug("[realTimeQueryExpress][快递鸟即时查询接口返回 {}]", respDTO);
+        if(!respDTO.getSuccess()){
+            throw exception(EXPRESS_API_QUERY_FAILED, respDTO.getReason());
+        }else{
+            if (CollUtil.isNotEmpty(respDTO.getTracks())) {
+                return INSTANCE.convertList(respDTO.getTracks());
+            }else{
+                return Collections.emptyList();
+            }
+        }
+    }
+
+    /**
+     * 快递鸟 通用的 API 请求, 暂时没有其他应用场景， 暂时放这里
+     * @param url 请求 url
+     * @param requestType 对应的请求指令 (快递鸟的RequestType)
+     * @param req  对应请求的请求参数
+     * @param respClass 对应请求的响应 class
+     * @param <Req> 每个请求的请求结构 Req DTO
+     * @param <Resp> 每个请求的响应结构 Resp DTO
+     */
+    private  <Req, Resp> Resp sendKdNiaoApiRequest(String url, String requestType, Req req,
+                                                   Class<Resp> respClass){
+        // 请求头
+        HttpHeaders headers = new HttpHeaders();
+        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
+        // 请求体
+        String reqData = JsonUtils.toJsonString(req);
+        String dataSign = generateDataSign(reqData, config.getApiKey());
+        MultiValueMap<String, String> requestBody = new LinkedMultiValueMap<>();
+        requestBody.add("RequestData", reqData);
+        requestBody.add("DataType", "2");
+        requestBody.add("EBusinessID", config.getBusinessId());
+        requestBody.add("DataSign", dataSign);
+        requestBody.add("RequestType", requestType);
+        log.debug("[sendKdNiaoApiRequest][快递鸟接口 RequestType : {}, 的请求参数 {}]", requestType, requestBody);
+
+        // 发送请求
+        HttpEntity<MultiValueMap<String, String>> requestEntity = new HttpEntity<>(requestBody, headers);
+        ResponseEntity<String> responseEntity = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
+        log.debug("快递鸟接口 RequestType : {}, 的响应结果 {}", requestType,  responseEntity);
+        // 处理响应
+        if (responseEntity.getStatusCode().is2xxSuccessful()) {
+            String response = responseEntity.getBody();
+            return JsonUtils.parseObject(response, respClass);
+        } else {
+            throw exception(EXPRESS_API_QUERY_ERROR);
+        }
+    }
+
+    /**
+     * 快递鸟生成请求签名 参见 <a href="https://www.yuque.com/kdnjishuzhichi/dfcrg1/zes04h">签名说明</a>
+     * @param reqData 请求实体
+     * @param apiKey  api Key
+     */
+    private String generateDataSign(String reqData, String apiKey) {
+        String plainText = String.format("%s%s", reqData, apiKey);
+        return URLEncodeUtil.encode(Base64.encode(DigestUtil.md5Hex(plainText)));
+    }
+
+}
@@ -75,7 +75,7 @@ public interface DeliveryExpressTemplateService {
  
     /**
      * 校验快递运费模板
-     * <p>
+     *
      * 如果校验不通过，抛出 {@link cn.iocoder.yudao.framework.common.exception.ServiceException} 异常
      *
      * @param templateId 模板编号
@@ -83,6 +83,7 @@ public interface DeliveryExpressTemplateService {
      */
     DeliveryExpressTemplateDO validateDeliveryExpressTemplate(Long templateId);
  
+    // TODO @jason：可以把 spuIds 改成传递 ids 么？价格计算那，在 TradePriceCalculateRespBO 冗余好 templateId 字段。目的是，减少重复的查询
     /**
      * 基于指定的 SPU 编号数组和收件人地址区域编号. 获取匹配运费模板
      *
@@ -242,10 +242,9 @@ public class DeliveryExpressTemplateServiceImpl implements DeliveryExpressTempla
             if (spu == null) {
                 return;
             }
+            // TODO @jason：避免循环查询；最好类似 expressTemplateMapper.selectBatchIds(spuMap.keySet()); 批量查询，内存组合；
             SpuDeliveryExpressTemplateRespBO bo = new SpuDeliveryExpressTemplateRespBO()
                     .setChargeMode(item.getChargeMode())
-                    // TODO @jason：是不是只要查询到一个，就不用查询下一个了；TemplateCharge 和 TemplateFree
-                    //  @芋艿 包邮的优先级> 费用的优先级 所以两个都要查询
                     .setTemplateCharge(findMatchExpressTemplateCharge(item.getId(), areaId))
                     .setTemplateFree(findMatchExpressTemplateFree(item.getId(), areaId));
             result.put(spu.getId(), bo);
@@ -18,6 +18,8 @@ public class SpuDeliveryExpressTemplateRespBO {
      */
     private Integer chargeMode;
  
+    // TODO @jaosn：可以把 DeliveryExpressTemplateChargeBO 和 DeliveryExpressTemplateFreeBO 搞成内嵌的类。这样简洁一点
+
     /**
      * 运费模板快递运费设置
      */
@@ -164,16 +164,7 @@ public class TradePriceCalculateRespBO {
          */
         private Integer payPrice;
  
-        /**
-         * 商品重量，单位：kg 千克
-         */
-        private Double weight;
-        /**
-         * 商品体积，单位：m^3 平米
-         */
-        private Double volume;
-
-        // ========== 商品信息 ==========
+        // ========== 商品 SPU 信息 ==========
         /**
          * 商品名
          */
@@ -189,6 +180,16 @@ public class TradePriceCalculateRespBO {
          */
         private Long categoryId;
  
+        // ========== 商品 SKU 信息 ==========
+        /**
+         * 商品重量，单位：kg 千克
+         */
+        private Double weight;
+        /**
+         * 商品体积，单位：m^3 平米
+         */
+        private Double volume;
+
         /**
          * 商品属性数组
          */
@@ -62,7 +62,7 @@ public class TradeDeliveryPriceCalculator implements TradePriceCalculator {
                 deliveryExpressTemplateService.getExpressTemplateMapBySpuIdsAndArea(spuIds, address.getAreaId());
         // 3. 计算配送费用
         if (CollUtil.isEmpty(spuExpressTemplateMap)) {
-            log.error("找不到商品 SPU ID {}, area Id {} ,对应的运费模板", spuIds, address.getAreaId());
+            log.error("[calculate][找不到商品 spuId{} areaId{} 对应的运费模板]", spuIds, address.getAreaId());
             throw exception(PRODUCT_EXPRESS_TEMPLATE_NOT_FOUND);
         }
         calculateDeliveryPrice(selectedItem, spuExpressTemplateMap, result);
@@ -170,7 +170,8 @@ public class TradeDeliveryPriceCalculator implements TradePriceCalculator {
      */
     private void divideDeliveryPrice(int deliveryPrice, List<OrderItem> orderItems) {
         // TODO @jason：分摊的话，是不是要按照比例呀？重量、价格、数量等等,
-        //  按比例是不是有点复杂。后面看看是否需要
+        //  按比例是不是有点复杂。后面看看是否需要；
+        // TODO 可以看看别的项目怎么搞的哈。
         int dividePrice = deliveryPrice / orderItems.size();
         for (OrderItem item : orderItems) {
             // 更新快递运费
@@ -207,6 +208,7 @@ public class TradeDeliveryPriceCalculator implements TradePriceCalculator {
                 // freeCount 是不是应该是 double ??
                 // TODO @jason：要不配置的时候，把它的单位和商品对齐？到底是 kg、还是斤
                 // TODO @芋艿 目前 包邮 件数/重量/体积 都用的是这个字段
+                // TODO @jason：那要不快递模版也改成 kg？这样是不是就不用 double ？
                 if (totalWeight >= templateFree.getFreeCount()
                         && totalPrice >= templateFree.getFreePrice()) {
                     return true;
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.iocoder.yudao.framework.common.exception.ServiceException;
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.web.client.RestTemplateAutoConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.web.client.RestTemplateBuilder;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.ActiveProfiles;
+
+import javax.annotation.Resource;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/**
+ * @author jason
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE, classes = Kd100ExpressQueryProviderTest.Application.class)
+@ActiveProfiles("trade-delivery-query") // 设置使用 trade-delivery-query 配置文件
+public class Kd100ExpressQueryProviderTest {
+    @Resource
+    private RestTemplateBuilder builder;
+    @Resource
+    private TradeExpressQueryProperties expressQueryProperties;
+
+    private Kd100ExpressQueryProvider kd100ExpressQueryProvider;
+
+    @BeforeEach
+    public void init(){
+        kd100ExpressQueryProvider = new Kd100ExpressQueryProvider(builder.build(),expressQueryProperties.getKd100());
+    }
+    @Test
+    @Disabled("需要 授权 key. 暂时忽略")
+    void testRealTimeQueryExpressFailed() {
+        ServiceException t =  assertThrows(ServiceException.class, () -> {
+            ExpressQueryReqDTO reqDTO = new ExpressQueryReqDTO();
+            reqDTO.setExpressCompanyCode("yto");
+            reqDTO.setLogisticsNo("YT9383342193097");
+            kd100ExpressQueryProvider.realTimeQueryExpress(reqDTO);
+        });
+        assertEquals(1011003007, t.getCode());
+    }
+
+    @Import({
+            RestTemplateAutoConfiguration.class
+    })
+    @EnableConfigurationProperties(TradeExpressQueryProperties.class)
+    public static class Application {
+    }
+}
 \ No newline at end of file
+package cn.iocoder.yudao.module.trade.framework.delivery.core.impl;
+
+import cn.iocoder.yudao.framework.common.exception.ServiceException;
+import cn.iocoder.yudao.module.trade.framework.delivery.config.TradeExpressQueryProperties;
+import cn.iocoder.yudao.module.trade.framework.delivery.core.dto.ExpressQueryReqDTO;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Disabled;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.web.client.RestTemplateAutoConfiguration;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.web.client.RestTemplateBuilder;
+import org.springframework.context.annotation.Import;
+import org.springframework.test.context.ActiveProfiles;
+
+import javax.annotation.Resource;
+
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+// TODO @芋艿：单测最后 review
+/**
+ * @author jason
+ */
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE, classes = KdNiaoExpressQueryProviderTest.Application.class)
+@ActiveProfiles("trade-delivery-query") // 设置使用 trade-delivery-query 配置文件 TODO @jason：可以直接写到 application-unit-test.yaml 配置文件里
+public class KdNiaoExpressQueryProviderTest {
+    @Resource
+    private RestTemplateBuilder builder;
+    @Resource
+    private TradeExpressQueryProperties expressQueryProperties;
+
+    private KdNiaoExpressQueryProvider kdNiaoExpressQueryProvider;
+
+    @BeforeEach
+    public void init(){
+        kdNiaoExpressQueryProvider = new KdNiaoExpressQueryProvider(builder.build(),expressQueryProperties.getKdNiao());
+    }
+    @Test
+    @Disabled("需要 授权 key. 暂时忽略")
+    void testRealTimeQueryExpressFailed() {
+        assertThrows(ServiceException.class,() ->{
+            ExpressQueryReqDTO reqDTO = new ExpressQueryReqDTO();
+            reqDTO.setExpressCompanyCode("yy");
+            reqDTO.setLogisticsNo("YT9383342193097");
+            kdNiaoExpressQueryProvider.realTimeQueryExpress(reqDTO);
+        });
+    }
+
+    @Import({
+            RestTemplateAutoConfiguration.class
+    })
+    @EnableConfigurationProperties(TradeExpressQueryProperties.class)
+    public static class Application {
+    }
+}
+spring:
+  main:
+    lazy-initialization: true # 开启懒加载，加快速度
+    banner-mode: off # 单元测试，禁用 Banner
+
+--- #################### 交易快递查询相关配置 ####################
+
+yudao:
+  trade:
+    express:
+      query:
+        express-query-provider: kd_niao
+        kd-niao:
+          api-key: xxx
+          business-id: xxxxxxxx
+        kd100:
+          customer: xxxx
+          key: xxxxx