update

ad-engine-service/src/main/java/com/tzld/piaoquan/ad/engine/service/score/strategy/RankStrategyBasic.java

@@ -344,30 +344,59 @@ public abstract class RankStrategyBasic implements RankStrategy {
         }
     }
 
+    /**
+     * 计算保量权重系数
+     *
+     * 保量逻辑说明：
+     * 1. 根据广告主的保量配置（保量比例、保量上限）和实际曝光情况计算权重
+     * 2. 权重用于调整广告排序分数，帮助未达到保量目标的广告主获得更多曝光
+     * 3. 已达到保量上限的广告主权重为0，避免过度曝光
+     *
+     * @param guaranteeView 保量视图对象，包含广告主保量相关数据
+     *                     - adrId: 广告主ID
+     *                     - adrAlgoViewNum: 广告主当天算法曝光数
+     *                     - allAlgoViewNum: 全平台当天算法曝光数
+     *                     - guaranteeNum: 保量上限（广告主最大允许曝光数）
+     *                     - guaranteeRate: 保量比例（广告主期望占全平台曝光的百分比）
+     * @return 保量权重系数，范围[0.0, 2.0]，默认1.0
+     */
     protected double calculateGuaranteedWeight(GuaranteeView guaranteeView) {
+        // 1. 空值检查：如果保量视图为空，返回默认权重
         if (guaranteeView == null) {
             return 1.0;
         }
+
         double guaranteeWeight;
+
+        // 2. 保量配置检查：如果保量上限或保量比例未配置，返回默认权重
         if (guaranteeView.getGuaranteeNum() == null || guaranteeView.getGuaranteeNum() == 0
                 || guaranteeView.getGuaranteeRate() == null || guaranteeView.getGuaranteeRate() == 0.0) {
             guaranteeWeight = 1.0;
         } else {
+            // 3. 保量达标检查：如果广告主曝光数已达到或超过保量上限，停止加权
             if (guaranteeView.getAdrAlgoViewNum() != null &&
                     guaranteeView.getGuaranteeNum() <= guaranteeView.getAdrAlgoViewNum()) {
+                // 已达到保量目标，权重设为0，避免过度曝光
                 guaranteeWeight = 0.0;
             } else {
+                // 4. 计算保量权重
+                // 防止除零错误：如果曝光数为空或0，设为1
                 int allViewNum = guaranteeView.getAllAlgoViewNum() == null || guaranteeView.getAllAlgoViewNum() == 0 ?
                         1 : guaranteeView.getAllAlgoViewNum();
                 int adrAlogViewNum = guaranteeView.getAdrAlgoViewNum() == null || guaranteeView.getAdrAlgoViewNum() == 0 ?
                         1 : guaranteeView.getAdrAlgoViewNum();
-                // guaranteeView.getGuaranteeRate() 是百分之几  要乘0.01
+
+                // 核心计算公式：权重 = 保量比例 × 0.01 × 全平台曝光数 / 广告主曝光数
+                // guaranteeView.getGuaranteeRate() 是百分之几，需要乘0.01转换为小数
+                // 逻辑：如果广告主当前曝光占比低于目标保量比例，给予更高权重提升排序
                 guaranteeWeight = guaranteeView.getGuaranteeRate() * 0.01 * allViewNum / adrAlogViewNum;
+
+                // 5. 权重边界限制：避免权重过小或过大影响系统稳定性
                 if (guaranteeWeight < 0.5) {
-                    guaranteeWeight = 0.5;
+                    guaranteeWeight = 0.5;  // 最小权重限制
                 }
                 if (guaranteeWeight > 2) {
-                    guaranteeWeight = 2;
+                    guaranteeWeight = 2;    // 最大权重限制
                 }
             }
         }