优化代码注释为简体中文

2026-11-11 13:52:28 +08:00
parent b7d0674fda
commit f7384c88f6
106 changed files with 690 additions and 690 deletions
@@ -59,7 +59,7 @@ public class BmsCustomerPriceSet extends BaseEntity
    /** 计价类型 FIXED=固定价 DISCOUNT=折扣 */
    private String setType;

-    /** Package status D=pending-enable A=audit E=effective R=reject S=stopped */
+    /** 套餐状态 D=待启用 A=审核 E=生效 R=拒绝 S=停用 */
    private String priceSetStatus;

    /** 套餐生效日期 */
@@ -26,7 +26,7 @@ public class BmsPriceSetOption
    /** 计价类型 FIXED=固定价 DISCOUNT=折扣 */
    private String setType;

-    /** Package status D=pending-enable A=audit E=effective R=reject S=stopped */
+    /** 套餐状态 D=待启用 A=审核 E=生效 R=拒绝 S=停用 */
    private String status;

    /** 生效日期 */
@@ -94,7 +94,7 @@ public class BmsCustomerPriceSetServiceImpl implements IBmsCustomerPriceSetServi
            if (existing != null)
            {
                bind.setCustomerPricesetId(existing.getCustomerPricesetId());
-                // UI no longer collects bind dates: keep existing when not passed.
+                // UI 不再收集绑定日期：未传时保留原值。
                if (bind.getPrBegindate() == null)
                {
                    bind.setPrBegindate(existing.getPrBegindate());
@@ -107,7 +107,7 @@ public class BmsCustomerPriceSetServiceImpl implements IBmsCustomerPriceSetServi
            }
            else
            {
-                // pr_begindate NOT NULL; UI omits it — default to now (same as price-set bind).
+                // pr_begindate NOT NULL，UI 未传时默认取当前时间（与价格套餐绑定一致）。
                if (bind.getPrBegindate() == null)
                {
                    bind.setPrBegindate(DateUtils.getNowDate());
@@ -10,22 +10,22 @@ import org.springframework.stereotype.Component;
@ConfigurationProperties(prefix = "bms.billing")
 public class BillingProperties
 {
-    /** local = Spring event; redis = Redis list queue */
+    /** local = Spring 事件；redis = Redis 列表队列 */
    private String mqMode = "redis";
    private String mqQueueKey = "bms:billing:task";
    private boolean consumerEnabled = true;
-    /** Messages popped per scheduled tick (redis mode) */
+    /** 每个调度周期取出的消息数量（redis 模式） */
    private int consumerBatchSize = 32;
-    /** Concurrent processTask threads (redis mode) */
+    /** 并发执行 processTask 的线程数（redis 模式） */
    private int consumerThreads = 8;
-    /** Concurrent threads for monitor order-source sync */
+    /** 监控订单数源同步的并发线程数 */
    private int orderSourceSyncThreads = 8;
    /**
-     * Concurrent threads for order-list local rebill (2~24).
-     * Keep below Druid maxActive with headroom for other traffic.
+     * 订单列表本地重计费的并发线程数（2~24）。
+     * 需低于 Druid maxActive，并给其他流量留出余量。
     */
    private int localRebillThreads = 16;
-    /** Hourly auto-retry of prc_billing_task (all statuses) */
+    /** 每小时自动重试 prc_billing_task（所有状态） */
    private NightRetry nightRetry = new NightRetry();
    private Oracle oracle = new Oracle();

@@ -120,18 +120,18 @@ public class BillingProperties
    }

    /**
-     * Auto rebill window: pull prc_billing_task (all success_status) and retryTask.
-     * Default hours [0, 24) local time (all day); empty result skips billing.
+     * 自动重计费时间窗：拉取 prc_billing_task（所有 success_status）并执行 retryTask。
+     * 默认本地时间 [0, 24) 点（全天）；结果为空则跳过计费。
     */
    public static class NightRetry
    {
-        /** Master switch */
+        /** 总开关 */
        private boolean enabled = true;
-        /** Inclusive start hour (0 = 00:00) */
+        /** 起始小时，含（0 = 00:00） */
        private int startHour = 0;
-        /** Exclusive end hour (24 = all day) */
+        /** 结束小时，不含（24 = 全天） */
        private int endHour = 24;
-        /** Page size: bill this many then pull next page (default 500) */
+        /** 分页大小：计费这么多条后再拉下一页（默认 500） */
        private int batchSize = 500;

        public boolean isEnabled()
@@ -177,9 +177,9 @@ public class BillingProperties

    public static class Oracle
    {
-        /** Upstream main-order table name on SLAVE/Oracle DS */
+        /** SLAVE/Oracle 数据源上的上游主订单表名 */
        private String orderTable = "WEISHI_USER.TAB_ORDER";
-        /** Optional default product when Oracle row has no PRODUCT_CODE */
+        /** Oracle 行中没有 PRODUCT_CODE 时使用的可选默认产品 */
        private String defaultProductCode = "";

        public String getOrderTable()
@@ -14,7 +14,7 @@ public class BmsProduct extends BaseEntity
 {
    private static final long serialVersionUID = 1L;

-    /** maps to prc_price_set_product.psp_id */
+    /** 对应 prc_price_set_product.psp_id */
    private Long productId;
    private Long psvId;
    private String priceType;
@@ -30,7 +30,7 @@ public class BmsProduct extends BaseEntity
    private Date effectiveDate;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireDate;
-    /** 0 pending, 1 active, 2 expired */
+    /** 0 待生效，1 生效，2 已失效 */
    public static final String STATUS_PENDING = "0";
    public static final String STATUS_ACTIVE = "1";
    public static final String STATUS_EXPIRED = "2";
@@ -45,8 +45,8 @@ public class BmsProduct extends BaseEntity
    private Integer countryCount;
    private Integer surchargeCount;
    private List<BmsProductCountry> countries;
-    /** query alias of status (0/1/2) */
+    /** status 的查询别名（0/1/2） */
    private String effectStatus;
-    /** query: active = status in (0,1); expired = status 2 */
+    /** 查询：active = status in (0,1)；expired = status 2 */
    private String statusGroup;
 }
@@ -12,23 +12,23 @@ public class BmsProductCountry implements Serializable
 {
    private static final long serialVersionUID = 1L;

-    /** maps to prc_price_set_detail.psd_id */
+    /** 对应 prc_price_set_detail.psd_id */
    private Long detailId;
    private Long psvId;
    private Long pspId;
    private String priceType;
-    /** FK to product.product_id */
+    /** 外键，指向 product.product_id */
    private Long productId;
    private String productCode;
-    /** Parse/import helper only (not a DB column). */
+    /** 仅用于解析/导入辅助（非数据库字段）。 */
    private String productName;
    private String countryName;
    private String countryCode;
-    /** prc_zone.zone_id; null when product country has no zone */
+    /** prc_zone.zone_id；产品国家无分区时为 null */
    private Long zoneId;
-    /** e.g. Z1; null when no zone */
+    /** 例如 Z1；无分区时为 null */
    private String zoneCode;
-    /** e.g. Australia(Z1); null when no zone */
+    /** 例如 Australia(Z1)；无分区时为 null */
    private String zoneName;
    private BigDecimal weightMin;
    private BigDecimal weightMax;
@@ -39,10 +39,10 @@ public class BmsProductCountry implements Serializable
    private String leadTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date effectiveDate;
-    /** null=open; closed to next import effective_date */
+    /** null=未关闭；关闭到下次导入的 effective_date */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireDate;
-    /** 0 pending, 1 active, 2 expired */
+    /** 0 待生效，1 生效，2 已失效 */
    private String status;
    /** 0未删除 1已删除 */
    public static final String IS_DEL_NO = "0";
@@ -52,8 +52,8 @@ public class BmsProductCountry implements Serializable
    private Date createTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date updateTime;
-    /** query only: true = expire_date is null */
+    /** 仅查询用：true = expire_date 为 null */
    private Boolean openOnly;
-    /** query alias of status (0/1/2) */
+    /** status 的查询别名（0/1/2） */
    private String effectStatus;
 }
@@ -19,7 +19,7 @@ public class BmsProductImportTask implements Serializable
    private int percent;
    private String message;
    private String error;
-    /** Preview parse payload (products / details); not persisted to DB. */
+    /** 预览解析结果（products / details）；不落库。 */
    private Object result;

    public String getTaskId()
@@ -29,7 +29,7 @@ public class BmsRedlineProduct extends BaseEntity
    private Date effectiveDate;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireDate;
-    /** 0 pending, 1 active, 2 expired */
+    /** 0 待生效，1 生效，2 已失效 */
    public static final String STATUS_PENDING = "0";
    public static final String STATUS_ACTIVE = "1";
    public static final String STATUS_EXPIRED = "2";
@@ -44,8 +44,8 @@ public class BmsRedlineProduct extends BaseEntity
    private Integer countryCount;
    private Integer surchargeCount;
    private List<BmsRedlineProductCountry> countries;
-    /** query alias of status (0/1/2) */
+    /** status 的查询别名（0/1/2） */
    private String effectStatus;
-    /** query: active = status in (0,1); expired = status 2 */
+    /** 查询：active = status in (0,1)；expired = status 2 */
    private String statusGroup;
 }
@@ -12,23 +12,23 @@ public class BmsRedlineProductCountry implements Serializable
 {
    private static final long serialVersionUID = 1L;

-    /** maps to prc_price_set_detail.psd_id */
+    /** 对应 prc_price_set_detail.psd_id */
    private Long detailId;
    private Long psvId;
    private Long pspId;
    private String priceType;
-    /** FK to product.product_id / psp_id */
+    /** 外键，指向 product.product_id / psp_id */
    private Long productId;
    private String productCode;
-    /** Parse/import helper only (not a DB column). */
+    /** 仅用于解析/导入辅助（非数据库字段）。 */
    private String productName;
    private String countryName;
    private String countryCode;
-    /** prc_zone.zone_id; null when product country has no zone */
+    /** prc_zone.zone_id；产品国家无分区时为 null */
    private Long zoneId;
-    /** e.g. Z1; null when no zone */
+    /** 例如 Z1；无分区时为 null */
    private String zoneCode;
-    /** e.g. Australia(Z1); null when no zone */
+    /** 例如 Australia(Z1)；无分区时为 null */
    private String zoneName;
    private BigDecimal weightMin;
    private BigDecimal weightMax;
@@ -39,10 +39,10 @@ public class BmsRedlineProductCountry implements Serializable
    private String leadTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date effectiveDate;
-    /** null=open; closed to next import effective_date */
+    /** null=未关闭；关闭到下次导入的 effective_date */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireDate;
-    /** 0 pending, 1 active, 2 expired */
+    /** 0 待生效，1 生效，2 已失效 */
    private String status;
    /** 0未删除 1已删除 */
    public static final String IS_DEL_NO = "0";
@@ -52,8 +52,8 @@ public class BmsRedlineProductCountry implements Serializable
    private Date createTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date updateTime;
-    /** query only: true = expire_date is null */
+    /** 仅查询用：true = expire_date 为 null */
    private Boolean openOnly;
-    /** query alias of status (0/1/2) */
+    /** status 的查询别名（0/1/2） */
    private String effectStatus;
 }
@@ -19,7 +19,7 @@ public class BmsRedlineProductImportTask implements Serializable
    private int percent;
    private String message;
    private String error;
-    /** Preview parse payload (products / details); not persisted to DB. */
+    /** 预览解析结果（products / details）；不落库。 */
    private Object result;

    public String getTaskId()
@@ -13,7 +13,7 @@ public class CatalogPreviewApplyRequest implements Serializable

    private Long psvId;
    private List<BmsProduct> products;
-    /** key = upper-case productCode */
+    /** key = 大写后的 productCode */
    private Map<String, List<BmsProductCountry>> detailsByProductCode;

    public Long getPsvId()
@@ -17,17 +17,17 @@ public class PrcBillingTask extends BaseEntity
    private String transferNo;
    private String trackingNo;
    private String orderNo;
-    /** Customer code snapshot for filter / rebill */
+    /** 客户编码快照，用于筛选 / 重计费 */
    private String customerCode;
    /** PENDING / REBILL / REFUND */
    private String billType;
    /** WAITING / SUCCESS / FAILED */
    private String successStatus;
-    /** Billing time from mobile (not Oracle order time; not overwritten on writeback) */
+    /** 移动端传入的计费时间（非 Oracle 订单时间；回写时不会被覆盖） */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date billTime;
    private String billId;
-    /** Stable fail code for search, e.g. NO_CUSTOMER_PACKAGE */
+    /** 用于查询的稳定失败码，例如 NO_CUSTOMER_PACKAGE */
    private String failCode;
    private String errorMessage;
 }
@@ -8,7 +8,7 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;

 /**
- * Price-set detail batch bind customers.
+ * 价格套餐明细批量绑定客户。
 */
@Data
@EqualsAndHashCode(callSuper = true)
@@ -23,8 +23,8 @@ public class PrcCustomerPriceSetBatch extends BaseEntity
    @JsonFormat(pattern = "yyyy-MM-dd")
    private Date prEnddate;
    private String priceSetNote;
-    /** Customers to bind (need customerCode; id/name optional). */
+    /** 要绑定的客户（需要 customerCode；id/name 可选）。 */
    private List<PrcCustomerPriceSet> customers;
-    /** true = move already-bound customers onto this set; false = skip them. */
+    /** true = 把已绑定的客户迁移到本套餐；false = 跳过这些客户。 */
    private Boolean overwriteExisting;
 }
@@ -25,7 +25,7 @@ public class PrcOrderBill extends BaseEntity
    private String trackingNo;
    /** 批量查询：多个运单号精确匹配（仅查询用，非表字段） */
    private List<String> trackingNos;
-    /** transfer order no */
+    /** 转单号 */
    private String transferNo;
    /** 批量查询：多个转单号精确匹配（仅查询用，非表字段） */
    private List<String> transferNos;
@@ -50,7 +50,7 @@ public class PrcOrderBill extends BaseEntity
    private List<String> customerCodes;
    private Integer pieces;
    private BigDecimal actualWeight;
-    /** Receive weight from upstream TAB_ORDER.WEIGHT */
+    /** 收货重量，来自上游 TAB_ORDER.WEIGHT */
    private BigDecimal receiveWeight;
    private BigDecimal volume;
    private BigDecimal volumeWeight;
@@ -109,9 +109,9 @@ public class PrcOrderBill extends BaseEntity
    private BigDecimal registrationFee;
    private BigDecimal freightAmount;
    private BigDecimal surchargeAmount;
-    /** receivable total */
+    /** 应收合计 */
    private BigDecimal incomeTotal;
-    /** payable total */
+    /** 应付合计 */
    private BigDecimal payTotal;
    private String currency;
    /** 应收账单状态：UNBILLED未出账/PARTIAL部分出账/BILLED已出账。 */
@@ -122,7 +122,7 @@ public class PrcOrderBill extends BaseEntity
    private String creditArrearsStatus;
    /** NONE / REFUNDED */
    private String refundStatus;
-    /** Billing fail: 0 ok writes income bill+fee; non-0 amount=0, no income bill/fee */
+    /** 计费失败：0 正常，写入应收账单+费用；非 0 金额为 0，不写入应收账单/费用 */
    private Integer billingFailStatus;
    /** 失败原因 */
    private String errorMessage;
@@ -133,6 +133,6 @@ public class PrcOrderBill extends BaseEntity
    private List<PrcIncomeBillFee> incomeFees;
    private List<PrcPayBillFee> payFees;

-    /** Excel export fields (Java props; export only). */
+    /** Excel 导出字段（Java 属性名；仅导出用）。 */
    private List<String> exportFields;
 }
@@ -22,7 +22,7 @@ public class PrcOrderBillExportTask implements Serializable
    private String error;
    private String exportType;
    private String fileName;
-    /** Relative path under download root, or empty until success. */
+    /** 下载根目录下的相对路径，成功前为空。 */
    private String storageKey;
    private int rowCount;

@@ -22,7 +22,7 @@ public class PrcPriceExcelFile extends BaseEntity
    private Long pefId;
    /** PRODUCT / REDLINE / SALES */
    private String excelType;
-    /** FK prc_price_set_version.psv_id */
+    /** 外键 prc_price_set_version.psv_id */
    private Long psvId;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date effectiveTime;
@@ -32,6 +32,6 @@ public class PrcPriceExcelFile extends BaseEntity
    private String contentType;
    private String fileExtension;
    private String ossId;
-    /** Comma-separated sheet names (optional) */
+    /** 逗号分隔的 Sheet 名称（可选） */
    private String sheetNames;
 }
