Преглед на файлове

refactor: implement action-aware error policy engine and separate domain exceptions from recovery policies

- vs_types.py: pure domain facts in BizException without scheduler directives
- standalone.py, sentinel.py, booker.py: unified _dispatch_error_policy with action-aware matrix (login 429 locks account vs query 429 rotates proxy)
- test/test_metadata_exception.py: comprehensive unit tests for exception facts and policy matrix
Hu Jiarui преди 1 месец
родител
ревизия
b2dc6beb9d
променени са 5 файла, в които са добавени 574 реда и са изтрити 91 реда
  1. 110 38
      booker.py
  2. 107 17
      sentinel.py
  3. 120 18
      standalone.py
  4. 206 0
      test/test_metadata_exception.py
  5. 31 18
      vs_types.py

+ 110 - 38
booker.py

@@ -8,7 +8,9 @@ from typing import List, Dict, Callable, Optional
 
 from vs_types import (
     GroupConfig, VSPlgConfig, Task, VSBookResult, VSQueryResult, 
-    AppointmentType, QueryWaitMode, AvailabilityStatus, GroupStatus, PluginStatus, utc_now_str
+    AppointmentType, QueryWaitMode, AvailabilityStatus, GroupStatus, PluginStatus, utc_now_str,
+    BizException, RateLimiteddError, SessionExpiredOrInvalidError, PermissionDeniedError,
+    NetworkTimeoutError
 )
 from vs_plg_factory import VSPlgFactory 
 from toolkit.vs_cloud_api import VSCloudApi
@@ -148,6 +150,109 @@ class BaseBookerGCO:
     def _get_redis_key(self, routing_key: str) -> str:
         return f"vs:signal:{routing_key}"
 
+    def _normalize_error(self, err: Exception) -> BizException:
+        """规整化异常为领域异常 BizException,保留对历史特征字符串的兜底兼容"""
+        if isinstance(err, BizException):
+            return err
+        err_str = str(err)
+        if "42901" in err_str or "Rate limited" in err_str:
+            return RateLimiteddError(message=err_str)
+        if "40101" in err_str or "Session expired" in err_str or "session invalid" in err_str.lower():
+            return SessionExpiredOrInvalidError(message=err_str)
+        if "40301" in err_str or "403" in err_str or "Cloudflare Access Denied" in err_str:
+            return PermissionDeniedError(message=err_str)
+        return BizException(
+            code=50000,
+            message=f"Unhandled ({type(err).__name__}): {err_str}",
+        )
+
+    def _dispatch_error_policy(
+        self,
+        action: str,
+        err: Exception,
+        task: Optional[Task] = None,
+        plg_cfg: Optional[VSPlgConfig] = None,
+        task_id: Optional[int] = None
+    ) -> None:
+        """
+        Booker 错误调度与自愈策略引擎 (Policy Engine):
+        基于 (Action, 异常事实类型) 矩阵 + Booker 模式闭环执行自愈动作:
+        - spawn/login 时 429:判定为账号级限流,锁定账号,更新 Redis 订单/任务追踪器与生成冷却;
+        - book 时 429:档期提交频控或出口 IP 限制,不锁定账号,移除任务以轮换代理或重试;
+        - session expired / 401:会话失效,移除任务;
+        - 403 Forbidden / WAF:判定为 IP 受阻,移除任务以轮换代理;
+        - 内部直接完成日志输出与定时器维护,调用方无需感知具体冷却数值。
+        """
+        biz_err = self._normalize_error(err)
+        acc = None
+        if plg_cfg and plg_cfg.account:
+            acc = plg_cfg.account
+        elif task and getattr(task.instance, "config", None) and task.instance.config.account:
+            acc = task.instance.config.account
+
+        # 1. 目标站限流 / 429
+        if isinstance(biz_err, RateLimiteddError):
+            if action in ("spawn", "login", "create_session"):
+                backoff = float(self.m_cfg.login_backoff)
+                self._log(f"🔒 [Account Rate Limited] 429 throttled during {action} (Account credential/frequency restricted).")
+                if acc and getattr(acc, "username", "") not in ("", "Guest") and getattr(acc, "id", 0):
+                    try:
+                        VSCloudApi.Instance().lock_account(acc.id, int(backoff))
+                        self._log(f"🔒 Account [{acc.username}] locked for {int(backoff)}s via Cloud API.")
+                    except Exception as lock_err:
+                        self._log(f"Failed to lock account via cloud API: {lock_err}")
+
+                effective_task_id = task_id if task_id is not None else (task.task_ref if task else None)
+                if effective_task_id is not None:
+                    self.redis_client.zadd(self.m_tracker_key, {str(effective_task_id): time.time() + self.m_cfg.login_backoff})
+
+                self.m_spawn_cooldown_until = time.time() + backoff
+                if task:
+                    self._remove_task(task, "spawn account rate limited")
+
+            elif action == "book":
+                # 预订提交时 429:接口频控或 IP 限制,绝不锁账号,移除实例以更换代理重试
+                self._log("🔄 [Booking Rate Limited] 429 during booking (Slot/IP throttled, Account preserved). Removing task to rotate proxy...")
+                if task:
+                    self._remove_task(task, "booking rate limited")
+            else:
+                self._log(f"⚠️ [Rate Limited] 429 encountered during {action}.")
+                if task:
+                    self._remove_task(task, f"{action} rate limited")
+
+        # 2. 会话过期 / 401
+        elif isinstance(biz_err, SessionExpiredOrInvalidError):
+            if action in ("spawn", "login", "create_session"):
+                self._log(f"❌ [Auth Failed] Booker spawn failed (401). Cooling down spawn for 5s...")
+                self.m_spawn_cooldown_until = time.time() + 5.0
+            else:
+                self._log(f"🔄 [Session Expired] Booker session died during {action}. Removing task...")
+                if task:
+                    self._remove_task(task, f"{action} session expired")
+
+        # 3. 权限被拒 / WAF 拦截 / 403
+        elif isinstance(biz_err, PermissionDeniedError):
+            proxy_cd = float(getattr(self.m_cfg, "proxy_cd", 60.0) or 60.0)
+            self._log(f"🛡️ [WAF Blocked] 403 Forbidden during {action}. Removing task to rotate proxy...")
+            if task:
+                self._remove_task(task, f"{action} waf blocked")
+            if action == "spawn":
+                self.m_spawn_cooldown_until = time.time() + proxy_cd
+
+        # 4. 网络或浏览器超时
+        elif isinstance(biz_err, NetworkTimeoutError):
+            self._log(f"⏱️ [Timeout] Network/browser timeout during {action}.")
+            if task:
+                task.next_run = time.time() + 5.0
+
+        # 5. 兜底策略
+        else:
+            self._log(f"⚠️ [{action}] Unexpected error: {biz_err.message} (code={biz_err.code})")
+            if action == "spawn":
+                self.m_spawn_cooldown_until = time.time() + 10.0
+            elif task:
+                task.next_run = time.time() + 10.0
+
     def _is_within_active_hours(self) -> bool:
         """判断当前是否在允许创建实例的时间段内"""
         start_str = self.m_cfg.active_time_start
