feat(zto): support date arg via effective-offset (reuses cross-month nav)

Co-Authored-By: Claude <noreply@anthropic.com>

inbound_verify/sites/zto.py

@@ -125,18 +125,18 @@ def zto_smart_menu_click(page, menu_path):
             page.wait_for_timeout(1000)
 
 
-def zto_expected_download(page, force=False):
+def zto_expected_download(page, force=False, date=None):
     """中通：应到货物数据下载（内部含异常兜底重试，路由层无感）。"""
 
     return with_retry(
         "中通",
         "应到",
-        lambda: zto_expected_download_impl(page, force=force),
+        lambda: zto_expected_download_impl(page, force=force, date=date),
         lambda: zto_reset(page),
     )
 
 
-def zto_expected_download_impl(page, force=False):
+def zto_expected_download_impl(page, force=False, date=None):
     """中通：应到货物数据下载（单次执行，无重试；供自动化测试探测原始结果用）。"""
     print("\n▶ 开始执行【中通 - 应到货物数据下载】任务...")
 
@@ -160,8 +160,13 @@ def zto_expected_download_impl(page, force=False):
 
         # 读取服务端日期偏移（0=今天，1=昨天…），单日：起止同日
         offset = state_store.get_offset("中通")
-
-        print(f">> 正在设定查询日期: 偏移 {offset}（0=今天）...")
+        if date:
+            # 指定日期：折算成相对今天的有效偏移，复用下方 target_time 计算与跨月翻月
+            target_date = datetime.strptime(date, "%Y-%m-%d").date()
+            offset = (datetime.now().date() - target_date).days
+            print(f">> 正在设定查询日期: 指定日期 {date}（折算偏移 {offset}）...")
+        else:
+            print(f">> 正在设定查询日期: 偏移 {offset}（0=今天）...")
         ewb_frame.locator("#beginDate").click()
         page.wait_for_timeout(500)
 
@@ -373,18 +378,18 @@ def zto_expected_download_impl(page, force=False):
         return False
 
 
-def zto_actual_download(page, force=False):
+def zto_actual_download(page, force=False, date=None):
     """中通：实到货物数据下载（内部含异常兜底重试，路由层无感）。"""
 
     return with_retry(
         "中通",
         "实到",
-        lambda: zto_actual_download_impl(page),
+        lambda: zto_actual_download_impl(page, date=date),
         lambda: zto_reset(page),
     )
 
 
-def zto_actual_download_impl(page):
+def zto_actual_download_impl(page, date=None):
     """中通：实到货物数据下载（单次执行，无重试；供自动化测试探测原始结果用）。"""
     print("\n▶ 开始执行【中通 - 实到货物数据下载】任务...")
 
@@ -408,8 +413,12 @@ def zto_actual_download_impl(page):
 
         # 2. 读取服务端日期偏移（0=今天，1=昨天…），单日：起止同日
         offset = state_store.get_offset("中通", "actual")
-
-        print(f">> 正在设定查询日期: 偏移 {offset}（0=今天）...")
+        if date:
+            target_date = datetime.strptime(date, "%Y-%m-%d").date()
+            offset = (datetime.now().date() - target_date).days
+            print(f">> 正在设定查询日期: 指定日期 {date}（折算偏移 {offset}）...")
+        else:
+            print(f">> 正在设定查询日期: 偏移 {offset}（0=今天）...")
         arr_frame.locator("#daterange").click()
         page.wait_for_timeout(500)