@@ -15,9 +15,9 @@ public class PrcPriceSet extends BaseEntity
 {
    private static final long serialVersionUID = 1L;

-    /** Ordinary package (default). */
+    /** 普通套餐（默认）。 */
    public static final String CATEGORY_PACKAGE = "PACKAGE";
-    /** Boss exclusive quote. */
+    /** 老板专属报价。 */
    public static final String CATEGORY_EXCLUSIVE = "EXCLUSIVE";
    /** Label / 打单套餐（应收价卡套餐）. */
    public static final String CATEGORY_LABEL = "LABEL";
@@ -28,7 +28,7 @@ public class PrcPriceSet extends BaseEntity
    private String priceSetNote;
    /** FIXED / DISCOUNT */
    private String setType;
-    /** PACKAGE=ordinary set / EXCLUSIVE=boss exclusive quote / LABEL=打单套餐 */
+    /** PACKAGE=普通套餐 / EXCLUSIVE=老板专属报价 / LABEL=打单套餐 */
    private String setCategory;
    private BigDecimal defaultDiscount;
    private String defaultType;
@@ -43,27 +43,27 @@ public class PrcPriceSet extends BaseEntity

    private Integer productCount;
    private Integer customerCount;
-    /** List display: bound customer code/name summary (not a DB column). */
+    /** 列表展示：已绑定客户编码/名称摘要（非数据库字段）。 */
    private String boundCustomers;
    private Boolean expired;
    private String keyword;
-    /** Query only: filter packages by bound customer id. */
+    /** 仅查询用：按绑定客户ID筛选套餐。 */
    private Long customerId;
    private String submitFlag;
-    /** current version on create/edit save */
+    /** 新建/编辑保存时的当前版本 */
    private PrcPriceSetVersion version;
    private List<PrcPriceSetDetail> details;
    private List<PrcPriceSetVersion> versions;
    private List<PrcCustomerPriceSet> customers;
-    /** async save task id (not persisted) */
+    /** 异步保存任务ID（不落库） */
    private String saveTaskId;
-    /** Y: ignored on save; library pull only via /detail/pullFromLibrary */
+    /** Y：保存时忽略；只能通过 /detail/pullFromLibrary 从库拉取 */
    private String pullFromLibrary;
-    /** Y: even if version already has details, delete+re-pull from library */
+    /** Y：即使版本已有明细，也删除后重新从库拉取 */
    private String forcePullLibrary;
    /**
-     * Request-only: bind this Excel attachment (pef_id) to the saved version.psv_id
-     * (not a column on prc_price_set).
+     * 仅请求用：把这个 Excel 附件（pef_id）绑定到保存的版本 psv_id
+     * （不是 prc_price_set 的字段）。
     */
    private Long pefId;
    /** 请求专用：多个 Excel 附件 pef_id，保存时绑到版本（非表字段） */
@@ -30,14 +30,14 @@ public class PrcPriceSetDetail implements Serializable
    private String weightLabel;
    private BigDecimal weightMin;
    private BigDecimal weightMax;
-    /** legacy migrate source id */
+    /** 历史迁移来源ID */
    private Long productCountryId;
    private BigDecimal fvValue;
    private BigDecimal fvRegistrationFee;
    private String sizeLimit;
    private String lastMile;
    private String leadTime;
-    /** display-only base from PRODUCT type when comparing discounts */
+    /** 比较折扣时仅用于展示的 PRODUCT 类型基价 */
    private BigDecimal baseFreightPrice;
    private BigDecimal baseRegistrationFee;
    private BigDecimal discountValue;
@@ -47,7 +47,7 @@ public class PrcPriceSetDetail implements Serializable
    private Date effectiveDate;
    @JsonFormat(pattern = "yyyy-MM-dd")
    private Date expireDate;
-    /** 0 not deleted / 1 deleted */
+    /** 0 未删除 / 1 已删除 */
    public static final String IS_DEL_NO = "0";
    public static final String IS_DEL_YES = "1";
    private String isDel;
@@ -29,12 +29,12 @@ public class PrcPriceSetProduct implements Serializable
    private Date effectiveTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireTime;
-    /** 0 draft / 3 pending / 1 effect / 2 expired */
+    /** 0 草稿 / 3 待生效 / 1 生效 / 2 已失效 */
    private String status;
-    /** legacy migrate source id */
+    /** 历史迁移来源ID */
    private Long sourceProductId;
    private String sourceSheet;
-    /** 0 not deleted / 1 deleted */
+    /** 0 未删除 / 1 已删除 */
    public static final String IS_DEL_NO = "0";
    public static final String IS_DEL_YES = "1";
    private String isDel;
@@ -23,27 +23,27 @@ public class PrcPriceSetVersion extends BaseEntity
    private Integer versionSeq;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date effectiveTime;
-    /** null = open; set to next version effective_time when that version starts */
+    /** null = 未关闭；当下一版本开始时设置为该版本的 effective_time */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireTime;
-    /** 0 draft / 3 pending / 1 active / 2 expired */
+    /** 0 草稿 / 3 待生效 / 1 生效 / 2 已失效 */
    private String status;
    /**
-     * Create-price mode for this version (column: price_build_mode).
-     * SALES: PULL = product library; IMPORT = Excel + prior version; IMPORT_FRESH = Excel blank.
-     * PRODUCT/REDLINE: IMPORT = copy from effect version; IMPORT_FRESH = rebuild (Excel).
-     * Legacy catalog: COPY → IMPORT, old IMPORT → IMPORT_FRESH (see migrate SQL).
+     * 该版本的建价模式（字段：price_build_mode）。
+     * SALES：PULL = 产品库；IMPORT = Excel + 上一个版本；IMPORT_FRESH = Excel 空白。
+     * PRODUCT/REDLINE：IMPORT = 从生效版本复制；IMPORT_FRESH = 重建（Excel）。
+     * 历史目录：COPY → IMPORT，旧的 IMPORT → IMPORT_FRESH（见迁移 SQL）。
     */
    private String priceBuildMode;
-    /** 0 normal / 1 soft-deleted */
+    /** 0 正常 / 1 软删除 */
    private String isDel;

    private List<PrcPriceSetDetail> details;
    private List<PrcPriceSetProduct> products;
-    /** query display: active product rows */
+    /** 查询展示：生效的产品行数 */
    private Integer productCount;
-    /** query display: active detail rows */
+    /** 查询展示：生效的明细行数 */
    private Integer detailCount;
-    /** query only: pending / expired / effect */
+    /** 仅查询用：待生效 / 已失效 / 生效 */
    private String statusGroup;
 }
@@ -17,7 +17,7 @@ public class PrcQuoteFee implements Serializable
    /** bms_fee_type: BASIC_FREIGHT / REGISTRATION_FEE / SURCHARGE */
    private String feeType;
    private String feeName;
-    /** prc_surcharge.sc_id, 0 for freight/registration */
+    /** prc_surcharge.sc_id，运费/挂号费为 0 */
    private Long scId;
    private BigDecimal amount;
    private String currency;
@@ -22,7 +22,7 @@ public class PrcSurcharge extends BaseEntity
    private String currency;
    /** 字典 bms_round_mode：UP / DOWN / HALF_UP */
    private String roundMode;
-    /** on / of */
+    /** 开 / 关 */
    private String ssCode;
    /** 0未删除 1已删除 */
    public static final String IS_DEL_NO = "0";
@@ -28,10 +28,10 @@ public class PrcSurchargeRel extends BaseEntity

    private Long relId;
    private Long scId;
-    /** psp_id for PRODUCT/REDLINE/SALES */
+    /** PRODUCT/REDLINE/SALES 时为 psp_id */
    private Long productId;
    private String productCode;
-    /** psd_id for PRODUCT/REDLINE/SALES (null=all) */
+    /** PRODUCT/REDLINE/SALES 时为 psd_id（null=全部） */
    private Long detailId;
    /** PRODUCT / SALES / REDLINE */
    private String priceType;
@@ -13,7 +13,7 @@ public class PrcWeightSectionTemplate extends BaseEntity

    private Long wstId;
    private String wstName;
-    /** on / off */
+    /** 开 / 关 */
    private String ssCode;
    private String pgCode;
    private Long snId;
@@ -13,7 +13,7 @@ public class PrcZone implements Serializable

    private Long zoneId;
    private Long regionId;
-    /** ISO2 country code stored on prc_zone */
+    /** 存储在 prc_zone 上的 ISO2 国家代码 */
    private String countryCode;
    private String zoneCode;
    private String zoneName;
@@ -23,8 +23,8 @@ public class PrcZone implements Serializable
    private Date createTime;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date updateTime;
-    /** list display, not a table column */
+    /** 列表展示，非表字段 */
    private Integer detailCount;
-    /** list display from region */
+    /** 列表展示，来源于 region */
    private String countryNameCn;
 }
@@ -13,7 +13,7 @@ public class RedlineCatalogPreviewApplyRequest implements Serializable

    private Long psvId;
    private List<BmsRedlineProduct> products;
-    /** key = upper-case productCode */
+    /** key = 大写后的 productCode */
    private Map<String, List<BmsRedlineProductCountry>> detailsByProductCode;

    public Long getPsvId()
@@ -15,17 +15,17 @@ public class AddIncomeBillFeeRequest implements Serializable
    @NotBlank(message = "billId required")
    private String billId;

-    /** Surcharge config id (prc_surcharge.sc_id). */
+    /** 附加费配置ID（prc_surcharge.sc_id）。 */
    @NotNull(message = "scId required")
    private Long scId;

-    /** Dict bms_fee_type; empty = use surcharge.feeType. */
+    /** 字典 bms_fee_type；为空则使用 surcharge.feeType。 */
    private String feeType;

-    /** Empty = calculate from surcharge chargeType. */
+    /** 为空则按附加费的 chargeType 计算。 */
    private BigDecimal amount;

-    /** Default CNY. */
+    /** 默认 CNY。 */
    private String currency;

    private String remark;
@@ -11,7 +11,7 @@ public class BatchAddIncomeBillFeePreview implements Serializable
    private static final long serialVersionUID = 1L;

    private int matchCount;
-    /** First N rows for UI preview. */
+    /** 供界面预览的前 N 行。 */
    private List<PrcOrderBill> samples = new ArrayList<PrcOrderBill>();

    public int getMatchCount()
@@ -15,13 +15,13 @@ public class BatchAddIncomeBillFeeRequest implements Serializable
 {
    private static final long serialVersionUID = 1L;

-    /** ALL = list filters; SELECTED = billIds only. */
+    /** ALL = 列表筛选条件；SELECTED = 仅 billIds。 */
    private String scopeMode;

-    /** Selected bill ids when scopeMode=SELECTED. */
+    /** scopeMode=SELECTED 时选中的账单ID。 */
    private List<String> billIds;

-    /** Same filters as billing list search. */
+    /** 与计费列表搜索相同的筛选条件。 */
    private List<String> orderNos;
    private List<String> trackingNos;
    private List<String> transferNos;
@@ -31,33 +31,33 @@ public class BatchAddIncomeBillFeeRequest implements Serializable
    private List<String> productCodes;
    private String countryCode;
    private String creditArrearsStatus;
-    /** Same as list filter order_status IN (...). */
+    /** 与列表筛选 order_status IN (...) 相同。 */
    private List<Integer> orderStatuses;
-    /** Same as list filter billing_fail_status IN (...). */
+    /** 与列表筛选 billing_fail_status IN (...) 相同。 */
    private List<Integer> billingFailStatuses;

-    /** Billing time range (biz_date), inclusive; format yyyy-MM-dd. */
+    /** 计费时间范围（biz_date），含边界；格式 yyyy-MM-dd。 */
    private String beginBizDate;
    private String endBizDate;

-    /** Receive/pickup time range (pickup_date), inclusive. */
+    /** 收货/提货时间范围（pickup_date），含边界。 */
    private String beginPickupDate;
    private String endPickupDate;

-    /** Surcharge config id (prc_surcharge.sc_id). */
+    /** 附加费配置ID（prc_surcharge.sc_id）。 */
    @NotNull(message = "scId required")
    private Long scId;

-    /** Dict bms_fee_type; empty = use surcharge.feeType. */
+    /** 字典 bms_fee_type；为空则使用 surcharge.feeType。 */
    private String feeType;

    /**
-     * Fixed amount for every matched bill.
-     * Empty = calculate per bill from surcharge chargeType / weight / freight.
+     * 每个匹配账单的固定金额。
+     * 为空则按附加费的 chargeType / 重量 / 运费逐票计算。
     */
    private BigDecimal amount;

-    /** Default CNY. */
+    /** 默认 CNY。 */
    private String currency;

    private String remark;
@@ -12,14 +12,14 @@ public class BillingTaskRetryByFilterRequest implements Serializable
 {
    private static final long serialVersionUID = 1L;

-    /** Customer code (exact match) */
+    /** 客户编码（精确匹配） */
    private String customerCode;
-    /** Bill time start yyyy-MM-dd */
+    /** 计费时间起 yyyy-MM-dd */
    private String beginTime;
-    /** Bill time end yyyy-MM-dd */
+    /** 计费时间止 yyyy-MM-dd */
    private String endTime;
-    /** Optional: FAILED / WAITING / SUCCESS / ALL; default ALL */
+    /** 可选：FAILED / WAITING / SUCCESS / ALL；默认 ALL */
    private String successStatus;
-    /** Optional batch size; server clamps to 20~200, default 50 */
+    /** 可选批大小；服务端限制在 20~200，默认 50 */
    private Integer batchSize;
 }
@@ -18,13 +18,13 @@ public class BillingTaskSubmitRequest implements Serializable
    private String transferNo;
    private String trackingNo;
    private String orderNo;
-    /** Optional customer code; also filled from Oracle when task runs */
+    /** 可选客户编码；任务执行时也会从 Oracle 补全 */
    private String customerCode;
-    /** Billing time from mobile; persisted to prc_billing_task.bill_time */
+    /** 移动端传入的计费时间；写入 prc_billing_task.bill_time */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date billTime;
-    /** Optional: PENDING / REBILL / REFUND. Empty = auto PENDING or REBILL. */
+    /** 可选：PENDING / REBILL / REFUND。为空则自动取 PENDING 或 REBILL。 */
    private String billType;
-    /** Optional body apiCode when header X-Api-Code missing */
+    /** 可选请求体 apiCode，请求头缺少 X-Api-Code 时使用 */
    private String apiCode;
 }
@@ -10,7 +10,7 @@ public class ChargeWeightTemplateRequest implements Serializable
 {
    private static final long serialVersionUID = 1L;

-    /** true = fill orderNo/customer from current list filters */
+    /** true = 按当前列表筛选条件填充 orderNo/customer */
    private boolean fillByFilter;

    private List<String> orderNos;
@@ -21,11 +21,11 @@ public class ChargeWeightTemplateRequest implements Serializable
    private List<String> customerCodes;
    private List<String> productCodes;
    private String creditArrearsStatus;
-    /** Same as list filter order_status IN (...). */
+    /** 与列表筛选 order_status IN (...) 相同。 */
    private List<Integer> orderStatuses;
    private String beginBizDate;
    private String endBizDate;
-    /** Receive/pickup time range (pickup_date), inclusive. */
+    /** 收货/提货时间范围（pickup_date），含边界。 */
    private String beginPickupDate;
    private String endPickupDate;
 }
@@ -7,7 +7,7 @@ import com.fasterxml.jackson.annotation.JsonFormat;
 import lombok.Data;

 /**
- * Order-list billing fail reason popup payload.
+ * 订单列表计费失败原因弹窗数据。
 */
@Data
 public class OrderBillFailReasonVo implements Serializable
@@ -35,10 +35,10 @@ public class OrderBillFailReasonVo implements Serializable
    private String setType;
    private Long psvId;
    private String versionNo;
-    /** Price-cycle version effective time. */
+    /** 价卡周期的版本生效时间。 */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date effectiveTime;
-    /** Price-cycle version expire time; null = open. */
+    /** 价卡周期的版本失效时间；null = 未关闭。 */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date expireTime;
    private Long psdId;
@@ -60,8 +60,8 @@ public class OrderBillFailReasonVo implements Serializable

    private Integer billingFailStatus;
    private String billingFailStatusLabel;
-    /** Raw persisted fail text. */
+    /** 原始落库的失败文本。 */
    private String errorMessage;
-    /** Templated human-readable fail reason. */
+    /** 模板化后的可读失败原因。 */
    private String failReasonDetail;
 }
@@ -13,7 +13,7 @@ public class RecalcBillPriceRequest implements Serializable
    /** PRODUCT | REDLINE */
    private String mode;

-    /** ALL = filters; SELECTED = billIds. */
+    /** ALL = 筛选条件；SELECTED = billIds。 */
    private String scopeMode;
    private List<String> billIds;
    private List<String> orderNos;
@@ -25,13 +25,13 @@ public class RecalcBillPriceRequest implements Serializable
    private List<String> productCodes;
    private String countryCode;
    private String creditArrearsStatus;