@@ -345,16 +450,7 @@ class BuiltinBookerGCO(BaseBookerGCO):
             success = True
             self._log(f"+++ Built-in Booker spawned: {plg_cfg.account.username}")
         except Exception as e:
-            err_str = str(e)
-            self.m_spawn_cooldown_until = time.time() + 30.0
-            self._log(f"Spawn failed: {err_str}. Backing off for 30s...")
-            rate_limited_indicators = [
-                "42901" in err_str,
-                "Rate limited" in err_str
-            ]
-            if any(rate_limited_indicators):
-                if plg_cfg and plg_cfg.account.username != "Guest":
-                    VSCloudApi.Instance().lock_account(plg_cfg.account.id, self.m_cfg.login_backoff)
+            self._dispatch_error_policy("spawn", e, plg_cfg=plg_cfg)
         finally:
             if not success and instance:
                 self._cleanup_instance(instance, "spawn failed")
@@ -388,14 +484,7 @@ class BuiltinBookerGCO(BaseBookerGCO):
             else:
                 self._log(f"❌ BOOK FAILED for Order: {order_id}")
         except Exception as e:
-            err_str = str(e)
-            self._log(f"Exception during booking: {err_str}")
-            rate_limited_indicators = [
-                "42901" in err_str,
-                "Rate limited" in err_str
-            ]
-            if any(rate_limited_indicators):
-                self._remove_task(task, "booking rate limited")
+            self._dispatch_error_policy("book", e, task=task)
 
 
 class OrderBookerGCO(BaseBookerGCO):
@@ -502,14 +591,7 @@ class OrderBookerGCO(BaseBookerGCO):
                 self._log(f"❌ BOOK FAILED for Order: {order_id}. Will retry on next signal.")
 
         except Exception as e:
-            err_str = str(e)
-            self._log(f"Exception during booking: {err_str}")
-            rate_limited_indicators = [
-                "42901" in err_str,
-                "Rate limited" in err_str
-            ]
-            if any(rate_limited_indicators):
-                self._remove_task(task, "booking rate limited")
+            self._dispatch_error_policy("book", e, task=task)
 
     def _creator_loop(self):
         self._log("Creator loop started.")
@@ -581,17 +663,7 @@ class OrderBookerGCO(BaseBookerGCO):
             success = True             
             self._log(f"+++ Order Booker spawned: {plg_cfg.account.username} (Target: {acceptable_keys})")
         except Exception as e:
-            err_str = str(e)
-            self.m_spawn_cooldown_until = time.time() + 30.0
-            self._log(f"Order Booker spawn failed: {err_str}. Backing off for 30s...")
-            rate_limited_indicators = [
-                "42901" in err_str,
-                "Rate limited" in err_str
-            ]
-            if any(rate_limited_indicators):
-                if task_id is not None:
-                    self.redis_client.zadd(self.m_tracker_key, {str(task_id): time.time() + self.m_cfg.login_backoff})  
-        
+            self._dispatch_error_policy("spawn", e, plg_cfg=plg_cfg, task_id=task_id)
         finally:
             if not success and instance:
                 self._cleanup_instance(instance, "spawn failed")

