tb-order-sync 0.4.1 → 0.4.5

package/cli/setup.py

@@ -7,9 +7,10 @@ Usage:
 
 from __future__ import annotations
 
-import getpass
+import os
 import re
 import shutil
+import subprocess
 import sys
 import webbrowser
 from datetime import datetime
@@ -18,7 +19,8 @@ from typing import Any, Callable, Optional, Sequence
 from urllib.parse import parse_qs, urlparse
 
 try:
-    from rich.console import Console
+    from rich.align import Align
+    from rich.console import Console, Group
     from rich.panel import Panel
     from rich.table import Table
     from rich.text import Text
@@ -28,7 +30,8 @@ except ImportError:
 
 from dotenv import dotenv_values
 
-from config.settings import PROJECT_ROOT
+from config.settings import APP_HOME, APP_VERSION, PACKAGE_ROOT
+from utils.sheet_selector import resolve_latest_month_sheet
 
 # ── UI 文案 ────────────────────────────────────────────────────────────────
 BANNER_TITLE = "多表格同步服务 — 配置向导"
@@ -43,8 +46,8 @@ STEP_SUMMARY = "配置总览"
 STEP_WRITE = "写入配置"
 STEP_TEST = "连接测试"
 
-ENV_PATH = PROJECT_ROOT / ".env"
-ENV_EXAMPLE_PATH = PROJECT_ROOT / ".env.example"
+ENV_PATH = APP_HOME / ".env"
+ENV_EXAMPLE_PATH = PACKAGE_ROOT / ".env.example"
 
 # Column letter validator
 _COL_RE = re.compile(r"^[A-Z]{1,3}$")
@@ -58,6 +61,19 @@ FEISHU_TOKEN_DOC_URL = (
     "authentication-management/access-token/tenant_access_token_internal"
 )
 FEISHU_TOKEN_TUTORIAL_URL = "https://www.feishu.cn/content/000214591773"
+_SETUP_LOGO = (
+    "[bold #8ecae6]████████╗██████╗     ██████╗ ██████╗ ██████╗ ███████╗██████╗[/bold #8ecae6]\n"
+    "[bold #38bdf8]╚══██╔══╝██╔══██╗   ██╔═══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗[/bold #38bdf8]\n"
+    "[bold #22d3ee]   ██║   ██████╔╝   ██║   ██║██████╔╝██║  ██║█████╗  ██████╔╝[/bold #22d3ee]\n"
+    "[bold #2dd4bf]   ██║   ██╔══██╗   ██║   ██║██╔══██╗██║  ██║██╔══╝  ██╔══██╗[/bold #2dd4bf]\n"
+    "[bold #86efac]   ██║   ██████╔╝   ╚██████╔╝██║  ██║██████╔╝███████╗██║  ██║[/bold #86efac]\n"
+    "[bold #bbf7d0]   ╚═╝   ╚═════╝     ╚═════╝ ╚═╝  ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝[/bold #bbf7d0]"
+)
+
+
+def _build_setup_version_badge() -> Panel:
+    text = Text(f"v{APP_VERSION}", style="bold #0f172a", justify="center")
+    return Panel(text, border_style="#94d2bd", box=box.ROUNDED, padding=(0, 2), title="版本")
 
 
 # ── Validators ─────────────────────────────────────────────────────────────
@@ -100,6 +116,33 @@ def _mask_secret(value: str) -> str:
     return value[:4] + "****"
 
 
