fix(fsgx): 直推积分奖励链路校验（问题2）

- 买家直推人非分销员时中断直推级差链，避免祖先越级拿 reward_direct
- 同步更新 fsgx-issues-0330 文档问题2用例说明

Made-with: Cursor

docs/fsgx-issues-0330-1.md

@@ -1,9 +1,19 @@
 # 测试问题
 
-## 分销员的**直推积分奖励**问题
+## 分销员的**直推积分奖励**问题1
 - **已检查**当前用户UID=30推荐UID=34推荐UID=31，现在UID=31购买的报单商品订单，
   检查UID=30创客是否有直推积分奖励，如果有是不对的，原因：UID=34，UID=30都是创客分销员，一个订单在同一个级别的分销员只能获得一次直推积分奖励，且是直推关系。
 
+## 分销员的**直推积分奖励**问题2
+- case1: 当前用户UID=2推荐UID=46推荐UID=47，现在UID=47购买的报单商品订单情况下（目前数据库中有订单和用户数据），验证如下：
+  检查UID=46是创客：
+    UID=2是否有直推积分奖励，如果没有是不对的，原因：UID=2分销等级>UID=46,是应该获得直推积分奖励的差额部分，使用**直推积分奖励**的递归计算方法，逐一查询上级的直推积分奖励**直到最高分销等级结束**；
+  检查UID=46还不是创客：
+    UID=2是否有直推积分奖励，如果有是不对的，原因：不是直推关系；
+- case2: 当前用户UID=46推荐UID=47推荐UID=48，现在UID=48购买的报单商品订单情况下（目前数据库中有订单和用户数据），验证如下：
+  检查UID=46应该没有直推积分奖励才对，因为UID=46不是UID=48的直接推荐人，
+- **直推积分奖励**落库的时候一定要检查直推关系。
+
 ## 新增**伞下积分奖励**开关功能
 - **已修复**新增伞下积分奖励开关功能，默认是关闭的
 
@@ -12,7 +22,7 @@
 
 ## 我的资产页面，pages/assets/index
 - **已修复**积分明细跳转路径修改为：pages/users/user_integral_detail/index
-- 顶部navbar改成和pages/users/user_spread_user/index页面一样的样式，同时美化页面其他部分的样式
+- **已修复**顶部navbar改成和pages/users/user_spread_user/index页面一样的样式，同时美化页面其他部分的样式
 
 ## 佣金状态页面，pages/queue/status
-- 顶部navbar改成和pages/users/user_spread_user/index页面一样的样式，同时美化页面其他部分的样式
+- **已修复**顶部navbar改成和pages/users/user_spread_user/index页面一样的样式，同时美化页面其他部分的样式

pro_v3.5.1/app/services/hjf/PointsRewardServices.php

@@ -82,6 +82,11 @@ class PointsRewardServices extends BaseServices
      *   max(0, 自身 direct_reward_points - 链中已见最高 direct_reward_points) * qty
      * 非分销员（grade=0）跳过但继续向上传递，$lowerDirectReward 不变。
      *
+     * 直推关系约束（$directCascadeActive）：
+     *   当买家直接推荐人（depth=0）不是分销员（grade=0）时，直推级差链终止，
+     *   其所有上级祖先不得获得 reward_direct（不存在直推关系）。
+     *   伞下奖励（reward_umbrella）不受此约束，仍按自身开关独立发放。
+     *
      * @param int    $uid                  当前被奖励用户
      * @param int    $fromUid              触发方（下级）用户 ID
      * @param string $orderId              来源订单号
@@ -90,6 +95,7 @@ class PointsRewardServices extends BaseServices
      * @param int    $orderDbId            订单表主键 id
      * @param array  $preUpgradeLevels     升级前各用户的 agent_level 快照 [uid => level_id]（B2）
      * @param int    $qty                  报单商品数量，积分按数量倍乘（B3）