+ 107 - 17
sentinel.py

@@ -4,9 +4,13 @@ import json
 import random
 import threading
 from datetime import datetime
-from typing import List, Dict, Callable
+from typing import List, Dict, Callable, Optional
 
-from vs_types import GroupConfig, VSPlgConfig, Task, QueryWaitMode, GroupStatus, PluginStatus, utc_now_str
+from vs_types import (
+    GroupConfig, VSPlgConfig, Task, QueryWaitMode, GroupStatus, PluginStatus, utc_now_str,
+    BizException, RateLimiteddError, SessionExpiredOrInvalidError, PermissionDeniedError,
+    NetworkTimeoutError
+)
 from vs_plg_factory import VSPlgFactory 
 from toolkit.vs_cloud_api import VSCloudApi
 from toolkit.proxy_manager import ProxyManager
@@ -126,7 +130,103 @@ class SentinelGCO:
 
     def _get_redis_key(self, routing_key: str) -> str:
         return f"vs:signal:{routing_key}"
-    
+
+    def _normalize_error(self, err: Exception) -> BizException:
+        """规整化异常为领域异常 BizException,保留对历史特征字符串的兜底兼容"""
+        if isinstance(err, BizException):
+            return err
+        err_str = str(err)
+        if "42901" in err_str or "Rate limited" in err_str:
+            return RateLimiteddError(message=err_str)
+        if "40101" in err_str or "Session expired" in err_str or "session invalid" in err_str.lower():
+            return SessionExpiredOrInvalidError(message=err_str)
+        if "40301" in err_str or "403" in err_str or "Cloudflare Access Denied" in err_str:
+            return PermissionDeniedError(message=err_str)
+        return BizException(
+            code=50000,
+            message=f"Unhandled ({type(err).__name__}): {err_str}",
+        )
+
+    def _dispatch_error_policy(
+        self,
+        action: str,
+        err: Exception,
+        task: Optional[Task] = None,
+        plg_cfg: Optional[VSPlgConfig] = None
+    ) -> None:
+        """
+        Sentinel 错误调度与自愈策略引擎 (Policy Engine):
+        基于 (Action, 异常事实类型) 矩阵 + 哨兵池模式闭环执行自愈动作:
+        - spawn/login 时 429:判定为账号级限流,锁定账号并设置 m_spawn_cooldown_until 退避;
+        - query 时 429:会话已登录,判定为出口 IP 频率超限,不锁定账号,移除任务以触发 creator 换代理生成新实例;
+        - session expired / 401:移除故障任务;
+        - 403 Forbidden / WAF:判定为出口 IP 被风控,移除任务以轮换代理;
+        - 内部直接完成日志输出与定时器维护,调用方无需感知具体冷却数值。
+        """
+        biz_err = self._normalize_error(err)
+        acc = None
+        if plg_cfg and plg_cfg.account:
+            acc = plg_cfg.account
+        elif task and getattr(task.instance, "config", None) and task.instance.config.account:
+            acc = task.instance.config.account
+
+        # 1. 目标站限流 / 429
+        if isinstance(biz_err, RateLimiteddError):
+            if action in ("spawn", "login", "create_session"):
+                backoff = float(self.m_cfg.login_backoff)
+                self._log(f"🔒 [Account Rate Limited] 429 throttled during {action} (Account credential/frequency restricted).")
+                if acc and getattr(acc, "username", "") not in ("", "Guest") and getattr(acc, "id", 0):
+                    try:
+                        VSCloudApi.Instance().lock_account(acc.id, int(backoff))
+                        self._log(f"🔒 Account [{acc.username}] locked for {int(backoff)}s via Cloud API.")
+                    except Exception as lock_err:
+                        self._log(f"Failed to lock account via cloud API: {lock_err}")
+                self.m_spawn_cooldown_until = time.time() + backoff
+                if task:
+                    self._remove_task(task, "spawn account rate limited")
+            elif action == "query":
+                # 查询时 429:出口 IP 限流,绝不锁账号,移除当前 task 触发自动换新代理!
+                self._log("🔄 [Proxy Rate Limited] Sentinel query hit 429 (IP throttled, Account preserved). Removing task to rotate proxy...")
+                if task:
+                    self._remove_task(task, "query ip rate limited")
+            else:
+                self._log(f"⚠️ [Rate Limited] 429 encountered during {action}.")
+                if task:
+                    task.next_run = time.time() + 10.0
+
+        # 2. 会话过期 / 401
+        elif isinstance(biz_err, SessionExpiredOrInvalidError):
+            if action in ("spawn", "login", "create_session"):
+                self._log(f"❌ [Auth Failed] Sentinel spawn failed (401). Cooling down spawn for 5s...")
+                self.m_spawn_cooldown_until = time.time() + 5.0
+            else:
+                self._log(f"🔄 [Session Expired] Sentinel session expired during {action}. Removing task...")
+                if task:
+                    self._remove_task(task, f"{action} session expired")
+
+        # 3. 权限被拒 / WAF 拦截 / 403
+        elif isinstance(biz_err, PermissionDeniedError):
+            proxy_cd = float(getattr(self.m_cfg, "proxy_cd", 60.0) or 60.0)
+            self._log(f"🛡️ [WAF Blocked] 403 Forbidden during {action}. Removing task to rotate proxy...")
+            if task:
+                self._remove_task(task, f"{action} waf blocked")
+            if action == "spawn":
+                self.m_spawn_cooldown_until = time.time() + proxy_cd
+
+        # 4. 网络或浏览器超时
+        elif isinstance(biz_err, NetworkTimeoutError):
+            self._log(f"⏱️ [Timeout] Network/browser timeout during {action}.")
+            if task:
+                task.next_run = time.time() + 5.0
+
+        # 5. 兜底策略
+        else:
+            self._log(f"⚠️ [{action}] Unexpected error: {biz_err.message} (code={biz_err.code})")
+            if action == "spawn":
+                self.m_spawn_cooldown_until = time.time() + 10.0
+            elif task:
+                task.next_run = time.time() + 10.0
+
     def _is_within_active_hours(self) -> bool:
         """
         判断当前是否在允许创建实例的时间段内
@@ -217,13 +317,12 @@ class SentinelGCO:
                             }
                             redis_key = self._get_redis_key(apt_type.routing_key)
                             self.redis_client.setex(redis_key, ttl, json.dumps(payload))
-                    except Exception as e:
-                        self._log(f"Query exception: {e}")
-                    finally:
                         task.next_run = time.time() + interval
+                    except Exception as e:
+                        self._dispatch_error_policy("query", e, task=task)
                     break
             except Exception as e:
-                self._log(f"Monitor loop error: {e}")
+                self._dispatch_error_policy("monitor_loop", e)
 
     def _creator_loop(self):
         self._log("Creator loop started.")
@@ -275,16 +374,7 @@ class SentinelGCO:
             success = True
             self._log(f"+++ Sentinel spawned: {plg_cfg.account.username}")
         except Exception as e:
-            err_str = str(e)
-            self.m_spawn_cooldown_until = time.time() + 30.0
-            self._log(f"Spawn failed: {err_str}. Backing off for 30s...")
-            rate_limited_indicators = [
-                "42901" in err_str,
-                "Rate limited" in err_str
-            ]
-            if any(rate_limited_indicators):
-                if plg_cfg and plg_cfg.account.username != "Guest":
-                    VSCloudApi.Instance().lock_account(plg_cfg.account.id, self.m_cfg.login_backoff)
+            self._dispatch_error_policy("spawn", e, plg_cfg=plg_cfg)
         finally:
             if not success and instance:
                 self._cleanup_instance(instance, "spawn failed")

+ 120 - 18
standalone.py

@@ -5,10 +5,24 @@ import threading
 from datetime import datetime
 from typing import Dict, Callable, Optional
 
-from vs_types import BookerStandaloneConfig, QueryWaitMode, VSPlgConfig, VSQueryResult, VSBookResult, GroupStatus, PluginStatus, utc_now_str
+from vs_types import (
+    BookerStandaloneConfig,
+    QueryWaitMode,
+    VSPlgConfig,
+    VSQueryResult,
+    VSBookResult,
+    GroupStatus,
+    PluginStatus,
+    utc_now_str,
+    BizException,
+    RateLimiteddError,
+    SessionExpiredOrInvalidError,
+    PermissionDeniedError,
+)
 from vs_plg_factory import VSPlgFactory
 from utils.safe_redis_cli import SafeRedisClient
 from toolkit.proxy_manager import ProxyManager
+from toolkit.vs_cloud_api import VSCloudApi
 from toolkit.notifier import notify_date_changes, notify_book_result
 
 
@@ -154,13 +168,99 @@ class StandaloneGCO:
             self.m_instance = instance
 
         self._log("Creating session...")
-        self.m_last_login_time = time.time()
         instance.create_session()
+        self.m_last_login_time = time.time()
         interval = self._get_wait_interval()
         self.m_next_query_time = time.time() + interval
         self.m_next_keepalive_time = time.time() + 10.0
         self._log(f"Session created successfully. Initial query scheduled in {interval:.1f}s (at {datetime.fromtimestamp(self.m_next_query_time).strftime('%H:%M:%S')}).")
 
+    def _normalize_error(self, err: Exception) -> BizException:
+        """
+        将任意异常规整化为领域异常 BizException。
+        保留对未结构化历史异常字符串特征的兜底兼容识别。
+        """
+        if isinstance(err, BizException):
+            return err
+
+        err_str = str(err)
+        if "42901" in err_str or "Rate limited" in err_str:
+            return RateLimiteddError(message=err_str)
+        if "40101" in err_str or "Session expired" in err_str or "session invalid" in err_str.lower():
+            return SessionExpiredOrInvalidError(message=err_str)
+        if "40301" in err_str or "403" in err_str or "Cloudflare Access Denied" in err_str:
+            return PermissionDeniedError(message=err_str)
+
+        return BizException(
+            code=50000,
+            message=f"Unhandled ({type(err).__name__}): {err_str}",
+        )
+
+    def _dispatch_error_policy(self, action: str, err: Exception) -> None:
+        """
+        Standalone 错误调度与自愈策略引擎 (Policy Engine):
+        基于 (Action, 异常事实类型) 矩阵 + Standalone 单机模式 + 本组配置闭环执行自愈动作:
+        - create_session/login 时 429:判定为账号级限流,锁定账号,执行 login_interval 退避等待;
+        - query 时 429:会话已建立,判定为出口 IP 频率超限,不锁定账号,销毁实例触发下轮代理轮换;
+        - session expired / 401:销毁当前实例,重置下一次查询时间为 5s 后以触发重新登录;
+        - 403 Forbidden / WAF:判定为 IP 被封,清理实例换 IP 并退避;
+        - 内部直接完成日志输出与定时器维护,调用方无需感知具体冷却数值。
+        """
+        biz_err = self._normalize_error(err)
+        acc = self.m_cfg.account if (self.m_cfg.account and self.m_cfg.account.username not in ("", "Guest")) else None
+
+        # 1. 目标站限流 / 429
+        if isinstance(biz_err, RateLimiteddError):
+            if action in ("create_session", "login", "spawn"):
+                backoff = float(self.m_cfg.login_interval)
+                self._log(f"🔒 [Account Rate Limited] 429 throttled during {action} (Account credential/frequency restricted).")
+                if acc and getattr(acc, "id", 0):
+                    try:
+                        VSCloudApi.Instance().lock_account(acc.id, int(backoff))
+                        self._log(f"🔒 Account [{acc.username}] locked for {int(backoff)}s via Cloud API.")
+                    except Exception as lock_err:
+                        self._log(f"Failed to lock account via cloud API: {lock_err}")
+                self.m_last_login_time = time.time()
+                self._cleanup_instance(f"{action} account rate limited")
+            elif action == "query":
+                # 查询时 429:出口 IP 限流,绝不锁账号,换 IP 即可!
+                self._log("🔄 [Proxy Rate Limited] Query hit 429 (IP throttled, Account preserved). Cleaning instance to rotate proxy...")
+                self._cleanup_instance("query ip rate limited")
+                self.m_next_query_time = time.time() + 10.0
+            else:
+                self._log(f"⚠️ [Rate Limited] 429 encountered during {action}.")
+                self.m_next_query_time = time.time() + 10.0
+
+        # 2. 会话过期 / 401
+        elif isinstance(biz_err, SessionExpiredOrInvalidError):
+            if action in ("create_session", "login", "spawn"):
+                self._log(f"❌ [Auth Failed] Session creation failed (401 invalid credentials or challenge). Backing off for 10s...")
+                self.m_last_login_time = time.time() - self.m_cfg.login_interval + 10.0
+                self._cleanup_instance(f"{action} auth failed")
+            else:
+                self._log(f"🔄 [Session Expired] Session died during {action}. Cleaning up instance for re-login in 5s...")
+                self._cleanup_instance(f"{action} session expired")
+                self.m_next_query_time = time.time() + 5.0
+
+        # 3. 权限被拒 / WAF 拦截 / 403
+        elif isinstance(biz_err, PermissionDeniedError):
+            self._log(f"🛡️ [WAF Blocked] 403 Forbidden detected during {action}. Cleaning instance to rotate proxy (60s cooldown)...")
+            self._cleanup_instance(f"{action} waf blocked")
+            self.m_next_query_time = time.time() + 60.0
+
+        # 4. 网络或浏览器超时
+        elif isinstance(biz_err, NetworkTimeoutError):
+            self._log(f"⏱️ [Timeout] Network/browser timeout during {action}. Retrying in 5s...")
+            self.m_next_query_time = time.time() + 5.0
+
+        # 5. 兜底策略
+        else:
+            self._log(f"⚠️ [{action}] Unexpected error: {biz_err.message} (code={biz_err.code})")
+            if action in ("create_session", "worker_loop"):
+                self.m_last_login_time = time.time() - self.m_cfg.login_interval + 5.0
+            else:
+                self.m_next_query_time = time.time() + 10.0
+
     def _worker_loop(self):
         """
         后台守护循环:心跳保活 -> 时间判定 -> 查询 -> 预定
