Align Firstrade execution block messaging (#20)

Author: Pigbibi

README.md

@@ -202,9 +202,15 @@ When `FIRSTRADE_PERSIST_STRATEGY_RUNS=true` and a GCS state bucket is configured
 `strategy-runs/<masked-account>/<strategy-profile>/<yyyy-mm>/latest.json` plus a
 timestamped history path. The record includes the planned targets, compact
 portfolio snapshot, evaluation metadata, submitted orders, skipped orders, and
-stage (`ORDERS_PLANNED`, `DRY_RUN_COMPLETED`, or `SUBMITTED`). For live runs,
+stage (`ORDERS_PLANNED`, `DRY_RUN_COMPLETED`, `NO_ACTION`, `SUBMITTED`,
+`EXECUTION_BLOCKED`, `PARTIAL_SUBMITTED`, or `FUNDING_BLOCKED`). For live runs,
 an existing terminal record in the same account/profile/month blocks duplicate
-order submission.
+order submission. Terminal records include `SUBMITTED`, `FUNDING_BLOCKED`,
+`RECONCILED`, and `COMPLETED`; transient execution blockers such as unavailable
+quotes remain non-terminal so the scheduler can retry while the strategy's
+trading-day execution window is still open. A pure insufficient-cash block is
+recorded as `FUNDING_BLOCKED` with the skipped-order reason and is not retried
+automatically for that period.
 
 ## Cloud Run Shape
 

application/rebalance_service.py

@@ -81,6 +81,24 @@ def _is_terminal_funding_block(blocking_skips: list[dict[str, Any]]) -> bool:
     )
 
 
+def _resolve_strategy_run_stage(
+    *,
+    dry_run_only: bool,
+    execution_blocked: bool,
+    terminal_funding_block: bool,
+    action_done: bool,
+) -> str:
+    if dry_run_only:
+        return "DRY_RUN_COMPLETED"
+    if terminal_funding_block and not action_done:
+        return "FUNDING_BLOCKED"
+    if execution_blocked and action_done:
+        return "PARTIAL_SUBMITTED"
+    if execution_blocked:
+        return "EXECUTION_BLOCKED"
+    return "SUBMITTED" if action_done else "NO_ACTION"
+
+
 def _series_from_price_history(market_data_port, symbol: str) -> pd.Series:
     series = market_data_port.get_price_series(symbol)
     index = pd.DatetimeIndex([pd.Timestamp(point.as_of) for point in series.points])