+def resolve_link_selection(raw: str, link_count: int) -> list[int]:
+    """Resolve numeric selection for link-opening prompts.
+
+    Rules:
+    - 0 / empty / /skip => skip
+    - 1 => open all
+    - 2..N+1 => open one specific link
+    """
+    value = raw.strip().lower()
+    if value in {"", "0", "/skip", "skip", "n", "no", "q", "quit"}:
+        return []
+    try:
+        choice = int(value)
+    except ValueError as exc:
+        raise ValueError("请输入数字编号") from exc
+
+    if choice == 0:
+        return []
+    if choice == 1:
+        return list(range(link_count))
+
+    index = choice - 2
+    if 0 <= index < link_count:
+        return [index]
+    raise ValueError("编号超出范围")
+
+
 def parse_tencent_sheet_reference(raw: str) -> tuple[str, str]:
     """Parse a Tencent Docs sheet URL or raw file id.
 
@@ -122,6 +165,10 @@ def parse_tencent_sheet_reference(raw: str) -> tuple[str, str]:
     return file_id, sheet_id
 
 
+class SetupInputTerminated(RuntimeError):
+    """Raised when the setup input stream is unexpectedly closed."""
+
+
 # ── Setup Wizard ───────────────────────────────────────────────────────────
 class SetupWizard:
     def __init__(self, console: Optional[Console] = None) -> None:
@@ -137,6 +184,18 @@ class SetupWizard:
 
     # ── Prompt helpers ─────────────────────────────────────────────────────
 
+    @staticmethod
+    def _read_line(prompt: str = "  > ") -> str:
+        """Read one input line using the plain stdlib input path.
+
+        This is intentionally not using `Console.input`, because the Windows
+        packaged runtime is more stable with the built-in `input()` behavior.
+        """
+        try:
+            return input(prompt).strip()
+        except EOFError as exc:
+            raise SetupInputTerminated("输入流已结束") from exc
+
     def _prompt(
         self,
         label: str,
@@ -145,24 +204,35 @@ class SetupWizard:
         secret: bool = False,
         validator: Optional[Callable[[str], bool]] = None,
         error_msg: str = "输入无效，请重新输入",
+        allow_skip: bool = False,
     ) -> str:
         """Prompt user for a value with optional validation and masking."""
         existing = self._existing.get(key, "")
         effective_default = existing or default
 
         while True:
-            if secret:
-                hint = f" [当前: {_mask_secret(effective_default)}]" if effective_default else ""
-                self.console.print(f"  {label}{hint}")
-                raw = getpass.getpass("  > ")
-                if not raw and effective_default:
-                    raw = effective_default
-            else:
-                hint = f" [默认: {effective_default}]" if effective_default else ""
-                self.console.print(f"  {label}{hint}")
-                raw = input("  > ").strip()
-                if not raw and effective_default:
-                    raw = effective_default
+            hint_value = _mask_secret(effective_default) if secret and effective_default else effective_default
+            hint_label = "当前" if secret else "默认"
+            hint = f" [{hint_label}: {hint_value}]" if hint_value else ""
+            note = " [dim]可直接粘贴[/dim]"
+            if allow_skip:
+                note += " [dim]输入 /skip 暂时跳过[/dim]"
+
+            self.console.print(f"  {label}{hint}{note}")
+            try:
+                raw = self._read_line()
+            except SetupInputTerminated:
+                if allow_skip:
+                    self.console.print("  [yellow]输入已结束，已暂时跳过当前项[/yellow]")
+                    return ""
+                raise
+
+            if allow_skip and raw.lower() == "/skip":
+                self.console.print("  [yellow]已暂时跳过，可稍后重新运行 setup 补充[/yellow]")
+                return ""
+
+            if not raw and effective_default:
+                raw = effective_default
 
             if validator and not validator(raw):
                 self.console.print(f"  [red]{error_msg}[/red]")
@@ -173,9 +243,15 @@ class SetupWizard:
     def _prompt_bool(self, label: str, default: bool = False) -> bool:
         hint = "Y/n" if default else "y/N"
         self.console.print(f"  {label} [{hint}]")
-        raw = input("  > ").strip().lower()
+        try:
+            raw = self._read_line().lower()
+        except SetupInputTerminated:
+            self.console.print("  [yellow]输入已结束，已使用默认选项[/yellow]")
+            return default
         if not raw:
             return default
+        if raw in {"/skip", "skip"}:
+            return default
         return raw in ("y", "yes", "是")
 
     def _offer_open_links(self, title: str, links: Sequence[tuple[str, str]]) -> None:
@@ -186,25 +262,74 @@ class SetupWizard:
         self.console.print(f"  [dim]{title}：[/dim]")
         for idx, (label, url) in enumerate(links, start=1):
             self.console.print(f"    {idx}. {label}: [cyan]{url}[/cyan]")
+        if len(links) == 1:
+            choice_help = "0=暂时跳过，1=打开全部，2=打开该链接"
+        else:
+            choice_help = f"0=暂时跳过，1=打开全部，2..{len(links) + 1}=打开单个链接"
+        self.console.print(f"  [dim]输入编号：{choice_help}，也可输入 /skip[/dim]")
 
-        if not self._prompt_bool("是否现在用浏览器打开这些链接？", default=False):
+        while True:
+            try:
+                raw = self._read_line()
+            except SetupInputTerminated:
+                self.console.print("  [yellow]输入已结束，已跳过打开链接[/yellow]")
+                return
+            try:
+                indexes = resolve_link_selection(raw, len(links))
+            except ValueError as exc:
+                self.console.print(f"  [red]{exc}[/red]")
+                continue
+            break
+
+        if not indexes:
+            self.console.print("  [dim]已跳过打开链接[/dim]")
             return
 
         opened = 0
-        for _, url in links:
+        for index in indexes:
+            label, url = links[index]
             try:
-                if webbrowser.open_new_tab(url):
+                if self._open_url(url):
                     opened += 1
-            except webbrowser.Error as exc:
-                self.console.print(f"  [yellow]打开失败: {url} ({exc})[/yellow]")
+                else:
+                    self.console.print(f"  [yellow]未能打开: {label} - {url}[/yellow]")
             except Exception as exc:  # pragma: no cover - defensive guard
-                self.console.print(f"  [yellow]打开失败: {url} ({exc})[/yellow]")
+                self.console.print(f"  [yellow]打开失败: {label} - {url} ({exc})[/yellow]")
 
         if opened:
             self.console.print(f"  [green]已尝试打开 {opened} 个链接[/green]")
         else:
             self.console.print("  [yellow]未能自动打开浏览器，请手动复制上面的链接[/yellow]")
 
+    @staticmethod
+    def _open_url(url: str) -> bool:
+        """Open a URL in the default browser with platform fallbacks."""
+        try:
+            if sys.platform == "darwin":
+                subprocess.Popen(["open", url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                return True
+            if os.name == "nt":
+                try:
+                    os.startfile(url)  # type: ignore[attr-defined]
+                    return True
+                except Exception:
+                    pass
+                subprocess.Popen(
+                    ["cmd", "/c", "start", "", url],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+                return True
+            subprocess.Popen(["xdg-open", url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            return True
+        except Exception:
+            pass
+
+        try:
+            return bool(webbrowser.open_new_tab(url))
+        except webbrowser.Error:
+            return False
+
     def _show_tencent_guide(self) -> None:
         """Display beginner guidance for Tencent Docs Open API setup."""
         body = (
@@ -287,16 +412,20 @@ class SetupWizard:
         self.values["TENCENT_CLIENT_ID"] = self._prompt(
             "Client ID", "TENCENT_CLIENT_ID", secret=True, validator=_not_empty,
             error_msg="Client ID 不能为空",
+            allow_skip=True,
         )
         self.values["TENCENT_CLIENT_SECRET"] = self._prompt(
             "Client Secret（当前运行可留空）", "TENCENT_CLIENT_SECRET", secret=True,
+            allow_skip=True,
         )
         self.values["TENCENT_OPEN_ID"] = self._prompt(
             "Open ID（可选，部分接口需要）", "TENCENT_OPEN_ID", secret=True,
+            allow_skip=True,
         )
         self.values["TENCENT_ACCESS_TOKEN"] = self._prompt(
             "Access Token", "TENCENT_ACCESS_TOKEN", secret=True, validator=_not_empty,
             error_msg="Access Token 不能为空",
+            allow_skip=True,
         )
 
     def _step_sheet_ids(self) -> None:
@@ -311,7 +440,12 @@ class SetupWizard:
                 ref = self._prompt(
                     f"{name}链接或 File ID", file_key, validator=_not_empty,
                     error_msg="请输入腾讯文档链接或 File ID",
+                    allow_skip=True,
                 )
+                if not ref:
+                    self.values[file_key] = ""
+                    self.values[sheet_key] = ""
+                    break
                 file_id, sheet_id = parse_tencent_sheet_reference(ref)
                 if not file_id:
                     self.console.print("  [red]无法从链接中解析 File ID，请重新输入完整链接或直接填 File ID[/red]\n")
@@ -322,12 +456,23 @@ class SetupWizard:
                 self.values[sheet_key] = self._prompt(
                     f"{name} Sheet ID", sheet_key, default=sheet_id, validator=_not_empty,
                     error_msg="Sheet ID 不能为空",
+                    allow_skip=True,
                 )
                 break
 
         prompt_sheet_target("A 表（订单表）", "TENCENT_A_FILE_ID", "TENCENT_A_SHEET_ID")
+        self.values["TENCENT_A_SHEET_NAME_KEYWORD"] = self._prompt(
+            "A 表按名称自动选最新月份（可选关键字，如 毛利率）",
+            "TENCENT_A_SHEET_NAME_KEYWORD",
+            default="",
+        )
         self.console.print("")
         prompt_sheet_target("B 表（退款表）", "TENCENT_B_FILE_ID", "TENCENT_B_SHEET_ID")
+        self.values["TENCENT_B_SHEET_NAME_KEYWORD"] = self._prompt(
+            "B 表按名称自动选最新月份（可选关键字，如 客户退款）",
+            "TENCENT_B_SHEET_NAME_KEYWORD",
+            default="",
+        )
 
     def _step_feishu_creds(self) -> None:
         self.console.print(f"\n[bold cyan]🐦 {STEP_FEISHU}[/bold cyan]")
@@ -343,15 +488,19 @@ class SetupWizard:
 
         self.values["FEISHU_APP_ID"] = self._prompt(
             "飞书 App ID", "FEISHU_APP_ID", secret=True, validator=_not_empty,
+            allow_skip=True,
         )
         self.values["FEISHU_APP_SECRET"] = self._prompt(
             "飞书 App Secret", "FEISHU_APP_SECRET", secret=True, validator=_not_empty,
+            allow_skip=True,
         )
         self.values["FEISHU_C_FILE_TOKEN"] = self._prompt(
             "C 表 File Token", "FEISHU_C_FILE_TOKEN", validator=_not_empty,
+            allow_skip=True,
         )
         self.values["FEISHU_C_SHEET_ID"] = self._prompt(
             "C 表 Sheet ID", "FEISHU_C_SHEET_ID", validator=_not_empty,
+            allow_skip=True,
         )
 
     def _step_runtime(self) -> None:
@@ -464,7 +613,9 @@ class SetupWizard:
             ]),
             ("表格 ID", [
                 "TENCENT_A_FILE_ID", "TENCENT_A_SHEET_ID",
+                "TENCENT_A_SHEET_NAME_KEYWORD",
                 "TENCENT_B_FILE_ID", "TENCENT_B_SHEET_ID",
+                "TENCENT_B_SHEET_NAME_KEYWORD",
             ]),
             ("飞书配置", [
                 "FEISHU_APP_ID", "FEISHU_APP_SECRET",
@@ -551,7 +702,9 @@ class SetupWizard:
         self.console.print(f"\n[bold cyan]🔌 {STEP_TEST}[/bold cyan]")
         self.console.print("  正在执行启动自检：状态目录 + 腾讯文档 A/B 表读取...\n")
 
-        state_dir = Path(self.values.get("STATE_DIR", "state"))
+        state_dir = Path(self.values.get("STATE_DIR", "state")).expanduser()
+        if not state_dir.is_absolute():
+            state_dir = APP_HOME / state_dir
         try:
             state_dir.mkdir(parents=True, exist_ok=True)
             probe = state_dir / ".write_test"
@@ -571,20 +724,36 @@ class SetupWizard:
                 access_token=self.values.get("TENCENT_ACCESS_TOKEN", ""),
                 open_id=self.values.get("TENCENT_OPEN_ID", ""),
             )
+            a_target = resolve_latest_month_sheet(
+                conn,
+                file_id=self.values.get("TENCENT_A_FILE_ID", ""),
+                fallback_sheet_id=self.values.get("TENCENT_A_SHEET_ID", ""),
+                title_keyword=self.values.get("TENCENT_A_SHEET_NAME_KEYWORD", ""),
+            )
+            b_target = resolve_latest_month_sheet(
+                conn,
+                file_id=self.values.get("TENCENT_B_FILE_ID", ""),
+                fallback_sheet_id=self.values.get("TENCENT_B_SHEET_ID", ""),
+                title_keyword=self.values.get("TENCENT_B_SHEET_NAME_KEYWORD", ""),
+            )
             a_rows = conn.read_rows(
                 self.values.get("TENCENT_A_FILE_ID", ""),
-                self.values.get("TENCENT_A_SHEET_ID", ""),
+                a_target.sheet_id,
                 start_row=0,
                 end_row=2,
             )
             b_rows = conn.read_rows(
                 self.values.get("TENCENT_B_FILE_ID", ""),
-                self.values.get("TENCENT_B_SHEET_ID", ""),
+                b_target.sheet_id,
                 start_row=0,
                 end_row=2,
             )
             self.console.print(f"  [bold green]✅ A 表可读：{len(a_rows)} 行[/bold green]")
             self.console.print(f"  [bold green]✅ B 表可读：{len(b_rows)} 行[/bold green]")
+            if a_target.source != "fixed":
+                self.console.print(f"  [bold green]✅ A 表自动选择：{a_target.title} ({a_target.sheet_id})[/bold green]")
+            if b_target.source != "fixed":
+                self.console.print(f"  [bold green]✅ B 表自动选择：{b_target.title} ({b_target.sheet_id})[/bold green]")
             if a_rows:
                 self.console.print(f"  A 表表头: {a_rows[0][:5]}...")
             if b_rows:
@@ -691,8 +860,17 @@ class SetupWizard:
     def run_full(self) -> None:
         """Run the complete setup wizard."""
         try:
+            hero = Group(
+                Align.center(Text.from_markup(_SETUP_LOGO)),
+                Align.right(_build_setup_version_badge()),
+            )
             self.console.print(Panel(
-                f"[bold]{BANNER_TITLE}[/bold]\n{BANNER_SUBTITLE}",
+                Group(
+                    hero,
+                    Text(""),
+                    Text(BANNER_TITLE, style="bold", justify="center"),
+                    Text(BANNER_SUBTITLE, style="default", justify="center"),
+                ),
                 border_style="cyan",
                 padding=(1, 2),
             ))
@@ -737,6 +915,9 @@ class SetupWizard:
         except KeyboardInterrupt:
             self.console.print("\n\n[yellow]已取消配置向导[/yellow]")
             sys.exit(0)
+        except SetupInputTerminated:
+            self.console.print("\n\n[yellow]输入已结束，配置向导已安全退出[/yellow]")
+            sys.exit(1)
 
 
 # ── CLI handlers ───────────────────────────────────────────────────────────

package/config/settings.py

@@ -2,24 +2,76 @@
 
 from __future__ import annotations
 
+import json
 import os
 import sys
 from enum import Enum
 from functools import lru_cache
 from pathlib import Path
 
-from pydantic import Field
+from pydantic import field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-def _get_project_root() -> Path:
-    """Resolve project root, compatible with PyInstaller frozen exe."""
+def _get_package_root() -> Path:
+    """Resolve package root, compatible with PyInstaller frozen exe."""
     if getattr(sys, "frozen", False):
-        # Running as packaged exe — use exe's directory as root
         return Path(sys.executable).resolve().parent
     return Path(__file__).resolve().parent.parent
 
 
-PROJECT_ROOT = _get_project_root()
+def _read_app_version(package_root: Path) -> str:
+    """Read the app version from package.json when available."""
+    explicit = os.environ.get("TB_APP_VERSION", "").strip()
+    if explicit:
+        return explicit
+
+    package_json = package_root / "package.json"
+    if package_json.exists():
+        try:
+            payload = json.loads(package_json.read_text(encoding="utf-8"))
+            version = str(payload.get("version", "")).strip()
+            if version:
+                return version
+        except (OSError, json.JSONDecodeError, TypeError, ValueError):
+            pass
+
+    return "0.0.0"
+
+
+def _looks_like_global_node_package(root: Path) -> bool:
+    """Best-effort detection for an npm global package install."""
+    parts = {part.lower() for part in root.parts}
+    return root.name == "tb-order-sync" and "node_modules" in parts
+
+
+def _default_app_home() -> Path:
+    """Resolve the writable runtime home for config/state/venv."""
+    package_root = _get_package_root()
+    explicit = os.environ.get("TB_HOME", "").strip()
+    if explicit:
+        return Path(explicit).expanduser().resolve()
+
+    if getattr(sys, "frozen", False):
+        return package_root
+
+    if _looks_like_global_node_package(package_root):
+        home = Path.home()
+        if os.name == "nt":
+            appdata = os.environ.get("APPDATA")
+            if appdata:
+                return Path(appdata).expanduser().resolve() / "tb-order-sync"
+            return (home / "AppData" / "Roaming" / "tb-order-sync").resolve()
+        if sys.platform == "darwin":
+            return (home / "Library" / "Application Support" / "tb-order-sync").resolve()
+        return (home / ".tb-order-sync").resolve()
+
+    return package_root
+
+
+PACKAGE_ROOT = _get_package_root()
+APP_HOME = _default_app_home()
+PROJECT_ROOT = PACKAGE_ROOT
+APP_VERSION = _read_app_version(PACKAGE_ROOT)
 
 
 class AppEnv(str, Enum):
@@ -37,7 +89,7 @@ class Settings(BaseSettings):
     """All configuration knobs, sourced from .env / environment variables."""
 
     model_config = SettingsConfigDict(
-        env_file=os.environ.get("DOTENV_PATH", str(PROJECT_ROOT / ".env")),
+        env_file=os.environ.get("DOTENV_PATH", str(APP_HOME / ".env")),
         env_file_encoding="utf-8",
         case_sensitive=False,
         extra="ignore",
@@ -46,7 +98,7 @@ class Settings(BaseSettings):
     # ── 基础 ──────────────────────────────────────────────
     app_env: AppEnv = AppEnv.DEV
     log_level: str = "INFO"
-    state_dir: str = str(PROJECT_ROOT / "state")
+    state_dir: str = str(APP_HOME / "state")
 
     # ── 腾讯文档 ──────────────────────────────────────────
     tencent_client_id: str = ""
@@ -55,8 +107,10 @@ class Settings(BaseSettings):
     tencent_access_token: str = ""
     tencent_a_file_id: str = ""
     tencent_a_sheet_id: str = ""
+    tencent_a_sheet_name_keyword: str = ""
     tencent_b_file_id: str = ""
     tencent_b_sheet_id: str = ""
+    tencent_b_sheet_name_keyword: str = ""
 
     # ── 飞书（预留） ─────────────────────────────────────
     feishu_app_id: str = ""
@@ -89,6 +143,18 @@ class Settings(BaseSettings):
     refund_status_text: str = "已退款"
     data_error_text: str = "数据异常"
 
+    @field_validator("state_dir", mode="before")
+    @classmethod
+    def _resolve_state_dir(cls, value: object) -> str:
+        """Resolve relative state_dir values against APP_HOME."""
+        if value in (None, ""):
+            return str(APP_HOME / "state")
+
+        path = Path(str(value)).expanduser()
+        if not path.is_absolute():
+            path = APP_HOME / path
+        return str(path.resolve())
+
 
 @lru_cache(maxsize=1)
 def get_settings() -> Settings:

package/connectors/tencent_docs.py

@@ -21,6 +21,7 @@ from connectors.base import BaseSheetConnector, CellUpdate
 from config.mappings import col_index_to_letter
 from utils.logger import get_logger
 from utils.retry import default_retry
+from utils.sheet_selector import SheetInfo
 
 logger = get_logger(__name__)
 
@@ -184,6 +185,22 @@ class TencentDocsConnector(BaseSheetConnector):
             return [str(v) if v is not None else "" for v in rows[0]]
         return []
 
+    @default_retry(max_attempts=5)
+    def list_sheets(self, file_id: str) -> list[SheetInfo]:
+        """List spreadsheet tabs for a Tencent Docs file.
+
+        Uses the file metadata endpoint and extracts sheet IDs/titles defensively
+        because the exact response nesting can vary.
+        """
+        url = f"/openapi/spreadsheet/v3/files/{file_id}"
+        logger.info("Listing sheets for file=%s", file_id)
+        data = self._unwrap_response(self._http.get(url))
+        sheets = self._extract_sheet_infos(data)
+        if not sheets:
+            raise RuntimeError("Tencent Docs API returned no sheet metadata for this file")
+        logger.info("Found %d sheets for file=%s: %s", len(sheets), file_id, ", ".join(item.title for item in sheets))
+        return sheets
+
     @default_retry(max_attempts=5)
     def update_row_style(
         self,
@@ -361,3 +378,73 @@ class TencentDocsConnector(BaseSheetConnector):
             "blue": int(value[4:6], 16),
             "alpha": 255,
         }
+
+    @staticmethod
+    def _extract_sheet_infos(data: Any) -> list[SheetInfo]:
+        sheets: list[SheetInfo] = []
+        seen: set[str] = set()
+
+        def walk(node: Any) -> None:
+            if isinstance(node, dict):
+                sheet_id = TencentDocsConnector._extract_sheet_id(node)
+                title = TencentDocsConnector._extract_sheet_title(node)
+                if sheet_id and title and sheet_id not in seen:
+                    seen.add(sheet_id)
+                    sheets.append(
+                        SheetInfo(
+                            sheet_id=sheet_id,
+                            title=title,
+                            index=TencentDocsConnector._extract_sheet_index(node, default=len(sheets)),
+                        )
+                    )
+                for value in node.values():
+                    walk(value)
+            elif isinstance(node, list):
+                for item in node:
+                    walk(item)
+
+        walk(data)
+        sheets.sort(key=lambda item: item.index)
+        return sheets
+
+    @staticmethod
+    def _extract_sheet_id(node: dict[str, Any]) -> str:
+        for key in ("sheetId", "sheetID", "sheet_id"):
+            value = node.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        props = node.get("properties")
+        if isinstance(props, dict):
+            for key in ("sheetId", "sheetID", "sheet_id"):
+                value = props.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+        return ""
+
+    @staticmethod
+    def _extract_sheet_title(node: dict[str, Any]) -> str:
+        for key in ("title", "name", "sheetName", "sheetTitle"):
+            value = node.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+        props = node.get("properties")
+        if isinstance(props, dict):
+            for key in ("title", "name", "sheetName", "sheetTitle"):
+                value = props.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+        return ""
+
+    @staticmethod
+    def _extract_sheet_index(node: dict[str, Any], *, default: int) -> int:
+        for key in ("index", "sheetIndex", "order"):
+            value = node.get(key)
+            if isinstance(value, int):
+                return value
+        props = node.get("properties")
+        if isinstance(props, dict):
+            for key in ("index", "sheetIndex", "order"):
+                value = props.get(key)
+                if isinstance(value, int):
+                    return value
+        return default