@@ -177,15 +277,12 @@ class StandaloneGCO:
                     self.m_stop_event.wait(5.0)
                     continue
 
-                # 1. 会话初始化
+                # 1. 会话初始化与自愈
                 if self.m_instance is None:
                     try:
                         self._init_instance()
                     except Exception as e:
-                        self._cleanup_instance("session creation failed")
-                        cooldown = self.m_cfg.login_interval
-                        self._log(f"Failed to create session: {e}. Retrying in {int(cooldown)}s (login interval cooldown)...")
-                        self.m_stop_event.wait(cooldown)
+                        self._dispatch_error_policy("create_session", e)
                         continue
 
                 # 2. 健康检查
@@ -230,19 +327,25 @@ class StandaloneGCO:
                     apt_type = random.choice(apt_types)
 
                 self._log(f"Querying slots for {apt_type.routing_key}...")
-                query_result = self.m_instance.query(apt_type)
-                query_result.apt_type = apt_type
-                notify_date_changes(query_result, cache=self.m_current_dates, logger=self._log)
+                try:
+                    query_result = self.m_instance.query(apt_type)
+                    query_result.apt_type = apt_type
+                    notify_date_changes(query_result, cache=self.m_current_dates, logger=self._log)
+                except Exception as e:
+                    self._dispatch_error_policy("query", e)
+                    continue
 
                 # 5. 发现档期,执行自动预定
                 if query_result.success:
                     self._log("🔥 SLOT FOUND! Initiating AUTO-BOOKING...")