-    /** Same as list filter order_status IN (...). */
+    /** 与列表筛选 order_status IN (...) 相同。 */
    private List<Integer> orderStatuses;
-    /** Same as list filter billing_fail_status IN (...). */
+    /** 与列表筛选 billing_fail_status IN (...) 相同。 */
    private List<Integer> billingFailStatuses;
    private String beginBizDate;
    private String endBizDate;
-    /** Receive/pickup time range (pickup_date), inclusive. */
+    /** 收货/提货时间范围（pickup_date），含边界。 */
    private String beginPickupDate;
    private String endPickupDate;
 }
@@ -39,7 +39,7 @@ public class TabOrderCompareTask implements Serializable
     * 每项：transferNo / upstreamStatus / localStatus
     */
    private List<Map<String, Object>> statusMismatchSamples = new ArrayList<Map<String, Object>>();
-    /** status-mismatch transfer_no sample (flat, for UI fill) */
+    /** 状态不一致的 transfer_no 样本（扁平结构，便于界面回填） */
    private List<String> statusMismatchTransferNos = new ArrayList<String>();

    public String getTaskId() { return taskId; }
@@ -18,7 +18,7 @@ public class TabOrderExportTask implements Serializable
    private String message;
    private String error;
    private String fileName;
-    /** Relative path under download root. */
+    /** 下载根目录下的相对路径。 */
    private String storageKey;
    private int rowCount;

@@ -50,6 +50,6 @@ public class TabOrderMonitorQuery implements Serializable
    private Integer blPickup;
    /** 分批同步计费每批条数 */
    private Integer batchSize;
-    /** Excel export field names (Java props; export only). */
+    /** Excel 导出字段名（Java 属性名；仅导出用）。 */
    private List<String> exportFields;
 }
@@ -21,7 +21,7 @@ public class TmsPriceBillRequest extends TmsPriceQuoteRequest
    private String orderNo;

    private String trackingNo;
-    /** transfer order no */
+    /** 转单号 */
    private String transferNo;
    /** 所属销售员 */
    private String belongSaler;
@@ -36,11 +36,11 @@ public class TmsPriceBillRequest extends TmsPriceQuoteRequest
    /** 客服员编码 */
    private String serviceManCode;
    private String customerName;
-    /** From upstream LINE_NAME (fallback PRODUCT_NAME). */
+    /** 来自上游 LINE_NAME（无则取 PRODUCT_NAME）。 */
    private String productName;
    private Integer pieces;
    private BigDecimal actualWeight;
-    /** Upstream TAB_ORDER.WEIGHT (receive weight) */
+    /** 上游 TAB_ORDER.WEIGHT（收货重量） */
    private BigDecimal receiveWeight;
    private BigDecimal volume;
    private BigDecimal volumeWeight;
@@ -52,11 +52,11 @@ public class TmsPriceBillRequest extends TmsPriceQuoteRequest
    private String warehouseCode;
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date orderTime;
-    /** Upstream TAB_ORDER.ORDER_STATUS */
+    /** 上游 TAB_ORDER.ORDER_STATUS */
    private Integer orderStatus;
-    /** Upstream TAB_ORDER.BL_PICKUP 0/1 */
+    /** 上游 TAB_ORDER.BL_PICKUP 0/1 */
    private Integer blPickup;
-    /** Upstream TAB_ORDER.PICKUP_DATE */
+    /** 上游 TAB_ORDER.PICKUP_DATE */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date pickupDate;
    private String orderRemark;
@@ -13,7 +13,7 @@ public class TmsPriceQuoteFeeLine implements Serializable
    private String feeId;
    private String feeType;
    private String feeName;
-    /** surcharge config id, 0 for freight/registration */
+    /** 附加费配置ID，运费/挂号费为 0 */
    private Long scId;
    private BigDecimal amount;
    /** 产品价（目录价分摊） */
@@ -25,6 +25,6 @@ public class TmsPriceQuoteFeeLine implements Serializable
    private String remark;
    /** UNBILLED / BILLED */
    private String arBillStatus;
-    /** 0=system 1=manual */
+    /** 0=系统 1=人工 */
    private String manualFlag;
 }
@@ -14,7 +14,7 @@ public class TmsPriceQuoteRequest implements Serializable

    private Long customerId;

-    /** Required. Maps to ctr_customer.customer_code; used in quote unique key. */
+    /** 必填。对应 ctr_customer.customer_code；参与报价唯一键。 */
    @NotBlank(message = "customerCode is required")
    private String customerCode;

@@ -26,20 +26,20 @@ public class TmsPriceQuoteRequest implements Serializable
     */
    private String channelId;

-    /** ISO2; countryName alternative */
+    /** ISO2；作为 countryName 的替代 */
    private String countryCode;
-    /** country display name; countryCode alternative */
+    /** 国家显示名称；作为 countryCode 的替代 */
    private String countryName;

-    /** Dest postcode; required when product-country has zones */
+    /** 目的邮编；产品国家配置了分区时必填 */
    private String destPostcode;

    @NotNull(message = "weight is required")
    private BigDecimal weight;

-    /** yyyy-MM-dd or yyyy-MM-dd HH:mm:ss; quote defaults today; bill required */
+    /** yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss；试算默认当天；计费必填 */
    private String bizDate;
    private Integer tmsId;
-    /** Header X-Api-Code first; body as fallback */
+    /** 优先取请求头 X-Api-Code；否则取请求体 */
    private String apiCode;
 }
@@ -25,11 +25,11 @@ public class TmsPriceQuoteResult implements Serializable
    private String setType;
    private Integer bindPriority;
    private Long customerPricesetId;
-    /** Hit package version id (prc_price_set_version.psv_id) */
+    /** 命中的套餐版本ID（prc_price_set_version.psv_id） */
    private Long psvId;
-    /** Hit package version no (e.g. V1) */
+    /** 命中的套餐版本号（例如 V1） */
    private String versionNo;
-    /** Hit package detail id when package version detail matched */
+    /** 套餐版本明细命中时，命中的套餐明细ID */
    private Long psdId;

    private String productCode;
@@ -56,19 +56,19 @@ public class TmsPriceQuoteResult implements Serializable
    private BigDecimal freightAmount;
    /** 附加费合计（按产品关联命中后汇总） */
    private BigDecimal surchargeAmount;
-    /** product catalog total: base freight*weight + base registration (no package surcharge) */
+    /** 产品价合计：基础运费*重量 + 基础挂号费（不含套餐附加费） */
    private BigDecimal productAmount;
-    /** redline total from redline_product_country (+ REDLINE surcharges) */
+    /** 红线价合计，来自 redline_product_country（含 REDLINE 附加费） */
    private BigDecimal redlineAmount;
-    /** matched redline_product_country.detail_id for REDLINE surcharge scope */
+    /** 命中的 redline_product_country.detail_id，用于 REDLINE 附加费范围 */
    private Long redlineCountryId;
-    /** cost total (currently = product catalog amount) */
+    /** 成本合计（当前 = 产品价合计） */
    private BigDecimal costAmount;
-    /** receivable total (order bill) */
+    /** 应收合计（订单账单） */
    private BigDecimal incomeTotal;
-    /** payable total (order bill); also quote payable */
+    /** 应付合计（订单账单）；也是报价应付 */
    private BigDecimal payTotal;
-    /** quote / legacy field; same as incomeTotal for bill sync */
+    /** 报价 / 历史字段；账单同步时与 incomeTotal 相同 */
    private BigDecimal payableTotal;
    private String currency = "CNY";
    /** UP / DOWN / HALF_UP */
@@ -81,7 +81,7 @@ public class TmsPriceQuoteResult implements Serializable
    private String billId;
    private String orderNo;
    private String trackingNo;
-    /** transfer order no */
+    /** 转单号 */
    private String transferNo;
    /** 所属销售员 */
    private String belongSaler;
@@ -103,11 +103,11 @@ public class TmsPriceQuoteResult implements Serializable
    private String creditArrearsStatus;
    /** NONE / REFUNDED */
    private String refundStatus;
-    /** Billing fail: 0 ok (income bill+fee); 1/2/3 sales; 23/24/25 catalog */
+    /** 计费失败：0 正常（写入应收账单+费用）；1/2/3 销售价；23/24/25 产品价 */
    private Integer billingFailStatus;
    private Integer pieces;
    private BigDecimal actualWeight;
-    /** Receive weight from upstream TAB_ORDER.WEIGHT */
+    /** 收货重量，来自上游 TAB_ORDER.WEIGHT */
    private BigDecimal receiveWeight;
    private BigDecimal volume;
    private BigDecimal volumeWeight;
@@ -120,10 +120,10 @@ public class TmsPriceQuoteResult implements Serializable
    private String warehouseCode;
    private Date orderTime;
    private String orderRemark;
-    /** true=hit stored quote */
+    /** true=命中已存报价 */
    private Boolean fromCache;
    /** 计费请求 JSON（当次响应/日志用，不落库） */
    private String requestJson;
-    /** original billing response JSON from Elasticsearch */
+    /** 来自 Elasticsearch 的原始计费响应 JSON */
    private String responseJson;
 }
@@ -14,10 +14,10 @@ public class UpdateIncomeBillFeeRequest implements Serializable
    @NotBlank(message = "feeId required")
    private String feeId;

-    /** Optional: change surcharge config. */
+    /** 可选：更换附加费配置。 */
    private Long scId;

-    /** Dict bms_fee_type. */
+    /** 字典 bms_fee_type。 */
    private String feeType;

    private BigDecimal amount;
@@ -1,13 +1,13 @@
 package com.bms.price.enums;

 /**
- * prc_order_bill.billing_fail_status numeric codes.
- * 0 success;
- * 1/2/3 sales-price (package) miss: product / country / weight;
- * 23/24/25 product-catalog price miss: product / country / weight;
- * 4+ map to prc_billing_task.fail_code.
- * 26 not billed yet (order-source sync only).
- * Income bill + fee rows: only status 0.
+ * prc_order_bill.billing_fail_status 数字编码。
+ * 0 成功；
+ * 1/2/3 销售价（套餐）未命中：产品 / 国家 / 重量段；
+ * 23/24/25 产品价（目录）未命中：产品 / 国家 / 重量段；
+ * 4 及以上对应 prc_billing_task.fail_code。
+ * 26 尚未计费（仅订单数源同步使用）。
+ * 应收账单 + 费用行：仅状态 0 才写入。
 */
 public enum BillBillingFailStatus
 {
@@ -34,13 +34,13 @@ public enum BillBillingFailStatus
    CUSTOMER_DISABLED(20),
    FREIGHT_MISSING(21),
    UNKNOWN(22),
-    /** Product catalog (产品价) miss: no product rows. */
+    /** 产品价（目录）未命中：没有产品行。 */
    CATALOG_PRODUCT(23),
-    /** Product catalog miss: product hit but country/zone miss. */
+    /** 产品价未命中：产品命中但国家/分区未命中。 */
    CATALOG_COUNTRY(24),
-    /** Product catalog miss: product+country hit but weight band miss. */
+    /** 产品价未命中：产品+国家命中但重量段未命中。 */
    CATALOG_WEIGHT(25),
-    /** Order landed from upstream but not billed yet. */
+    /** 订单已从上游落地但尚未计费。 */
    NOT_BILLED(26);

    private final int code;
@@ -86,7 +86,7 @@ public enum BillBillingFailStatus
        return code != null && code.intValue() == NOT_BILLED.code;
    }