+     * @param bool   $directCascadeActive  直推级差链是否仍然有效
      */
     private function propagateReward(
         int    $uid,
@@ -99,7 +105,8 @@ class PointsRewardServices extends BaseServices
         int    $depth = 0,
         int    $orderDbId = 0,
         array  $preUpgradeLevels = [],
-        int    $qty = 1
+        int    $qty = 1,
+        bool   $directCascadeActive = true
     ): void {
         if ($depth >= 10 || $uid <= 0) {
             return;
@@ -117,24 +124,21 @@ class PointsRewardServices extends BaseServices
         $grade = $this->agentLevelServices->getGradeByLevelId($agentLevelId);
 
         if ($grade === 0) {
-            // 非分销员：跳过奖励，但继续向上传递，$lowerDirectReward 保持不变
+            // 非分销员：跳过奖励，继续向上传递
+            // 若当前节点是买家的直接推荐人（depth=0），直推级差链从此中断：
+            // 上级祖先与买家之间没有直推关系，不应获得 reward_direct
+            $nextCascadeActive = ($depth === 0) ? false : $directCascadeActive;
             if ($user['spread_uid']) {
-                $this->propagateReward((int)$user['spread_uid'], $uid, $orderId, $lowerDirectReward, $depth + 1, $orderDbId, $preUpgradeLevels, $qty);
+                $this->propagateReward((int)$user['spread_uid'], $uid, $orderId, $lowerDirectReward, $depth + 1, $orderDbId, $preUpgradeLevels, $qty, $nextCascadeActive);
             }
             return;
         }
 
         $directReward = $this->agentLevelServices->getDirectRewardPoints($agentLevelId);
 
-        // 级差：本节点只拿超出下级已取走部分的差额，再乘以数量
+        // 直推级差：仅在直推链有效时发放（买家直接推荐人必须是分销员）
-        // 间接上级（depth>0，即非直推父节点）受伞下奖励开关控制（hjf_umbrella_reward_enable，默认关闭）
+        if ($directCascadeActive) {
-        if ($depth > 0) {
-            $umbrellaRewardEnable = (int)sys_config('hjf_umbrella_reward_enable', 0);
-            $actual = $umbrellaRewardEnable ? max(0, $directReward - $lowerDirectReward) * $qty : 0;
-        } else {
             $actual = max(0, $directReward - $lowerDirectReward) * $qty;
-        }
-
             if ($actual > 0) {
                 $this->grantFrozenPoints(
                     $uid,
@@ -145,6 +149,26 @@ class PointsRewardServices extends BaseServices
                     $orderDbId
                 );
             }
+        }
+
+        // 伞下积分奖励：独立逻辑，仅对间接上级（depth>0）生效，受开关控制
+        // 使用 umbrella_reward_points 平额发放（非级差），各等级独立拿自身额度
+        if ($depth > 0) {
+            $umbrellaRewardEnable = (int)sys_config('hjf_umbrella_reward_enable', 0);
+            if ($umbrellaRewardEnable) {
+                $umbrellaPoints = $this->agentLevelServices->getUmbrellaRewardPoints($agentLevelId);
+                if ($umbrellaPoints > 0) {
+                    $this->grantFrozenPoints(
+                        $uid,
+                        $umbrellaPoints * $qty,
+                        $orderId,
+                        'reward_umbrella',
+                        '伞下奖励' . " x{$qty} - 来源订单 {$orderId}",
+                        $orderDbId
+                    );
+                }
+            }
+        }
 
         // 向上传递时，下限取当前节点与已有下限中的较大值，确保上级只拿增量
         $nextLower = max($directReward, $lowerDirectReward);
@@ -157,7 +181,8 @@ class PointsRewardServices extends BaseServices
                 $depth + 1,
                 $orderDbId,
                 $preUpgradeLevels,
-                $qty
+                $qty,
+                $directCascadeActive
             );
         }
     }