@@ -316,6 +334,12 @@ def run_strategy_cycle(
     execution_blocked = bool(blocking_skips)
     funding_blocked = _is_terminal_funding_block(blocking_skips)
     terminal_funding_block = funding_blocked and not execution_result.action_done
+    strategy_run_stage = _resolve_strategy_run_stage(
+        dry_run_only=settings.dry_run_only,
+        execution_blocked=execution_blocked,
+        terminal_funding_block=terminal_funding_block,
+        action_done=execution_result.action_done,
+    )
     result = {
         "ok": not execution_blocked,
         "api_kind": "unofficial-reverse-engineered",
@@ -326,6 +350,7 @@ def run_strategy_cycle(
         "live_trading_enabled": settings.live_trading_enabled,
         "session_reused": bool(getattr(client, "session_reused", False)),
         "strategy_run_period": run_period,
+        "strategy_run_stage": strategy_run_stage,
         "strategy_run_persisted": strategy_run_persisted,
         "portfolio": plan.get("portfolio", {}),
         "allocation": plan.get("allocation", {}),
@@ -344,18 +369,8 @@ def run_strategy_cycle(
     if strategy_run_persistence_error:
         result["strategy_run_persistence_error"] = strategy_run_persistence_error
     if persist_strategy_runs:
-        stage = "DRY_RUN_COMPLETED"
-        if not settings.dry_run_only:
-            if terminal_funding_block and not execution_result.action_done:
-                stage = "FUNDING_BLOCKED"
-            elif execution_blocked and execution_result.action_done:
-                stage = "PARTIAL_SUBMITTED"
-            elif execution_blocked:
-                stage = "EXECUTION_BLOCKED"
-            else:
-                stage = "SUBMITTED" if execution_result.action_done else "NO_ACTION"
         completed_state = build_strategy_run_state(
-            stage=stage,
+            stage=strategy_run_stage,
             account=masked_account,
             strategy_profile=strategy_runtime.profile,
             strategy_display_name=strategy_runtime.display_name,

notifications/telegram.py

@@ -55,6 +55,8 @@
         "order_id_suffix": "（订单号: {order_id}）",
         "no_order_submitted": "未下单: 原因={reason}",
         "execution_blocked_banner": "⚠️ 执行阻塞: {reason}",
+        "execution_blocked_retryable_banner": "⚠️ 执行阻塞，可在窗口内自动重试: {reason}",
+        "funding_blocked_banner": "⚠️ 资金不足，本周期不再自动重试: {reason}",
         "no_rebalance_needed": "✅ 无需调仓",
         "no_trades": "✅ 无需调仓",
         "no_executable_orders": "无可执行订单",
@@ -135,6 +137,8 @@
         "order_id_suffix": " (ID: {order_id})",
         "no_order_submitted": "No order submitted: reason={reason}",
         "execution_blocked_banner": "⚠️ Execution blocked: {reason}",
+        "execution_blocked_retryable_banner": "⚠️ Execution blocked; retryable within window: {reason}",
+        "funding_blocked_banner": "⚠️ Funding blocked; no more automatic retries for this period: {reason}",
         "no_rebalance_needed": "✅ No rebalance needed",
         "no_trades": "✅ No rebalance needed",
         "no_executable_orders": "no executable orders",
@@ -557,7 +561,13 @@ def render_cycle_summary(result: Mapping[str, Any], *, lang: str = "en") -> str:
     if bool(result.get("execution_blocked")):
         blocked = list(result.get("execution_blocking_skips") or skipped)
         reason = _format_skipped_reason(blocked, translator=translator)
-        lines.append(translator("execution_blocked_banner", reason=reason))
+        if bool(result.get("funding_blocked")):
+            banner_key = "funding_blocked_banner"
+        elif result.get("execution_block_retryable") is True:
+            banner_key = "execution_blocked_retryable_banner"
+        else:
+            banner_key = "execution_blocked_banner"
+        lines.append(translator(banner_key, reason=reason))
 
     dashboard_lines = _format_dashboard_lines(portfolio, execution, translator=translator)
     if dashboard_lines:

tests/test_rebalance_service.py

@@ -185,6 +185,7 @@ def test_run_strategy_cycle_persists_strategy_run_state(monkeypatch):
     assert stages == ["ORDERS_PLANNED", "DRY_RUN_COMPLETED"]
     assert result["strategy_run_persisted"] is True
     assert result["strategy_run_period"]
+    assert result["strategy_run_stage"] == "DRY_RUN_COMPLETED"
     latest_payload = store.writes[-2][1]
     assert latest_payload["stage"] == "DRY_RUN_COMPLETED"
     assert latest_payload["submitted_orders"][0]["symbol"] == "AAA"
@@ -263,6 +264,7 @@ def test_run_strategy_cycle_persists_live_execution_blocked_without_terminal_sta
     assert result["ok"] is False
     assert result["execution_blocked"] is True
     assert result["execution_block_retryable"] is True
+    assert result["strategy_run_stage"] == "EXECUTION_BLOCKED"
     assert latest_payload["stage"] == "EXECUTION_BLOCKED"
 
 
@@ -315,6 +317,7 @@ def evaluate(self, **inputs):
     assert result["execution_blocked"] is True
     assert result["execution_block_retryable"] is False
     assert result["funding_blocked"] is True
+    assert result["strategy_run_stage"] == "FUNDING_BLOCKED"
     assert result["skipped_orders"][0]["reason"] == "insufficient_cash_for_whole_share"
     assert latest_payload["stage"] == "FUNDING_BLOCKED"
 
@@ -383,6 +386,7 @@ def get_quote(self, _account, symbol):
     assert result["action_done"] is True
     assert result["ok"] is False
     assert result["execution_blocked"] is True
+    assert result["strategy_run_stage"] == "PARTIAL_SUBMITTED"
     assert latest_payload["stage"] == "PARTIAL_SUBMITTED"
 
 
@@ -525,14 +529,16 @@ def test_render_cycle_summary_formats_skipped_orders_in_unified_english_template
     assert "targets:" not in message
 
 
-def test_render_cycle_summary_shows_execution_blocked_banner():
+def test_render_cycle_summary_shows_funding_blocked_banner():
     message = render_cycle_summary(
         {
             "account": "****1234",
             "strategy_profile": "mega_cap_leader_rotation_top50_balanced",
             "strategy_display_name": "Mega Cap Leader Rotation Top50 Balanced",
             "dry_run_only": False,
             "execution_blocked": True,
+            "execution_block_retryable": False,
+            "funding_blocked": True,
             "execution_blocking_skips": [
                 {"symbol": "NVDA", "reason": "insufficient_cash_for_whole_share"}
             ],
@@ -553,4 +559,36 @@ def test_render_cycle_summary_shows_execution_blocked_banner():
         lang="zh",
     )
 
-    assert "⚠️ 执行阻塞: 现金不足以买入一整股:NVDA" in message
+    assert "⚠️ 资金不足，本周期不再自动重试: 现金不足以买入一整股:NVDA" in message
+
+
+def test_render_cycle_summary_shows_retryable_execution_blocked_banner():
+    message = render_cycle_summary(
+        {
+            "account": "****1234",
+            "strategy_profile": "mega_cap_leader_rotation_top50_balanced",
+            "strategy_display_name": "Mega Cap Leader Rotation Top50 Balanced",
+            "dry_run_only": False,
+            "execution_blocked": True,
+            "execution_block_retryable": True,
+            "execution_blocking_skips": [
+                {"symbol": "NVDA", "reason": "quote_unavailable"}
+            ],
+            "portfolio": {
+                "total_equity": 500.0,
+                "liquid_cash": 500.0,
+                "portfolio_rows": (("NVDA",),),
+                "market_values": {"NVDA": 0.0},
+                "quantities": {"NVDA": 0},
+            },
+            "allocation": {"targets": {"NVDA": 500.0}},
+            "execution": {},
+            "submitted_orders": [],
+            "skipped_orders": [
+                {"symbol": "NVDA", "reason": "quote_unavailable"}
+            ],
+        },
+        lang="en",
+    )
+
+    assert "⚠️ Execution blocked; retryable within window: quote unavailable:NVDA" in message