-                    book_result = self.m_instance.book(query_result, self.m_cfg.user_preferences)
-                    notify_book_result(book_result, logger=self._log)
-                    if book_result.success:
-                        self._log(f"🎉 BOOKING SUCCESSFUL for {apt_type.routing_key}!")
-                        # 预定成功后可继续或等待后续任务
-                        self.m_stop_event.wait(5.0)
+                    try:
+                        book_result = self.m_instance.book(query_result, self.m_cfg.user_preferences)
+                        notify_book_result(book_result, logger=self._log)
+                        if book_result.success:
+                            self._log(f"🎉 BOOKING SUCCESSFUL for {apt_type.routing_key}!")
+                            self.m_stop_event.wait(5.0)
+                    except Exception as e:
+                        self._dispatch_error_policy("book", e)
 
                 # 6. 在所有操作(包括抢单流程)执行完毕后,再统一计算并调度下一次查询时间与保活时间
                 interval = self._get_wait_interval()
@@ -254,5 +357,4 @@ class StandaloneGCO:
                 self._log(f"Next query scheduled in {interval:.1f}s (at {datetime.fromtimestamp(self.m_next_query_time).strftime('%H:%M:%S')})...")
 
             except Exception as e:
-                self._log(f"Standalone loop exception: {e}")
-                self.m_stop_event.wait(2.0)
+                self._dispatch_error_policy("worker_loop", e)

