From a4e9f952254ce37317a2761d3463b4e450a9fe75 Mon Sep 17 00:00:00 2001
From: Pigbibi <20649888+Pigbibi@users.noreply.github.com>
Date: Sat, 16 May 2026 10:20:13 +0800
Subject: [PATCH] Add shared cash sweep whole-share helper

---
 src/quant_platform_kit/common/cash_sweep.py | 33 +++++++++++++++++++++
 tests/test_cash_sweep.py                    | 23 +++++++++++++-
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/src/quant_platform_kit/common/cash_sweep.py b/src/quant_platform_kit/common/cash_sweep.py
index 2f250c7..eeaaa28 100644
--- a/src/quant_platform_kit/common/cash_sweep.py
+++ b/src/quant_platform_kit/common/cash_sweep.py
@@ -41,3 +41,36 @@ def estimate_cash_sweep_sale_quantity_to_fund_buy(
         )
     return 0
 
+
+def should_sell_cash_sweep_to_fund_whole_share_buy(
+    max_quantity: float,
+    cash_sweep_price: float,
+    base_buying_power: float,
+    funding_needs: Iterable[tuple[float, float]],
+) -> bool:
+    """Return whether selling the full cash sweep position can fund a whole-share buy.
+
+    The helper is intentionally conservative: it only returns True when the current
+    buying power is insufficient for at least one whole-share candidate, but selling
+    the whole cash sweep position would cover that whole-share purchase.
+    """
+    if max_quantity <= 0:
+        return False
+    sweep_price = float(cash_sweep_price or 0.0)
+    if sweep_price <= 0.0:
+        return False
+    current_buying_power = max(0.0, float(base_buying_power or 0.0))
+    sweep_capacity = float(max_quantity) * sweep_price
+    if sweep_capacity <= 0.0:
+        return False
+
+    for underweight_value, ask_price in funding_needs:
+        _ = underweight_value
+        quote_price = float(ask_price or 0.0)
+        if quote_price <= 0.0:
+            continue
+        if current_buying_power >= quote_price:
+            return False
+        if current_buying_power + sweep_capacity >= quote_price:
+            return True
+    return False
diff --git a/tests/test_cash_sweep.py b/tests/test_cash_sweep.py
index e8e5c88..ec98e37 100644
--- a/tests/test_cash_sweep.py
+++ b/tests/test_cash_sweep.py
@@ -8,7 +8,10 @@
 if str(SRC) not in sys.path:
     sys.path.insert(0, str(SRC))
 
-from quant_platform_kit.common.cash_sweep import estimate_cash_sweep_sale_quantity_to_fund_buy  # noqa: E402
+from quant_platform_kit.common.cash_sweep import (  # noqa: E402
+    estimate_cash_sweep_sale_quantity_to_fund_buy,
+    should_sell_cash_sweep_to_fund_whole_share_buy,
+)
 
 
 class CashSweepHelperTests(unittest.TestCase):
@@ -39,6 +42,24 @@ def test_ignores_invalid_funding_needs(self):
         )
         self.assertEqual(qty, 0)
 
+    def test_detects_when_full_sweep_can_fund_a_whole_share_buy(self):
+        should_sell = should_sell_cash_sweep_to_fund_whole_share_buy(
+            1,
+            100.0,
+            100.0,
+            [(167.79, 167.79)],
+        )
+        self.assertTrue(should_sell)
+
+    def test_rejects_when_full_sweep_cannot_fund_a_whole_share_buy(self):
+        should_sell = should_sell_cash_sweep_to_fund_whole_share_buy(
+            1,
+            100.0,
+            14.46,
+            [(500.0, 504.60)],
+        )
+        self.assertFalse(should_sell)
+
 
 if __name__ == "__main__":
     unittest.main()