Feature/docs codocs: 完善工具类与核心配置的 Javadoc 注释mment refactor

litemall-core/src/main/java/org/linlinjava/litemall/core/express/ExpressService.java

@@ -36,10 +36,10 @@ public void setProperties(ExpressProperties properties) {
     }
 
     /**
-     * 获取物流供应商名
+      * 根据供应商编码获取物流供应商名称。
      *
-     * @param vendorCode
-     * @return
+      * @param vendorCode 物流供应商编码
+      * @return 供应商名称；未找到时返回 {@code null}
      */
     public String getVendorName(String vendorCode) {
         for (Map<String, String> item : properties.getVendors()) {
@@ -54,11 +54,11 @@ public List<Map<String, String>> getVendors() {
     }
 
     /**
-     * 获取物流信息
+     * 查询指定物流单的物流信息。未启用物流查询或查询失败时返回 {@code null}。
      *
-     * @param expCode
-     * @param expNo
-     * @return
+     * @param expCode 物流供应商编码
+     * @param expNo 物流单号
+     * @return 物流信息；未启用或查询失败时返回 {@code null}
      */
     public ExpressInfo getExpressInfo(String expCode, String expNo) {
         if (!properties.isEnable()) {
@@ -79,9 +79,12 @@ public ExpressInfo getExpressInfo(String expCode, String expNo) {
     }
 
     /**
-     * Json方式 查询订单物流轨迹
+        * 以 JSON 格式请求物流轨迹。
      *
-     * @throws Exception
+        * @param expCode 物流供应商编码
+        * @param expNo 物流单号
+        * @return 物流查询接口返回的 JSON
+        * @throws Exception 请求编码或 HTTP 请求失败时抛出
      */
     private String getOrderTracesByJson(String expCode, String expNo) throws Exception {
         String requestData = "{'OrderCode':'','ShipperCode':'" + expCode + "','LogisticCode':'" + expNo + "'}";
@@ -96,17 +99,16 @@ private String getOrderTracesByJson(String expCode, String expNo) throws Excepti
 
         String result = HttpUtil.sendPost(ReqURL, params);
 
-        //根据公司业务处理返回的信息......
-
         return result;
     }
 
     /**
-     * MD5加密
+        * 使用指定字符集计算字符串的 MD5 摘要。
      *
-     * @param str     内容
-     * @param charset 编码方式
-     * @throws Exception
+        * @param str 待摘要的内容
+        * @param charset 字符编码
+        * @return 小写十六进制摘要
+        * @throws Exception 无法获取 MD5 算法或字符编码时抛出
      */
     private String MD5(String str, String charset) throws Exception {
         MessageDigest md = MessageDigest.getInstance("MD5");

litemall-core/src/main/java/org/linlinjava/litemall/core/express/config/ExpressProperties.java

@@ -6,41 +6,84 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * 快递查询服务的配置属性，对应 {@code litemall.express} 配置项。
+ */
 @ConfigurationProperties(prefix = "litemall.express")
 public class ExpressProperties {
     private boolean enable;
     private String appId;
     private String appKey;
     private List<Map<String, String>> vendors = new ArrayList<>();
 
+    /**
+     * 返回是否启用快递查询。
+     *
+     * @return 启用时为 {@code true}
+     */
     public boolean isEnable() {
         return enable;
     }
 
+    /**
+     * 设置是否启用快递查询。
+     *
+     * @param enable 是否启用
+     */
     public void setEnable(boolean enable) {
         this.enable = enable;
     }
 
+    /**
+     * 返回快递供应商列表。每项使用 {@code code} 和 {@code name} 分别表示供应商编码和名称。
+     *
+     * @return 快递供应商配置列表
+     */
     public List<Map<String, String>> getVendors() {
         return vendors;
     }
 
+    /**
+     * 设置快递供应商列表。
+     *
+     * @param vendors 快递供应商配置列表，每项包含供应商编码和名称
+     */
     public void setVendors(List<Map<String, String>> vendors) {
         this.vendors = vendors;
     }
 
+    /**
+     * 返回快递服务的应用密钥。
+     *
+     * @return 应用密钥
+     */
     public String getAppKey() {
         return appKey;
     }
 
+    /**
+     * 设置快递服务的应用密钥。
+     *
+     * @param appKey 应用密钥
+     */
     public void setAppKey(String appKey) {
         this.appKey = appKey;
     }
 
+    /**
+     * 返回快递服务的应用标识。
+     *
+     * @return 应用标识
+     */
     public String getAppId() {
         return appId;
     }
 
+    /**
+     * 设置快递服务的应用标识。
+     *
+     * @param appId 应用标识
+     */
     public void setAppId(String appId) {
         this.appId = appId;
     }

litemall-db/src/main/java/org/linlinjava/litemall/db/dao/LitemallOrderMapper.java

@@ -5,148 +5,152 @@
 import org.linlinjava.litemall.db.domain.LitemallOrder;
 import org.linlinjava.litemall.db.domain.LitemallOrderExample;
 
+/**
+ * 订单表（litemall_order）的 MyBatis Mapper 接口。
+ *
+ * <p>方法由 MyBatis Generator 生成，分两类：xxxByExample 面向动态条件查询与批量操作，
+ * xxxByPrimaryKey 面向主键单条操作。本接口只负责 SQL 映射，
+ * 订单状态是否允许流转等业务规则在 LitemallOrderService 及其上层实现。
+ *
+ * <p>注意：按主键或按条件的查询不会自动过滤 deleted 字段，
+ * 需要排除已逻辑删除的订单时，请使用 xxxWithLogicalDelete 系列或自行带 deleted 条件。
+ *
+ * @author lvweihao0403
+ * @since 1.0.0
+ */
 public interface LitemallOrderMapper {
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件统计订单数量。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 匹配的记录数
      */
     long countByExample(LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件物理删除订单。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 影响行数；业务删除请改用 logicalDeleteByExample
      */
     int deleteByExample(LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键物理删除订单。
+     * @param id 订单主键
+     * @return 影响行数；业务删除请改用 logicalDeleteByPrimaryKey
      */
     int deleteByPrimaryKey(Integer id);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 插入一条订单，写入全部字段（null 会覆盖数据库默认值）。
+     * @param record 订单实体，非 null
+     * @return 影响行数；业务插入请改用 insertSelective
      */
     int insert(LitemallOrder record);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 插入一条订单，只写入对象中非 null 的字段，保留数据库默认值。
+     * @param record 订单实体，非 null
+     * @return 影响行数；业务写入推荐使用本方法
      */
     int insertSelective(LitemallOrder record);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件查询单条订单。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 订单；无匹配时返回 null
      */
     LitemallOrder selectOneByExample(LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件查询单条订单，只返回指定列。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @param selective 需要返回的列集合，不传表示全部列
+     * @return 订单；无匹配时返回 null
      */
     LitemallOrder selectOneByExampleSelective(@Param("example") LitemallOrderExample example, @Param("selective") LitemallOrder.Column ... selective);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件查询订单列表，只返回指定列，用于避免查询大字段。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @param selective 需要返回的列集合，不传表示全部列
+     * @return 订单列表
      */
     List<LitemallOrder> selectByExampleSelective(@Param("example") LitemallOrderExample example, @Param("selective") LitemallOrder.Column ... selective);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件查询订单列表。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 订单列表
      */
     List<LitemallOrder> selectByExample(LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键查询单条订单，只返回指定列。
+     * @param id 订单主键
+     * @param selective 需要返回的列集合，不传表示全部列
+     * @return 订单；不存在时返回 null
      */
     LitemallOrder selectByPrimaryKeySelective(@Param("id") Integer id, @Param("selective") LitemallOrder.Column ... selective);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
+     * 按主键查询单条订单。
      *
-     * @mbg.generated
+     * <p>注意：本方法不过滤 deleted 字段，已逻辑删除的订单同样会返回；
+     * 下单校验、支付回调等场景应改用带 deleted = 0 条件的查询。
+     * @param id 订单主键
+     * @return 订单；记录不存在时返回 null，调用方必须判空
      */
     LitemallOrder selectByPrimaryKey(Integer id);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键查询单条订单，并显式指定是否包含已逻辑删除的记录。
+     * @param id 订单主键
+     * @param andLogicalDeleted true 只查已删除记录，false 只查未删除记录
+     * @return 订单；不存在时返回 null
      */
     LitemallOrder selectByPrimaryKeyWithLogicalDelete(@Param("id") Integer id, @Param("andLogicalDeleted") boolean andLogicalDeleted);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件更新订单，只更新对象中非 null 的字段。
+     * @param record 订单实体，非 null
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 影响行数
      */
     int updateByExampleSelective(@Param("record") LitemallOrder record, @Param("example") LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件更新订单全部字段，未赋值字段会被写成 null，慎用。
+     * @param record 订单实体，非 null
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 影响行数；业务更新推荐 updateByExampleSelective
      */
     int updateByExample(@Param("record") LitemallOrder record, @Param("example") LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键更新订单，只更新对象中非 null 的字段。
+     * @param record 订单实体，非 null
+     * @return 影响行数；业务更新推荐使用本方法
      */
     int updateByPrimaryKeySelective(LitemallOrder record);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键更新订单全部字段。
+     * @param record 订单实体，非 null
+     * @return 影响行数；未赋值字段会被覆盖，慎用
      */
     int updateByPrimaryKey(LitemallOrder record);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按条件逻辑删除订单（deleted 置 1），保留数据用于对账与审计。
+     * @param example 查询条件（LitemallOrderExample），可为 null
+     * @return 影响行数
      */
     int logicalDeleteByExample(@Param("example") LitemallOrderExample example);
 
     /**
-     * This method was generated by MyBatis Generator.
-     * This method corresponds to the database table litemall_order
-     *
-     * @mbg.generated
+     * 按主键逻辑删除订单（deleted 置 1）。
+     * @param id 订单主键
+     * @return 影响行数
      */
     int logicalDeleteByPrimaryKey(Integer id);
 }