-    /** Only success (0) persists prc_income_bill. */
+    /** 仅成功（0）才写入 prc_income_bill。 */
    public static boolean storesIncomeBill(Integer code)
    {
        return code == null || code.intValue() == SUCCESS.code;
@@ -7,9 +7,9 @@ package com.bms.price.enums;
 */
 public enum BillOrderStatus
 {
-    /** Upstream: returned package; also set after billing-list fee refund. */
+    /** 上游：包裹退回；账单列表费用退款后也会置为此状态。 */
    REFUNDED(9),
-    /** Upstream: cancelled / deleted. */
+    /** 上游：已取消 / 已删除。 */
    CANCELLED(10);

    private final int code;
@@ -34,7 +34,7 @@ public enum BillOrderStatus
        return status != null && status.intValue() == code;
    }

-    /** Upstream ORDER_STATUS 9/10 -> fee refund path. */
+    /** 上游 ORDER_STATUS 9/10 -> 走费用退款流程。 */
    public static boolean requiresFeeRefund(Integer status)
    {
        return REFUNDED.matches(status) || CANCELLED.matches(status);
@@ -12,17 +12,17 @@ public enum BillTaskFailCode
    NO_ACTIVE_PACKAGE_VERSION("NO_ACTIVE_PACKAGE_VERSION"),
    ALREADY_IN_AR_BILL("ALREADY_IN_AR_BILL"),
    PRODUCT_ARCHIVE_MISSING("PRODUCT_ARCHIVE_MISSING"),
-    /** Soft-fail: sales price (package) product miss. */
+    /** 软失败：销售价（套餐）产品未命中。 */
    PRODUCT_NOT_HIT("PRODUCT_NOT_HIT"),
-    /** Soft-fail: sales price country/zone miss. */
+    /** 软失败：销售价国家/分区未命中。 */
    COUNTRY_NOT_HIT("COUNTRY_NOT_HIT"),
-    /** Soft-fail: sales price weight band miss. */
+    /** 软失败：销售价重量段未命中。 */
    WEIGHT_NOT_HIT("WEIGHT_NOT_HIT"),
-    /** Soft-fail: product catalog (产品价) product miss. */
+    /** 软失败：产品价（目录）产品未命中。 */
    CATALOG_PRODUCT_NOT_HIT("CATALOG_PRODUCT_NOT_HIT"),
-    /** Soft-fail: product catalog country/zone miss. */
+    /** 软失败：产品价国家/分区未命中。 */
    CATALOG_COUNTRY_NOT_HIT("CATALOG_COUNTRY_NOT_HIT"),
-    /** Soft-fail: product catalog weight band miss. */
+    /** 软失败：产品价重量段未命中。 */
    CATALOG_WEIGHT_NOT_HIT("CATALOG_WEIGHT_NOT_HIT"),
    PRICE_NOT_HIT("PRICE_NOT_HIT"),
    ZONE_PRICE_NOT_HIT("ZONE_PRICE_NOT_HIT"),
@@ -53,7 +53,7 @@ public enum BillTaskFailCode
    }

    /**
-     * Map free-text error message to a stable fail code for search.
+     * 把自由文本错误信息映射为可用于查询的稳定失败码。
     */
    public static String resolveCode(String errorMessage)
    {
@@ -78,7 +78,7 @@ public enum BillTaskFailCode
        {
            return PRODUCT_ARCHIVE_MISSING.code;
        }
-        // Soft-fail: product catalog before sales (more specific Chinese prefix)
+        // 软失败：产品价先于销售价判断（中文前缀更具体）
        if (containsAny(msg, "产品价未匹配重量段", "CATALOG_WEIGHT_NOT_HIT", "billingFail.catalogWeight"))
        {
            return CATALOG_WEIGHT_NOT_HIT.code;
@@ -91,7 +91,7 @@ public enum BillTaskFailCode
        {
            return CATALOG_PRODUCT_NOT_HIT.code;
        }
-        // Soft-fail sales price (order matters: weight/country before generic product)
+        // 软失败：销售价（顺序重要：重量段/国家先于笼统的产品）
        if (containsAny(msg, "销售价未匹配重量段", "未匹配重量段", "WEIGHT_NOT_HIT", "billingFail.weight"))
        {
            return WEIGHT_NOT_HIT.code;
@@ -3,11 +3,11 @@ package com.bms.price.enums;
 /** 计费任务类型，对应 prc_billing_task.bill_type */
 public enum BillTaskType
 {
-    /** first-time billing */
+    /** 首次计费 */
    PENDING("PENDING"),
-    /** same transfer/order already billed */
+    /** 同一转单/订单已计费过 */
    REBILL("REBILL"),
-    /** refund */
+    /** 退款 */
    REFUND("REFUND");

    private final String code;
@@ -22,36 +22,36 @@ public interface BmsProductCountryMapper
    /** 按明细行主键更新可编辑字段（重量段/运费/挂号费/尺寸/尾程/时效/生效失效日期） */
    public int updateBmsProductCountry(BmsProductCountry country);

-    /** Import overlay: update price/zone/attrs on matched country row */
+    /** 导入覆盖：更新命中国家行的价格/分区/属性 */
    public int updateBmsProductCountryImport(BmsProductCountry country);

-    /** Soft delete by product_id */
+    /** 按 product_id 逻辑删除 */
    public int deleteByProductId(Long productId);

-    /** Soft delete by product_code */
+    /** 按 product_code 逻辑删除 */
    public int deleteByProductCode(String productCode);

-    /** Soft delete by product_code + effective_date */
+    /** 按 product_code + effective_date 逻辑删除 */
    public int deleteByProductCodeAndEffectiveDate(
        @Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Max open (expire_date is null) effective_date for product */
+    /** 该产品最大的未结束（expire_date 为空）生效日期 */
    public Date selectMaxOpenEffectiveDate(@Param("productCode") String productCode);

-    /** Close open versions: set expire_date = newEffectiveDate where effective_date &lt; newEffectiveDate */
+    /** 结束未关闭版本：把 effective_date &lt; newEffectiveDate 的行 expire_date 置为 newEffectiveDate */
    public int expireOpenByProductCode(
        @Param("productCode") String productCode,
        @Param("newEffectiveDate") Date newEffectiveDate);

-    /** After deleting a pending version: reopen country rows closed at that effective date */
+    /** 删除待生效版本后：恢复在该生效日期被关闭的国家行 */
    public int reopenExpiredByProductCodeAndExpireDate(
        @Param("productCode") String productCode,
        @Param("expireDate") Date expireDate);

    /**
-     * Close open rows for one product + country where effective_date &lt; newEffectiveDate.
-     * Match by country_code when present, otherwise country_name.
+     * 关闭某产品 + 国家下 effective_date &lt; newEffectiveDate 的未关闭行。
+     * 有 country_code 时按它匹配，否则按 country_name 匹配。
     */
    public int expireOpenByProductCodeAndCountry(
        @Param("productCode") String productCode,
@@ -59,26 +59,26 @@ public interface BmsProductCountryMapper
        @Param("countryName") String countryName,
        @Param("newEffectiveDate") Date newEffectiveDate);

-    /** Recompute status from effective_date / expire_date vs today */
+    /** 按 effective_date / expire_date 与今天重新计算状态 */
    public int refreshStatusByDates();

-    /** Replace same-day version only */
+    /** 仅替换同一生效日期的版本 */
    public int deleteOpenByProductCodeAndEffectiveDate(
        @Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Hard-delete all detail rows of one product (psp_id). */
+    /** 物理删除某产品的全部明细行（psp_id）。 */
    public int physicalDeleteByPspId(@Param("productId") Long productId);

-    /** Hard-delete detail rows of one product + country (psp_id scope). */
+    /** 物理删除某产品 + 国家的明细行（psp_id 范围）。 */
    public int physicalDeleteByPspIdAndCountry(
        @Param("productId") Long productId,
        @Param("countryCode") String countryCode,
        @Param("countryName") String countryName);

    /**
-     * Hard-delete draft/pending detail rows for one product + country (same-version replace).
-     * Only versions with status draft(0) or pending(3) are affected.
+     * 物理删除某产品 + 国家的草稿/待生效明细行（同版本替换）。
+     * 只影响状态为草稿(0)或待生效(3)的版本。
     */
    public int deleteOpenByProductCodeAndCountryOnDate(
        @Param("productCode") String productCode,
@@ -86,17 +86,17 @@ public interface BmsProductCountryMapper
        @Param("countryName") String countryName,
        @Param("effectiveDate") Date effectiveDate);

-    /** Hard-delete surcharge_rel rows linked to draft/pending details for product+country. */
+    /** 物理删除产品+国家草稿/待生效明细关联的 surcharge_rel 行。 */
    public int deleteSurchargeRelByProductCodeAndCountryOnDate(
        @Param("productCode") String productCode,
        @Param("countryCode") String countryCode,
        @Param("countryName") String countryName,
        @Param("effectiveDate") Date effectiveDate);

-    /** Open country rows (expire_date is null) for product */
+    /** 该产品未结束（expire_date 为空）的国家行 */
    public List<BmsProductCountry> selectOpenByProductCode(@Param("productCode") String productCode);

-    /** Copy previously open rows into a new effective_date (caller must expire first) */
+    /** 把之前未结束的行复制到新的生效日期（调用方需先结束旧版本） */
    public int copyOpenCountries(
        @Param("productCode") String productCode,
        @Param("productId") Long productId,
@@ -104,9 +104,9 @@ public interface BmsProductCountryMapper
        @Param("status") String status);

    /**
-     * Match by product + country + weight + bizDate (+ optional zoneCode).
-     * When zoneCode is empty, prefer rows without zone.
-     * When zoneCode is set, require matching zone_code.
+     * 按产品 + 国家 + 重量 + 业务日期（+ 可选 zoneCode）匹配。
+     * zoneCode 为空时优先取无分区的行。
+     * zoneCode 有值时要求 zone_code 一致。
     */
    public BmsProductCountry selectMatchByProductCountryWeight(
        @Param("productCode") String productCode,
@@ -117,8 +117,8 @@ public interface BmsProductCountryMapper
        @Param("bizDate") Date bizDate);

    /**
-     * Lowest PRODUCT catalog weight band for product/country/zone (ignore weight).
-     * Used when charge weight is below the minimum band.
+     * 产品/国家/分区下最低的 PRODUCT 目录重量段（忽略重量）。
+     * 用于计费重量低于最小重量段时。
     */
    public BmsProductCountry selectMinBandByProductCountry(
        @Param("productCode") String productCode,
@@ -127,21 +127,21 @@ public interface BmsProductCountryMapper
        @Param("zoneCode") String zoneCode,
        @Param("bizDate") Date bizDate);

-    /** Count product-country rows that have a zone for this product+country+bizDate */
+    /** 统计该产品+国家+业务日期下带分区的产品国家行数 */
    public int countZonedByProductCountry(
        @Param("productCode") String productCode,
        @Param("countryCode") String countryCode,
        @Param("countryName") String countryName,
        @Param("bizDate") Date bizDate);

-    /** Count catalog rows by product (+ bizDate window), ignore country/zone/weight. */
+    /** 按产品（+ 业务日期区间）统计目录行数，忽略国家/分区/重量。 */
    public int countByProduct(
        @Param("productCode") String productCode,
        @Param("bizDate") Date bizDate);

    /**
-     * Count catalog rows by product + country + zone (+ bizDate), ignore weight.
-     * Used to diagnose country miss vs weight miss.
+     * 按产品 + 国家 + 分区（+ 业务日期）统计目录行数，忽略重量。
+     * 用于区分是国家未命中还是重量未命中。
     */
    public int countByProductCountryZone(
        @Param("productCode") String productCode,
@@ -14,43 +14,43 @@ public interface BmsProductMapper
 {
    public BmsProduct selectBmsProductById(Long productId);

-    /** Latest row by product_code (effective_date desc) */
+    /** 按 product_code 取最新行（effective_date 倒序） */
    public BmsProduct selectBmsProductByCode(String productCode);

-    /** Unique business key: product_code + effective_date */
+    /** 唯一业务键：product_code + effective_date */
    public BmsProduct selectBmsProductByCodeAndDate(@Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Product row in a specific version */
+    /** 指定版本中的产品行 */
    public BmsProduct selectByCodeAndPsvId(@Param("productCode") String productCode, @Param("psvId") Long psvId);

-    /** Product version effective on bizDate */
+    /** 业务日期生效的产品版本 */
    public BmsProduct selectEffectiveBmsProductByCode(@Param("productCode") String productCode,
        @Param("bizDate") Date bizDate);

    public List<BmsProduct> selectBmsProductList(BmsProduct product);

-    /** Dropdown options: slim columns, no country/surcharge count subqueries */
+    /** 下拉选项：仅精简列，不含国家/附加费计数子查询 */
    public List<BmsProduct> selectBmsProductOptions(BmsProduct product);

    public int insertBmsProduct(BmsProduct product);

    public int updateBmsProduct(BmsProduct product);

-    /** Soft delete: set del_flag = 2 */
+    /** 逻辑删除：del_flag 置为 2 */
    public int deleteBmsProductByIds(Long[] productIds);

-    /** Close previous open versions: expire_date = newEffectiveDate */
+    /** 结束之前的未关闭版本：expire_date 置为 newEffectiveDate */
    public int expireOpenByProductCode(
        @Param("productCode") String productCode,
        @Param("newEffectiveDate") Date newEffectiveDate,
        @Param("excludeId") Long excludeId);

-    /** After deleting a pending version: reopen rows closed at that effective date */
+    /** 删除待生效版本后：恢复在该生效日期被关闭的行 */
    public int reopenExpiredByProductCodeAndExpireDate(
        @Param("productCode") String productCode,
        @Param("expireDate") Date expireDate);

-    /** Recompute status from effective_date / expire_date vs today */
+    /** 按 effective_date / expire_date 与今天重新计算状态 */
    public int refreshStatusByDates();
 }
@@ -22,7 +22,7 @@ public interface BmsRedlineProductCountryMapper
    /** 按明细行主键更新可编辑字段（重量段/运费/挂号费/尺寸/尾程/时效/生效失效日期） */
    public int updateBmsRedlineProductCountry(BmsRedlineProductCountry country);

-    /** Import overlay: update price/zone/attrs on matched country row */
+    /** 导入覆盖：更新命中国家行的价格/分区/属性 */
    public int updateBmsRedlineProductCountryImport(BmsRedlineProductCountry country);

    public int deleteByProductId(Long productId);
@@ -33,22 +33,22 @@ public interface BmsRedlineProductCountryMapper
        @Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Max open (expire_date is null) effective_date for product */
+    /** 该产品最大的未结束（expire_date 为空）生效日期 */
    public Date selectMaxOpenEffectiveDate(@Param("productCode") String productCode);

-    /** Close open versions: set expire_date = newEffectiveDate where effective_date &lt; newEffectiveDate */
+    /** 结束未关闭版本：把 effective_date &lt; newEffectiveDate 的行 expire_date 置为 newEffectiveDate */
    public int expireOpenByProductCode(
        @Param("productCode") String productCode,
        @Param("newEffectiveDate") Date newEffectiveDate);

-    /** After deleting a pending version: reopen rows closed at that effective date */
+    /** 删除待生效版本后：恢复在该生效日期被关闭的行 */
    public int reopenExpiredByProductCodeAndExpireDate(
        @Param("productCode") String productCode,
        @Param("expireDate") Date expireDate);

    /**
-     * Close open rows for one product + country where effective_date &lt; newEffectiveDate.
-     * Match by country_code when present, otherwise country_name.
+     * 关闭某产品 + 国家下 effective_date &lt; newEffectiveDate 的未关闭行。
+     * 有 country_code 时按它匹配，否则按 country_name 匹配。
     */
    public int expireOpenByProductCodeAndCountry(
        @Param("productCode") String productCode,
@@ -56,26 +56,26 @@ public interface BmsRedlineProductCountryMapper
        @Param("countryName") String countryName,
        @Param("newEffectiveDate") Date newEffectiveDate);

-    /** Recompute status from effective_date / expire_date vs today */
+    /** 按 effective_date / expire_date 与今天重新计算状态 */
    public int refreshStatusByDates();

-    /** Replace same-day version only */
+    /** 仅替换同一生效日期的版本 */
    public int deleteOpenByProductCodeAndEffectiveDate(
        @Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Hard-delete all detail rows of one product (psp_id). */
+    /** 物理删除某产品的全部明细行（psp_id）。 */
    public int physicalDeleteByPspId(@Param("productId") Long productId);

-    /** Hard-delete detail rows of one product + country (psp_id scope). */
+    /** 物理删除某产品 + 国家的明细行（psp_id 范围）。 */
    public int physicalDeleteByPspIdAndCountry(
        @Param("productId") Long productId,
        @Param("countryCode") String countryCode,
        @Param("countryName") String countryName);

    /**
-     * Hard-delete draft/pending detail rows for one product + country (same-version replace).
-     * Only versions with status draft(0) or pending(3) are affected.
+     * 物理删除某产品 + 国家的草稿/待生效明细行（同版本替换）。
+     * 只影响状态为草稿(0)或待生效(3)的版本。
     */
    public int deleteOpenByProductCodeAndCountryOnDate(
        @Param("productCode") String productCode,
@@ -83,17 +83,17 @@ public interface BmsRedlineProductCountryMapper
        @Param("countryName") String countryName,
        @Param("effectiveDate") Date effectiveDate);

-    /** Hard-delete surcharge_rel rows linked to draft/pending details for product+country. */
+    /** 物理删除产品+国家草稿/待生效明细关联的 surcharge_rel 行。 */
    public int deleteSurchargeRelByProductCodeAndCountryOnDate(
        @Param("productCode") String productCode,
        @Param("countryCode") String countryCode,
        @Param("countryName") String countryName,
        @Param("effectiveDate") Date effectiveDate);

-    /** Open country rows (expire_date is null) for product */
+    /** 该产品未结束（expire_date 为空）的国家行 */
    public List<BmsRedlineProductCountry> selectOpenByProductCode(@Param("productCode") String productCode);

-    /** Copy previously open rows into a new effective_date (caller must expire first) */
+    /** 把之前未结束的行复制到新的生效日期（调用方需先结束旧版本） */
    public int copyOpenCountries(
        @Param("productCode") String productCode,
        @Param("productId") Long productId,
@@ -101,9 +101,9 @@ public interface BmsRedlineProductCountryMapper
        @Param("status") String status);

    /**
-     * Match by product + country + weight + bizDate (+ optional zoneCode).
-     * When zoneCode is empty, prefer rows without zone.
-     * When zoneCode is set, require matching zone_code.
+     * 按产品 + 国家 + 重量 + 业务日期（+ 可选 zoneCode）匹配。
+     * zoneCode 为空时优先取无分区的行。
+     * zoneCode 有值时要求 zone_code 一致。
     */
    public BmsRedlineProductCountry selectMatchByProductCountryWeight(
        @Param("productCode") String productCode,
@@ -113,7 +113,7 @@ public interface BmsRedlineProductCountryMapper
        @Param("weight") BigDecimal weight,
        @Param("bizDate") Date bizDate);

-    /** Count product-country rows that have a zone for this product+country+bizDate */
+    /** 统计该产品+国家+业务日期下带分区的产品国家行数 */
    public int countZonedByProductCountry(
        @Param("productCode") String productCode,
        @Param("countryCode") String countryCode,
@@ -14,17 +14,17 @@ public interface BmsRedlineProductMapper
 {
    public BmsRedlineProduct selectBmsRedlineProductById(Long productId);

-    /** Latest row by product_code (effective_date desc) */
+    /** 按 product_code 取最新行（effective_date 倒序） */
    public BmsRedlineProduct selectBmsRedlineProductByCode(String productCode);

-    /** Unique business key: product_code + effective_date */
+    /** 唯一业务键：product_code + effective_date */
    public BmsRedlineProduct selectBmsRedlineProductByCodeAndDate(@Param("productCode") String productCode,
        @Param("effectiveDate") Date effectiveDate);

-    /** Product row in a specific version */
+    /** 指定版本中的产品行 */
    public BmsRedlineProduct selectByCodeAndPsvId(@Param("productCode") String productCode, @Param("psvId") Long psvId);

-    /** Product version effective on bizDate */
+    /** 业务日期生效的产品版本 */
    public BmsRedlineProduct selectEffectiveBmsRedlineProductByCode(@Param("productCode") String productCode,
        @Param("bizDate") Date bizDate);

@@ -36,17 +36,17 @@ public interface BmsRedlineProductMapper

    public int deleteBmsRedlineProductByIds(Long[] productIds);

-    /** Close previous open versions: expire_date = newEffectiveDate */
+    /** 结束之前的未关闭版本：expire_date 置为 newEffectiveDate */
    public int expireOpenByProductCode(
        @Param("productCode") String productCode,
        @Param("newEffectiveDate") Date newEffectiveDate,
        @Param("excludeId") Long excludeId);

-    /** After deleting a pending version: reopen rows closed at that effective date */
+    /** 删除待生效版本后：恢复在该生效日期被关闭的行 */
    public int reopenExpiredByProductCodeAndExpireDate(
        @Param("productCode") String productCode,
        @Param("expireDate") Date expireDate);

-    /** Recompute status from effective_date / expire_date vs today */
+    /** 按 effective_date / expire_date 与今天重新计算状态 */
    public int refreshStatusByDates();
 }
@@ -4,7 +4,7 @@ import org.apache.ibatis.annotations.Param;
 import com.bms.price.domain.ChannelProductMap;

 /**
- * Channel-product pay-type mapping.
+ * 渠道-产品付款方式映射。
 */
 public interface ChannelProductMapMapper
 {
@@ -22,7 +22,7 @@ public interface OracleUpstreamOrderMapper

    long countTabOrderMonitor(@Param("orderTable") String orderTable, @Param("query") TabOrderMonitorQuery query);

-    /** Key-first page for customer+time queries (sort narrow columns only). */
+    /** 客户+时间查询的主键优先分页（仅对窄列排序）。 */
    List<Map<String, Object>> selectTabOrderMonitorKeyPage(
        @Param("orderTable") String orderTable,
        @Param("query") TabOrderMonitorQuery query,
@@ -38,17 +38,17 @@ public interface OracleUpstreamOrderMapper
        @Param("startRow") long startRow,
        @Param("endRow") long endRow);

-    /** List detail by ids: display columns only. */
+    /** 按 ID 查明细：仅返回展示列。 */
    List<Map<String, Object>> selectTabOrderMonitorListByIds(
        @Param("orderTable") String orderTable,
        @Param("ids") List<String> ids);

-    /** Distinct product codes for product-vs-package check (grouped, no pagination). */
+    /** 产品与套餐比对用的去重产品编码（分组，不分页）。 */
    List<Map<String, Object>> selectTabOrderProductCodes(
        @Param("orderTable") String orderTable,
        @Param("query") TabOrderMonitorQuery query);

-    /** Order ids for one product code under the same filters (no pagination). */
+    /** 相同筛选条件下某个产品编码的订单 ID（不分页）。 */
    List<Map<String, Object>> selectTabOrderIdsByProduct(
        @Param("orderTable") String orderTable,
        @Param("query") TabOrderMonitorQuery query);
@@ -14,18 +14,18 @@ public interface PrcBillingTaskMapper

    int updatePrcBillingTask(PrcBillingTask task);

-    /** CAS: WAITING -> processing claim not needed; writeback SUCCESS/FAILED */
+    /** CAS：WAITING -> processing 无需抢占；回写 SUCCESS/FAILED */
    int updateBillingResult(PrcBillingTask task);

-    /** Delete the queue row once prc_order_bill is saved. transfer_no is the unique key. */
+    /** prc_order_bill 保存后删除队列行。transfer_no 为唯一键。 */
    int deleteByTransferNo(@Param("transferNo") String transferNo);

-    /** Count tasks for filter retry (customer + bill_time window). */
+    /** 统计筛选重试的任务数（客户 + 账单时间窗口）。 */
    int countTaskIdsByFilter(PrcBillingTask query);

    /**
-     * Keyset page of task ids only (asc) to avoid loading full rows into memory.
-     * lastTaskId exclusive lower bound; pass 0 for first page.
+     * 仅按任务 ID 做键集分页（升序），避免把完整行加载到内存。
+     * lastTaskId 为排他下界；首页传 0。
     */
    List<Long> selectTaskIdsByFilter(
        @Param("query") PrcBillingTask query,
@@ -25,7 +25,7 @@ public interface PrcCustomerPriceSetMapper

    public int countByPriceSetId(Long priceSetId);

-    /** Count binds of this customer; optional exclude current bind or current set */
+    /** 统计该客户的绑定数；可选排除当前绑定或当前套餐 */
    public int countByCustomerId(@Param("customerId") Long customerId,
        @Param("excludeId") Long excludeId,
        @Param("excludePriceSetId") Long excludePriceSetId);
@@ -40,7 +40,7 @@ public interface PrcCustomerPriceSetMapper
                            @Param("endDate") java.util.Date endDate);

    /**
-     * Customer package binds (package not stopped). Temporal match uses version effective_time in quote/bill.
+     * 客户套餐绑定（套餐未停用）。时效匹配在报价/账单中使用版本的 effective_time。
     */
    public java.util.List<PrcCustomerPriceSet> selectEffectiveByCustomer(
        @Param("customerId") Long customerId);
@@ -17,11 +17,11 @@ public interface PrcIncomeBillFeeMapper

    public PrcIncomeBillFee selectByFeeId(String feeId);

-    /** Lookup by unique key uk_bill_fee_item (bill_id, fee_type, sc_id). */
+    /** 按唯一键 uk_bill_fee_item（bill_id、fee_type、sc_id）查询。 */
    public PrcIncomeBillFee selectByBillIdAndFeeTypeAndScId(@Param("billId") String billId,
        @Param("feeType") String feeType, @Param("scId") Long scId);

-    /** Count fees of a bill under given ar_bill_status and fee_type (e.g. BILLED + BASIC_FREIGHT). */
+    /** 统计某账单在指定 ar_bill_status 和 fee_type 下的费用数（例如 BILLED + BASIC_FREIGHT）。 */
    public int countByBillIdAndArBillStatusAndFeeType(@Param("billId") String billId,
        @Param("arBillStatus") String arBillStatus, @Param("feeType") String feeType);

@@ -48,6 +48,6 @@ public interface PrcIncomeBillFeeMapper

    public int deleteByBillId(String billId);

-    /** Rebill: delete auto fees only; keep manual_flag=1 rows. */
+    /** 重新出账：只删除自动费用；保留 manual_flag=1 的行。 */
    public int deleteAutoFeesByBillId(String billId);
 }
@@ -21,16 +21,16 @@ public interface PrcOrderBillMapper

    public List<PrcOrderBill> selectPrcOrderBillList(PrcOrderBill bill);

-    /** bill_id only (same filters / data-scope as list), for large local rebill. */
+    /** 只取 bill_id（筛选条件/数据权限与列表一致），用于本地大批量重新出账。 */
    List<String> selectPrcOrderBillIds(PrcOrderBill bill);

-    /** Count matching bills (same filters / data-scope as list). */
+    /** 统计匹配的账单数（筛选条件/数据权限与列表一致）。 */
    int countPrcOrderBillIds(PrcOrderBill bill);

-    /** Distinct customer+product groups for product-check (order counts in filter window). */
+    /** 产品校验用的去重客户+产品分组（统计筛选窗口内的订单数）。 */
    List<Map<String, Object>> selectDistinctProductGroups(PrcOrderBill bill);

-    /** Drill-down orders for one product under product-check filters. */
+    /** 产品校验筛选条件下钻某个产品的订单。 */
    List<PrcOrderBill> selectOrderBillsByProductForCheck(@Param("query") PrcOrderBill query, @Param("limit") int limit);

    /**
@@ -138,6 +138,6 @@ public interface PrcOrderBillMapper
    /** 只更新应付合计，不改应收。 */
    int updatePayTotal(@Param("billId") String billId, @Param("payTotal") BigDecimal payTotal);

-    /** Count order bills that reference this sales package version. */
+    /** 统计引用该销售套餐版本的订单账单数。 */
    int countByPsvId(@Param("psvId") Long psvId);
 }
@@ -13,10 +13,10 @@ public interface PrcPriceExcelFileMapper

    public List<PrcPriceExcelFile> selectPrcPriceExcelFileList(PrcPriceExcelFile query);

-    /** Excel files bound to a version via psv_id */
+    /** 通过 psv_id 绑定到某版本的 Excel 文件 */
    public List<PrcPriceExcelFile> selectByPsvId(@Param("psvId") Long psvId);

-    /** Hard delete attachments of a version. */
+    /** 物理删除某版本的附件。 */
    public int physicalDeleteByPsvId(@Param("psvId") Long psvId);

    public int insertPrcPriceExcelFile(PrcPriceExcelFile row);
@@ -25,15 +25,15 @@ public interface PrcPriceSetDetailMapper

    public int deletePrcPriceSetDetailByIds(Long[] psdIds);

-    /** Delete SALES details for all versions of a price set */
+    /** 删除某价格套餐所有版本的 SALES 明细 */
    public int deletePrcPriceSetDetailByPriceSetId(Long priceSetId);

    public int deletePrcPriceSetDetailByPsvId(Long psvId);

-    /** Hard delete detail rows by ids (draft / pending). */
+    /** 按 ID 物理删除明细行（草稿 / 待生效）。 */
    public int physicalDeleteByIds(Long[] psdIds);

-    /** Hard delete all detail rows under a version. */
+    /** 物理删除某版本下的全部明细行。 */
    public int physicalDeleteByPsvId(@Param("psvId") Long psvId);

    public int deleteOrphanDetailsByPriceSetId(Long priceSetId);
@@ -44,15 +44,15 @@ public interface PrcPriceSetDetailMapper

    public int countByPsvId(Long psvId);

-    /** Count detail rows including soft-deleted (for deleted-version tab). */
+    /** 统计明细行数，包含已逻辑删除的数据（供已删除版本页签使用）。 */
    public int countByPsvIdAll(Long psvId);

    public int copyDetailsFromVersion(@Param("srcPsvId") Long srcPsvId, @Param("newPsvId") Long newPsvId);

-    /** Copy version effective time, expire time and status onto catalog detail rows. */
+    /** 把版本生效时间、失效时间和状态复制到目录明细行。 */
    public int syncEffectByPriceType(@Param("priceType") String priceType);

-    /** Copy SALES version effect fields onto package detail rows. */
+    /** 把 SALES 版本的生效字段复制到套餐明细行。 */
    public int syncEffectByPriceSetId(@Param("priceSetId") Long priceSetId);

    public int insertFixedDetailsFromLibrary(
@@ -75,8 +75,8 @@ public interface PrcPriceSetDetailMapper
        @Param("weight") BigDecimal weight);

    /**
-     * Lowest FIXED weight band for product/country/zone (ignore weight).
-     * Used when charge weight is below the minimum band.
+     * 产品/国家/分区下最低的 FIXED 重量段（忽略重量）。
+     * 用于计费重量低于最小重量段时。
     */
    public PrcPriceSetDetail selectFixedMinBand(
        @Param("psvId") Long psvId,
@@ -86,8 +86,8 @@ public interface PrcPriceSetDetailMapper
        @Param("zoneCode") String zoneCode);

    /**
-     * Next FIXED weight band whose weight_min is strictly above {@code weight}
-     * (ceil into the gap between bands, e.g. 1.001 -> 1.01~2).
+     * 下一个 weight_min 严格大于 {@code weight} 的 FIXED 重量段
+     * （重量落在段间空隙时向上取整，例如 1.001 -> 1.01~2）。
     */
    public PrcPriceSetDetail selectFixedNextBandUp(
        @Param("psvId") Long psvId,
@@ -126,7 +126,7 @@ public interface PrcPriceSetDetailMapper
    public int updatePriceTypeByPsvId(@Param("psvId") Long psvId, @Param("priceType") String priceType);

    /**
-     * Match PRODUCT/REDLINE detail by catalog type + bizDate window on version.
+     * 按目录类型 + 版本上的业务日期区间匹配 PRODUCT/REDLINE 明细。
     */
    public PrcPriceSetDetail selectCatalogMatch(
        @Param("priceType") String priceType,
@@ -12,7 +12,7 @@ public interface PrcPriceSetMapper
 {
    public PrcPriceSet selectPrcPriceSetById(Long priceSetId);

-    /** Header only (no product/customer count subqueries). */
+    /** 仅表头（不含产品/客户计数子查询）。 */
    public PrcPriceSet selectPrcPriceSetHeaderById(Long priceSetId);

    public List<PrcPriceSet> selectPrcPriceSetList(PrcPriceSet set);
@@ -21,7 +21,7 @@ public interface PrcPriceSetMapper

    public int updatePrcPriceSet(PrcPriceSet set);

-    /** Update name / note only (does not touch set_type / discount / status). */
+    /** 仅更新名称 / 备注（不修改 set_type / discount / status）。 */
    public int updateBasicInfo(PrcPriceSet set);

    public int updatePrcPriceSetStatus(PrcPriceSet set);
@@ -23,16 +23,16 @@ public interface PrcPriceSetProductMapper

    public int deleteByPsvIdAndCode(@Param("psvId") Long psvId, @Param("productCode") String productCode);

-    /** Hard delete one product under a version (draft / pending). */
+    /** 物理删除某版本下的一个产品（草稿 / 待生效）。 */
    public int physicalDeleteByPsvIdAndCode(@Param("psvId") Long psvId, @Param("productCode") String productCode);

-    /** Hard delete all product rows under a version. */
+    /** 物理删除某版本下的全部产品行。 */
    public int physicalDeleteByPsvId(@Param("psvId") Long psvId);

-    /** Copy active PRODUCT catalog into this SALES version. */
+    /** 把生效的 PRODUCT 目录复制到该 SALES 版本。 */
    public int insertFromLibrary(@Param("psvId") Long psvId);

-    /** Preview: active PRODUCT catalog products. */
+    /** 预览：生效的 PRODUCT 目录产品。 */
    public List<PrcPriceSetProduct> selectFromLibrary();

    public int copyFromVersion(@Param("srcPsvId") Long srcPsvId, @Param("newPsvId") Long newPsvId);
@@ -41,9 +41,9 @@ public interface PrcPriceSetProductMapper

    public int updatePriceTypeByPsvId(@Param("psvId") Long psvId, @Param("priceType") String priceType);

-    /** Copy version effective_time and status onto catalog product rows. */
+    /** 把版本 effective_time 和状态复制到目录产品行。 */
    public int syncEffectByPriceType(@Param("priceType") String priceType);

-    /** Copy SALES version effect fields onto package product rows. */
+    /** 把 SALES 版本的生效字段复制到套餐产品行。 */
    public int syncEffectByPriceSetId(@Param("priceSetId") Long priceSetId);
 }
@@ -14,13 +14,13 @@ public interface PrcPriceSetVersionMapper

    public List<PrcPriceSetVersion> selectPrcPriceSetVersionList(PrcPriceSetVersion version);

-    /** Catalog versions (price_set_id null) with product/detail counts. */
+    /** 目录版本（price_set_id 为空）及产品/明细计数。 */
    public List<PrcPriceSetVersion> selectCatalogVersionList(PrcPriceSetVersion version);

-    /** Max seq for SALES by price_set_id */
+    /** 按 price_set_id 取 SALES 最大序号 */
    public Integer selectMaxVersionSeq(@Param("priceSetId") Long priceSetId);

-    /** Max seq for catalog type (price_set_id null) or SALES when priceSetId set */
+    /** 目录类型（price_set_id 为空）或传了 priceSetId 时的 SALES 最大序号 */
    public Integer selectMaxVersionSeqByType(@Param("priceType") String priceType,
        @Param("priceSetId") Long priceSetId);

@@ -30,7 +30,7 @@ public interface PrcPriceSetVersionMapper

    public int deletePrcPriceSetVersionByIds(Long[] psvIds);

-    /** Soft-delete catalog/sales version row (is_del=1). */
+    /** 逻辑删除目录/销售版本行（is_del=1）。 */
    public int softDeleteById(@Param("psvId") Long psvId, @Param("updateBy") String updateBy);

    public int deletePrcPriceSetVersionByPriceSetId(Long priceSetId);
@@ -38,14 +38,14 @@ public interface PrcPriceSetVersionMapper
    public List<Long> selectPriceSetIds();

    /**
-     * SALES version effective at asOf for a price set.
+     * 某价格套餐在 asOf 生效的 SALES 版本。
     */
    public PrcPriceSetVersion selectActiveByPriceSetAt(
        @Param("priceSetId") Long priceSetId,
        @Param("asOf") Date asOf);

    /**
-     * Catalog (PRODUCT/REDLINE) version effective at asOf.
+     * 在 asOf 生效的目录（PRODUCT/REDLINE）版本。
     */
    public PrcPriceSetVersion selectActiveByTypeAt(
        @Param("priceType") String priceType,
@@ -35,20 +35,20 @@ public interface PrcSurchargeRelMapper
        @Param("productIds") List<Long> productIds,
        @Param("priceType") String priceType);

-    /** Hard delete surcharge rows by detail ids (draft / pending). */
+    /** 按明细 ID 物理删除附加费行（草稿 / 待生效）。 */
    public int physicalDeleteByDetailIdsAndPriceType(
        @Param("detailIds") List<Long> detailIds,
        @Param("priceType") String priceType);

-    /** Hard delete surcharge rows by set-product ids (draft / pending). */
+    /** 按套餐产品 ID 物理删除附加费行（草稿 / 待生效）。 */
    public int physicalDeleteByProductIdsAndPriceType(
        @Param("productIds") List<Long> productIds,
        @Param("priceType") String priceType);

-    /** Hard delete surcharge rows linked to products/details under a version. */
+    /** 物理删除某版本下产品/明细关联的附加费行。 */
    public int physicalDeleteByPsvId(@Param("psvId") Long psvId);

-    /** Soft-delete surcharge rows linked to products/details under a version. */
+    /** 逻辑删除某版本下产品/明细关联的附加费行。 */
    public int softDeleteByPsvId(@Param("psvId") Long psvId);

    /** 附加费版本化编辑后，把产品关联从旧记录重指向新记录 */
@@ -28,7 +28,7 @@ public interface PrcZoneDetailMapper
    public int deletePrcZoneDetailByRegionId(Long regionId);

    /**
-     * Resolve zone by country ISO2 + postcode (exact first, then longest prefix).
+     * 按国家 ISO2 + 邮编解析分区（先精确匹配，再取最长前缀）。
     */
    public PrcZone selectZoneByCountryPostcode(
        @Param("countryCode") String countryCode,
@@ -41,7 +41,7 @@ public class BillingTaskMqConsumer
    @Autowired(required = false)
    private StringRedisTemplate stringRedisTemplate;

-    /** Local MQ mode: async event listener. */
+    /** 本地 MQ 模式：异步事件监听。 */
    @Async
    @EventListener
    public void onLocalEvent(BillingTaskMqEvent event)
@@ -58,8 +58,8 @@ public class BillingTaskMqConsumer
    }

    /**
-     * Redis MQ mode: pop a batch each tick and process concurrently.
-     * Previously only 1 message / schedule cycle — queue backlog grew while inserts were fast.
+     * Redis MQ 模式：每次调度弹出一批消息并发处理。
+     * 原先每个调度周期只处理 1 条消息 —— 写入较快时队列会积压。
     */
    @Scheduled(fixedDelayString = "${bms.billing.consumer-delay-ms:200}")
    public void pollRedisQueue()
@@ -8,17 +8,17 @@ import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "bms.elasticsearch")
 public class ElasticsearchProperties
 {
-    /** false = skip ES write/read */
+    /** false = 跳过 ES 读写 */
    private boolean enabled = true;

-    /** e.g. http://127.0.0.1:9200 */
+    /** 例如 http://127.0.0.1:9200 */
    private String uris = "http://127.0.0.1:9200";

    private String username;

    private String password;

-    /** index name */
+    /** 索引名称 */
    private String index = "bms_biz_log";

    public boolean isEnabled()
@@ -69,7 +69,7 @@ public class EsBillSearchStore implements IBillSearchStore
            doc.put("bizId", bizId.trim());
            doc.put("status", StringUtils.isEmpty(status) ? EsBizLogSupport.STATUS_SUCCESS : status.trim());
            doc.put("error", StringUtils.isEmpty(errorMessage) ? null : errorMessage);
-            // Index dynamic mapping is strict on a few fields; coerce before PUT.
+            // 索引动态映射对部分字段类型要求严格，PUT 前先做类型转换。
            doc.put("request", normalizeRequestForEs(parseOrRaw(requestJson)));
            doc.put("response", normalizeResponseForEs(parseOrRaw(responseJson)));
            String ts = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(now);
@@ -87,8 +87,8 @@ public class EsBillSearchStore implements IBillSearchStore
    }

    /**
-     * request.bizDate is mapped as date (ISO / epoch only); bill writes "yyyy-MM-dd HH:mm:ss".
-     * request.taskId is mapped as long; UUID strings must not stay under taskId.
+     * request.bizDate 映射为 date（仅支持 ISO / epoch）；计费写入的是 "yyyy-MM-dd HH:mm:ss"。
+     * request.taskId 映射为 long；UUID 字符串不能留在 taskId 下。
     */
    private Object normalizeRequestForEs(Object request)
    {
@@ -103,8 +103,8 @@ public class EsBillSearchStore implements IBillSearchStore
    }

    /**
-     * response.ok mapped as long; response.success as boolean; response.taskId as long.
-     * Local rebill DONE used UUID taskId + numeric success and was rejected by ES.
+     * response.ok 映射为 long；response.success 映射为 boolean；response.taskId 映射为 long。
+     * 本地重算完成消息曾使用 UUID taskId + 数字型 success，被 ES 拒绝。
     */
    private Object normalizeResponseForEs(Object response)
    {
@@ -135,7 +135,7 @@ public class EsBillSearchStore implements IBillSearchStore
            return;
        }
        String bizDate = ((String) raw).trim();
-        // "yyyy-MM-dd HH:mm:ss" -> ISO-local so ES date mapper accepts it.
+        // 将 "yyyy-MM-dd HH:mm:ss" 转为 ISO 本地时间，便于 ES 日期映射解析。
        if (bizDate.length() >= 19 && bizDate.charAt(10) == ' ')
        {
            obj.put("bizDate", bizDate.substring(0, 10) + "T" + bizDate.substring(11));
@@ -504,7 +504,7 @@ public class EsBillSearchStore implements IBillSearchStore
        filters.add(boolWrap);
    }

-    /** Match country code / name (exact or contains). */
+    /** 匹配国家编码 / 名称（精确或包含）。 */
    private void addCountryKeywordFilter(JSONArray filters, String countryKeyword)
    {
        if (StringUtils.isEmpty(countryKeyword))
@@ -603,7 +603,7 @@ public class EsBillSearchStore implements IBillSearchStore
        filters.add(wrap);
    }

-    /** Match write-time by minute prefix, e.g. 2026-11-05 13:27. */
+    /** 按分钟前缀匹配写入时间，例如 2026-11-05 13:27。 */
    private void addUpdateTimePrefixFilter(JSONArray filters, String updateTimePrefix)
    {
        if (StringUtils.isEmpty(updateTimePrefix))
@@ -631,7 +631,7 @@ public class EsBillSearchStore implements IBillSearchStore
        filters.add(wrap);
    }

-    /** Prefer numeric term; also accept keyword/string mapping of bizKeys.psvId. */
+    /** 优先使用数值 term，同时兼容 bizKeys.psvId 的 keyword/字符串映射。 */
    private void addPsvIdFilter(JSONArray filters, Long psvId)
    {
        if (psvId == null)
@@ -18,7 +18,7 @@ public final class EsBizLogSupport
    public static final String STATUS_SUCCESS = "SUCCESS";
    public static final String STATUS_FAIL = "FAIL";

-    /** Request attribute: fail already written to ES in this request. */
+    /** 请求属性：本次请求中的失败日志已写入 ES。 */
    public static final String ATTR_FAIL_LOGGED = "bms.es.fail.logged";

    private static final int ERROR_MAX = 2000;
@@ -95,7 +95,7 @@ public final class EsBizLogSupport
    }

    /**
-     * Billing ES bizId: prefer transferNo, then orderNo.
+     * 计费 ES bizId：优先取 transferNo，其次取 orderNo。
     */
    public static String billBizId(TmsPriceBillRequest request)
    {
@@ -138,8 +138,8 @@ public final class EsBizLogSupport
    }

    /**
-     * Common entry for quote/bill API failures (validation / JSON parse / business / unexpected).
-     * Dedups with {@link #ATTR_FAIL_LOGGED} so controller/service/advice can all call safely.
+     * 报价 / 计费 API 失败的公共入口（校验 / JSON 解析 / 业务 / 未预期异常）。
+     * 通过 {@link #ATTR_FAIL_LOGGED} 去重，使 controller/service/advice 均可安全调用。
     */
    public static void saveApiFail(IBillSearchStore store, HttpServletRequest httpRequest, Object boundTarget,
        Throwable e)
@@ -162,7 +162,7 @@ public final class EsBizLogSupport
        }
        Object payload = boundTarget != null ? boundTarget : rawBody;
        String bizId = resolveFailBizId(logType, boundTarget, rawBody);
-        // saveFail also marks ATTR_FAIL_LOGGED
+        // saveFail 内部也会标记 ATTR_FAIL_LOGGED
        saveFail(store, logType, bizId, payload, errorMessage);
        if (!isFailLogged(httpRequest))
        {
@@ -8,20 +8,20 @@ public final class EsLogType
 {
    public static final String BILL = "BILL";
    public static final String QUOTE = "QUOTE";
-    /** Order credit occupy/release */
+    /** 订单额度占用/释放 */
    public static final String CREDIT = "CREDIT";
-    /** Clear order credit arrears after balance in */
+    /** 充值到账后清除订单额度欠款 */
    public static final String ARREARS = "ARREARS";
-    /** Monitor: sync billing from TAB_ORDER */
+    /** 监控：从 TAB_ORDER 同步计费 */
    public static final String ORDER_SOURCE_SYNC = "ORDER_SOURCE_SYNC";
-    /** Monitor: sales / product / redline price before-after changes */
+    /** 监控：销售价 / 产品价 / 红线价的变更前后记录 */
    public static final String PRICE_CHANGE = "PRICE_CHANGE";

    private EsLogType()
    {
    }

-    /** One document per bizId + write time. */
+    /** 每个 bizId + 写入时间对应一条文档。 */
    public static String docId(String logType, String bizId)
    {
        return docId(logType, bizId, new Date());
@@ -19,7 +19,7 @@ public interface IBillSearchStore
    BillSearchPage search(String logType, String bizId, String status, int pageNum, int pageSize);

    /**
-     * Search with optional sales-version / priceKind filters (request.bizKeys.psvId, request.priceKind).
+     * 支持可选的销售版本 / 价格类型过滤查询（request.bizKeys.psvId、request.priceKind）。
     */
    default BillSearchPage search(String logType, String bizId, String status, Long psvId, String priceKind,
        int pageNum, int pageSize)
@@ -28,7 +28,7 @@ public interface IBillSearchStore
    }

    /**
-     * Search with optional productCode + updateTime (exact) / updateTimePrefix (e.g. yyyy-MM-dd HH:mm) filters.
+     * 支持可选的 productCode + updateTime（精确）/ updateTimePrefix（例如 yyyy-MM-dd HH:mm）过滤查询。
     */
    default BillSearchPage search(String logType, String bizId, String status, Long psvId, String priceKind,
        String productCode, String updateTime, int pageNum, int pageSize)
@@ -44,7 +44,7 @@ public interface IBillSearchStore
    }

    /**
-     * Search with optional countryKeyword (matches bizKeys.countryCode / countryName).
+     * 支持可选的 countryKeyword 过滤查询（匹配 bizKeys.countryCode / countryName）。
     */
    default BillSearchPage search(String logType, String bizId, String status, Long psvId, String priceKind,
        String productCode, String updateTime, String updateTimePrefix, String countryKeyword,
@@ -54,7 +54,7 @@ public interface IBillSearchStore
    }

    /**
-     * Group PRICE_CHANGE logs by productCode + updateTime for one package version.
+     * 按产品编码 + 更新时间对某一套餐版本下的 PRICE_CHANGE 日志分组。
     */
    default PriceChangeGroupPage searchPriceChangeGroups(Long psvId, String priceKind, String status,
        int pageNum, int pageSize)
@@ -25,7 +25,7 @@ public final class PriceChangeEsLog
    public static final String ACTION_DELETE = "DELETE";
    public static final String ACTION_IMPORT = "IMPORT";

-    /** Async import workers have no SecurityContext; pass operName via this override. */
+    /** 异步导入线程没有 SecurityContext，通过该覆盖值传入操作人名称。 */
    private static final ThreadLocal<String> OPERATOR_OVERRIDE = new ThreadLocal<String>();

    private PriceChangeEsLog()
@@ -106,7 +106,7 @@ public final class PriceChangeEsLog
        changes.add(change(field, fieldLabel, oldValue, newValue));
    }

-    /** Sales detail price fields (freight / registration / discount). */
+    /** 销售明细价格字段（运费 / 挂号费 / 折扣）。 */
    public static List<Map<String, String>> diffSalesDetail(PrcPriceSetDetail oldRow, PrcPriceSetDetail newRow)
    {
        List<Map<String, String>> changes = new ArrayList<Map<String, String>>();
@@ -159,7 +159,7 @@ public final class PriceChangeEsLog
        return keys;
    }

-    /** Display weight band for sales detail logs (e.g. 0&lt;W≤0.5). */
+    /** 销售明细日志展示用的重量段（例如 0&lt;W≤0.5）。 */
    public static String weightBandOf(PrcPriceSetDetail d)
    {
        if (d == null)
@@ -1,7 +1,7 @@
 package com.bms.price.search;

 /**
- * Price-change log group key: productCode + write time.
+ * 价格变更日志分组键：productCode + 写入时间。
 */
 public class PriceChangeGroup
 {
@@ -3,7 +3,7 @@ package com.bms.price.search;
 import java.util.ArrayList;
 import java.util.List;

-/** Paginated product+time groups of price-change logs. */
+/** 价格变更日志按产品 + 时间分组的查询结果。 */
 public class PriceChangeGroupPage
 {
    private long total;
@@ -43,7 +43,7 @@ public final class TabOrderSyncEsLog
        store.save(EsLogType.ORDER_SOURCE_SYNC, bizId, reqJson, respJson, st, errorMessage);
    }

-    /** Persist one failed sync order so it appears in order-source operation log. */
+    /** 持久化一条同步失败的订单，使其出现在订单源操作日志中。 */
    public static void saveOneFail(IBillSearchStore store, Object row, Object response, String errorMessage)
    {
        String transferNo = null;
@@ -19,7 +19,7 @@ public interface IBmsProductService

    public List<BmsProduct> selectBmsProductList(BmsProduct product);

-    /** Product dropdown options (no status refresh, no count subqueries). */
+    /** 产品下拉选项（不刷新状态，不做计数子查询）。 */
    public List<BmsProduct> selectBmsProductOptions(BmsProduct product);

    public int insertBmsProduct(BmsProduct product);
@@ -40,19 +40,19 @@ public interface IBmsProductService

    public String importCountryProductExcel(MultipartFile file, String countryCode, String operName, Date effectiveDate) throws Exception;

-    /** Submit async all-country import; returns taskId for polling getImportTask. */
+    /** 提交异步全国家导入；返回 taskId 用于轮询 getImportTask。 */
    public String submitImportProductExcelAsync(MultipartFile file, boolean updateSupport, String operName, Date effectiveDate) throws Exception;

-    /** Submit async single-country import; returns taskId for polling getImportTask. */
+    /** 提交异步单国家导入；返回 taskId 用于轮询 getImportTask。 */
    public String submitImportCountryProductExcelAsync(MultipartFile file, String countryCode, String operName, Date effectiveDate) throws Exception;

-    /** Poll Redis progress for product import task. */
+    /** 轮询产品导入任务的 Redis 进度。 */
    public BmsProductImportTask getImportTask(String taskId);

-    /** Sync import from bytes (used by async runner; taskId may be null). */
+    /** 从字节内容同步导入（供异步执行器使用；taskId 可以为空）。 */
    public String importProductExcel(byte[] bytes, String filename, boolean updateSupport, String operName, String taskId, Date effectiveDate) throws Exception;

-    /** Sync country import from bytes (used by async runner; taskId may be null). */
+    /** 从字节内容同步导入国家数据（供异步执行器使用；taskId 可以为空）。 */
    public String importCountryProductExcel(byte[] bytes, String filename, String countryCode, String operName, String taskId, Date effectiveDate) throws Exception;

    public java.util.Map<String, List<BmsProductCountry>> parseQuoteExcelByProduct(MultipartFile file) throws Exception;
@@ -62,41 +62,41 @@ public interface IBmsProductService
    public java.util.Map<String, List<BmsProductCountry>> parseCountryQuoteExcelByProduct(byte[] bytes, String filename,
        String countryCode) throws Exception;

-    /** Parse multi-country workbook; return product list only (no DB write). */
+    /** 解析多国家工作簿；只返回产品列表（不写数据库）。 */
    public java.util.Map<String, Object> previewImportCatalog(byte[] bytes, String filename) throws Exception;

-    /** Parse single-country workbook; return product list only (no DB write). */
+    /** 解析单国家工作簿；只返回产品列表（不写数据库）。 */
    public java.util.Map<String, Object> previewImportCountryCatalog(byte[] bytes, String filename, String countryCode)
        throws Exception;

-    /** Submit async multi-country parse-only preview; poll getImportTask for result. */
+    /** 提交异步多国家仅解析预览；轮询 getImportTask 获取结果。 */
    public String submitPreviewImportAsync(org.springframework.web.multipart.MultipartFile file) throws Exception;

-    /** One task parses up to 5 workbooks and merges by product code. */
+    /** 一个任务最多解析 5 个工作簿，并按产品编码合并。 */
    public String submitPreviewImportAsync(java.util.List<org.springframework.web.multipart.MultipartFile> files)
        throws Exception;

-    /** Submit async single-country parse-only preview; poll getImportTask for result. */
+    /** 提交异步单国家仅解析预览；轮询 getImportTask 获取结果。 */
    public String submitPreviewImportCountryAsync(org.springframework.web.multipart.MultipartFile file, String countryCode)
        throws Exception;

-    /** One task parses up to 5 single-country workbooks and merges by product code. */
+    /** 一个任务最多解析 5 个单国家工作簿，并按产品编码合并。 */
    public String submitPreviewImportCountryAsync(java.util.List<org.springframework.web.multipart.MultipartFile> files,
        String countryCode) throws Exception;

-    /** Later workbook overwrites the same product code. */
+    /** 后一个工作簿会覆盖相同产品编码的数据。 */
    public java.util.Map<String, Object> mergeCatalogPreview(java.util.Map<String, Object> base,
        java.util.Map<String, Object> incoming);

    /**
-     * Persist create-page preview into draft/pending version (no activate, no effectiveDate required).
-     * Replaces only countries present in detailsByProductCode for each product.
+     * 将新建页面的预览数据落库为草稿/待生效版本（不启用，也不需要 effectiveDate）。
+     * 对每个产品，只替换 detailsByProductCode 中出现的国家。
     */
    public int applyCatalogPreview(CatalogPreviewApplyRequest request);

-    /** One product in its own transaction, for parallel apply. */
+    /** 单个产品使用独立事务，便于并行应用。 */
    public int applyOneCatalogProduct(Long psvId, String code, BmsProduct meta, java.util.List<BmsProductCountry> details);

-    /** Returns taskId; poll import task. Products are saved on a worker pool. */
+    /** 返回 taskId；轮询导入任务。产品由 worker 线程池保存。 */
    public String submitApplyCatalogPreviewAsync(CatalogPreviewApplyRequest request);
 }
@@ -37,61 +37,61 @@ public interface IBmsRedlineProductService

    public String importCountryProductExcel(MultipartFile file, String countryCode, String operName, Date effectiveDate) throws Exception;

-    /** Submit async all-country import; returns taskId for polling getImportTask. */
+    /** 提交异步全国家导入；返回 taskId 用于轮询 getImportTask。 */
    public String submitImportProductExcelAsync(MultipartFile file, boolean updateSupport, String operName, Date effectiveDate) throws Exception;

-    /** Submit async single-country import; returns taskId for polling getImportTask. */
+    /** 提交异步单国家导入；返回 taskId 用于轮询 getImportTask。 */
    public String submitImportCountryProductExcelAsync(MultipartFile file, String countryCode, String operName, Date effectiveDate) throws Exception;

-    /** Poll Redis progress for product import task. */
+    /** 轮询产品导入任务的 Redis 进度。 */
    public BmsRedlineProductImportTask getImportTask(String taskId);

-    /** Sync import from bytes (used by async runner; taskId may be null). */
+    /** 从字节内容同步导入（供异步执行器使用；taskId 可以为空）。 */
    public String importProductExcel(byte[] bytes, String filename, boolean updateSupport, String operName, String taskId, Date effectiveDate) throws Exception;

-    /** Sync country import from bytes (used by async runner; taskId may be null). */
+    /** 从字节内容同步导入国家数据（供异步执行器使用；taskId 可以为空）。 */
    public String importCountryProductExcel(byte[] bytes, String filename, String countryCode, String operName, String taskId, Date effectiveDate) throws Exception;

    public java.util.Map<String, List<BmsRedlineProductCountry>> parseQuoteExcelByProduct(MultipartFile file) throws Exception;

    public java.util.Map<String, List<BmsRedlineProductCountry>> parseQuoteExcelByProduct(byte[] bytes, String filename) throws Exception;

-    /** Parse multi-country workbook; return product list only (no DB write). */
+    /** 解析多国家工作簿；只返回产品列表（不写数据库）。 */
    public java.util.Map<String, Object> previewImportCatalog(byte[] bytes, String filename) throws Exception;

-    /** Parse single-country workbook; return product list only (no DB write). */
+    /** 解析单国家工作簿；只返回产品列表（不写数据库）。 */
    public java.util.Map<String, Object> previewImportCountryCatalog(byte[] bytes, String filename, String countryCode)
        throws Exception;

-    /** Submit async multi-country parse-only preview; poll getImportTask for result. */
+    /** 提交异步多国家仅解析预览；轮询 getImportTask 获取结果。 */
    public String submitPreviewImportAsync(org.springframework.web.multipart.MultipartFile file) throws Exception;

-    /** One task parses up to 5 workbooks and merges by product code. */
+    /** 一个任务最多解析 5 个工作簿，并按产品编码合并。 */
    public String submitPreviewImportAsync(java.util.List<org.springframework.web.multipart.MultipartFile> files)
        throws Exception;

-    /** Submit async single-country parse-only preview; poll getImportTask for result. */
+    /** 提交异步单国家仅解析预览；轮询 getImportTask 获取结果。 */
    public String submitPreviewImportCountryAsync(org.springframework.web.multipart.MultipartFile file, String countryCode)
        throws Exception;

-    /** One task parses up to 5 single-country workbooks and merges by product code. */
+    /** 一个任务最多解析 5 个单国家工作簿，并按产品编码合并。 */
    public String submitPreviewImportCountryAsync(java.util.List<org.springframework.web.multipart.MultipartFile> files,
        String countryCode) throws Exception;

-    /** Later workbook overwrites the same product code. */
+    /** 后一个工作簿会覆盖相同产品编码的数据。 */
    public java.util.Map<String, Object> mergeCatalogPreview(java.util.Map<String, Object> base,
        java.util.Map<String, Object> incoming);

    /**
-     * Persist create-page preview into draft/pending version (no activate, no effectiveDate required).
-     * Replaces only countries present in detailsByProductCode for each product.
+     * 将新建页面的预览数据落库为草稿/待生效版本（不启用，也不需要 effectiveDate）。
+     * 对每个产品，只替换 detailsByProductCode 中出现的国家。
     */
    public int applyCatalogPreview(RedlineCatalogPreviewApplyRequest request);

-    /** One product in its own transaction, for parallel apply. */
+    /** 单个产品使用独立事务，便于并行应用。 */
    public int applyOneCatalogProduct(Long psvId, String code, BmsRedlineProduct meta,
        java.util.List<BmsRedlineProductCountry> details);

-    /** Returns taskId; poll import task. Products are saved on a worker pool. */
+    /** 返回 taskId；轮询导入任务。产品由 worker 线程池保存。 */
    public String submitApplyCatalogPreviewAsync(RedlineCatalogPreviewApplyRequest request);
 }
@@ -9,37 +9,37 @@ import com.bms.price.domain.vo.BillingTaskSubmitRequest;

 public interface IPrcBillingTaskService
 {
-    /** Warehouse inbound: create task + publish MQ. */
+    /** 仓库入库：创建任务并发送 MQ。 */
    PrcBillingTask submitInbound(BillingTaskSubmitRequest request);

-    /** Monitor sync: create task then process immediately (no extra MQ). */
+    /** 监控同步：创建任务后立即处理（不再发额外 MQ）。 */
    PrcBillingTask submitAndProcess(BillingTaskSubmitRequest request);

    /**
-     * Monitor sync with upstream Oracle full row already fetched by order list:
-     * billing maps the row directly, skipping per-order Oracle public-network queries.
+     * 监控同步，且上游 Oracle 整行数据已由订单列表取回：
+     * 计费直接映射该行，跳过逐单的 Oracle 公网查询。
     */
    PrcBillingTask submitAndProcess(BillingTaskSubmitRequest request, Map<String, Object> upstreamRow);

-    /** MQ consumer entry: Oracle query -> bill -> writeback success status. */
+    /** MQ 消费入口：查询 Oracle -> 计费 -> 回写成功状态。 */
    void processTask(Long taskId);

    PrcBillingTask getById(Long taskId);

-    /** Admin list (failed / waiting / filter). */
+    /** 后台列表（失败 / 等待 / 按条件筛选）。 */
    List<PrcBillingTask> selectList(PrcBillingTask query);

    /**
-     * Manual resync: reset to WAITING then process again (including SUCCESS for correction).
-     * @return task after retry
+     * 手工重新同步：重置为 WAITING 后重新处理（包括已 SUCCESS 的用于更正）。
+     * @return 重试后的任务
     */
    PrcBillingTask retryTask(Long taskId);

    /**
-     * Start async filter retry (customer + bill_time). Returns async task id for progress poll.
+     * 启动异步按条件重试（客户 + bill_time）。返回异步任务 ID 用于进度轮询。
     */
    String startRetryByFilter(BillingTaskRetryByFilterRequest request);

-    /** Poll async filter-retry progress. */
+    /** 轮询异步按条件重试的进度。 */
    PrcBillingTaskRetryTask getRetryByFilterTask(String asyncTaskId);
 }
@@ -26,18 +26,18 @@ public interface IPrcOrderBillService
    TmsPriceQuoteResult bill(TmsPriceBillRequest request);

    /**
-     * Order-source sync only: overwrite local {@code prc_order_bill} + {@code prc_order_bill_ext}
-     * from an Oracle TAB_ORDER row. No quote / credit / fee / refund / AR validation.
-     * Rebilling remains on the order-list local-rebill path.
+     * 仅用于订单来源同步：用 Oracle TAB_ORDER 的一行数据覆盖本地 {@code prc_order_bill} 和 {@code prc_order_bill_ext}。
+     * 不做报价 / 授信 / 费用 / 退费 / 应收校验。
+     * 重新计费仍走订单列表的本地重算路径。
     *
-     * @param upstreamRow Oracle TAB_ORDER full row
+     * @param upstreamRow Oracle TAB_ORDER 整行数据
     * @return billId
     */
    String syncUpstreamOverwrite(java.util.Map<String, Object> upstreamRow);

    /**
-     * Persist prc_order_bill and ext when billing cannot produce a quote.
-     * Status outside 0/1/2/3 does not write prc_income_bill.
+     * 计费无法生成报价时，仍然落库 prc_order_bill 及其扩展表。
+     * 状态不在 0/1/2/3 范围内时不写入 prc_income_bill。
     */
    void persistFailedSnapshot(TmsPriceBillRequest request, int billingFailStatus, String errorMessage);

@@ -61,27 +61,27 @@ public interface IPrcOrderBillService

    TmsPriceQuoteResult getBill(String billId);

-    /** Billing fail reason for order-list popup (data-scoped). */
+    /** 订单列表弹窗使用的计费失败原因（带数据权限）。 */
    OrderBillFailReasonVo getBillingFailReason(String billId);

    TmsPriceQuoteResult getBillByOrderNo(String orderNo);

-    /** Manual add income fee from surcharge config; refresh receivable totals. */
+    /** 按附加费配置手工添加收入费用；同时刷新应收合计。 */
    TmsPriceQuoteResult addIncomeFee(AddIncomeBillFeeRequest request);

-    /** Update manual UNBILLED income fee; refresh receivable totals. */
+    /** 修改手工录入的 UNBILLED 收入费用；同时刷新应收合计。 */
    TmsPriceQuoteResult updateIncomeFee(UpdateIncomeBillFeeRequest request);

-    /** Delete manual UNBILLED income fee; refresh receivable totals. */
+    /** 删除手工录入的 UNBILLED 收入费用；同时刷新应收合计。 */
    TmsPriceQuoteResult deleteIncomeFee(String feeId);

-    /** Preview matched bills for batch add fee (data-scoped). */
+    /** 预览批量添加费用命中的账单（带数据权限）。 */
    BatchAddIncomeBillFeePreview previewBatchAddIncomeFee(BatchAddIncomeBillFeeRequest request);

-    /** Submit async batch add fee; returns taskId. */
+    /** 提交异步批量添加费用；返回 taskId。 */
    String submitBatchAddIncomeFee(BatchAddIncomeBillFeeRequest request);

-    /** Poll Redis progress for batch add fee task. */
+    /** 轮询批量添加费用任务的 Redis 进度。 */
    BatchAddIncomeBillFeeTask getBatchAddIncomeFeeTask(String taskId);

    /** 提供给 TMS 判断订单是否可以继续处理的客户状态查询。 */
@@ -106,90 +106,90 @@ public interface IPrcOrderBillService
    TmsPriceQuoteResult updateCreditArrearsStatus(String billId);

    /**
-     * Update charge_weight (manual override), keep weight, and rebill.
-     * Applies data-scope check.
+     * 更新 charge_weight（手工覆盖），保留原重量，并重新计费。
+     * 会做数据权限校验。
     *
-     * @param billId bill id
-     * @param chargeWeight new charge weight (kg)
+     * @param billId 账单 ID
+     * @param chargeWeight 新的计费重量（kg）
     */
    TmsPriceQuoteResult updateChargeWeight(String billId, BigDecimal chargeWeight);

    /**
-     * Update charge_weight without data-scope check (pre-validated async import).
+     * 更新 charge_weight，不做数据权限校验（供已校验的异步导入使用）。
     */
    TmsPriceQuoteResult updateChargeWeightByBillId(String billId, BigDecimal chargeWeight);

    /**
-     * Submit async import of charge_weight updates; returns taskId.
+     * 提交 charge_weight 更新的异步导入；返回 taskId。
     *
-     * @param rows excel rows
+     * @param rows Excel 行数据
     * @return taskId
     */
    String submitImportChargeWeight(List<ChargeWeightImportRow> rows);

-    /** Poll Redis progress for charge-weight import task. */
+    /** 轮询计费重量导入任务的 Redis 进度。 */
    ChargeWeightImportTask getChargeWeightImportTask(String taskId);

    /**
-     * Build import-template rows. Empty when fillByFilter=false;
-     * otherwise fill orderNo/customer from list filters (data-scoped).
+     * 构建导入模板行。fillByFilter=false 时返回空；
+     * 否则按列表筛选条件填入 orderNo/customer（带数据权限）。
     */
    List<ChargeWeightImportRow> buildChargeWeightTemplateRows(ChargeWeightTemplateRequest request);

    /**
-     * Submit async recalc of product_amount or redline_amount (request.mode).
-     * Existing bills only; no AR restriction; sales amounts untouched.
+     * 提交 product_amount 或 redline_amount 的异步重算（由 request.mode 决定）。
+     * 仅处理已有账单；不受应收限制；不修改销售金额。
     *
     * @return taskId
     */
    String submitRecalcBillPrice(RecalcBillPriceRequest request);

-    /** Poll Redis progress for product/redline recalc task. */
+    /** 轮询产品价/红线价重算任务的 Redis 进度。 */
    BatchAddIncomeBillFeeTask getRecalcBillPriceTask(String taskId);

    /**
-     * Recalc and persist product_amount or redline_amount by mode (PRODUCT/REDLINE).
-     * Requires existing prc_order_bill; skips AR editable guard.
+     * 按模式（PRODUCT/REDLINE）重算并落库 product_amount 或 redline_amount。
+     * 要求 prc_order_bill 已存在；跳过应收可编辑校验。
     */
    void recalcBillPriceByBillId(String billId, String mode);

    /**
-     * Full rebill from local prc_order_bill only (no Oracle upstream).
-     * Refund-like local status (order_status 9/10 or refund_status=REFUNDED):
-     * skip when prc_income_bill_fee already has fee_type=REFUND; otherwise {@link #refund}.
-     * Else rebuilds request from the bill row then {@link #bill}.
+     * 仅基于本地 prc_order_bill 做完整重算（不调 Oracle 上游）。
+     * 本地状态类似退费（order_status 9/10 或 refund_status=REFUNDED）时：
+     * 若 prc_income_bill_fee 已有 fee_type=REFUND 则跳过，否则走 {@link #refund}。
+     * 其余情况用账单行重建请求后走 {@link #bill}。
     */
    TmsPriceQuoteResult rebillLocalByBillId(String billId);

    /**
-     * Async local rebill by selected billIds or list filters. Returns taskId for progress poll.
-     * Large sets: only bill_id loaded, then processed by continuous parallel workers.
+     * 按选中的 billId 或列表筛选条件做异步本地重算。返回 taskId 用于进度轮询。
+     * 数据量大时只加载 bill_id，再由持续的并行 worker 处理。
     */
    String submitLocalRebill(LocalRebillRequest request);

-    /** Poll Redis progress for local rebill task. */
+    /** 轮询本地重算任务的 Redis 进度。 */
    BatchAddIncomeBillFeeTask getLocalRebillTask(String taskId);

-    /** Cooperative cancel for a running local rebill task. */
+    /** 协作取消正在运行的本地重算任务。 */
    BatchAddIncomeBillFeeTask cancelLocalRebill(String taskId);

-    /** Data-scoped bill_id list for local rebill (same filters as order-bill list). */
+    /** 本地重算用的带数据权限的 bill_id 列表（筛选条件与订单账单列表一致）。 */
    List<String> selectBillIdsForLocalRebill(PrcOrderBill query);

-    /** Data-scoped count for local rebill. */
+    /** 本地重算的带数据权限的数量统计。 */
    int countBillIdsForLocalRebill(PrcOrderBill query);

    /**
-     * Submit async Excel export for order list or billing list.
-     * Requires at least one meaningful filter; returns taskId for poll/download.
+     * 提交订单列表或计费列表的异步 Excel 导出。
+     * 至少需要一个有效筛选条件；返回 taskId 用于轮询/下载。
     *
-     * @param exportType {@link PrcOrderBillExportTask#TYPE_ORDER} or {@link PrcOrderBillExportTask#TYPE_BILLING}
+     * @param exportType {@link PrcOrderBillExportTask#TYPE_ORDER} 或 {@link PrcOrderBillExportTask#TYPE_BILLING}
     */
    String submitOrderBillExport(String exportType, PrcOrderBill query);

-    /** Poll Redis progress for order/billing list export task. */
+    /** 轮询订单/计费列表导出任务的 Redis 进度。 */
    PrcOrderBillExportTask getOrderBillExportTask(String taskId);

-    /** Stream SUCCESS export file to response by taskId. */
+    /** 按 taskId 将 SUCCESS 状态的导出文件流式写入响应。 */
    void downloadOrderBillExport(String taskId, HttpServletResponse response) throws Exception;
 }
@@ -11,19 +11,19 @@ public interface IPrcPriceExcelFileService
 {
    public PrcPriceExcelFile selectPrcPriceExcelFileById(Long pefId);

-    /** Excel files bound to a price version */
+    /** 绑定到价格版本的 Excel 文件 */
    List<PrcPriceExcelFile> selectByPsvId(Long psvId);

    /**
-     * Persist uploaded Excel under upload/price/excel and insert metadata row.
+     * 将上传的 Excel 保存到 upload/price/excel，并写入元数据记录。
     *
     * @param excelType PRODUCT / REDLINE / SALES
-     * @param psvId version id (nullable for draft preview; bind later)
-     * @return inserted row with pefId
+     * @param psvId 版本 ID（草稿预览时可为空，之后再绑定）
+     * @return 包含 pefId 的新增记录
     */
    public PrcPriceExcelFile saveImportExcel(String excelType, Date effectiveTime, byte[] bytes,
        String filename, String operName, Long psvId) throws Exception;

-    /** Bind an existing attachment row to a version */
+    /** 将已有的附件记录绑定到指定版本 */
    public int bindPsvId(Long pefId, Long psvId);
 }
@@ -22,14 +22,14 @@ public interface IPrcPriceSetService

    public List<PrcPriceSet> selectPrcPriceSetList(PrcPriceSet set);

-    /** Fail if the package is not in the expected category (PACKAGE / EXCLUSIVE). */
+    /** 套餐不属于预期类别（PACKAGE / EXCLUSIVE）时抛出失败。 */
    public void assertSetCategory(Long priceSetId, String expectedCategory);

    public Long savePrcPriceSet(PrcPriceSet set);

    public int updatePrcPriceSet(PrcPriceSet set);

-    /** Update package name and note only; allowed for effect / draft / stopped. */
+    /** 只更新套餐名称和备注；生效 / 草稿 / 已停用状态均可操作。 */
    public int updateBasicInfo(PrcPriceSet set);

    public int deletePrcPriceSetByIds(Long[] priceSetIds);
@@ -42,29 +42,29 @@ public interface IPrcPriceSetService

    public int disable(Long priceSetId, String updateBy);

-    /** Re-enable a stopped package (S -> E). */
+    /** 重新启用已停用的套餐（S -> E）。 */
    public int enable(Long priceSetId, String updateBy);

    /**
-     * Activate a draft or reschedule a pending version with user-specified effectiveTime.
-     * effectiveTime &lt;= now -&gt; EFFECT; future -&gt; PENDING(3). Then refresh 0/3/1/2.
+     * 按用户指定的 effectiveTime 启用草稿版本，或重排待生效版本。
+     * effectiveTime &lt;= now -&gt; EFFECT；未来时间 -&gt; PENDING(3)。随后刷新 0/3/1/2。
     */
    public int activateVersion(Long psvId, Date effectiveTime, String updateBy);

    /**
-     * Copy source version into a new draft version under the same package:
-     * insert prc_price_set_version + copy prc_price_set_detail (+ surcharge snapshots).
-     * @return new psvId
+     * 将源版本复制为同一套餐下的新草稿版本：
+     * 插入 prc_price_set_version 并复制 prc_price_set_detail（含附加费快照）。
+     * @return 新的 psvId
     */
    public Long copyVersion(Long sourcePsvId, String createBy);

    /**
-     * Create an empty draft version under the package (no detail copy).
-     * @return new psvId
+     * 在套餐下创建空草稿版本（不复制明细）。
+     * @return 新的 psvId
     */
    public Long createVersion(Long priceSetId, String createBy);

-    /** Delete a draft version and its details / surcharge snapshots */
+    /** 删除草稿版本及其明细 / 附加费快照 */
    public int deleteVersion(Long psvId, String updateBy);

    public Long copy(Long priceSetId, String createBy);
@@ -74,12 +74,12 @@ public interface IPrcPriceSetService
    public List<PrcPriceSetDetail> selectDetailList(PrcPriceSetDetail detail);

    /**
-     * Load all detail rows for one product under a version (no pagination).
+     * 查询某版本下单个产品的全部明细行（不分页）。
     */
    public List<PrcPriceSetDetail> selectDetailListByProduct(Long psvId, String productCode);

    /**
-     * Load all detail rows for a version (no pagination). For batch prefetch vs N byProduct calls.
+     * 查询某版本的全部明细行（不分页）。用于批量预取，替代 N 次按产品查询。
     */
    public List<PrcPriceSetDetail> selectDetailListByVersion(Long psvId);

@@ -99,109 +99,109 @@ public interface IPrcPriceSetService

    public int insertCustomer(PrcCustomerPriceSet customer);

-    /** Batch bind customers to a price set; returns summary message. */
+    /** 批量将客户绑定到价格套餐；返回汇总提示信息。 */
    public String batchInsertCustomers(PrcCustomerPriceSetBatch batch);

    public int updateCustomer(PrcCustomerPriceSet customer);

    public int deleteCustomerByIds(Long[] customerPricesetIds);

-    /** chain expire_time = next version effective_time, then refresh 0/3/1/2 */
+    /** 串联 expire_time = 下一版本的 effective_time，然后刷新 0/3/1/2 */
    public int refreshAllVersionStatus();

-    /** submit async save, return taskId immediately */
+    /** 提交异步保存，立即返回 taskId */
    public String submitSaveAsync(PrcPriceSet set);

    /**
-     * Submit async batch write of detail surcharge snapshots (product-level pick can hit many rows).
-     * @return taskId for polling getSaveTask
+     * 提交明细附加费快照的异步批量写入（按产品选择可能命中大量行）。
+     * @return taskId 用于轮询 getSaveTask
     */
    public String submitDetailSurchargeAsync(List<PrcPriceSetDetail> details);

-    /** Sync batch update of detail surcharge snapshots */
+    /** 同步批量更新明细附加费快照 */
    public int batchUpdateDetailSurcharges(List<PrcPriceSetDetail> details);

-    /** poll async save progress */
+    /** 轮询异步保存进度 */
    public PrcPriceSetSaveTask getSaveTask(String taskId);

    /**
-     * Submit async import of Weishi B2C quote Excel into FIXED package detail prices.
-     * @return taskId for polling getSaveTask
+     * 提交 Weishi B2C 报价 Excel 的异步导入，写入 FIXED 套餐明细价格。
+     * @return taskId 用于轮询 getSaveTask
     */
    public String submitImportDetailPricesAsync(Long priceSetId, Long psvId, MultipartFile file, String operName) throws Exception;

    /**
-     * @param updateOnly true = only update matched existing details (no insert / no new product)
+     * @param updateOnly true = 只更新匹配到的已有明细（不新增 / 不新增产品）
     */
    public String submitImportDetailPricesAsync(Long priceSetId, Long psvId, MultipartFile file, String operName,
        boolean updateOnly) throws Exception;

    /**
-     * @param replaceByProductCountry true = Excel build-price mode: replace only product+country scopes in this file
-     * @param countryCode optional; when set, parse single-country dedicated-line Excel (product country-import format)
+     * @param replaceByProductCountry true = Excel 建价模式：只替换本文件中的 产品+国家 范围
+     * @param countryCode 可选；有值时解析单国家专线 Excel（产品国家导入格式）
     */
    public String submitImportDetailPricesAsync(Long priceSetId, Long psvId, MultipartFile file, String operName,
        boolean updateOnly, boolean replaceByProductCountry, String countryCode) throws Exception;

-    /** One task imports up to 5 workbooks in order. */
+    /** 一个任务按顺序最多导入 5 个工作簿。 */
    public String submitImportDetailPricesAsync(Long priceSetId, Long psvId, List<MultipartFile> files, String operName,
        boolean updateOnly, boolean replaceByProductCountry, String countryCode) throws Exception;

-    /** Parse up to 5 workbooks in one call. Later file wins on the same product+country scope. */
+    /** 一次解析最多 5 个工作簿。相同 产品+国家 范围以后一个文件为准。 */
    public Map<String, Object> previewImportDetailPricesMany(List<byte[]> bytesList, List<String> names,
        boolean updateOnly, List<PrcPriceSetDetail> existingDetails, boolean replaceByProductCountry, String countryCode)
        throws Exception;

    /**
-     * @param exclusiveTemplate true = HALARA large-customer exclusive quote Excel (destination / handling fee)
+     * @param exclusiveTemplate true = HALARA 大客户专属报价 Excel（目的地 / 操作费）
     */
    public Map<String, Object> previewImportDetailPricesMany(List<byte[]> bytesList, List<String> names,
        boolean updateOnly, List<PrcPriceSetDetail> existingDetails, boolean replaceByProductCountry, String countryCode,
        boolean exclusiveTemplate) throws Exception;

    /**
-     * Sync worker: parse bytes and upsert FIXED detail prices matched by
-     * product + country + zone(if any) + weight band (insert when missing unless updateOnly).
+     * 同步 worker：解析字节内容，并按 产品 + 国家 + 分区（如有）+ 重量段
+     * 匹配后 upsert FIXED 明细价格（缺失时插入，updateOnly 时不插入）。
     */
    public String importDetailPrices(Long priceSetId, Long psvId, byte[] bytes, String filename, String operName) throws Exception;

-    /** Sync worker with optional taskId for progress reporting. */
+    /** 同步 worker，可选传入 taskId 用于上报进度。 */
    public String importDetailPrices(Long priceSetId, Long psvId, byte[] bytes, String filename, String operName, String taskId) throws Exception;

    public String importDetailPrices(Long priceSetId, Long psvId, byte[] bytes, String filename, String operName,
        String taskId, boolean updateOnly) throws Exception;

    /**
-     * @param replaceByProductCountry package Excel build-price only; other import modes pass false
-     * @param countryCode optional single-country dedicated-line import
+     * @param replaceByProductCountry 仅套餐 Excel 建价使用；其他导入模式传 false
+     * @param countryCode 可选，单国家专线导入
     */
    public String importDetailPrices(Long priceSetId, Long psvId, byte[] bytes, String filename, String operName,
        String taskId, boolean updateOnly, boolean replaceByProductCountry, String countryCode) throws Exception;

    /**
-     * Submit async pull of product library into version details.
-     * @return taskId for polling getSaveTask
+     * 提交将产品库异步拉取到版本明细。
+     * @return taskId 用于轮询 getSaveTask
     */
    public String submitPullFromLibraryAsync(Long priceSetId, Long psvId, boolean force, String operName);

-    /** Sync worker: replace (or skip) version details from product / product_country. */
+    /** 同步 worker：从 product / product_country 替换（或跳过）版本明细。 */
    public String pullFromLibrary(Long priceSetId, Long psvId, boolean force, String operName, String taskId);

    /**
-     * Preview pull: return products + FIXED details from library without writing DB.
+     * 预览拉取：从产品库返回产品 + FIXED 明细，不写数据库。
     */
    public Map<String, Object> previewPullFromLibrary();

    /**
-     * Preview import: parse Excel into products + details without writing DB.
-     * When updateOnly, merge prices into existingDetails (in-memory match).
+     * 预览导入：将 Excel 解析为产品 + 明细，不写数据库。
+     * updateOnly 时把价格合并进 existingDetails（内存中匹配）。
     */
    public Map<String, Object> previewImportDetailPrices(byte[] bytes, String filename, boolean updateOnly,
        List<PrcPriceSetDetail> existingDetails) throws Exception;

    /**
-     * @param replaceByProductCountry package Excel build-price only: keep other product/country rows
-     * @param countryCode optional single-country dedicated-line import
+     * @param replaceByProductCountry 仅套餐 Excel 建价使用：保留下其他 产品/国家 行
+     * @param countryCode 可选，单国家专线导入
     */
    public Map<String, Object> previewImportDetailPrices(byte[] bytes, String filename, boolean updateOnly,
        List<PrcPriceSetDetail> existingDetails, boolean replaceByProductCountry, String countryCode) throws Exception;
@@ -12,7 +12,7 @@ public interface IPrcZoneService

    public List<PrcZoneRegion> selectZoneRegionList(PrcZoneRegion query);

-    /** Delete all zones (and details) for the given region ids */
+    /** 删除指定区域 ID 下的所有分区（及其明细） */
    public int deleteZonesByRegionIds(Long[] regionIds);

    public PrcZone selectPrcZoneById(Long zoneId);
@@ -23,7 +23,7 @@ public interface ITmsPriceQuoteService
 {
    TmsPriceQuoteResult quote(TmsPriceQuoteRequest request);

-    /** Calc only, no prc_quote persist. Used by receivable billing. */
+    /** 仅计算，不落库 prc_quote。供应收计费使用。 */
    TmsPriceQuoteResult calculate(TmsPriceQuoteRequest request);

    List<PrcQuote> selectQuoteList(PrcQuote query);
@@ -31,16 +31,16 @@ public interface ITmsPriceQuoteService
    TmsPriceQuoteResult getQuote(String quoteId);

    /**
-     * Products under the customer's bound effective package version (for trial dropdown).
-     * @param customerCode required
-     * @param bizDate optional; default today (same as-of window as quote)
+     * 客户绑定的生效套餐版本下的产品（用于试算下拉）。
+     * @param customerCode 必填
+     * @param bizDate 可选；默认当天（与报价使用相同的时点窗口）
     */
    List<PrcPriceSetProduct> listBoundPackageProducts(String customerCode, Date bizDate);

    /**
-     * Union of products from all effective bound packages (for order-source product check).
-     * @param customerCode required
-     * @param bizDate optional; default today
+     * 所有生效绑定套餐下产品的并集（用于订单来源产品校验）。
+     * @param customerCode 必填
+     * @param bizDate 可选；默认当天
     */
    List<PrcPriceSetProduct> listAllBoundPackageProducts(String customerCode, Date bizDate);
 }
@@ -24,9 +24,9 @@ public class SysFileTemplate extends BaseEntity
    public static final String CODE_CHARGE_WEIGHT = "CHARGE_WEIGHT";

    private Long templateId;
-    /** Dict: sys_file_template_type */
+    /** 字典：sys_file_template_type */
    private String templateType;
-    /** Unique business code */
+    /** 唯一业务编码 */
    private String fileCode;
    private String templateName;
    private String fileName;
@@ -35,6 +35,6 @@ public class SysFileTemplate extends BaseEntity
    private Long fileSize;
    private String contentType;
    private String fileExtension;
-    /** 0 normal / 1 disable */
+    /** 0 正常 / 1 停用 */
    private String status;
 }
@@ -10,7 +10,7 @@ public interface BmsProductCodeMappingMapper

    BmsProductCodeMapping selectById(Long mapId);

-    /** Active mapping by upstream code (status=0, del_flag=0). */
+    /** 按上游编码取有效映射（status=0，del_flag=0）。 */
    BmsProductCodeMapping selectActiveByUpstreamCode(@Param("upstreamCode") String upstreamCode);

    int countByUpstreamCode(@Param("upstreamCode") String upstreamCode, @Param("excludeId") Long excludeId);
@@ -21,8 +21,8 @@ public interface IBmsBizRuleService
    int deleteByIds(Long[] ruleIds);

    /**
-     * Apply active weight rules (currently VOL_8000) to bill request.
-     * @return overridden charge weight when a rule matches; null when no rule applies
+     * 将生效的重量规则（目前为 VOL_8000）应用到计费请求。
+     * @return 规则命中时返回覆盖后的计费重量；无规则适用时返回 null
     */
    BigDecimal resolveWeightByRule(TmsPriceBillRequest request, BigDecimal systemWeight);
 }
@@ -16,9 +16,9 @@ public interface IBmsProductCodeMappingService
    int deleteByIds(Long[] mapIds);

    /**
-     * Resolve BMS product code from upstream code.
-     * Used after package product miss: returns mapped code when active mapping exists;
-     * otherwise returns original code.
+     * 根据上游编码解析 BMS 产品编码。
+     * 用于套餐产品未命中之后：存在生效映射时返回映射后的编码；
+     * 否则返回原编码。
     */
    String resolveBmsProductCode(String upstreamCode);
 }
@@ -19,9 +19,9 @@ public interface ISysFileTemplateService

    int deleteSysFileTemplateByIds(Long[] templateIds);

-    /** Upload / replace Excel file on OSS for an existing template row. */
+    /** 为已有模板记录上传 / 替换 OSS 上的 Excel 文件。 */
    SysFileTemplate uploadFile(Long templateId, MultipartFile file, String operName) throws Exception;

-    /** Download by file_code (enabled templates only). */
+    /** 按 file_code 下载（仅限已启用的模板）。 */
    void downloadByFileCode(String fileCode, HttpServletResponse response) throws Exception;
 }