+ 206 - 0
test/test_metadata_exception.py

@@ -0,0 +1,206 @@
+import unittest
+import time
+from unittest.mock import MagicMock, patch
+from vs_types import (
+    BizException,
+    RateLimiteddError,
+    RateLimitedError,
+    SessionExpiredOrInvalidError,
+    SessionExpiredError,
+    PermissionDeniedError,
+    NotFoundError,
+    BizLogicError,
+    NetworkTimeoutError,
+    VSPluginError,
+    BookerStandaloneConfig,
+    VSPlgConfig,
+)
+from standalone import StandaloneGCO
+
+
+class TestMetadataExceptions(unittest.TestCase):
+    def test_exception_pure_facts(self):
+        """验证异常仅表达领域事实(状态码、HTTP状态、信息),不携带调度器执行策略"""
+        # 1. RateLimiteddError
+        err_rate = RateLimiteddError("Too fast")
+        self.assertEqual(err_rate.code, 42901)
+        self.assertEqual(err_rate.http_status, 429)
+        self.assertEqual(err_rate.message, "Too fast")
+        self.assertFalse(hasattr(err_rate, "lock_account"))
+        self.assertFalse(hasattr(err_rate, "destroy_session"))
+        self.assertFalse(hasattr(err_rate, "cooldown_sec"))
+        self.assertFalse(hasattr(err_rate, "rotate_proxy"))
+
+        # 别名验证
+        self.assertIs(RateLimitedError, RateLimiteddError)
+        self.assertIs(SessionExpiredError, SessionExpiredOrInvalidError)
+        self.assertIs(VSPluginError, BizException)
+
+        # 2. SessionExpiredOrInvalidError
+        err_session = SessionExpiredOrInvalidError("Kicked out")
+        self.assertEqual(err_session.code, 40101)
+        self.assertEqual(err_session.http_status, 401)
+
+        # 3. NetworkTimeoutError
+        err_net = NetworkTimeoutError("Gateway timeout")
+        self.assertEqual(err_net.code, 50401)
+        self.assertEqual(err_net.http_status, 504)
+
+        # 4. PermissionDeniedError
+        err_perm = PermissionDeniedError("403 Forbidden")
+        self.assertEqual(err_perm.code, 40301)
+        self.assertEqual(err_perm.http_status, 403)
+
+    def test_standalone_normalize_error(self):
+        cfg = BookerStandaloneConfig(identifier="test_group")
+        gco = StandaloneGCO(cfg=cfg, redis_conf={})
+
+        # 已是规范异常
+        rate_err = RateLimiteddError()
+        self.assertIs(gco._normalize_error(rate_err), rate_err)
+
+        # 历史遗留字符串 "42901" 兼容识别
+        raw_429 = Exception("Request failed with 42901 code")
+        normalized_429 = gco._normalize_error(raw_429)
+        self.assertIsInstance(normalized_429, RateLimiteddError)
+
+        # 历史遗留字符串 "Session expired" 兼容识别
+        raw_sess = Exception("Error: Session expired on server")
+        normalized_sess = gco._normalize_error(raw_sess)
+        self.assertIsInstance(normalized_sess, SessionExpiredOrInvalidError)
+
+        # 未知异常保底
+        raw_unknown = KeyError("element_not_found")
+        normalized_unknown = gco._normalize_error(raw_unknown)
+        self.assertIsInstance(normalized_unknown, BizException)
+        self.assertEqual(normalized_unknown.code, 50000)
+
+    @patch("toolkit.vs_cloud_api.VSCloudApi.Instance")
+    def test_standalone_action_matrix_policy(self, mock_cloud_instance):
+        mock_cloud = MagicMock()
+        mock_cloud_instance.return_value = mock_cloud
+
+        cfg = BookerStandaloneConfig(identifier="test_group")
+        cfg.account.id = 12345
+        cfg.account.username = "test_user"
+        cfg.login_interval = 1200
+        gco = StandaloneGCO(cfg=cfg, redis_conf={})
+
+        mock_inst = MagicMock()
+        gco.m_instance = mock_inst
+
+        # 场景 A: 登录/建连时 429 -> 账号受限,锁账号
+        err = RateLimiteddError()
+        gco._dispatch_error_policy("create_session", err)
+        mock_cloud.lock_account.assert_called_once_with(12345, 1200)
+        mock_inst.cleanup.assert_called_once()
+        self.assertIsNone(gco.m_instance)
+
+        # 场景 B: 查询时 429 -> 会话已登录,属出口 IP 频率超限,绝不锁账号,换 IP 即可!
+        mock_cloud.reset_mock()
+        mock_inst2 = MagicMock()
+        gco.m_instance = mock_inst2
+        gco._dispatch_error_policy("query", err)
+        mock_cloud.lock_account.assert_not_called()
+        mock_inst2.cleanup.assert_called_once()
+        self.assertIsNone(gco.m_instance)
+        self.assertGreater(gco.m_next_query_time, time.time())
+
+    def test_standalone_dispatch_session_expired_policy(self):
+        cfg = BookerStandaloneConfig(identifier="test_group")
+        gco = StandaloneGCO(cfg=cfg, redis_conf={})
+
+        mock_inst = MagicMock()
+        gco.m_instance = mock_inst
+
+        # 触发 SessionExpiredOrInvalidError
+        err = SessionExpiredOrInvalidError()
+        gco._dispatch_error_policy("query", err)
+
+        # 验证会话已销毁,并排期 5s 后重连
+        mock_inst.cleanup.assert_called_once()
+        self.assertIsNone(gco.m_instance)
+        self.assertGreater(gco.m_next_query_time, time.time())
+
+    @patch("toolkit.vs_cloud_api.VSCloudApi.Instance")
+    def test_sentinel_error_dispatch(self, mock_cloud_instance):
+        from sentinel import SentinelGCO
+        from vs_types import GroupConfig, Task
+
+        mock_cloud = MagicMock()
+        mock_cloud_instance.return_value = mock_cloud
+
+        cfg = GroupConfig(identifier="test_sentinel")
+        cfg.login_backoff = 1800
+        cfg.proxy_cd = 300
+        gco = SentinelGCO(cfg=cfg, redis_conf={})
+
+        # 场景 1: spawn 时 429 -> 账号被限,锁账号
+        plg_cfg = VSPlgConfig()
+        plg_cfg.account.id = 999
+        plg_cfg.account.username = "sentinel_user"
+        gco._dispatch_error_policy("spawn", RateLimiteddError(), plg_cfg=plg_cfg)
+        mock_cloud.lock_account.assert_called_once_with(999, 1800)
+        self.assertGreater(gco.m_spawn_cooldown_until, time.time())
+
+        # 场景 2: query 时 429 -> IP 被限,不锁账号,移除 task 换代理
+        mock_cloud.reset_mock()
+        mock_inst = MagicMock()
+        mock_inst.config = plg_cfg
+        task = Task(instance=mock_inst)
+        gco.m_tasks.append(task)
+
+        gco._dispatch_error_policy("query", RateLimiteddError(), task=task)
+        mock_cloud.lock_account.assert_not_called()
+        self.assertNotIn(task, gco.m_tasks)
+        mock_inst.cleanup.assert_called_once()
+
+        # 场景 3: spawn 触发 SessionExpiredOrInvalidError
+        gco._dispatch_error_policy("spawn", SessionExpiredOrInvalidError(), plg_cfg=plg_cfg)
+        self.assertGreater(gco.m_spawn_cooldown_until, 0)
+
+        # 场景 4: 模拟 PermissionDeniedError
+        mock_inst2 = MagicMock()
+        task2 = Task(instance=mock_inst2)
+        gco.m_tasks.append(task2)
+        gco._dispatch_error_policy("query", PermissionDeniedError(), task=task2)
+        self.assertNotIn(task2, gco.m_tasks)
+
+    @patch("toolkit.vs_cloud_api.VSCloudApi.Instance")
+    def test_booker_error_dispatch(self, mock_cloud_instance):
+        from booker import BuiltinBookerGCO
+        from vs_types import GroupConfig, Task
+
+        mock_cloud = MagicMock()
+        mock_cloud_instance.return_value = mock_cloud
+
+        cfg = GroupConfig(identifier="test_booker")
+        cfg.login_backoff = 900
+        cfg.proxy_cd = 120
+        gco = BuiltinBookerGCO(cfg=cfg, redis_conf={})
+
+        mock_inst = MagicMock()
+        mock_inst.config = None
+        task = Task(instance=mock_inst)
+        gco.m_tasks.append(task)
+
+        # 场景 1: 模拟 booking 触发 RateLimiteddError -> 接口/IP频控,不锁账号,移除 task
+        err = RateLimiteddError()
+        gco._dispatch_error_policy("book", err, task=task)
+
+        mock_cloud.lock_account.assert_not_called()
+        self.assertNotIn(task, gco.m_tasks)
+        mock_inst.cleanup.assert_called_once()
+
+        # 场景 2: 模拟 spawn 触发 RateLimiteddError -> 账号受限,锁账号
+        mock_cloud.reset_mock()
+        plg_cfg = VSPlgConfig()
+        plg_cfg.account.id = 777
+        plg_cfg.account.username = "booker_user"
+        gco._dispatch_error_policy("spawn", RateLimiteddError(), plg_cfg=plg_cfg)
+        mock_cloud.lock_account.assert_called_once_with(777, 900)
+        self.assertGreater(gco.m_spawn_cooldown_until, time.time())
+
+
+if __name__ == "__main__":
+    unittest.main()

+ 31 - 18
vs_types.py

@@ -9,8 +9,8 @@ from typing import Optional, List, Any, Dict
 class BizException(Exception):
     def __init__(
         self,
-        code: int,
-        message: str,
+        code: int = 40000,
+        message: str = "Business exception",
         http_status: int = 400,
         extra: Optional[Dict[str, Any]] = None,
     ):
@@ -22,36 +22,49 @@ class BizException(Exception):
         
     def __str__(self):
         return (
-        f"{self.__class__.__name__}("
-        f"code={self.code}, "
-        f"http_status={self.http_status}, "
-        f"message='{self.message}', "
-        f"extra={self.extra})"
-    )
+            f"{self.__class__.__name__}("
+            f"code={self.code}, "
+            f"http_status={self.http_status}, "
+            f"message='{self.message}', "
+            f"extra={self.extra})"
+        )
 
     def __repr__(self):
         return self.__str__()
 
 
 class NotFoundError(BizException):
-    def __init__(self, message="Resource not found"):
-        super().__init__(code=40401, message=message, http_status=404)
+    def __init__(self, message="Resource not found", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=40401, message=message, http_status=404, extra=extra)
 
 class RateLimiteddError(BizException):
-    def __init__(self, message="Rate limited"):
-        super().__init__(code=42901, message=message, http_status=429)
+    def __init__(self, message="Rate limited", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=42901, message=message, http_status=429, extra=extra)
+
+# 语义别名(兼顾拼写纠正与向后兼容)
+RateLimitedError = RateLimiteddError
         
 class SessionExpiredOrInvalidError(BizException):
-    def __init__(self, message="Session expired or invalid"):
-        super().__init__(code=40101, message=message, http_status=401)
+    def __init__(self, message="Session expired or invalid", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=40101, message=message, http_status=401, extra=extra)
+
+# 语义别名
+SessionExpiredError = SessionExpiredOrInvalidError
 
 class PermissionDeniedError(BizException):
-    def __init__(self, message="Permission denied"):
-        super().__init__(code=40301, message=message, http_status=403)
+    def __init__(self, message="Permission denied", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=40301, message=message, http_status=403, extra=extra)
 
 class BizLogicError(BizException):
-    def __init__(self, message="Business logic error"):
-        super().__init__(code=40001, message=message)
+    def __init__(self, message="Business logic error", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=40001, message=message, http_status=400, extra=extra)
+
+class NetworkTimeoutError(BizException):
+    def __init__(self, message="Network or browser timeout", extra: Optional[Dict[str, Any]] = None):
+        super().__init__(code=50401, message=message, http_status=504, extra=extra)
+
+# 语义别名:调度层与插件层统一使用 VSPluginError
+VSPluginError = BizException
 
 class AvailabilityStatus(str, Enum):
     NoneAvailable = "NoAvailable"